# Unicom Video Cut

> Unicom-video-cut

- Skill: `unicomai/unicom-video-cut` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add unicomai/unicom-video-cut`
- Raw SKILL.md: https://api.skillmd.com/api/skills/unicomai/unicom-video-cut/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: UnicomAI (https://skillmd.com/u/unicomai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/unicomai/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. **每个切边留有填充。** 每个切点都要加一点缓冲时间（30~200毫秒）。因为字幕时间戳有误差（会漂移 50~100毫秒），缓冲能吸收这个误差。节奏快的视频用小缓冲，节奏慢的电影用大缓冲。
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](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：盘点

```bash
# 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 分步渲染：

```bash
# 步骤 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` 追加一节，记录策略、决策、理由和待办。

## 反模式

常见失败做法：

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