视频引擎
一个经过验证的流水线，用于将脚本转化为可直接发布的视频（通过代码实现）。它是风格无关的：引擎（语音、时间轴、动画基元、质量检查、渲染）保持不变；视觉风格、节奏、角色和音效则每个项目根据需求文档和客户参考资料单独设计。
如果用户已有基于此引擎构建的项目，在构建任何新内容之前，请先阅读其布局文档（VIDEOS.md / SAGAS.md）、引擎合约（src/engine/video.ts 或 saga.ts）、一个风格（src/styles/<style>/：kit.ts、Video.tsx）和一个已完成的场景。复用其引擎，而不是从头开始。两种布局已经验证有效：
- 系列：共享角色、语音和格式的单集（例如，一个带有TTS和吉祥物的儿童数学故事系列）。
- 独立视频：一次性解说视频，每个视频有独立的主题、提供的语音、素材，可能还有独特的视觉风格（例如，深色图表风格的技术解说视频，渲染为16:9和9:16比例）。
不可妥协的原则
- 音频是时钟。 先生成/导入语音，进行单词级对齐，然后根据单词制作动画。切勿为了达到指定时长而加速或修剪语音。
- 每个视觉事件都锚定在一个说出的单词上（
at(block, 'exact phrase', {word, n})）。如果短语未出现在对齐结果中，则大声报错——绝不自创时间戳。 - 纯粹的时间函数。 场景状态 = f(t)。帧之间无状态 → 预览等同于任意帧的渲染，且质量检查可以采样任意时刻。
- 确定性纹理。 在对象本地坐标中使用种子噪声 → 无闪烁/抖动。进行测量（静态区域的帧差异 ≈ 0）。
- 先验证再渲染；前后审查帧。 自动检查捕获逻辑/时间错误；连续画面捕获构图错误（重叠、拥挤、隐藏元素）。两者都是必需的。
- 仅在获得同意后花钱。 TTS调用消耗积分：先试运行（区块+字符数）→ 询问 → 生成。根据影响音频的所有输入哈希值进行缓存。
- 如实报告。 说明哪些内容已自动验证，哪些已人工检查，以及哪些未检查（例如“我未听取音频”）。
- 众多视频，一个引擎——从第一个视频开始。 共享引擎 + 可复用风格 + 每个视频（或每个系列）一个独立的文件夹，包含该视频自己的脚本、语音、场景、缩略图、素材和专属组件。引擎从不导入视频或风格；每条命令都会指定视频路径。参见
references/project-layout.md。
工作流程
- 将视频放置在项目布局中 — 新仓库：在编写任何场景之前设置好多视频布局；现有仓库：
npm run video -- new/npm run saga -- new（在客户已填充音频+脚本的文件夹上运行）。参见references/project-layout.md。 - 需求与格式 — 目标受众、目标、平台、时长、宽高比、语言/区域、变现约束（例如 YouTube“为儿童制作”）。参见
references/formats-and-niches.md。 - 风格圣经 — 从客户参考资料推断或提供2-3个方向；锁定色板、排版、纹理、角色、动效语言、音效色板，存储在
style.json/文档中。参见references/style-design.md。 - 脚本即数据 — 包含
tts_text（含语音标签）、subtitle_text、可选问题/等待、视觉指示、预期答案/事实的区块。使用JSON schema进行验证。 - 语音 — 使用带时间戳的ElevenLabs（或导入手动剪辑 + 本地强制对齐）。参见
references/voice-and-alignment.md。 - 时间线 — 放置剪辑、测量间隙/等待、主语音轨标准化、逐帧语音包络、SRT字幕。参见
references/timeline-and-audio.md。 - 场景脚本 — 每个视频一个，使用工具包（对象、移动、标签、方程式/文本揭示、姿势、音效、装饰）的声明式构建器。参见
references/animation-remotion.md。 - 验证 — schema、等待、“在说出之前不揭示任何内容”、计数/答案、无重叠、安全区域、字幕带空闲。参见
references/qa-and-validation.md。 - 静态画面审查 — 12-15个关键瞬间的连续画面；修复并重复。
- 渲染 — 后台运行、日志记录、内存安全的并发；使用ffprobe + 响度验证。参见
references/render-and-performance.md。 - 交付物 — MP4、
<name>.<lang>_<REGION>.srt、缩略图（必须，由流水线自身生成——绝不是一个独立的可选步骤；根据格式：16:9为1280×720，9:16为1080×1920封面，关键内容居中以便1:1/3:4裁剪；若缺失则运行失败，在输出质量检查中检查其大小，并进行查看）、主音频、单词时间、事件时间线、质量检查报告、上传元数据（标题/描述，包含真实章节/话题标签/标签）。
技术栈（默认；需要说明偏离理由）
- Remotion 4（React + SVG） 用于确定性帧渲染、Studio/Player预览、CLI批量。检查许可（个人或≤3名员工免费）。
- macOS上的Chromium GL
angle（速度提高约30%）。硬件编码器很少有帮助（瓶颈是绘制）——请测量。 - ElevenLabs
POST /v1/text-to-speech/{voice}/with-timestamps（字符对齐）。库中的语音需要通过API付费。 - Python虚拟环境中的 stable-ts (Whisper) 用于手动剪辑的本地强制对齐；ElevenLabs强制对齐API作为精确替代方案。
- ffmpeg 用于混音、响度（EBU R128）、remux/faststart、连续画面、闪烁测量。
- 字体：OFL（Google Fonts）本地存储并附带许可文件。音效/音乐：程序化合成或使用许可素材；保留副本 + 许可表格。
容易出错的地方（经验教训）
ctx.at()默认必须返回短语的第一个单词；重复短语需要n（例如，“una más”说了两次）。- 重叠检查必须使用对象的缩放后尺寸；缩放后验证可能失效——引擎更改后重新验证所有内容。
- 由“转移/拿出”助手创建的对象在场景变化时也必须获得
remove时间，否则它们会泄露到后续场景中。 - 在问题的等待窗口期间移动对象会破坏“等待期间冻结”；在等待结束后再移动。
- 切勿显示旁白尚未提及的数字/答案（在场景、标签、方程式、字幕中）。在数字单词处拆分字幕提示。
- 渲染并发：每个Chromium实例约2.6 GB RAM；8 GB Mac上运行6个 → 大量交换和渲染停滞。默认为
floor(totalmem/2.6GB)。 - 内嵌字幕需要保留的条带；验证没有对象进入该区域。
- 固定文本框中的长标题溢出 — 根据长度自动调整大小。
- 在信任导入的音频之前，检查每个剪辑的内容（转录 → 与脚本比较，检查数字与单词的对应关系）；剪辑可能缺失或顺序错乱。对生成的TTS也做同样检查（通过代理“聆听”：Whisper转录与脚本比对，所有数字都存在）。
- Remotion
bundle()每次调用都会将public/（所有语音）复制到操作系统临时目录并且从不删除；多次静态画面运行会填满460 GB磁盘。脚本结束时务必rm -rf该bundle。在长时间批量工作中监控可用磁盘。 - SVG滤镜使用元素的边界框：完全水平或垂直的路径（零面积bbox）加上滤镜会渲染为无内容。平衡杆、数轴刻度和引导线因此消失。笔直轴向笔画不需要滤镜。
- 问题的数据可能需要保持可见（价格、数据政策），但答案不能。如果价格等于数字答案，则在问题前移除价格。
- 扁平的单一视频仓库在第二个视频到来时必须重构。此时，首先捕获基线：静态画面md5、缩略图、JSON/SRT交付物和语音md5。移动后，所有内容必须字节一致。移动文件，绝不删除；将遗留内容放入
_legacy/供用户审查。 staticFile()只能访问public/：每个视频的媒体文件位于视频文件夹中，在每次bundle之前同步到public/videos/<slug>/。新视频需要一个占位时间线（无区块），以便静态导入能编译通过。- 客户脚本通常混合了旁白和视觉指示（例如 NARRACIÓN / REFERENCIA VISUAL — NO NARRAR）。仅对齐旁白，并将视觉笔记按章节保留在
script.json中，因为它们是场景保真度的规格。 - 提供的音频可能并未说出提供的脚本内容（配音演员即兴发挥或后来重录）。在对齐之前，务必先读取免费转录，并根据实际说出的内容（放在
narracion.md中，与客户的脚本并列）进行对齐。针对错误文本的强制对齐会静默地产生错误的时间。 - 技术解说需要保真度，而非装饰。计算可以计算的内容：真实的照片张量、真实的卷积、每个像素的真实噪声公式、真实的采样器更新。其余标注为示意性（“esquema didáctico”、“salida ilustrativa”），保留
references/decisiones.md，并在上传文案中同样说明。在绘制前，对照主要来源验证产品声明。例如，Imagen是像素空间级联扩散，而非潜在扩散。 - 公式：在流水线步骤中使用MathJax将客户的TeX渲染为SVG路径（无字体依赖），然后以
formula元素绘制。 - 从左到右构建的示意图除非整个组在增长时滑动，否则永远不会居中。使用自动重新居中，在新元素进入之前滑动，在退出的元素淡出之后滑动。保持标题在CX固定，组进入间隔 ≥ 0.6秒。对于链条，首先绘制空槽位。
- 无缝循环：
- 不使用淡入淡出。
- 使开头和结尾等于自然的暂停。
- 使用精确生成为视频时长的音乐。
- 以开口元素的精确副本结束：缩放副本会因抗锯齿而产生差异。
- 通过无字幕的首帧与末帧差异进行验证。
- SVG中的栅格照片应放入
<foreignObject><Img/></foreignObject>，因为Remotion会等待<Img>。裸SVG<image>可能渲染空白帧。 - 带有关键帧数值参数（时钟分钟、倾斜、电平、爆炸偏移）的通用属性调度器可以扩展到几十个新对象，而无需修改渲染器。在编写场景之前，先构建属性审查表（开发静态画面）。
开始一个新项目
- 在现有引擎仓库中新建视频或系列（首选）：使用其脚手架命令（例如
npm run video -- new --video <slug>或npm run saga -- new --saga <slug>）。它将从_template/创建文件夹，进行注册，并可选择将一个基础风格复制到src/styles/<new-style>作为重新设计的起点。 - 新仓库：在编写任何场景之前，根据
references/project-layout.md设置好多视频布局：package.json、tsconfig.json、remotion.config.ts、src/engine/（场景模型、单词提示、格式、字幕、视频合约）、src/styles/<style>/中的一个风格、scripts/（时间线、验证、静态画面、渲染、缩略图、检查、new命令）、tools/（对齐、程序化素材）、一个_template/文件夹、注册表和Root.tsx。然后npm install，并且只有在需要对齐提供的音频时才创建一个带有stable-ts的Python虚拟环境。 - 根据领域的区块结构（如钩子、教学、实例、问题/等待、总结等角色）调整脚本schema。
- 实现风格圣经：色板、字体（本地、许可）、滤镜、背景纹理（由脚本生成）、角色或主持人、音效/音乐。
- 使用真实音频渲染12-15秒的样本 → 用户批准 → 然后扩展。
- 将项目规则保存在项目的
CLAUDE.md中（成本/同意、命名约定、语言、审查步骤），并将布局保存在VIDEOS.md/SAGAS.md中。
参考文件
references/style-design.md— 推断/提出视觉标识、风格圣经、一致性规则。references/voice-and-alignment.md— ElevenLabs、缓存、错误、手动剪辑、强制对齐。references/timeline-and-audio.md— 剪辑放置、等待、响度、音乐闪避、音效、字幕。references/animation-remotion.md— 场景数据模型、创作工具包、角色绑定、动效语言、预览。references/textures-and-rendering-looks.md— 用于多种外观的种子化SVG滤镜配方。references/qa-and-validation.md— 自动化规则、视觉审查、输出检查。references/render-and-performance.md— 渲染设置、内存、队列、交付物、上传元数据。references/formats-and-niches.md— 宽高比、安全区域、领域剧本。references/project-layout.md— 每个仓库多个视频：每个视频的文件夹、可复用风格、视频合约、素材同步、迁移扁平仓库。