edit-video

编辑视频

分三个阶段进行对话式视频编辑：转录、规划剪辑、渲染。

前提条件

• bun — TypeScript 运行时
• ffmpeg / ffprobe — 视频处理工具（必须位于 PATH 中）

环境变量（可选，均有默认值）：

变量	用途	默认值
AUDETIC_API_URL	Audetic 转录服务 URL	https://audio.audetic.link

命令

所有路径均相对于此技能目录。使用 bun run 运行。

命令	用途
scripts/transcribe.ts <video>	转录单个视频文件——在文件旁生成 JSON、Markdown 转录文本和分析文件
scripts/transcribe.ts <directory>	转录目录中的所有视频文件——在目录中生成合并后的 JSON、Markdown 转录文本和分析文件
scripts/preview.ts <edl.json>	在渲染前验证并预览 EDL
scripts/render.ts <edl.json>	使用 ffmpeg 流复制从 EDL 渲染最终视频
scripts/adjust.ts <edl.json> --segment N --start/--end <value>	调整现有 EDL 中的时间戳或移除片段
scripts/caption.ts <video> <transcript.json>	在视频中烧录 Shorts 风格字幕（可选参数 --edl、--output）

工作流——单个文件

1. 转录

bun run scripts/transcribe.ts <video-file>

将音频压缩为 MP3，上传到 audetic 转录服务，并在视频旁生成三个文件：

• .json — 转录结果（供工具使用）
• -transcript.md — 易读的转录文本表格
• -analysis.md — 带有信号标记的转录文本（间隔、语速）

2. 规划剪辑

阅读转录文本和分析文件。分析文件提供机械性信号：

标记	含义
gap:Xs	此片段前有 X 秒静音
slow	每秒少于 0.5 个词（打字、长时间停顿、空白片段）
silence	片段中未检测到任何词语
WPS 列	每秒词数（数值越高，语音越密集）

有关信号的详细指南，请参阅 references/signal-interpretation.md。

结合这些信号和你对内容的理解，决定保留或剪掉哪些部分。工具会检测静音和语速；哪些内容是填充、哪些有实质意义，由你判断。

确定剪辑方案后，编写 EDL（剪辑决策列表）JSON 文件：

{
  "output": "/absolute/path/to/output.mp4",
  "segments": [
    { "source": "/absolute/path/to/video.mp4", "start": "00:00:00.000", "end": "00:02:15.500", "label": "Introduction" },
    { "source": "/absolute/path/to/video.mp4", "start": "00:05:30.000", "end": "00:12:45.200", "label": "Main discussion" }
  ]
}

• 每个片段都必须包含 source 字段，值为其源视频的绝对路径
• 时间戳必须采用 HH:MM:SS.mmm 格式（ffmpeg 原生格式）
• 片段按播放顺序排列——重新排列片段会改变输出顺序
• label 为可选字段，用于说明每个片段的内容
• 只有包含的片段会出现在输出中；其余内容都会被剪掉

完整的架构说明请参阅 references/edl-schema.md。

3. 预览

bun run scripts/preview.ts <edl.json>

渲染前务必先预览。预览会显示片段明细、保留／剪掉的百分比，并验证 EDL。

3a. 调整（迭代编辑）

预览后，使用 adjust.ts 针对性微调，无需重写 EDL：

# Trim 0.5s off the end of segment 1
bun run scripts/adjust.ts <edl.json> --segment 1 --end -0.5s

# Move the start of segment 2 earlier by 1 second
bun run scripts/adjust.ts <edl.json> --segment 2 --start -1s

# Extend the end of segment 3 by 2 seconds
bun run scripts/adjust.ts <edl.json> --segment 3 --end +2s

# Set end of segment 1 to an exact timestamp
bun run scripts/adjust.ts <edl.json> --segment 1 --end 00:05:30.000

# Remove segment 2 entirely
bun run scripts/adjust.ts <edl.json> --remove 2

片段编号从 1 开始，与预览输出一致。相对增量使用 +Xs／-Xs（支持小数）。绝对值使用 HH:MM:SS.mmm 格式。工具会验证结果并输出更新后的摘要。

根据需要重复预览和调整，直到剪辑效果合适，然后进行渲染。

4. 渲染

bun run scripts/render.ts <edl.json>

使用 ffmpeg 流复制（速度快，在最近的关键帧处剪切）。生成最终视频。

5. 添加字幕（可选）

bun run scripts/caption.ts <edited-video.mp4> <transcript.json> --edl <edl.json>

在视频中烧录加粗、居中的字幕（Hormozi 风格）。使用 --edl 将转录时间映射到剪辑后的视频时间轴。需要完整重新编码。

有关默认样式和自定义选项，请参阅 references/caption-style.md。

工作流——多个片段（目录）

当用户有多个需要剪辑成单个视频的短片段时，请使用此工作流。

1. 转录所有片段

bun run scripts/transcribe.ts <directory>

查找所有视频文件（*.mp4、*.mkv、*.mov、*.webm、*.ts），逐个转录，并在该目录中生成合并后的输出：

• transcript.json — 合并后的转录稿，每个片段都包含 source 字段
• transcript.md — 合并后的易读表格，包含 Source 列
• analysis.md — 合并后的分析，包含 Source 列（在片段边界处重置间隔检测）

2. 规划剪辑

流程与单文件模式相同，但转录稿和分析会包含 Source 列，显示每个片段来自哪个视频。编写 EDL，并为每个片段填写 source 路径：

{
  "output": "/absolute/path/to/combined.mp4",
  "segments": [
    { "source": "/absolute/path/to/clip001.mp4", "start": "00:00:02.000", "end": "00:00:12.000", "label": "Opening" },
    { "source": "/absolute/path/to/clip003.mp4", "start": "00:00:00.000", "end": "00:00:08.500", "label": "Key moment" },
    { "source": "/absolute/path/to/clip007.mp4", "start": "00:00:01.000", "end": "00:00:14.000", "label": "Closing" }
  ]
}

3. 预览 + 渲染

流程与单文件工作流相同。预览会列出所有来源及其时长，并显示每个片段的来源文件名。

4. 添加字幕（可选）

流程与单文件模式相同 — 对渲染后的输出运行 caption.ts，并添加 --edl。

叙事剪辑

当用户提出的目标超出“剪掉填充部分”时，使用叙事剪辑 — 例如主题、基调、目标时长或受众。

完整的剪辑模式目录请参阅 references/narrative-patterns.md。

思考过程：

1. 阅读转录稿和分析。识别不同的时刻 / 内容节拍。
2. 确定哪些时刻符合用户指定的叙事目标。
3. 确定最佳顺序 — 按时间顺序排列是一种选择，但也可考虑：先抛出钩子、逐步升级、提问与回答、首尾呼应。
4. 为每个片段标注其叙事作用。
5. 汇总片段时长，确认是否符合目标。

将标签用作叙事作用： 使用 label 字段记录功能（例如 "HOOK: the punchline"、"SETUP: context"、"PAYOFF: resolution"）。

叙事备注： 使用 EDL 中可选的 narrative_notes 字段记录剪辑思路。

示例：

{
  "output": "/path/to/output.mp4",
  "narrative_notes": "Goal: 60s punchy clip. Led with the reaction for hook, then backed into the setup.",
  "segments": [
    { "source": "/path/to/video.mp4", "start": "00:05:30.000", "end": "00:05:55.000", "label": "HOOK: surprised reaction" },
    { "source": "/path/to/video.mp4", "start": "00:01:00.000", "end": "00:02:15.500", "label": "SETUP: reading the tweet" },
    { "source": "/path/to/video.mp4", "start": "00:06:00.000", "end": "00:06:30.000", "label": "PAYOFF: final take" }
  ]
}

输出文件命名

单文件模式

scripts/lib/config.ts 中的 outputPaths 函数会根据视频路径生成标准输出路径：

输出	模式
转录稿 JSON	<name>.json
转录稿 MD	<name>-transcript.md
分析 MD	<name>-analysis.md
EDL	<name>-edl.json
剪辑后的视频	<name>-edited.mp4
添加字幕后的视频	<name>-captioned.mp4

目录模式

directoryOutputPaths 函数会在目录内生成输出路径：

输出	模式
转录稿 JSON	transcript.json
转录稿 MD	transcript.md
分析 MD	analysis.md

会话流程

单个文件

1. 用户提供视频文件路径
2. 对该文件运行 transcribe.ts
3. 阅读 -analysis.md 和 -transcript.md 文件
4. 与用户讨论保留/剪掉哪些内容（或接受叙事目标）
5. 编写 EDL JSON 文件（每个片段的 source 都指向该视频）
6. 运行 preview.ts 进行验证 — 与用户一起检查 6a. 如果需要调整，运行 adjust.ts 进行针对性微调（根据需要重复预览和调整）
7. 运行 render.ts 生成最终视频
8. （可选）如果用户想要 Shorts 风格字幕，运行 caption.ts 并添加 --edl
9. 告知输出路径和最终时长

多个片段

1. 用户提供包含多个片段的目录
2. 对该目录运行 transcribe.ts
3. 阅读目录中的合并版 analysis.md 和 transcript.md
4. 与用户讨论要包含哪些片段/内容段
5. 编写 EDL JSON 文件（每个片段的 source 都指向对应视频）
6. 运行 preview.ts 进行验证 — 与用户一起检查 6a. 如果需要调整，运行 adjust.ts 进行针对性微调（根据需要重复预览和调整）
7. 运行 render.ts 生成合并后的视频
8. （可选）如果用户想要 Shorts 风格字幕，运行 caption.ts 并添加 --edl
9. 告知输出路径和最终时长

提示

• 关键帧精度不足：流复制会在最近的关键帧处剪切，因此剪切位置最多可能偏差约 0.5 秒。这样做的代价是无需重新编码即可快速渲染。
• 较长视频：转录所需时间随视频时长增加。对于超过 30 分钟的视频，请提醒用户可能需要等待一段时间。
• 务必先预览：未经预览，切勿渲染。预览可以发现验证错误，并让用户在确认后再提交。
• 时长目标：给定目标时长时，将分析结果中所选片段的 Dur 列数值相加。反复调整，直到 EDL 符合要求。
• 重新解读信号：间隙不只是剪切候选点，也标记着主题边界。片段节奏缓慢不一定乏味——顿悟前的停顿也可能很有戏剧性。
• 混合编解码器：合并来自不同来源的片段时，预览工具会针对混合文件扩展名发出警告。来自同一设备或应用的片段通常没有问题。
• 字幕重新编码：烧录字幕需要对视频进行完整编码（而非流复制），因此耗时比渲染更长。开始前请告知用户这一点。
• 迭代调整：创建初始 EDL 后，使用 adjust.ts 微调片段，例如裁剪或延长。它会处理时间戳运算，因此小幅调整时无需重写 EDL。
• 主动提供字幕：当用户提到 Shorts、Reels、TikTok 或短视频内容时，可在渲染后主动提供添加 Shorts 风格字幕的选项。