Communitygithub.com

IGTA-Tech/claude-skills-research

当用户提供 YouTube 链接或要求下载/获取/抓取 YouTube 转录文本时,下载 YouTube 视频转录文本。也可在用户想要转录音频或获取视频字幕时使用。

claude-skills-research 是什么?

该技能是 YouTube 转录文本下载器,专为 AI 代理(如 Claude Code、Cursor、Codex)设计。它使用 yt-dlp 工具从 YouTube 视频中下载字幕(包括人工字幕和自动生成的字幕)。优先级顺序是:首先检查 yt-dlp 安装,然后列出可用字幕,尝试人工字幕,回退到自动生成字幕,最后在无字幕时使用 Whisper 进行转录(需用户确认)。技能支持在 macOS(Homebrew)、Linux(apt)和所有系统(pip)上自动安装 yt-dlp。用户需要提供 YouTube URL,代理会自动处理下载、格式转换(VTT 或纯文本)和去重。如果用户需要从 YouTube 视频中提取文本内容进行摘要、分析或其他 AI 任务,此技能非常重要。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/IGTA-Tech/claude-skills-research/tree/HEAD/tapestry-skills-for-claude-code/youtube-transcript

在你喜欢的 AI 中提问

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

文档

YouTube 转录文本下载器

该技能帮助使用 yt-dlp 从 YouTube 视频下载转录文本(字幕/标题)。

何时使用此技能

在以下情况下激活此技能:

  • 用户提供 YouTube 链接并想要转录文本
  • 用户要求“从 YouTube 下载转录文本”
  • 用户想要从视频中“获取字幕”或“获取标题”
  • 用户要求“转录音频 YouTube 视频”
  • 用户需要 YouTube 视频的文本内容

工作原理

优先级顺序:

  1. 检查是否安装了 yt-dlp - 如需要则安装
  2. 列出可用字幕 - 查看实际可用的内容
  3. 首先尝试人工字幕 (--write-sub) - 质量最高
  4. 回退到自动生成字幕 (--write-auto-sub) - 通常可用
  5. 最后手段:Whisper 转录 - 如果没有字幕(需要用户确认)
  6. 确认下载 并向用户显示文件保存位置
  7. 可选清理 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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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('&amp;', '&').replace('&gt;', '>').replace('&lt;', '<')
            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 模型)前询问用户
  • ✅ 处理后清理临时文件
  • ✅ 在每一步提供清晰的反馈,说明正在发生什么
  • ✅ 优雅地处理错误,并提供有用信息

Individual skills in this repo

This repo contains 7 individual skills — each has its own dedicated page.

IGTA-Tech/claude-skills-research

Use when localizing apps, using String Catalogs, generating type-safe symbols (Xcode 26+), handling plurals, RTL layouts, locale-aware formatting, or migrating from .strings files - comprehensive i18n patterns for Xcode 15-26

IGTA-Tech/claude-skills-research

Use when implementing SwiftUI animations, understanding VectorArithmetic, using @Animatable macro, choosing between spring and timing curve animations, or debugging animation behavior - comprehensive animation reference from iOS 13 through iOS 26

IGTA-Tech/claude-skills-research

Use when CAAnimation completion handler doesn't fire, spring physics look wrong on device, animation duration mismatches actual time, gesture + animation interaction causes jank, or timing differs between simulator and real hardware - systematic CAAnimation diagnosis with CATransaction patterns, frame rate awareness, and device-specific behavior

IGTA-Tech/claude-skills-research

This skill should be used when comparing two videos to analyze compression results or quality differences. Generates interactive HTML reports with quality metrics (PSNR, SSIM) and frame-by-frame visual comparisons. Triggers when users mention "compare videos", "video quality", "compression analysis", "before/after compression", or request quality assessment of compressed videos.

IGTA-Tech/claude-skills-research

Download YouTube videos and HLS streams (m3u8) from platforms like Mux, Vimeo, etc. using yt-dlp and ffmpeg. Use this skill when users request downloading videos, extracting audio, handling protected streams with authentication headers, or troubleshooting download issues like nsig extraction failures, 403 errors, or cookie extraction problems.

IGTA-Tech/claude-skills-research

Write high-converting landing page copy using proven frameworks like PAS (Problem-Agitate-Solution), AIDA, and StoryBrand. Creates headlines, value propositions, CTAs, and full page sections optimized for conversion. Use when users need landing page copy, sales page content, or marketing website text.

IGTA-Tech/claude-skills-research

Downloads videos from YouTube and other platforms for offline viewing, editing, or archival. Handles various formats and quality options.

相关技能