remotion-render-pipeline
将合成项目转换为可交付的 MP4。
触发器
remotion-composition-builder报告ready: true。- 用户说“渲染”/“交付”并附带已知的作业 ID。
输入参数
jobIdcomposition— 与src/Root.tsx匹配的 ID(例如Explainer)outputPath— 相对于remotion-studio/output/的路径props— 完整的输入属性(品牌 + 故事板 + ...)以 JSON 形式提供linear—{teamId, projectId}用于工单路由
方法
- 前置类型检查 —
cd remotion-studio && npx tsc --noEmit。失败时,将错误返回给remotion-composition-builder。 - 语音旁白合成 —
render/voiceover.ts将每场景的 MP3 写入public/audio/{jobId}/scene-N.mp3(位于public/下以便staticFile()解析)。使用缓存键sha1(voiceId|style|text)。如果缺少ELEVENLABS_API_KEY,则跳过——合成项目仍可仅以屏幕文本运行。 - 渲染 —
npx tsx render/render.ts --comp={composition} --out={outputPath} --props='{...}' --jobId={jobId}。包装为 600 秒超时;卡死/崩溃时重试一次。 - 验证 — 文件存在,时长与预期相差 ±0.5 秒,编码为
h264,分辨率与合成项目匹配,大小小于 100MB。 - 交付:
- 上传至 Supabase 存储桶
remotion-renders— 签名 URL,保留 90 天。 - 通过
app.server.telegram_video.send_telegram_video()(共享工具)发送 Telegram。若文件大于 45MB,则发送签名 URL 链接而非内联上传(Telegram 上限为 50MB)。 - 在
{teamId}/{projectId}中创建 Linear 工单,包含:渲染 URL、源摘要、BrandConfig 版本(src/brands/{slug}.ts的 Git SHA)、合成文件路径。
- 上传至 Supabase 存储桶
- 状态 — 将摘要写入
.research/renders/{jobId}.json。
输出
{
"jobId": "ra-nir-explainer-2026-04-28T15-30-00",
"mp4Path": "remotion-studio/output/ra-nir-explainer-2026-04-28T15-30-00.mp4",
"supabaseUrl": "https://<project>.supabase.co/storage/v1/object/sign/remotion-renders/...",
"telegramSent": true,
"linearIssue": "RA-2049",
"validation": { "durationSec": 60.0, "codec": "h264", "resolution": "1920x1080", "sizeMB": 12.4 }
}
边界约束
- 绝不要在
tsc --noEmit失败时运行渲染——这会浪费 2-5 分钟保证产生坏输出。 - 在渲染验证通过前,绝不要自动合并源 PR(合成 + 品牌变更)。
- 绝不要将带有
[DRAFT]标记的渲染上传到正式品牌存储桶——草稿应上传至remotion-drafts。
失败升级
- 超时/卡死 → 终止进程,重试一次 → 若再次失败,创建 Linear 工单,优先级为 2,并附加标准错误输出。
- 验证失败(时长/编码错误)→ 创建 Linear 工单,优先级为 3,并附上差异与预期对比。
- Telegram 失败 → 降级为
send_telegram_document(),以.mp4作为附件发送。
复用组件
render/render.tsrender/voiceover.tsapp/server/telegram_video.py(共享工具)config/harness/projects.json用于解析 Linear 团队/项目信息
每项目 API 密钥
此技能从调用项目内部(Synthex、Pi-SEO、RestoreAssist 等)被调用。每个项目通过其自身的 .env / .env.local 提供密钥。技能从不读取 Pi-Dev-Ops 的密钥。
渲染时必需或可选的 env 变量:
ELEVENLABS_API_KEY— 语音旁白合成。缺失 = 静默渲染,仅显示屏幕文本(记录警告,渲染继续)。TELEGRAM_BOT_TOKEN,TELEGRAM_CHAT_ID— Telegram 交付。缺失 = 跳过 Telegram 步骤(MP4 仍写入磁盘,若配置了 Supabase 则也上传)。SUPABASE_URL,SUPABASE_SERVICE_ROLE_KEY— 签名 URL 上传。缺失 = 跳过 Supabase 步骤。LINEAR_API_KEY— 工单创建。缺失 = 跳过 Linear 步骤。REMOTION_LICENSE_KEY— 在 Remotion 公平源码许可下任何商业渲染所必需。
从项目 shell 调用的示例:
cd ~/Pi-CEO/Synthex
source .env.local # 项目自身的密钥
cd ~/Pi-Dev-Ops/remotion-studio
npx tsx render/render.ts \
--comp=Explainer \
--out=$OLDPWD/.remotion-renders/synthex-launch.mp4 \
--jobId=synthex-launch-$(date +%s) \
--props='{"brand":"synthex","hookSec":8,"ctaSec":8,"storyboard":[...]}'
或者通过 Pi-Dev-Ops 编排器 API 调用,该 API 在会话生成时会继承调用项目的环境变量。
输出约定:默认将 MP4 写入 <调用项目>/.remotion-renders/ 目录(已 gitignore)——使每个项目的产物保留在其自身目录树中。可通过 --out=... 覆盖。