YouTube 转录文本下载器
该技能帮助使用 yt-dlp 从 YouTube 视频下载转录文本(字幕/标题)。
何时使用此技能
在以下情况下激活此技能:
- 用户提供 YouTube 链接并想要转录文本
- 用户要求“从 YouTube 下载转录文本”
- 用户想要从视频中“获取字幕”或“获取标题”
- 用户要求“转录音频 YouTube 视频”
- 用户需要 YouTube 视频的文本内容
工作原理
优先级顺序:
- 检查是否安装了 yt-dlp - 如需要则安装
- 列出可用字幕 - 查看实际可用的内容
- 首先尝试人工字幕 (
--write-sub) - 质量最高 - 回退到自动生成字幕 (
--write-auto-sub) - 通常可用 - 最后手段:Whisper 转录 - 如果没有字幕(需要用户确认)
- 确认下载 并向用户显示文件保存位置
- 可选清理 VTT 格式,如果用户想要纯文本
安装检查
重要:始终先检查是否已安装 yt-dlp:
which yt-dlp || command -v yt-dlp
如果未安装
根据系统尝试自动安装:
macOS (Homebrew):
brew install yt-dlp
Linux (apt/Debian/Ubuntu):
sudo apt update && sudo apt install -y yt-dlp
替代方案 (pip - 适用于所有系统):
pip3 install yt-dlp
# 或
python3 -m pip install yt-dlp
如果安装失败:告知用户需要手动安装 yt-dlp,并提供来自 https://github.com/yt-dlp/yt-dlp#installation 的安装说明
检查可用字幕
始终先执行此操作,然后再尝试下载:
youtube-dlp --list-subs "YOUTUBE_URL"
这将显示可用的字幕类型,无需下载任何内容。查找:
- 人工字幕(质量更好)
- 自动生成字幕(通常可用)
- 可用语言
下载策略
选项 1:人工字幕(首选)
首先尝试此选项 - 质量最高,由人工创建:
youtube-dlp --write-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"
选项 2:自动生成字幕(回退)
如果人工字幕不可用:
youtube-dlp --write-auto-sub --skip-download --output "OUTPUT_NAME" "YOUTUBE_URL"
两个命令都会创建一个 .vtt 文件(WebVTT 字幕格式)。
选项 3:Whisper 转录(最后手段)
仅在人工字幕和自动生成字幕都不可用时使用。
步骤 1:显示文件大小并请求确认
# 获取音频文件大小估算
youtube-dlp --print "%(filesize,filesize_approx)s" -f "bestaudio" "YOUTUBE_URL"
# 或获取时长以估算
youtube-dlp --print "%(duration)s %(title)s" "YOUTUBE_URL"
重要:向用户显示文件大小并询问:“没有可用的字幕。我可以下载音频(大约 X MB)并使用 Whisper 进行转录。是否继续?”
等待用户确认后再继续。
步骤 2:检查 Whisper 安装
command -v whisper
如果未安装,询问用户:“Whisper 未安装。是否安装 pip install openai-whisper(模型约需 1-3GB)?这是一次性安装。”
等待用户确认后再安装。
如果获得批准,则安装:
pip3 install openai-whisper
步骤 3:仅下载音频
youtube-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "YOUTUBE_URL"
步骤 4:使用 Whisper 转录
# 自动检测语言(推荐)
whisper audio_VIDEO_ID.mp3 --model base --output_format vtt
# 或指定语言(如果已知)
whisper audio_VIDEO_ID.mp3 --model base --language en --output_format vtt
模型选项(目前坚持使用 base):
tiny- 最快,最不准确(约 1GB)base- 良好的平衡(约 1GB)← 使用此选项small- 更好的准确性(约 2GB)medium- 非常好(约 5GB)large- 最佳准确性(约 10GB)
步骤 5:清理
转录完成后,询问用户:“转录完成!是否删除音频文件以节省空间?”
如果是:
rm audio_VIDEO_ID.mp3
获取视频信息
提取视频标题(用于文件名)
youtube-dlp --print "%(title)s" "YOUTUBE_URL"
使用此功能根据视频标题创建有意义的文件名。为文件系统兼容性清理标题:
- 将
/替换为- - 替换可能导致问题的特殊字符
- 考虑使用清理版本:
$(youtube-dlp --print "%(title)s" "URL" | tr '/' '-' | tr ':' '-')
后处理
转换为纯文本(推荐)
YouTube 的自动生成 VTT 文件包含重复的行,因为字幕会随时间戳重叠逐步显示。在转换为纯文本时始终进行去重,同时保留原始说话顺序。
python3 -c "
import sys, re
seen = set()
with open('transcript.en.vtt', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > transcript.txt
完整的后处理(包括视频标题)
# 获取视频标题
VIDEO_TITLE=$(youtube-dlp --print "%(title)s" "YOUTUBE_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
# 查找 VTT 文件
VTT_FILE=$(ls *.vtt | head -n 1)
# 去重转换
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > "${VIDEO_TITLE}.txt"
echo "✓ 已保存到:${VIDEO_TITLE}.txt"
# 清理 VTT 文件
rm "$VTT_FILE"
echo "✓ 已清理临时 VTT 文件"
输出格式
- VTT 格式 (
.vtt):包含时间戳和格式,适合视频播放器 - 纯文本 (
.txt):仅文本内容,适合阅读或分析
提示
- 文件名将为
{output_name}.{language_code}.vtt(例如transcript.en.vtt) - 大多数 YouTube 视频都有自动生成的英文字幕
- 某些视频可能提供多种语言选项
- 如果自动字幕不可用,尝试使用
--write-sub获取人工字幕
完整工作流程示例
VIDEO_URL="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
# 获取视频标题用于文件名
VIDEO_TITLE=$(youtube-dlp --print "%(title)s" "$VIDEO_URL" | tr '/' '_' | tr ':' '-' | tr '?' '' | tr '"' '')
OUTPUT_NAME="transcript_temp"
# ============================================
# 步骤 1:检查是否安装了 yt-dlp
# ============================================
if ! command -v yt-dlp &> /dev/null; then
echo "未找到 yt-dlp,正在尝试安装..."
if command -v brew &> /dev/null; then
brew install yt-dlp
elif command -v apt &> /dev/null; then
sudo apt update && sudo apt install -y yt-dlp
else
pip3 install yt-dlp
fi
fi
# ============================================
# 步骤 2:列出可用字幕
# ============================================
echo "正在检查可用字幕..."
youtube-dlp --list-subs "$VIDEO_URL"
# ============================================
# 步骤 3:首先尝试人工字幕
# ============================================
echo "正在尝试下载人工字幕..."
if youtube-dlp --write-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
echo "✓ 人工字幕下载成功!"
ls -lh ${OUTPUT_NAME}.*
else
# ============================================
# 步骤 4:回退到自动生成字幕
# ============================================
echo "人工字幕不可用。正在尝试自动生成字幕..."
if youtube-dlp --write-auto-sub --skip-download --output "$OUTPUT_NAME" "$VIDEO_URL" 2>/dev/null; then
echo "✓ 自动生成字幕下载成功!"
ls -lh ${OUTPUT_NAME}.*
else
# ============================================
# 步骤 5:最后手段 - Whisper 转录
# ============================================
echo "⚠ 此视频没有可用字幕。"
# 获取文件大小
FILE_SIZE=$(youtube-dlp --print "%(filesize_approx)s" -f "bestaudio" "$VIDEO_URL")
DURATION=$(youtube-dlp --print "%(duration)s" "$VIDEO_URL")
TITLE=$(youtube-dlp --print "%(title)s" "$VIDEO_URL")
echo "视频:$TITLE"
echo "时长:$((DURATION / 60)) 分钟"
echo "音频大小:约 $((FILE_SIZE / 1024 / 1024)) MB"
echo ""
echo "是否要下载并使用 Whisper 转录?(y/n)"
read -r RESPONSE
if [[ "$RESPONSE" =~ ^[Yy]$ ]]; then
# 检查 Whisper
if ! command -v whisper &> /dev/null; then
echo "Whisper 未安装。现在安装?(约需 1-3GB)(y/n)"
read -r INSTALL_RESPONSE
if [[ "$INSTALL_RESPONSE" =~ ^[Yy]$ ]]; then
pip3 install openai-whisper
else
echo "没有 Whisper 无法继续。退出。"
exit 1
fi
fi
# 下载音频
echo "正在下载音频..."
youtube-dlp -x --audio-format mp3 --output "audio_%(id)s.%(ext)s" "$VIDEO_URL"
# 获取实际音频文件名
AUDIO_FILE=$(ls audio_*.mp3 | head -n 1)
# 转录
echo "正在使用 Whisper 转录(可能需要几分钟)..."
whisper "$AUDIO_FILE" --model base --output_format vtt
# 清理
echo "转录完成!是否删除音频文件?(y/n)"
read -r CLEANUP_RESPONSE
if [[ "$CLEANUP_RESPONSE" =~ ^[Yy]$ ]]; then
rm "$AUDIO_FILE"
echo "音频文件已删除。"
fi
ls -lh *.vtt
else
echo "转录已取消。"
exit 0
fi
fi
fi
# ============================================
# 步骤 6:转换为可读纯文本并去重
# ============================================
VTT_FILE=$(ls ${OUTPUT_NAME}*.vtt 2>/dev/null || ls *.vtt | head -n 1)
if [ -f "$VTT_FILE" ]; then
echo "正在转换为可读格式并删除重复内容..."
python3 -c "
import sys, re
seen = set()
with open('$VTT_FILE', 'r') as f:
for line in f:
line = line.strip()
if line and not line.startswith('WEBVTT') and not line.startswith('Kind:') and not line.startswith('Language:') and '-->' not in line:
clean = re.sub('<[^>]*>', '', line)
clean = clean.replace('&', '&').replace('>', '>').replace('<', '<')
if clean and clean not in seen:
print(clean)
seen.add(clean)
" > "${VIDEO_TITLE}.txt"
echo "✓ 已保存到:${VIDEO_TITLE}.txt"
# 清理临时 VTT 文件
rm "$VTT_FILE"
echo "✓ 已清理临时 VTT 文件"
else
echo "⚠ 未找到可转换的 VTT 文件"
fi
echo "✓ 完成!"
注意:此完整工作流程处理所有情况,在每个决策点都有适当的错误检查和用户提示。
错误处理
常见问题及解决方案:
1. yt-dlp 未安装
- 根据系统尝试自动安装(Homebrew/apt/pip)
- 如果安装失败,提供手动安装链接
- 在继续之前验证安装
2. 没有可用字幕
- 首先列出可用字幕以确认
- 同时尝试
--write-sub和--write-auto-sub - 如果两者都失败,提供 Whisper 转录选项
- 在下载音频前显示文件大小并请求用户确认
3. 无效或私密视频
- 检查 URL 格式是否正确:
https://www.youtube.com/watch?v=VIDEO_ID - 某些视频可能是私密的、受年龄限制或受地理限制的
- 告知用户来自 yt-dlp 的具体错误
4. Whisper 安装失败
- 可能需要系统依赖(ffmpeg, rust)
- 提供回退:“手动安装:
pip3 install openai-whisper” - 检查可用磁盘空间(模型需要 1-10GB,取决于大小)
5. 下载中断或失败
- 检查互联网连接
- 验证足够的磁盘空间
- 如果出现 SSL 问题,请使用
--no-check-certificate重试
6. 多种字幕语言
- 默认情况下,yt-dlp 会下载所有可用语言
- 可以使用
--sub-langs en指定仅英文 - 首先使用
--list-subs列出可用语言
最佳实践:
- ✅ 在尝试下载前始终检查可用内容 (
--list-subs) - ✅ 在进入下一步之前验证每一步是否成功
- ✅ 在进行大文件下载(音频文件、Whisper 模型)前询问用户
- ✅ 处理后清理临时文件
- ✅ 在每一步提供清晰的反馈,说明正在发生什么
- ✅ 优雅地处理错误,并提供有用信息