Unicom Video Cut

Unicom-video-cut

本技能定义了一套基于词级转录的短视频剪辑流程，强调音频驱动与后期字幕、叠加、调色的安全执行。

原则

1. 音频为主，视觉为辅。 使用语音识别模型对原始视频中的音频进行识别，形成转录文本，剪切候选点来自语音边界和静音间隙。仅在决策点深入查看视觉信息。
2. LLM根据原始转录文本和用户指引进行推理。 LLM只处理打包的短语级转录文件（takes_packed.md）。其他一切 —— 填充词标记、重拍检测、镜头分类、强调评分 —— 都在决策时动态推导。
3. 提问 → 确认 → 执行 → 迭代 → 持久化。 在用户用自然语言确认策略之前，绝不要开始剪辑。不要进行任何假设和猜测，观察素材，询问用户，然后剪辑。
4. 这份文档里给出的具体数值、预设、字体、颜色、时长、表达方式和方法，都只是一个成功案例中的“参考样式”。它们不是你必须照搬的规则，而是让你知道有哪些做法可行、为什么当时这么做有效。你应该根据实际素材和用户的真实需求，自行判断和选择最合适的表现方式。你必须遵守的只有下方「硬性规则」部分的内容。 其他都是你的自由。
5. 可以创造性地使用剪辑手法。 如果需要分屏、画中画、反应镜头、变速、交叉溶解等，就用合适的手段完成它。
6. 在展示给用户之前验证自己的输出。 观看每个切点附近的预览，检查爆音、视觉不连续、字幕被遮挡、叠加层错位。抽样检查调色一致性、字幕可读性、整体连贯性。最多 3 轮自评。自评通过后才呈现预览。

硬性规则（生产级正确性 —— 不可协商）

以下原则是保证视频正确定的硬性要求，如果出错可能会导致视频剪辑失败或输出损坏的事项，请务必严格遵守。

1. 字幕在滤镜链中最后应用，在所有叠加层之后再烧录字幕，否则叠加层会遮挡字幕。
2. 分段提取 → 再用 -c copy进行无损拼接，而不是一条命令一次性处理。否则每个片段都会被重复编码两次，白白浪费时间又损失画质。
3. 每个分段边界 30ms 音频淡入淡出。否则每个切点都有可听见的爆音。
4. 最终字幕文件要按输出时间轴重新计算时间戳：计算方法 output_time = word.start - segment_start + segment_offset，否则拼接后字幕会错位。
5. 永远不要在一个词中间剪切。 绝对不要把一个词切成两半。每个切点都要对齐到单词的边界（从字幕文稿中获取），确保切在词与词之间。
6. 每个切边留有填充。 每个切点都要加一点缓冲时间（30200毫秒）。因为字幕时间戳有误差（会漂移 50100毫秒），缓冲能吸收这个误差。节奏快的视频用小缓冲，节奏慢的电影用大缓冲。
7. 仅使用词级逐字 ASR。 只用逐字级别的、原样记录的语音识别。不要用"字幕/短语模式"（会丢失毫秒级的间隙信息）。不要用"规范化处理"（会把"嗯、啊、呃"这些语气词删掉或改写，丢失编辑线索）。
8. 每个源缓存转录。 源文件本身未变则永远不重新转录。
9. 执行前确认策略。 执行前先确认方案。在用户批准之前，绝对不要动视频
10. 所有会话输出放在 <videos_dir>/edit/。 永远不要写入技能目录内。
11. 优先使用工具和辅助脚本，而不是手写 ffmpeg 命令。辅助脚本封装了正确的参数和流程，能避免常见错误。只有当你完全理解它们的工作原理，并且需要做一些特殊处理时，才直接使用 ffmpeg。

这份文档剩下的部分都是示例演示。当实际情况需要时，可以灵活变通，不必死守规则。

目录结构

技能位于 unicom-video-cut/。用户素材放在他们指定的位置。所有会话输出放入 <videos_dir>/edit/。

<videos_dir>/
├── <源文件，保持不变>
└── edit/
    ├── project.md               ← 记忆；每个会话追加
    ├── takes_packed.md          ← 短语级转录，LLM 的主要阅读视图
    ├── edl.json                 ← 剪辑决策
    ├── transcripts/<name>.json  ← 缓存的原始转录 JSON
    ├── clips/                   ← 提取的片段
    ├── base.mp4                 ← 合并后的基础视频
    ├── master.srt               ← 输出时间线字幕
    ├── verify/                  ← 调试帧 / 时间线 PNG
    ├── preview.mp4
    └── final.mp4

环境要求

首次使用时，分别检查mediaclaw插件和FFmpeg工具是否可用：

• 若mediaclaw插件不可用，则提示用户缺少依赖，无法生成数字人视频，请用户修复后重新进行
• 若FFmpeg工具不可用，则按照同级目录下的 references/install-ffmpeg.md中的安装步骤引导用户进行安装，并检查是否可用，安装完成后提示用户已经完成安装
• Node.js + npm 可用（HyperFrames 需要 Node.js 22+）

辅助脚本（helpers/*.py）与此 SKILL.md 同目录。相对于此目录解析路径。

所需工具

本技能主要依赖以下 mediaclaw 工具：

• mediaclaw_speech_recognition：本地音/视频转录为词级 JSON，结果写入 <videos_dir>/edit/transcripts/。
• mediaclaw_build_srt：转录 JSON 生成 SRT，支持时间范围和偏移。
• mediaclaw_merge_srt：合并多个 SRT 并应用偏移。
• mediaclaw_burn_subtitles：将 SRT/ASS/SSA 字幕烧录入视频，force_style 可覆盖样式。
• mediaclaw_normalize_audio：响度标准化；支持 auto / single / measure。
• mediaclaw_apply_grade：视频调色，支持预设和原始 ffmpeg 滤镜。
• mediaclaw_apply_overlay：视频叠加，支持位置、坐标、透明度、缩放和时长。

所有本地脚本都在本目录的 helpers/ 下，相对路径解析基于本文件所在目录。

辅助脚本

常用脚本：

• helpers/extract_clip.py：提取分段片段，支持调色、淡入淡出、HDR 检测。
• helpers/concat_videos.py：无损合并片段，或在必要时用 filter 模式处理格式差异。
• helpers/pack_transcripts.py：把 transcripts/*.json 打包成 takes_packed.md。
• helpers/timeline_view.py：生成片段的视觉/音频预览图，用于决策点检查。

工作流程

阶段 1：盘点

# 1. 检查源视频
ffprobe input.mp4

# 2. 转录
mediaclaw_speech_recognition --file input.mp4

# 3. 打包转录
python helpers/pack_transcripts.py --edit-dir edit/

# 4. 视觉抽样
python helpers/timeline_view.py input.mp4 0.0 5.0

阶段 2：预扫描问题

快速浏览 takes_packed.md，注意口语错误、明显的口误或需要避免的表达。简单列表，注入编辑简报。

阶段 3：对话

描述素材，收集需求，提出策略，等待确认。

收集：内容类型、目标时长/画幅、审美/品牌方向、节奏感、必须保留的时刻、必须剪掉的时刻、调色偏好、字幕需求。

阶段 4：执行

按 EDL 分步渲染：

# 步骤 1：提取每个片段
python helpers/extract_clip.py source.mp4 clip.mp4 --start 10.5 --end 25.3 --grade warm_cinematic --auto-hdr

# 步骤 2：合并片段
python helpers/concat_videos.py base.mp4 clip*.mp4

# 步骤 3：生成字幕
mediaclaw_build_srt --transcript_path edit/transcripts/main.json --output_path edit/master.srt

# 步骤 4：应用叠加层
mediaclaw_apply_overlay --video_path base.mp4 --output_path with_overlay.mp4

# 步骤 5：烧录字幕
mediaclaw_burn_subtitles --video_path with_overlay.mp4 --subtitle_path master.srt --output_path with_subs.mp4

# 步骤 6：标准化音频
mediaclaw_normalize_audio --input_path with_subs.mp4 --output_path final.mp4

阶段 5：预览

使用 --preview 或 --draft 快速生成预览。

阶段 6：自评

用 timeline_view.py 检查每个切点（±1.5s 窗口）：

• 视觉不连续/闪烁/跳帧
• 音频爆音
• 字幕被遮挡
• 叠加层错位

同时抽样：开头 2s、结尾 2s、2–3 个中间点 —— 检查调色一致性、字幕可读性、整体连贯性。

如有失败：修复 → 重新渲染 → 重新评估。最多 3 轮自评。自评通过后才呈现预览。

阶段 7：迭代 + 持久化

自然语言反馈，重新规划，重新渲染。永不重新转录。确认后最终渲染。追加到 project.md。

剪辑技巧

• 音频优先。 候选切点来自词边界和静音间隙。
• 保留峰值。 笑声、妙语、重音节拍。延伸过妙语以包含反应 —— 笑声本身就是节拍。
• 说话人交接 在话语之间留有空间效果更好。常见值：400–600ms。快节奏用更小值，电影感用更大值。
• 音频事件作为信号。 （笑声）、（叹气）、（掌声） 标记节拍。延伸过去。
• 静音间隙是切点候选。 ≥400ms 的静音通常最干净。150–400ms 短语边界可用，需视觉检查。<150ms 不安全（短语中间）。
• 切点填充： 第一个保留词前 50ms，最后一个保留词后 80ms。混剪能量感用更紧的值，纪录片用更松的值。保持在 30–200ms 工作窗口内。
• 永远不要独立推理音频和视频。 每个切点必须两轨都合适。

打包转录

pack_transcripts.py 将 transcripts/*.json 合并为 takes_packed.md，按短语和静音分块。这是编辑决策的主读取视图。

剪辑决策

多镜头任务时：

• 先看 takes_packed.md，再总结素材、目标时长、节奏和关键保留点。
• 优先选择 ≥400ms 静音作为切点。无更好选项时保留可接受的口误。
• 所有时间必须对齐到词边界，且每个边缘补 30–200ms 缓冲。

调色

调色要“看一帧、改一点、再看”，不要只靠预设。常用预设：

• warm_cinematic：轻微青橙、低饱和。
• neutral_punch：最小对比、自然。
• subtle：几乎不动。
• none：直接复制。

硬性规则：调色优先在分段提取时应用，不要后期重复编码。

字幕

要同时考虑：分块方式、大小写、底部位置。经典组合：

• 快节奏短视频：2 词分块、大写、白字描边。
• 叙事/教育：句子大小写、自然断句、稍大底边距。

字幕必须最后烧录，并按输出时间轴偏移。

输出规格

默认匹配源，常见目标：1920×1080@24、1920×1080@30、1080×1920@30、3840×2160@24、1080×1080@30。

记忆

每次会话在 <edit>/project.md 追加一节，记录策略、决策、理由和待办。

反模式

常见失败做法：

• 先做格式/镜头层级计划，后看素材。
• 用短语级字幕做剪辑。
• 先把字幕烧进基础视频再叠加。
• 一次性把所有覆盖层塞入单个滤镜图。
• 在分段边界硬切。
• 文本对齐按部分字符串宽度。
• 先剪再确认策略。
• 重复转录已缓存文件。