agent-caption：本地离线，任意语言精准字幕

agent-caption — 技能说明

你是一名AI字幕代理。此仓库可为任何视频或音频中的语音和音乐添加准确、完美同步的字幕/副标题，支持任意语言（默认英语），并提供一流的Hinglish / 语码混合支持。支持Windows、macOS和Linux系统。

仓库地址： https://github.com/ahkamboh/agent-caption — 克隆命令：git clone https://github.com/ahkamboh/agent-caption 本文件原始地址（供聊天代理获取）： https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

核心原则：单词来自语音识别，但时间轴来自波形强制对齐——绝不使用原始ASR时间戳。因此，即使转录文本存在拼写错误，字幕也绝不会提前或延迟。

一次性设置（Windows / macOS / Linux）

要求：Python 3.10+、ffmpeg、约4 GB磁盘空间。（torch提供至3.14版本的wheels；如果whisperx在全新的Python版本上缺少对应wheel，请使用3.11–3.12版本。）

python setup.py        # 跨平台：创建 ./.venv-whisperx 并安装所有依赖
# macOS/Linux 便捷方式：bash setup.sh      ·      Windows 便捷方式：setup.bat

ffmpeg：macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg。 模型（Whisper large-v3 — 默认模型 — MMS_FA、whisperX）会在首次运行时自动下载。

最简单的方式——单命令封装（优先使用此方式）

对于“给这个视频加字幕”的请求，只需运行顶层封装脚本。它会完成转录 → 对齐 → 烧录自动比例字幕（针对任意分辨率使用正确的大小、间距和对齐方式），并在用户的ffmpeg不支持字幕相关功能时回退到无libass的渲染器（Pillow + overlay）：

python caption.py <视频>                                  # 英语，简洁，自动比例 -> <视频>.captioned.mp4
python caption.py <视频> --hinglish --style tiktok        # Hinglish + TikTok框
python caption.py <视频> --lang ur --pos center --size 6  # 其他语言/位置/大小
python caption.py <视频> --srt                            # 仅生成.srt文件（不烧录）
python caption.py <视频> --from-srt FILE                  # 烧录现有的.srt，自动比例

15种样式（内置字体）：clean（默认）bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle。仅当你需要原始转录文本、自定义渲染或翻译时，才使用下面的独立脚本。

模型： large-v3 是默认模型（最佳准确率）——无需任何标记；setup.py 会预先获取它。 若想在清晰的英语环境中追求速度，可添加 --fast（使用小模型）。--accurate 仍然存在但现已冗余。 Hinglish路径始终使用large-v3。

**自定义样式——根据用户描述构建任意外观。**将用户的描述映射到以下标记（这些标记会覆盖--style）：

• --font <名称|路径> — 内置字体（Poppins-Bold、Poppins-Black、Anton-Regular、BebasNeue-Regular、ArchivoBlack-Regular）或任意.ttf路径
• --fill #hex（文字颜色）· --outline #hex · --box #hex|#hexAA|none（文字后方背景块）
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N（描边粗细）
• --size <百分比>（高度）· --pos bottom|center|top

示例——用户描述 “热粉色大写字母，深色圆角块内，字体大，使用Anton字体” →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

要将全新的命名样式永久保存，在caption.py的STYLES字典中添加一个条目即可。

准确率——消除误听单词（免费、无需Token、无需人工复核）

强制对齐在构造上使时间轴绝对正确。它唯一无法修正的是单词是否被听对（如“their”/“there”、人名、俚语）。三项免费手段可将此误差降至接近零：

• --glossary "..." — 提供人名/品牌/俚语（可以是列表或.txt路径）。使ASR的初始提示偏向于专有名词，从而避免误听。对名称而言是最高效的单次改进。一次性列表。

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script FILE — 如果已有正确的单词（歌词、剧本），传入此文件。该工具会完全跳过ASR，仅对给定单词进行强制对齐 → 100%内容准确。

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — 对字幕进行离线同音词/语法检查（如“their”→“there”，“your”→“you're”）。本地运行LanguageTool（无需上传、不消耗Token）；绝不修改时间轴。可选依赖——通过 python setup.py --grammar 一次性启用（需要Java/JRE 8+）；若缺失则干净地跳过。

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # 叠加使用
  

性价比排序：--glossary（名称）→ --script（当文本已存在时）→ --grammar（同音词）。 基础模型默认已是large-v3。这些方法唯一无法捕获的残留错误需要人工或LLM来判断——这是唯一值得花费Token的地方，且仅针对标记出的单词，而非整个转录文本。

歌曲——首先分离人声（--content）

对于音乐，在进行ASR之前分离人声音轨可使歌词转录清晰得多（Whisper不再与伴奏音轨对抗）。这是条件性的——对清晰的语音而言既无意义又缓慢——因此通过以下方式控制：

python caption.py song.mp4 --content music                 # 强制人声分离（demucs）
python caption.py clip.mp4                                  # --content auto（默认）：检测到音乐后仅对人声进行分离
python caption.py podcast.mp4 --content speech              # 从不分离（或 --no-isolate）
python caption.py song.mp4 --content music --script lyrics.txt   # 最清晰的歌曲：已知歌词，在人声音轨上对齐时间轴

auto模式会运行快速音乐/语音检测，仅当检测到音乐时才进行分离——因此播客/采访不会被拖慢。烧录始终使用原始视频；只有转录/对齐的部分才是分离后的人音轨。需要demucs（由python setup.py安装）；若缺失则回退到原始音频。

始终使用虚拟环境的Python运行脚本——文中以PY表示：

• macOS / Linux： PY = ./.venv-whisperx/bin/python
• Windows： PY = .venv-whisperx\Scripts\python

脚本

• transcribe.py — Whisper → 单词级转录（默认英语；--lang xx 其他语言）。
• align.py — 强制对齐，获得帧级精准时间轴。--code-switch 用于Hinglish/混合语言。
• cs_transcribe.py — 对语码混合音频进行鲁棒单词识别（按片段进行语言识别）。
• mms_align.py — 通用MMS_FA强制对齐器（1100+种语言，任意书写系统）。
• validate_timing.py — 语码混合路径使用的时间轴合理性检查。
• export-subs.py — 转录文本 → .srt + .vtt。
• multilang-subs.py — 离线将字幕翻译成多种语言。
• grammar_fix.py — 离线同音词/语法修正（.srt文件，保留时间轴）；由--grammar调用。
• isolate_vocals.py — Demucs 歌曲人声分离 + 音乐/语音检测探针；由--content调用。
• qa.py — 快速确定性QA把关（检测字幕基本合理性 + ffprobe输出检查）→ 生成 work/<base>.qa.json。每次烧录后自动运行；--strict 使有问题的输出以非零状态退出。
• footprint.py — 生成 <base>.footprint.svg：一张一目了然的字幕健康图（每个单词按强制对齐置信度着色 + 间隔标记 + 总体结论）。每次加字幕自动运行；--no-footprint 可跳过。
• benchmark.py — 测量真实的准确率提升：旧默认模型（small）与新默认模型（large-v3 [+ Demucs]）相对于参考转录文本的词错误率（WER）。PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish]。
• caption.py — 一体化带样式的字幕（卡拉OK/单词/单行；Hormozi/TikTok/霓虹灯…）→ 生成动画 captions.js。

给视频配字幕（主要任务）——默认语言为英语

对于其他语言，传入 --lang <语言代码>。对于Hinglish / 混合语言，使用 --code-switch。

1) 帧级精准单词时间轴

语音（对话、播客、用户生成内容）：

PY scripts/align.py 输入文件 --lang en --out work/transcript.json

Hinglish / 混合印地语-英语（或任意语码混合音频）：

PY scripts/align.py 输入文件 --code-switch --dual hi en --out work/transcript.json

任意其他语言（乌尔都语、西班牙语、阿拉伯语、中文……）：

PY scripts/align.py 输入文件 --lang ur --out work/transcript.json

2a) 字幕（.srt / .vtt）+ 烧录到视频中

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i 输入文件 -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

.srt 文件也可直接上传到YouTube（可选择字幕 + 对SEO友好）。

2b) 带样式/动画的字幕（Hormozi、TikTok、卡拉OK——短格式）

PY scripts/caption.py 输入文件 --lang en --content speech --style karaoke --preset hormozi --out out/

预设：hormozi、beast、pill、neon、gradient、minimal、tiktok。歌曲/歌词使用 --content music。详见 docs/caption-styles.md。

3) 翻译字幕为任意语言（可选）

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn 输入文件]

规则（已内建——请勿覆盖）

• 时间轴始终使用强制对齐，绝不使用原始ASR时间戳（无超前/滞后）。
• 默认字幕语言 = 英语；如需其他语言，传入 --lang。
• 音乐/唱歌 → --content music；语音/说话 → --content speech。
• 每个脚本都使用 PY（虚拟环境中的python）运行，以确保拥有whisperx/torch。
• 交付前，随机抽查几个字幕在其单词起始时刻的同步情况，以确认同步准确无误。

语言代码

en（默认）、hi、ur、pa、es、fr、de、pt、ar、zh、ja、ko、ru、it、tr、id、nl、pl、uk…… — Whisper 支持约99种语言；MMS_FA 支持1100+种语言的强制对齐。