Communitygithub.com

视频转录与字幕添加

使用本地 Whisper 为无字幕视频(X/Twitter、YouTube、任何 yt-dlp URL 或本地文件)生成转录文本,编写 SRT 字幕文件,并将字幕压制到新的 MP4 文件中。当用户要求“获取转录文本”、“提取他们说的话”、“添加字幕”、“为本视频添加字幕”或“此视频没有字幕”时使用。

视频转录与字幕添加 是什么?

该技能提供了一套完整的本地化视频字幕处理流程,无需依赖任何云端服务。它使用 yt-dlp 下载视频,利用 faster-whisper 进行本地语音识别并生成 SRT 字幕文件,最后通过 ffmpeg 将字幕压制到视频中。支持多种视频来源,包括 X/Twitter、YouTube 和任意 yt-dlp 支持的 URL 或本地文件。技能包含了工具检查、视频下载、转录、修复误听行和字幕压制等步骤,并提供了模型选择建议(如 small 和 large-v3)以及常见错误警示。该技能可运行在支持 Python、yt-dlp、ffmpeg 及 faster-whisper 的任何平台上。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gengwg/skills/tree/HEAD/video-transcribe-and-caption

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

技能:视频转录与字幕添加

目的

将视频中的语音转换为文本,无需任何云服务:使用 yt-dlp 下载,使用 faster-whisper 本地转录,生成 SRT 字幕文件,并可选使用 ffmpeg 将字幕压制到视频中,使其在所有播放器中显示。

步骤

1. 检查工具

which yt-dlp ffmpeg uv; nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null

uvx yt-dlp 和 uv run --with faster-whisper 可避免安装任何东西。只有 ffmpeg 的 subtitles 过滤器需要一个带有 libass 的真正的 ffmpeg 构建(ffmpeg -filters | grep subtitles);imageio-ffmpeg 附带的二进制文件可能缺少该功能。

2. 下载

uvx yt-dlp -f "bv*[ext=mp4]+ba[ext=m4a]/b[ext=mp4]/b" --merge-output-format mp4 -o "video.%(ext)s" --no-playlist "<url>"
uvx yt-dlp --skip-download -j "<url>" | jq '{title, uploader, upload_date, description}'

3. 转录为 SRT

# srt.py — 使用命令运行:uv run --with faster-whisper python srt.py
from faster_whisper import WhisperModel

def ts(t):
    h, r = divmod(t, 3600); m, s = divmod(r, 60)
    return f"{int(h):02d}:{int(m):02d}:{int(s):02d},{int(s % 1 * 1000):03d}"

model = WhisperModel("large-v3", device="cpu", compute_type="int8")  # 如果有 GPU,则 device="cuda"
segments, info = model.transcribe("video.mp4", vad_filter=True, beam_size=5)
with open("video.srt", "w") as f:
    for i, s in enumerate(segments, 1):
        f.write(f"{i}\n{ts(s.start)} --> {ts(s.end)}\n{s.text.strip()}\n\n")

模型选择:

  • small 速度快,但多人音频、笑话和专业术语识别效果差。适合初步查看,不适合制作字幕。
  • large-v3 是推荐使用的模型。首次下载约 3 GB,存放在 ~/.cache/huggingface/hub/ 中;在慢速连接下,仅下载就可能需要 30 分钟以上。请先向用户说明并征得同意后再开始;medium 大小约为其一半。
  • 长转录任务应在后台运行,并如实报告进度:检查 HF 缓存中的 .incomplete 文件是否仍在增长(下载中)或进程是否处于高 CPU 使用状态(转录中)。

4. 修复误听行

Whisper 仍然会误听名称和领域特定词汇。通过词汇提示仅重新转录错误片段,而不是重新运行整个文件:

ffmpeg -loglevel error -y -ss 53 -to 64 -i video.mp4 -vn -ac 1 -ar 16000 clip.wav
segments, _ = model.transcribe("clip.wav", beam_size=5,
    initial_prompt="Short list of expected words: product names, jargon, emoji names.")

然后手动编辑这些 SRT 条目(保留时间戳)。当屏幕上的文字可以澄清音频时,截取一帧(ffmpeg -ss 58 -i video.mp4 -frames:v 1 f.jpg)会有所帮助。应向用户说明哪些行仍然置信度较低,而不是将猜测当作事实呈现。

5. 压制字幕

ffmpeg -hide_banner -loglevel error -y -i video.mp4 \
  -vf "subtitles=video.srt:force_style='FontSize=20,Outline=1,MarginV=30'" \
  -c:v libx264 -preset fast -crf 20 -c:a copy video_cc.mp4

将 SRT 文件保留在输出文件旁边,这样可以在不到一分钟内修复一行并重新渲染。对于软字幕(可切换),使用以下命令混流: ffmpeg -i video.mp4 -i video.srt -c copy -c:s mov_text video_cc.mp4。

交付物

原始视频、带字幕的视频、.srt 文件以及纯文本转录。提及缓存的模型大小,以便用户可以删除它。

常见错误

  • 将 small 模型的输出作为字幕使用。
  • 未询问用户便开始下载数 GB 的模型。
  • 为了修复三行错误而重新运行完整的转录。
  • 使用没有 libass 的 ffmpeg,导致出现“No such filter: subtitles”错误。

相关技能