先用一分钟看懂这件事
这个案例的重点不是“Codex 会剪视频”，而是如何把一次成功的复杂任务，变成以后能重复执行的能力。
1. 这项能力不是从一个大 Skill 开始的
一开始，我们并没有要求 Codex 直接完成“长视频拆成七条短视频”。这样做的问题是，出了错以后很难判断：是旁白不对、字幕不同步、画面选错，还是渲染失败。
更合理的路径，是先把最稳定、最容易验证的基础能力拆出来：生成音频和从音频生成字幕。它们各自能独立运行、独立检查，也能在后续任何视频工作流中复用。
01
搭建基础能力
先完成 TTS 和字幕两个 skill，为后续视频提供可用旁白和时间轴。
02
做一次真实实验
拿一条约五分钟源视频，根据目标文稿规划并裁剪出一条可观看的视频。
03
扩大验证范围
确认单条剪辑正确后，继续验证竖屏排版、字幕位置、视觉模板和批量输出。
04
沉淀为 recut skill
把已验证的步骤、输入规则、质量检查和失败处理收进一个可复用的编排 skill。
一开始只做两件事
TTS：把已经确定的文稿变成旁白音频。
字幕：根据最终音频生成 SRT 和精确时间段。
它们的共同价值是：让“声音”和“时间”先变成稳定、可检查的资产。
后来增加的是编排能力
长视频重剪不是第三个“媒体 API”。它需要理解原视频、选择画面、匹配新旁白、组织项目、渲染并验收。
因此它最终成为上层的 recut skill：不替代两个基础 skill，而是调用并协调它们。
2. 为什么在成功之后，还要把过程做成 Skill
一次完成剪辑，说明任务可做；把过程沉淀为 skill，才说明它能被可靠地重复做。
在第一次剪辑中，Codex 会经历一连串判断：先看源视频有什么内容，再决定短视频的主题；然后写或接收目标文稿，选择原视频里的相关画面；接着生成旁白、字幕和竖屏项目；最后检查成片是不是可交付。
如果这些判断只存在于一次聊天中，下次换一条视频就需要重新想一遍。recut skill 的作用，是把那些已经验证过的步骤固定下来，让下一次任务从“重新发明流程”变成“提供素材和目标，按同一套标准执行”。
人或 Agent 的判断选择主题、写文稿、确认原视频证据是否支持新旁白、决定每条短视频要表达什么。
Skill 的流程规定先分析、再转写、再生成媒体、再建项目、最后检查；避免遗漏关键环节。
脚本的执行调用 API、切视频、复制资产、生成 HTML 项目、渲染 MP4，并把结果写成可追溯的文件。
这也是为什么它不是一个“大提示词”。提示词只能描述目标；skill 还要给出执行顺序、文件约定、错误处理和验收标准。
3. 最终系统里有三个核心角色
当 recut skill 被沉淀下来后，系统不再靠一个组件做所有事。它把“怎么剪”“怎么说”“字幕何时出现”分给三个专长不同的角色。
上层：recut skill
读取源视频和编辑计划，组织每条短视频，选择原画面片段，创建渲染项目，调用下层能力，并输出最终 MP4。
↔
基础：TTS skill
接收已经确定的文稿和参考音色，生成旁白音频。它同时给出真实音频时长，成为后续节奏和时长校验的依据。
↔
基础：字幕 skill
接收最终旁白音频，生成 SRT 与时间段 JSON。它回答的是“这一句从第几秒开始，到第几秒结束”。
编辑计划主题、文稿、目标时长、画面重点
→
TTS旁白音频与真实时长
→
字幕SRT 与字幕时间轴
→
FFmpeg从源视频切出并标准化画面
→
HyperFrames组合画面、字幕、动画和音频，渲染竖屏视频
4. 一条短视频真正难在哪里：画面和旁白必须有关系
如果只是把长视频按时间平均切开，短视频很容易出现“旁白在讲配置，画面却停留在安装”的问题。recut skill 的关键不是切得快，而是让新旁白与源画面建立可追溯的对应关系。
源视频中的内容地图
开场打开配置执行验证结尾
先从源音频生成带时间戳的转写，并结合抽样画面理解每一段实际展示了什么。
→
短视频中的一个 beat
- 新旁白：提醒观众确认配置入口。
- 源画面：截取“打开配置”的真实时间段。
- 输出时长：根据旁白节奏分配几秒。
- 视觉焦点：放大配置区域，必要时加标注框。
beat 可以理解成“最小语义剪辑单元”。一条短视频通常由 3 到 8 个 beat 组成。它不只保存时间点，也保存这段画面为什么被选中、在成片里显示多久、该关注屏幕的哪个区域。
因此，最终画面和旁白并不是碰巧对上，而是由一份明确的编辑计划绑定在一起。技术上，这份计划写入 manifest；对人来说，它更像一张可审阅的剪辑分镜表。
5. 从长视频到竖屏短视频的六步生产过程
下面六步是 recut skill 固化下来的方法。读这一节不需要先理解 API 或代码，只要把它当成一条编辑生产线。
1分析源视频
读取时长、尺寸、帧率和音频轨；从不同位置抽取代表性画面，形成联系表。Codex 因此既能读到内容，也能看到界面。
2生成源转写
从源视频提取轻量音频，生成带时间戳的字幕。它回答“原视频在第几秒讲了什么”。
3规划文稿和 beat
根据源转写和画面，确定每条短视频的主题、旁白、原画面范围、目标时长和视觉焦点。
4生成旁白和字幕
把新文稿转成旁白，再以最终旁白为准生成字幕。真实音频时长成为视频时长的权威。
5裁剪并标准化画面
FFmpeg 根据每个 beat 切出源片段，按需要调整节奏和关注区域，统一成适合渲染的 30 帧媒体。
6组织项目并渲染
把画面、旁白、字幕、字体和可选 BGM 放进独立项目；通过 HyperFrames 生成竖屏版式、动画和最终 MP4。
6. 为什么它能从一条实验视频扩展到多条成片
批量输出最怕的不是速度慢，而是错误被放大：一个错误的音色、空字幕、缺字的字体或不合规的竖屏尺寸，可能同时影响所有视频。
所以 recut skill 把质量检查放进正式流程，而不是等全部渲染完再人工发现问题。
依赖先检查Node、Python、FFmpeg、ffprobe、中文字体、下层 skill 和渲染器都在构建前验证。
时长先检查旁白生成后读取真实时长；快速版、标准版、深入版分别有可接受区间。
项目先检查每条短视频都有独立项目、独立媒体资产和构建记录，可以单独复现。
成片再检查确认 1440×2560、30fps、存在音频流、文件非空，并检查字幕位置与文字对比度。
如果旁白实际时长不合适，正确做法不是直接拉长或压缩音频，而是把它作为改稿信号：信息不足就补充，表达冗余就压缩，然后重新生成旁白和字幕。
7. 拿到这份报告后，如何复刻一套自己的 Skill
复刻的目标不是复制某个视频文件或某个 API，而是复刻这条生产线：让一个上层编排 skill，稳定地调用旁白、字幕、媒体处理和渲染能力，并且在每一步留下可验证的结果。
7.1 先搭出三个 skill，而不是一个万能目录
your-video-recut-bundle/
├── source-video-batch-recut/ # 上层编排器
│ ├── SKILL.md # 触发条件、工作流、不可违反的规则
│ ├── scripts/
│ │ ├── doctor.mjs # 依赖与配置检查
│ │ ├── analyze_source.mjs # 源视频信息、抽帧、联系表
│ │ ├── prepare_source_transcript.mjs # 源音频提取和时间转写
│ │ └── create_recut_projects.mjs # 生成项目、切片和渲染
│ └── references/
│ ├── manifest.md # 编辑计划的数据约定
│ └── checklist.md # 交付验收标准
├── tts-generate-audio/ # 基础能力一：文稿 → 音频
│ ├── SKILL.md
│ ├── scripts/generate_tts_audio.py
│ └── assets/default-reference.mp3 # 没有用户音色时的默认参考音色
└── audio-generate-subtitle/ # 基础能力二：音频 → 字幕时间轴
├── SKILL.md
└── scripts/generate_subtitle_from_audio.py
每个 skill 都至少需要一个 SKILL.md。其中的 name 和 description 决定 Codex 何时应该触发它；正文只写执行流程和资源导航。需要稳定重复运行的事情写进 scripts/，详细字段和服务说明放进 references/，默认音色、字体或模板等运行时素材放进 assets/。
7.2 按这个顺序实现，风险最低
1先完成 TTS
输入文稿和参考音色，输出一个本地音频文件、真实时长和不含密钥的 metadata。没有用户音色时，显式选择默认音色。
2再完成字幕
输入音频和可选原稿，输出 SRT 与统一格式的字幕段落。把时间统一为秒级 start、end、text。
3建立源内容地图
用 ffprobe 读媒体信息，用 FFmpeg 抽取画面、提取源音频，再得到源视频的带时间戳转写。
4定义编辑计划
用 manifest 描述每条短视频的文稿、时长、主题和 beat。语义模式下，不允许缺少源画面时间范围。
5生成独立项目
把切出的源画面、新旁白、字幕、字体和可选 BGM 写进每条视频自己的渲染项目，确保可以单独重跑。
6把检查写进流程
先检查依赖、文件、时长和中文字体；再检查渲染项目；最后检查 MP4 尺寸、帧率、音频流和视觉结果。
7.3 四份数据契约决定系统能不能协作
不要让上层编排器去猜下层脚本的日志。每个阶段都应写出一个机器可读的结果文件；下一个阶段只依赖这些稳定字段。
| 阶段产物 | 最小字段与用途 |
|---|
| 源视频分析 | duration、width、height、fps、audioStreams、抽样帧/联系表路径。它决定源素材是否可用。 |
| 时间转写 | [{ start, end, text }]，单位统一为秒。源转写用于理解原视频；新旁白转写用于渲染字幕。 |
| 编辑 manifest | 根级 sourceVideo、workRoot、outputRoot、items；每个 item 至少有 id、文稿或音频、以及 3-8 个 beats。 |
| 构建记录 | 实际旁白、字幕、源片段、时长、模板、输出 MP4 路径。它用于复现、排错和审核成片来源。 |
7.4 必须实现的三个编辑规则
规则一：真实音频决定时长
文稿长度只能估算。旁白生成后必须以音频时长为准，检查它是否落在目标时长区间，再决定是否改稿和重新生成。
规则二：每个 beat 必须有证据画面
每段新旁白都要映射到源视频的 sourceIn 与 sourceOut。没有这个映射时，只能称为蒙太奇，不应声称语义对齐。
规则三：输入资产必须显式选择
音色和 BGM 使用明确文件路径或有序数组；没有音色就使用写明来源的默认音色。不要扫描用户目录后随机挑选文件。
规则四：缓存必须可判定
将文稿、参考音色、语速和输出格式做内容哈希，作为 TTS 缓存键；字幕缓存则基于音频哈希和字幕设置。这样改稿后不会误用旧音频。
7.5 用四次验证证明它值得成为 Skill
验证基础能力单独测试一段文稿能否生成音频；再单独测试该音频能否生成有效 SRT 和 segments。
验证语义映射用一条源视频做一条短视频，人工查看每个 beat 的画面是否支持旁白。
验证可渲染性确认项目能独立通过渲染器检查，字幕、字体、音频与画面在竖屏中不重叠。
验证批量复用换一条源视频、换多条 item 再运行；确认缓存、音色、BGM 和输出目录不会串用。
只有在这四次验证之后，才应该把流程写进正式的 SKILL.md。否则它更像一次性的脚本，而不是一个可交付、可扩展的 Codex skill。
8. 报告中应如何准确描述实现事实
案例故事可以讲“从两个能力到七条短视频”，但技术报告必须区分：哪些是当前本地 skill 已明确实现的事实，哪些是你们自己的实验结果或服务端实现。
| 表述 | 报告中的推荐写法 |
|---|
| 基础语音与字幕服务 | 当前本地 skill 明确调用 SciTiger 的异步 TTS 与字幕 API。若服务端实际接入阿里云 CosyVoice 或 ASR，应作为你们服务实现的补充说明，并以服务端证据为准。 |
| 默认音色 | 正确。若用户未提供参考音色，TTS skill 会使用 bundle 内携带的默认参考音频，避免任务因缺少音色而中断。 |
| 长视频拆成 7 条 | 可以作为本次案例成果展示；建议同时展示真实文件列表、时长或成片缩略图。其他案例应使用其实际输出数量。 |
| 横版到竖屏的验证 | 可以作为能力演化过程描述。当前 recut skill 的目标输出是 1440×2560 的竖屏 HyperFrames 视频。 |
| 渲染器 | 当前这条实现路径使用 FFmpeg 处理源画面，使用 HyperFrames 生成项目并渲染。Remotion 可以是替代选择，但不应写成当前路径的执行组件。 |
这套实现的安全边界
源视频音频会被发送到外部服务用于转写；新旁白文本和参考音色也会被发送用于生成。因此最终视频虽然在本地渲染，整个流程并不是纯离线流程。
API key、签名下载链接、私人音色、源视频、源转写和成片都不应被放进 skill 包或提交到仓库。源视频、音色和 BGM 的使用权也必须由使用者自行确认。
9. 结论：Skill 的价值是把一次成功变成下一次的起点
这套工作流最值得复用的，不是某个特定 TTS 服务、某套竖屏模板，甚至也不只是把视频拆成几段。真正可复用的是它的构建方式：先拆出基础能力，在真实任务中验证，再把经过验证的判断、步骤和质量门槛沉淀为一个可调用的 skill。
下一次只要提供新的源视频和目标，就不需要从零开始思考“先做什么、如何对齐、如何验收”。这就是从一次剪辑实验，走向可重复视频生产能力的过程。