视频转写

视频转写工具

适用/能力

• 转写出文档：抓取字幕或音频转写 → 输出 Markdown 文档（有字幕优先）。
• 翻译视频：转写 → 翻译 → 烧录中文字幕 → 输出带字幕的视频文件。
• 支持精确模式（默认，large-v3-turbo，95% 精度）和快速模式（medium，90% 精度，快 81%）。
• 双版本输出：中文内容生成中文版，非中文内容生成原文版 + 中文翻译版。

意图识别（必须严格遵守）

• 用户说"转写""转文字""出文档" → 只生成 Markdown 文档
• 用户说"翻译""翻译视频""配字幕""加字幕" → 必须执行完整的翻译视频管线（提取音频 → Whisper 生成 SRT → 调用 subtitle-polish 翻译 → 烧录字幕到视频 → 同时生成 Markdown 文档），不能只输出文档就结束
• 输入是 URL → 先下载再处理
• 输入是本地文件路径 → 直接处理

字幕类型（翻译管线必须先确认）

• 中文字幕：只显示中文翻译
• 中英双语字幕：中文在上，英文在下

翻译视频时，除非用户在对话中明确指定了字幕类型（说了"中文""双语""中英"等），否则必须用 AskUserQuestion 弹选项让用户选择。 ARGUMENTS 里的字幕类型不算用户指定。示例：

AskUserQuestion(
  question="选择字幕类型",
  options=["中文字幕（只显示中文）", "中英双语字幕（中文在上，英文在下）"]
)

双语字幕 SRT 格式（每条两行）：

1
00:00:03,660 --> 00:00:06,360
中文翻译在上面
English original below

双语烧录走 ASS，不走 subtitles + force_style（中文大 / 英文小，形成反差）：

• subtitle-polish 翻译产出「双语 SRT」（中文在上、英文在下，时间戳一句对一句）后，调脚本转双语 ASS：

  python3 ~/.claude/skills/xiaohu-subtitle-polish/scripts/bilingual_ass.py \
    <双语SRT> --output <双语ASS> [--cn-size N] [--height 视频高度]
  

• 再用 ass=<双语ASS> 滤镜烧录（不是 subtitles=）。完整规则见 xiaohu-subtitle-polish SKILL.md「双语字幕模式」段。
• 字号：用户给了中文字号就传 --cn-size，英文自动按 中文 / 1.7 算；没给则脚本按分辨率选默认。中文︰英文 ≈ 1.7 是实测干净反差。

⛔ 为什么不用 subtitles force_style 做双语：force_style 的 FontSize 对整条统一，做不到一条内中文大英文小；SRT 里的 inline {\fsN} 会被 ffmpeg 剥离（2026-05-31 实测三档字号 md5 全同）。只有 ASS 喂 libass 才能一条内分字号。 ⛔ ASS FontSize 是相对值不是像素：libass 已按视频分辨率自动缩放，不要按分辨率线性放大（1080p 的 17 乘 2 变 34 会让 4K 字幕占满下半屏）。2026-05-26 Jony Ive 法拉利视频踩坑根治。

强制规则（先读配置再执行）

• 执行任何命令/写入任何文件前，必须先读取本技能目录 config.json，取 output_dir 作为 <输出根>（支持 ~ 展开）。
• 文档中的所有 <输出根>/... 在执行前必须替换为真实绝对路径；禁止把 <输出根> 原样带到命令里执行（否则会写到当前目录，表现为“乱保存”）。
• 若 config.json 缺失、output_dir 为空/相对路径/不可写：立即停止并提示用户在网页面板填写，或用 --outdir <绝对路径> 覆盖。
• 只有当用户明确给出“绝对路径输出位置”并确认时，才允许写入用户指定路径；否则默认只写 <输出根>/tmp/ 与 <输出根>/data/。

建议的“输出根解析”固定前置步骤（避免手打长路径导致误写目录）：

# 在本技能目录执行
OUTPUT_ROOT="$(python3 - <<'PY'
import json, os
from pathlib import Path

cfg = json.load(open("config.json", "r", encoding="utf-8"))
out = Path(os.path.expanduser(str(cfg.get("output_dir", ""))).strip())
if not out.is_absolute():
    raise SystemExit("config.json: output_dir 必须是绝对路径或以 ~ 开头")
print(str(out))
PY
)"
mkdir -p "$OUTPUT_ROOT/tmp" "$OUTPUT_ROOT/data"
echo "OUTPUT_ROOT=$OUTPUT_ROOT"

后续所有命令都必须使用 $OUTPUT_ROOT/...，不要在命令里手写/粘贴完整长路径。

通用配置

路径说明：

• 脚本目录：scripts/
• 输出根需显式配置：在本技能目录下 config.json 设置 output_dir=<绝对路径>，或调用时用 --outdir <绝对路径>（命令行优先）。必须是绝对路径；output_dir 为空/缺失/相对路径时，脚本会强制提示用户输入绝对路径并写回 config.json，不会默认回落技能目录。根目录下自动创建/使用 tmp/（中间产物）和 data/（最终产物）。

转写引擎（默认走脚本，零配置开箱即用）：

• 默认：MLX Whisper / faster-whisper（scripts/transcribe_srt.py）——首次运行自动从 HuggingFace 下载模型，无需手动准备。所有场景一律首选脚本。
• 可选备份：whisper-cli（whisper-cpp）——仅当用户明确指定、或上面两个都装不了时才用。需自行 brew install whisper-cpp 并把 ggml 模型下到 ~/.cache/whisper-cpp/（见 初始化.md）：
  • 精确模式：~/.cache/whisper-cpp/ggml-large-v3-turbo.bin（默认模型）
  • 快速模式：~/.cache/whisper-cpp/ggml-medium.bin（用户没有要求不允许使用此模型）

输出路径选择逻辑

• 步骤0：先解析输出根（命令行 --outdir → config.json），output_dir 缺失/无效时立即提示用户输入绝对路径并写回 config.json，未配置不可继续。
• 默认将结果写入 <输出根>/data/，不再询问；用户指令/工作流若明确指定路径，优先使用指定路径（必须是绝对路径）。

转写方案选择逻辑（按场景和时长）

烧字幕场景（需要精确时间戳）

根据音频时长选择方案：

音频时长	方案	原因
<2 分钟	faster-whisper	word-level 精度最高，CPU 几秒完成
≥2 分钟	MLX Whisper	word-level + Metal GPU，速度和精度兼得

faster-whisper 命令（<2分钟短视频）：

python3 scripts/transcribe_srt.py "<输入文件>" --output "<输出文件>.srt"

MLX Whisper 命令（≥2分钟，翻译管线默认）— 一律走脚本，不在对话里现写 Python：

python3 scripts/transcribe_srt.py "<输入文件>" --output "<输出文件>.srt"
# 语种误判时加 --language en

脚本默认按 Whisper segment 边界切（不是按字符 greedy 切），下游字幕不会出现夹生帧。

禁止在烧字幕场景使用 whisper-cli：没有 word-level timestamps，字幕会明显不同步。

只出文档场景（不需要精确时间戳）

默认同样走脚本（自动下模型、零配置），转写后从 SRT 取纯文本（去掉序号和时间戳行）即可：

python3 scripts/transcribe_srt.py "<输入文件>" --output "<输出文件>.srt"

可选备份：若已装 whisper-cpp 且想要最快的纯文本输出，可用 whisper-cli（需自备 ggml 模型，见上方「转写引擎」）：

whisper-cli -m ~/.cache/whisper-cpp/ggml-large-v3-turbo.bin -t 8 <输入文件> -otxt
# 快速模式（用户说"快速"/"快"）：把模型换成 ggml-medium.bin

长视频特殊处理（>10分钟）

• 字幕翻译必须分段并行：每段约 500 条，用并行 Agent 翻译，翻译完合并重新编号
• YouTube 视频下载不要用 --download-sections（会先下完整视频再裁剪，极慢），直接下完整视频后用 ffmpeg -ss 裁剪
• 下载分辨率一步到位选 1080p，优先 AV1 格式（体积最小）

通用 Markdown 生成规则（适用于所有场景）

• 读取指定文本（清洗后的字幕 cleaned.txt 或 Whisper 输出 txt），严禁增删改原文，只做标点、合句、分段。
• 判定语言：
  • 中文：合并短句、规范标点、按语义分段，输出 1 个文件：<输出根>/data/<视频标题>-中文.md。
  • 非中文：先按原文语言生成 <输出根>/data/<视频标题>-原文.md（同样不得增删改），再按 非中文翻译规则.md 翻译该原文生成 <输出根>/data/<视频标题>-中文.md。
• 元信息 front matter：title、source_url。
• 必须覆盖全部文本内容，不得遗漏。

使用指导

抓取字幕（仅限出文档场景）

使用场景：只出文档时，视频有字幕则优先抓取字幕（比 Whisper 快）。 ⛔ 烧字幕场景禁止使用本流程：YouTube 自动字幕是滚动叠加格式，无法提取干净的逐句文本+精确时间戳。烧字幕必须走"翻译视频管线"用 Whisper 转写。

处理流程：

1. 先确保输出根有效（步骤0 已完成）。

2. 仅抓字幕（不下载视频）：

# 下载 .vtt 字幕（最快）
yt-dlp --skip-download --write-subs --write-auto-subs \
  --sub-lang "zh-Hans,zh-CN,en" \
  -o "<输出根>/tmp/%(id)s.%(ext)s" \
  "<视频URL>"

• 优先下载 .vtt 格式（最快，无需转换）。
• 兜底机制：如果字幕下载失败，自动切换到"无字幕兜底（音频转写）"流程
• YouTube 若缺字幕/需 PO token：推荐直接用脚本自动重试并从浏览器读取 cookies：

python3 scripts/youtube_subs_download.py "<视频URL>"

• 首次尝试无 cookies（更快）；失败后自动 --cookies-from-browser chrome 重试。
• 常用浏览器非 Chrome：python3 scripts/youtube_subs_download.py --browser firefox "<视频URL>"
• 仍失败（PO token / 更强风控）：再提示用户提供 --extractor-args "youtube:po_token=..." 或切换代理后重试。

2. 使用脚本清洗字幕（减少 50% tokens 消耗）：

# 清洗 vtt/srt → 纯文本（每行一句）
# <id>.zh-Hans.vtt 为 yt-dlp 实际输出的字幕文件名（语言代码可能是 zh-Hans、zh-CN 等）
scripts/vtt_to_text.sh "<输出根>/tmp/<id>.<语言代码>.vtt" > "<输出根>/tmp/cleaned.txt"

3. AI 读取清洗后的文本并生成 Markdown：

• 读取 <输出根>/tmp/cleaned.txt 全部内容，按“通用 Markdown 生成规则”产出。

无字幕兜底（音频转写）

使用场景：当视频没有字幕时，自动提取音频并用 Whisper 转写。

处理流程：

1. 提取音频（截断标题并去符号，文件名更短）：

yt-dlp -x --audio-format mp3 --embed-thumbnail --add-metadata \
  --restrict-filenames \
  -o "<输出根>/tmp/%(title).40s.%(ext)s" \
  "<视频URL>"

• YouTube 若遇 403/SABR：推荐用脚本失败自动读取浏览器 cookies 重试：

python3 scripts/youtube_audio_download.py "<视频URL>"

2. Whisper 转写（默认走脚本，自动下模型；不指定语言让其自动检测中/英/日等）：

python3 scripts/transcribe_srt.py "<输出根>/tmp/<audio>.mp3" --output "<输出根>/tmp/<audio>.srt"

可选备份：已装 whisper-cpp 时可用 whisper-cli 直接出 txt（需自备 ggml 模型，见上方「转写引擎」）：

whisper-cli -m ~/.cache/whisper-cpp/ggml-large-v3-turbo.bin -t 8 "<输出根>/tmp/<audio>.mp3" -otxt

3. AI 读取转写文本并生成 Markdown：

• 读取 <输出根>/tmp/<audio>.srt（默认脚本路线）或 <audio>.mp3.txt（whisper-cli 路线），去掉序号和时间戳行得到纯文本，按“通用 Markdown 生成规则”产出（<audio> 即视频ID）。

抖音视频处理

重要原则：

• 不要预先检查依赖和登录状态，直接执行主流程
• 遇到错误时再检查，这样可以节省时间并提高效率
• 信任环境配置，假设依赖和登录状态正常
• 输出根目录为必填：需在本技能目录 config.json 设置 output_dir（绝对路径），或调用时使用 --outdir <绝对路径>（命令行优先）。缺失/无效时脚本会提示用户输入绝对路径并写回 config.json。根目录下使用 tmp/、data/。
• 抓取使用可见浏览器（非 headless）以获取 aweme detail，脚本会将链接标准化为 https://www.douyin.com/video/<ID>。

链接格式转换（脚本自动处理）：短链需先跳转取完整 URL；modal_id 取 ID 后拼 /video/ID；标准 /video/<ID> 可直接使用。

处理流程：

1. 下载音频：

python3 scripts/douyin_download.py <抖音视频URL> --audio

输出：<输出根>/tmp/<视频标题>-音频.m4a

2. 转换音频格式：

ffmpeg -i "<输出根>/tmp/<视频标题>-音频.m4a" -acodec libmp3lame -q:a 2 "<输出根>/tmp/<视频标题>-音频.mp3"

3. Whisper 转写（默认走脚本，自动下模型）：

python3 scripts/transcribe_srt.py "<输出根>/tmp/<视频标题>-音频.mp3" --output "<输出根>/tmp/<视频标题>-音频.srt" --language zh

（其他语言可改 --language en/ja/...；可选备份引擎 whisper-cli 见上方「转写引擎」）

4. 生成 Markdown：
   • 读取 <输出根>/tmp/<视频标题>-音频.srt，去掉序号和时间戳行得到纯文本，按“通用 Markdown 生成规则”产出（默认中文）。

错误处理：

• 步骤1失败（下载音频）：
  • 如果报错 ModuleNotFoundError: No module named 'patchright'，读取 抖音初始化.md 安装依赖
  • 如果报错 未检测到浏览器登录状态，运行 python3 scripts/douyin_login.py 进行登录
  • 其他错误 → 读取 抖音初始化.md 查看技术细节和解决方案
• 其他步骤失败 → 读取 抖音初始化.md 查看技术细节和解决方案

翻译视频管线（完整流程）

触发条件：用户说"翻译视频""翻译该视频""配字幕""加字幕"等——最终目标 = 输出一个带中文字幕的视频文件（同时生成 Markdown 文档）。

⛔ 铁律：翻译管线的英文 SRT 只能由 Whisper 转写生成，禁止使用 YouTube 自动字幕（yt-dlp --write-auto-subs）。 原因：YouTube 自动字幕是滚动叠加格式（每条包含前一条文本），无法提取干净逐句文本+精确时间戳，导致烧录后字幕不同步。Whisper word-level timestamps 是唯一可靠的时间源。

输入判断：

• URL → 先用 yt-dlp / douyin_download 下载视频文件到 <输出根>/tmp/（只下视频，不抓字幕）
• 本地文件路径 → 直接使用

管线步骤：

步骤 0：确认字幕类型（⛔ 门控，必须在任何其他步骤之前执行）

用户在对话中明确指定了字幕类型（说了"中文""双语""中英""bilingual"等）→ 按用户指定的类型执行。 其他所有情况 → 必须用 AskUserQuestion 弹选项：

AskUserQuestion(
  question="选择字幕类型",
  options=["中文字幕（只显示中文）", "中英双语字幕（中文在上，英文在下）"]
)

⛔ 禁止绕过：ARGUMENTS 里的字幕类型不算用户指定——只有用户在对话中亲自说的才算。不弹选项就开始步骤1 = 流程错误。config.json 的 subtitle_type 只是默认值，不能替代用户确认。

步骤 1：提取音频

ffmpeg -i "<视频文件>" -vn -acodec libmp3lame -q:a 2 "<输出根>/tmp/<文件名>.mp3"

步骤 2：精确转写生成原文 SRT（按时长选方案）

短视频（<2分钟）→ faster-whisper：

python3 scripts/transcribe_srt.py "<输出根>/tmp/<文件名>.mp3" \
  --output "<输出根>/tmp/<文件名>.srt"

长视频（≥2分钟）→ MLX Whisper（默认，仍走脚本）：

python3 scripts/transcribe_srt.py "<输出根>/tmp/<文件名>.mp3" \
  --output "<输出根>/tmp/<文件名>.srt"

多语言混轨/语种误判 → 加 --language en（强制重转）：

python3 scripts/transcribe_srt.py "<输出根>/tmp/<文件名>.mp3" \
  --output "<输出根>/tmp/<文件名>.srt" \
  --language en

⛔ 任何情况下不要在对话里现写 mlx_whisper Python 代码——脚本已经按 Whisper segment 切（merge_words_to_segments 函数：segment 作基础 / 超 6s 才按词拆 / <500ms 才合并），绕开脚本自己写 MAX_CHARS=50 greedy 会把 A 句尾巴+B 句开头挤进同一帧（2026-05-28 ElevenLabs 踩坑根治）。

脚本特性：

• MLX Whisper Metal GPU 加速，word-level timestamps 精度最高（140 分钟音频约 5-8 分钟完成）
• --language 支持强制语种（en/zh/ja 等），不传则自动检测
• --max-line-ms 控制单条最大时长（默认 6000ms）
• MLX 不可用自动降级 faster-whisper

兜底：若 MLX Whisper 未安装（pip3 install --break-system-packages mlx-whisper），用 faster-whisper。若 faster-whisper 也不可用，最后用 whisper-cli -ml 50（精度最低，仅应急）。

输出：<输出根>/tmp/<文件名>.srt（原文 SRT，word-level 精确时间戳）

步骤 3：调用 xiaohu-subtitle-polish 技能翻译润色

使用 Skill 工具调用，传入原文 SRT 路径：

# 中文单语
/xiaohu-subtitle-polish <输出根>/tmp/<文件名>.srt --output <输出根>/tmp/<文件名>-zh.srt
# 中英双语（步骤 0 用户选了双语时）
/xiaohu-subtitle-polish <输出根>/tmp/<文件名>.srt --output <输出根>/tmp/<文件名>-zh.srt --bilingual

• subtitle-polish 负责全部字幕工作：翻译、去标点、断句（≤18字/行）、时间戳对齐、去冗余、专有名词处理
• 双语模式：subtitle-polish 产出「双语 SRT」（中文在上、英文在下，时间戳一句对一句），具体见其 SKILL.md「双语字幕模式」段
• video-md 不做任何字幕翻译和润色，全部交给 subtitle-polish
• 输出：润色后的中文 SRT（单语）或双语 SRT（双语）

⛔ subtitle-polish Skill 返回后，立即执行步骤 4（烧录）。不输出任何中间报告，不等用户确认。subtitle-polish 有自己的输出报告步骤，在管线中忽略它，直接继续。

步骤 4：烧录字幕 + 水印（默认带水印）

默认行为：从 config.json 的 settings 读取水印配置（watermark_enabled、watermark_text 等）。默认开启水印，用户说"不要水印""去掉水印"时关闭。

字幕 + 水印必须在同一条 ffmpeg 命令中完成（一次编码，避免画质损失）。

双语先转 ASS 再烧：双语模式下，先把双语 SRT 转成双语 ASS（中文大 / 英文小），烧录时用 ass=<双语ASS> 替代下面命令里的 subtitles=<SRT>:force_style=...，其余（水印 drawtext、-c:a aac）不变：

python3 ~/.claude/skills/xiaohu-subtitle-polish/scripts/bilingual_ass.py \
  <输出根>/tmp/<文件名>-zh.srt --output <输出根>/tmp/<文件名>-zh.ass [--cn-size N] [--height 高度]
# 烧录：-vf "ass=<输出根>/tmp/<文件名>-zh.ass,drawtext=...水印..."

中文单语仍按下面的 subtitles= + force_style 烧。

音频编码强制 AAC：yt-dlp 下载的音频经常是 Opus 编码，X/微信等平台不支持。烧录时必须用 -c:a aac -b:a 128k，禁止用 -c:a copy（2026-03-17 踩坑：Opus 音频导致 X 上传失败）。

原视频有硬字幕时的避让：如果原视频底部已有烧录过的字幕（如英文原字幕），新字幕需上移避让，不能遮挡原字幕。按分辨率选参数（详见 xiaohu-subtitle-polish SKILL.md 烧录段）：

• 720p 单行硬字幕：MarginV=42, FontSize=18
• 1080p 单行硬字幕：MarginV=42, FontSize=19
• 1080p 两行硬字幕（动态变行也按此值）：MarginV=60, FontSize=19
• 4K 单行硬字幕：MarginV=42, FontSize=19

⚠️ MarginV 单位不是像素——它相对 ASS 默认 PlayResY=288。在 1080p 视频里 MarginV=N 实际渲染高度 ≈ N × 3.75 px from bottom。所以 MarginV=110 → 412px ≈ 画面正中（不是 110px 距底），别按像素直觉调（2026-05-29 陶哲轩视频踩坑根治：我之前按像素直觉设 110 把中文推到画面正中）。

原英文动态变行（一句 1 行一句 2 行）：用避两行的 MarginV=60，1 行段中文显得稍高一点点是可接受代价（远好过中文挤进 2 行英文中间）。

烧录后必须抽 ≥2 帧验证——选原英文是 1 行的一帧 + 是 2 行的一帧，两帧都不遮挡才算过。只看一帧就交付 = 文档已警告过的踩坑。

无水印烧录（仅用户明确说"不要水印"时）：

ffmpeg -y -i "<视频文件>" \
  -vf "subtitles=<输出根>/tmp/<文件名>-zh.srt:force_style='FontName=PingFang SC,Bold=1,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H40000000,Outline=1,Shadow=0,MarginV=30'" \
  -c:a aac -b:a 128k ~/Downloads/<视频标题>-中文字幕.mp4

带水印烧录（默认）：

macOS drawtext 中文字体问题（重要）： ffmpeg 的 drawtext 滤镜使用 fontconfig 查找字体，但 macOS 的 fontconfig 无法索引苹方，会回退到 Verdana（不支持中文）→ 中文显示为方块。 必须使用 fontfile= 指定字体文件绝对路径，禁止使用 font= 名称查找。 注意：subtitles 滤镜用 CoreText 不受此影响，只有 drawtext 需要 fontfile。 水印字体用圆体（Yuanti SC），比苹方更好看，且 index 0 就是 SC 简体，不会出现方块问题。PingFang.ttc 的 index 0 是 HK 变体，简体字符显示为方块。

# 1. 解析水印中文字体路径（圆体 Yuanti SC，index 0 = SC 简体）
FONT=$(find /System/Library/AssetsV2 -name "Yuanti.ttc" 2>/dev/null | head -1)
[ -z "$FONT" ] && FONT=$(find /System/Library/AssetsV2 -name "PingFang.ttc" 2>/dev/null | head -1)
[ -z "$FONT" ] && FONT="/System/Library/Fonts/STHeiti Medium.ttc"

# 2. 字幕 + 间歇水印一次烧录
# 水印默认参数：透明度 28%、每次 4 秒、0.5 秒渐隐渐出、左上角、出现 3 次
# 时间点均匀分布（示例：8s/38s/72s，根据视频时长调整）
ffmpeg -y -i "<视频文件>" \
  -vf "subtitles=<SRT路径>:force_style='FontName=PingFang SC,Bold=1,FontSize=20,PrimaryColour=&H00FFFFFF,OutlineColour=&H40000000,Outline=1,Shadow=0,MarginV=30',\
drawtext=text='<水印文字>':fontfile=${FONT}:fontsize=44:fontcolor=white:alpha='0.28*min(min((t-T1)/0.5,1),(T1+4-t)/0.5)':x=40:y=35:enable='between(t,T1,T1+4)',\
drawtext=text='<水印文字>':fontfile=${FONT}:fontsize=44:fontcolor=white:alpha='0.28*min(min((t-T2)/0.5,1),(T2+4-t)/0.5)':x=40:y=35:enable='between(t,T2,T2+4)',\
drawtext=text='<水印文字>':fontfile=${FONT}:fontsize=44:fontcolor=white:alpha='0.28*min(min((t-T3)/0.5,1),(T3+4-t)/0.5)':x=40:y=35:enable='between(t,T3,T3+4)'" \
  -c:a aac -b:a 128k ~/Downloads/<视频标题>-中文字幕.mp4

水印参数说明：

参数	默认值	说明
透明度	0.28（28%）	淡而可见，不干扰观看
渐隐渐出	0.5 秒	自然过渡，不突兀
每次持续	见下方规则	按视频时长调整
最少次数	3 次	开头、中间、结尾必须各有一次
位置	左上角 (x=40, y=35)	不遮挡字幕
字号	44	4K 视频下小巧；1080p 可降至 24-28

水印参数从 config.json 的 settings 读取，用户可在配置面板修改。命令行/对话中指定的参数优先于配置文件。

水印次数和持续时间计算规则（按视频时长动态调整）：

视频时长	水印次数	每次持续
<5 分钟	3 次	4 秒
5-30 分钟	3 次	4 秒
30-60 分钟	5 次	5 秒
>60 分钟	每 15 分钟 1 次（最少 5 次）	10 秒

时间点分布规则：

• 第 1 次固定在开头（约 8-15 秒处）
• 最后 1 次固定在结尾前（结尾前 15-30 秒）
• 中间的次数在首尾之间均匀分布
• 例：140 分钟视频 → 9 次（每 15 分钟），T=15s/900s/1800s/2700s/3600s/4500s/5400s/6300s/8400s

输出保存到 ~/Downloads/。

步骤 5：生成 Markdown 文档（与字幕管线并行）

• 同时用 -otxt 模式获取纯文本，或直接读取 SRT 内容
• 按"通用 Markdown 生成规则"生成文档（非中文 → 原文版 + 中文版）

核心原则：

• 字幕翻译润色的所有规则由 xiaohu-subtitle-polish 技能定义和执行，video-md 不重复定义、不自行实现
• video-md 的职责 = 音频提取 + Whisper 转写 + 编排管线 + Markdown 生成
• 这是管线编排（orchestration），不是规则复制（duplication）
• ⛔ 管线不停顿：subtitle-polish 返回后必须直接继续烧录步骤（步骤 4），不得停下来报告中间结果等用户确认。整条管线只在最终产物（视频文件 + Markdown）全部完成后报告一次

Markdown 清洗要点

遵循“通用 Markdown 生成规则”：严禁增删改原文，仅做标点/分段/合并短句，front matter 仅含 title、source_url。

依赖

所需依赖：

• 工具：yt-dlp、ffmpeg；whisper-cpp（可选备份转写引擎，不装也能用）
• Python 包：mlx-whisper（Apple 芯片首选）或 faster-whisper（通用首选）、patchright（抖音视频处理必需）
• 脚本：scripts/transcribe_srt.py、scripts/vtt_to_text.sh、scripts/douyin_login.py、scripts/douyin_download.py
• 模型：mlx-whisper / faster-whisper 首次运行自动从 HuggingFace 下载，无需手动准备；whisper-cpp 备份引擎需自行把 ggml-large-v3-turbo.bin、ggml-medium.bin 下到 ~/.cache/whisper-cpp/

依赖检查原则：

• 直接执行主流程，遇错再查 初始化.md / 抖音初始化.md 补依赖，默认假设环境已装好

当遇到依赖相关错误时：

• 读取相应的初始化文档并按指引自动安装
• 常规初始化：初始化.md
• 抖音初始化：抖音初始化.md
• 安装完成后返回主流程继续执行用户请求

临时文件处理

临时文件位置：<输出根>/tmp/

临时文件类型：

• 字幕文件（.vtt, .srt）
• Whisper 转写输出的文本文件（.mp3.txt）
• 清洗后的字幕文本文件（cleaned.txt，仅字幕抓取时使用）

清理策略：

• AI 处理完成后，可清理临时字幕文件
• Whisper 转写结果文件可保留用于调试
• 用户可随时手动清理 <输出根>/tmp/ 目录
• 重要：最终输出文件（.md）保存在 <输出根>/data/，不受影响

错误处理

常见错误及处理方法：

1. 字幕下载失败：

   • 原因：视频无字幕、地区限制、需要 PO token
   • 处理：提示用户提供 cookies（--cookies-from-browser chrome）或切换代理
   • 兜底：自动切换到音频转写流程

2. Whisper 转写失败：

   • 原因：模型文件缺失、音频格式不支持
   • 处理：检查模型是否已下载，尝试转换音频格式

3. 磁盘空间不足：

   • 原因：临时文件或输出文件占用空间过大
   • 处理：清理 <输出根>/tmp/ 临时文件目录

翻译规则文档

• 非中文内容翻译时，按需读取 非中文翻译规则.md 并遵守其中规则。
• 中文内容严禁使用翻译规则；仅做标点、分段、合并短句，不得增删改原文。