remotion-cli

Remotion CLI

使用 npx remotion ... 运行命令，或通过项目定义的脚本运行。CLI 需要 Node.js 18+；执行渲染操作还需要安装 Chrome/Chromium（或使用 npx remotion install-executables）。

开发流程

1. 搭建项目： 使用 npx create-video@latest，或克隆模板。非交互式运行：npx create-video@latest --blank ./my-project。
2. 编写内容： 使用 /remotion-core 编写合成。
3. 编辑时快速查看效果： 运行 npm run dev，在 localhost:3000 打开 Remotion Studio。
4. 在 Studio 中检查： 拖动时间轴，确认所有帧均可渲染，并使用 npx remotion compositions src/index.ts 检查所有合成。
5. 渲染草稿： 先使用 --concurrency=1，以便发现非确定性错误。
6. 与用户预览确认： 打开 Studio，将 URL 提供给用户，并询问是否需要修改或渲染最终版本。
7. 仅在获批后渲染： 使用高质量编解码器交付。
8. 验证输出： 通过 ffprobe 确认文件存在、非空且时长符合预期。

# Dev server (fast live preview)
npm run dev
# OR
npx remotion studio src/index.ts

# List all registered compositions
npx remotion compositions src/index.ts

# Draft render (fast, lower quality)
npx remotion render src/index.ts MyComposition out/draft.mp4 --concurrency=1

# Final render (high quality)
npx remotion render src/index.ts MyComposition out/final.mp4 --codec=h264 --crf=18

# Verify output
ffprobe -v error -show_format -show_streams out/final.mp4

Remotion Studio

界面	时间	用途
Studio（npm run dev）	编写期间	实时预览帧、拖动时间轴、编辑 props
Studio Input Props 面板	随时	编辑合成 props 并查看实时效果
Studio 渲染按钮	获批后	在浏览器中触发本地渲染

Studio 默认运行于 localhost:3000。在进行任何渲染之前，它都是主要的审核界面。

render 命令选项

需求	命令
快速本地迭代	npx remotion render ... --concurrency=1 --quality=draft
本地最终交付（H.264）	npx remotion render ... --codec=h264 --crf=18
本地最终交付（ProRes）	npx remotion render ... --codec=prores --prores-profile=4444
从单帧生成静态图像	npx remotion still ... --frame=30
覆盖合成尺寸	npx remotion render ... --width=1920 --height=1080
覆盖 FPS	npx remotion render ... --fps=60
覆盖时长	npx remotion render ... --frames=0-150
传入输入 props	npx remotion render ... --props='{"title":"Hello"}'
从 JSON 文件读取 props	npx remotion render ... --props=./props.json

AWS Lambda 渲染

# Install Lambda package
npm install @remotion/lambda

# Deploy Lambda function (run once per AWS account/region)
npx remotion lambda functions deploy --memory=3009 --timeout=120

# Create a site (upload bundle to S3)
npx remotion lambda sites create --site-name=my-video-site

# Render via Lambda (fast, parallel)
npx remotion lambda render my-video-site MyComposition --region=us-east-1

# Check render progress
npx remotion lambda renders progress <render-id> --region=us-east-1

运行任何 Lambda 命令前，请阅读 references/lambda.md。Lambda 需要 IAM 角色、S3 存储桶和环境变量（AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_REGION）。

Agent 约定

• 调试时使用 --concurrency=1，以便发现非确定性错误
• 诊断渲染失败时使用 --log=verbose
• 切勿仅因 Studio 中看起来正常就进行渲染——务必等待用户批准
• 渲染前使用 npx remotion compositions src/index.ts 验证所有合成都已注册
• 批量渲染时，使用 Node.js API（renderMedia、renderFrames），不要循环调用 CLI
• 某些命令可通过 --log=json 获取 JSON 输出

remotion.config.ts

将 remotion.config.ts 放在项目根目录中，以设置持久默认值：

import {Config} from '@remotion/cli/config';

Config.setVideoImageFormat('jpeg');
Config.setOverwriteOutput(true);
Config.setConcurrency(4);
Config.setCodec('h264');
Config.setCrf(18);

运行命令前请阅读相应参考文档

需求	参考文档
studio、render、still、编解码器选项	references/render-options.md
lambda functions、lambda sites、lambda render	references/lambda.md
用于自定义部署的 bundle	references/bundle.md
upgrade、install-executables、doctor	references/upgrade-misc.md
compositions、--props、calculateMetadata	references/compositions.md

对于合成变量和 calculateMetadata，还请阅读 /remotion-core → references/calculate-metadata.md。对于媒体资源，请使用 /remotion-media。对于 Lambda 部署和成本优化，请阅读 references/lambda.md。