caption-clip

给 YouTube 视频片段添加字幕

使用时间戳下载 YouTube 视频片段，通过 Deepgram 转录，并嵌入样式化字幕。

前提条件

• 已安装 yt-dlp
• 已安装 ffmpeg
• .env 文件（或环境变量）中包含 DEEPGRAM_API_KEY
• Avenir Next 字体（不可用时会回退到 Arial）

工作流

步骤 1：下载片段

使用 yt-dlp 下载 YouTube 视频的特定片段：

yt-dlp --download-sections "*START-END" -o "clip_name.%(ext)s" "YOUTUBE_URL"

时间戳为 02:53-04:15 的示例：

yt-dlp --download-sections "*02:53-04:15" -o "clip_intro.%(ext)s" "https://www.youtube.com/watch?v=VIDEO_ID"

步骤 2：转换为 MP4

使用 ffmpeg 默认设置确保编码一致：

ffmpeg -i clip_name.webm -y clip_name.mp4

步骤 3：使用 Deepgram 转录

从 .env 加载 API 密钥并调用 Deepgram API：

DEEPGRAM_API_KEY=$(grep '^DEEPGRAM_API_KEY=' .env | cut -d'=' -f2 | tr -d '"' | tr -d "'")

curl -s --request POST \
  --url 'https://api.deepgram.com/v1/listen?model=nova-2&smart_format=true&punctuate=true&utterances=true' \
  --header "Authorization: Token $DEEPGRAM_API_KEY" \
  --header 'Content-Type: audio/mp4' \
  --data-binary @clip_name.mp4 > clip_transcript.json

步骤 4：生成 SRT

使用随附脚本将 Deepgram JSON 转换为 SRT 格式：

python3 ~/.claude/skills/caption-clip/scripts/json-to-srt.py clip_transcript.json clip.srt

步骤 5：清理转录文本

读取生成的 SRT 文件，并创建清理后的版本（clip_clean.srt）：

1. 修正转录错误 - 更正听错的词语
2. 删除填充词 - 删除：“like”“you know”“I'd say”“yeah”“um”“uh”“sort of”“kind of”
3. 合并片段 - 将简短话语合并为完整句子
4. 提高可读性 - 调整措辞，使其读起来比听起来更流畅
5. 修正时间戳 - 确保时间有效（例如，00:00:60 应为 00:01:00）

将清理后的内容写入 clip_clean.srt。

步骤 6：嵌入字幕

应用带半透明背景的样式化字幕：

ffmpeg -i clip_name.mp4 \
  -vf "subtitles=clip_clean.srt:force_style='FontSize=24,FontName=Avenir Next Medium,PrimaryColour=&H00FFFFFF,BackColour=&H80000000,BorderStyle=4,Outline=0,Shadow=0,MarginV=30,MarginL=40,MarginR=40'" \
  -c:a copy -y clip_captioned.mp4

字幕样式参考

参数	值	描述
FontSize	24	字号
FontName	Avenir Next Medium	简洁的无衬线字体（备用字体使用 Arial）
PrimaryColour	&H00FFFFFF	白色文字（AABBGGRR 格式）
BackColour	&H80000000	50% 透明度的黑色背景
BorderStyle	4	使用 BackColour 的不透明框
MarginV	30	距底部的垂直边距
MarginL/R	40	水平边距

备用字体

如果 Avenir Next 不可用，以下字体也适合字幕：

• SF Pro Display
• Helvetica Neue
• Futura
• Arial（通用备用字体）

检查可用字体：

fc-list : family | sort -u | grep -iE '(avenir|sf pro|helvetica|futura)'

输出文件

完成工作流后：

文件	描述
clip_name.mp4	下载的原始片段
clip_transcript.json	Deepgram 原始转录结果（保留以便重新运行）
clip.srt	自动生成的字幕
clip_clean.srt	清理/编辑后的字幕
clip_captioned.mp4	已嵌入字幕的最终视频