Remotion CLI
工具是 remotion,来自 @remotion/cli。每个命令都通过 npx remotion <command> 运行,并且每个命令都会先打包项目,因此类型错误或有问题的导入会表现为打包失败,而不是渲染失败。
npx remotion --help 和 npx remotion <command> --help 是标志参数的最高权威。 标志参数会随版本移动;请阅读帮助输出,不要轻信任何列表(包括本列表)。以下内容是工作流程和失败模式,而非标志参考。
工作流程
| 阶段 | 命令 | 原因 |
|---|---|---|
| 脚手架 | npx create-video@latest --blank | 写入匹配的 package.json、remotion.config.ts、tsconfig |
| 类型检查 | npx tsc --noEmit | 最便宜的门控;在任何渲染前捕获 schema/prop 漂移 |
| 列表 | npx remotion compositions | 确认您即将渲染的 id 确实存在 |
| 探测帧 | npx remotion still <id> out/probe.png --frame=<n> | 秒级而非分钟级;迭代的主力工具 |
| 审查 | npx remotion studio | 交给用户;他们自己擦洗时间线并编辑属性 |
| 渲染 | npx remotion render <id> out/video.mp4 | 仅在用户批准后执行 |
| 远程发布 | npx remotion bundle → npx remotion lambda render <url> <id> | 分布式渲染;需要已部署的 AWS 基础设施 |
在渲染前先探测帧
完整渲染一个 45 秒 1080p 的合成需要几分钟。而一帧探测只需要几秒钟,并且能回答大多数问题:文字是否在画面内、资产是否加载成功、颜色是否正确。探测每个场景的中段,查看每张图片,然后再开始渲染。
npx remotion still launch out/s1.png --frame=45
npx remotion still launch out/s2.png --frame=180
永远不要仅凭打包通过就报告合成功。请查看像素。
工作室是审查界面,不是您的调试器
npx remotion studio 提供一个带有时间线、由 Zod schema 驱动的属性编辑器以及帧级精确擦洗的项目界面。将其交给用户进行审批。对于您自己的验证,更倾向于使用 still 探测:它们是可脚本化的,并且您可以在不要求用户描述他们所看到内容的情况下查看输出。
传递属性
--props 接受一个 JSON 字符串或一个 JSON 文件的路径,并覆盖 defaultProps:
npx remotion render launch out/video.mp4 --props='{"productName":"Acme"}'
如果属性未通过合成的 Zod schema,则会大声渲染失败。这就是声明 schema 的意义所在,因此请保持其准确。
批量渲染
没有批量子命令。直接在 shell 中对 id 或属性负载进行循环:
for id in $(npx remotion compositions --quiet); do
npx remotion render "$id" "out/$id.mp4"
done
对于同一个合成需要多次渲染不同数据集的情况,更建议在 Node 脚本中使用 @remotion/renderer 的 renderMedia():它只打包一次,而不是每次渲染都打包,这通常会占用大部分时间。
渲染性能
--concurrency=<n>设置并行工作线程数。默认值是 CPU 核心数的一半(上限为 8);最大值是核心数,请求更多核心会报错,不会自动降低。在内存紧张的机器上,降低此值可以修复看起来像渲染器错误导致的崩溃。--jpeg(覆盖默认的 PNG 帧格式)在合成不需要保留透明度时能显著提速。npx remotion benchmark测量一次真实的渲染,因此可用它来证明并发数或编解码器更改的合理性,而不是猜测。npx remotion gpu报告浏览器实际将加速的内容。在将渲染慢的原因归咎于着色器或重型滤镜之前,值得先检查一下。
诊断失败
| 症状 | 可能的原因 |
|---|---|
| 打包失败 | 类型错误或有问题的导入。运行 npx tsc --noEmit 以获取可读的相同错误版本。 |
| "No composition with id …" | Root.tsx 中的 id 与您传入的不同。npx remotion compositions 可以确认。 |
| 渲染挂起,然后超时 | delayRender() 没有匹配的 continueRender()。每个延迟句柄都必须被释放。 |
| 每一帧看起来都像第 0 帧 | CSS 动画/过渡,或 requestAnimationFrame。渲染器不会推进浏览器时钟。 |
| 动画在帧之间闪烁或频闪 | 未播种的 Math.random()。请使用 random(seed)。 |
| 向前擦洗时动作正常,跳到某帧时中断 | 状态驱动的动画。请改为从 useCurrentFrame() 派生状态。 |
| 仅在 Lambda 或打包的渲染中资产 404 | 使用了硬编码路径而不是 staticFile()。 |
| 毫无意义的版本错误 | Remotion 包版本不匹配。npx remotion versions 会报告差异。 |
| 渲染过程中内存不足 | 机器的并发数过高。降低 --concurrency。 |
报告失败时请提供实际的错误输出。不要复述堆栈跟踪。
已退役的 HyperFrames CLI 能力去向
旧的 hyperframes CLI 中打包了 Remotion CLI 没有的创作、媒体和 QA 命令。以下都不是 Remotion 命令,因此不要尝试运行它们:
| 已退役命令 | 当前能力所在位置 |
|---|---|
init | npx create-video@latest --blank,然后 /hyperframes-core → references/project-structure.md |
lint、check、layout、validate | npx tsc --noEmit 加上 still 探测。那些门控执行的 data-* 契约已被移除。 |
snapshot、compare、grade-compare | 在选定帧上使用 npx remotion still;使用您自己的工具对 PNG 进行差异比较。 |
preview、play、present | npx remotion studio |
add、catalog | /hyperframes-registry |
capture | /product-launch-video(站点捕获)和 /media-use |
tts、transcribe、remove-background | /media-use |
beats、keyframes | /hyperframes-creative(节拍规划)、/hyperframes-keyframes |
cloud、publish | npx remotion bundle + remotion lambda / remotion cloudrun,或您自己的托管方案 |
skills、docs、upgrade、doctor | 这些技能已嵌入此仓库;npx remotion upgrade 和 npx remotion versions |
如果有工作流技能或参考文件仍指示您运行 npx hyperframes <anything>,则该指令已过时。请使用上表中的 Remotion 等效操作,并在您的摘要中说明您遇到了过时指针,以便修复。