codingsamss/video-transcribe

Video Transcribe & Visual Analysis Skill

从任意视频/音频链接提取内容并分析。支持音频转录、视频画面分析、或两者综合。支持 Twitter/X、YouTube、Bilibili 等 1000+ 站点。

触发条件

当用户提到以下内容时触发：

• "这个视频说了什么"、"帮我看看这个视频"、"视频内容"、"转录"
• "transcribe this video"、"what does this video say"
• 分享了包含视频的链接并希望了解内容
• "总结这个视频"、"视频摘要"
• "提取字幕"、"语音转文字"
• "视频画面是什么"、"视频里展示了什么"、"分析视频画面"
• "analyze video visually"、"what's shown in this video"

模式判断

收到视频链接后，根据用户措辞判断分析模式。按优先级从高到低匹配：

1. 音频转录模式（audio）

用户明确要求处理语音/音频内容时使用。

• 命中关键词：转录、字幕、语音转文字、提取字幕、他说了什么话、transcribe、subtitle、speech-to-text
• 典型表达："帮我转录这个视频"、"提取字幕"、"视频里他说了什么话"
• 流程：仅提取音频 → Groq Whisper 转录 → 文本总结

2. 画面分析模式（visual）

用户明确要求分析视觉/画面内容时使用。

• 命中关键词：画面、视觉、展示了什么、出现了什么、看到了什么、视频截图、视频帧、visual、frame、what's shown
• 典型表达："视频画面是什么"、"视频里展示了什么"、"分析一下视频画面"
• 流程：下载视频 → 提取关键帧 → Claude 视觉分析 → 画面描述

3. 综合分析模式（full）— 默认

用户笼统地想了解视频内容，或意图不明确时使用。

• 命中关键词：分析、内容、说了什么、总结、帮我看看、什么内容、analyze、summary
• 典型表达："这个视频说了什么"、"帮我看看这个视频"、"分析一下这个视频"
• 流程：下载视频 → 提取关键帧分析画面 → 提取音频转录 → 综合总结
• 如果音频转录结果为空或无意义（纯音乐/无语音），自动退化为纯画面分析
• 如果关键帧提取失败（纯音频文件），自动退化为纯音频转录

前置条件

1. yt-dlp 已安装: brew install yt-dlp
2. ffmpeg 已安装: brew install ffmpeg
3. GROQ_API_KEY 环境变量已设置（音频转录需要）
   • 申请地址: https://console.groq.com
   • 纯画面分析模式不需要 Groq API

工作目录

所有临时文件保存到: /tmp/video-transcribe/

处理完成后自动清理中间文件，仅保留最终文本输出。

执行流程

收到视频链接后，先完成模式判断，再按以下步骤执行：

Step 0: 清理工作目录

每次执行前，清理旧文件：

if [ -d /tmp/video-transcribe ]; then
  # 删除超过 1 天的文件
  find /tmp/video-transcribe -type f -mtime +1 -delete 2>/dev/null
  # 删除上次残留的所有中间文件（用 find 避免特殊字符文件名 glob 失败）
  find /tmp/video-transcribe -type f \( -name '*.mp3' -o -name '*.wav' -o -name '*.mp4' -o -name '*.webm' -o -name '*.jpg' \) -delete 2>/dev/null
fi
mkdir -p /tmp/video-transcribe

Step 1: 下载

根据模式选择下载方式：

音频模式：仅下载音频轨

yt-dlp --cookies-from-browser chrome \
  -x --audio-format mp3 --audio-quality 5 \
  -o '/tmp/video-transcribe/%(title)s.%(ext)s' \
  '$URL'

• -x --audio-format mp3 - 只提取音频转 MP3
• --audio-quality 5 - 中等质量（语音转录足够，减小体积）

画面分析模式 / 综合模式：下载完整视频

yt-dlp --cookies-from-browser chrome \
  -f "bestvideo[height<=720]+bestaudio/best[height<=720]" \
  --merge-output-format mp4 \
  -o '/tmp/video-transcribe/%(title)s.%(ext)s' \
  '$URL'

• 限制 720p 分辨率，画面分析足够清晰且节省空间
• --merge-output-format mp4 确保输出为 mp4 便于后续 ffmpeg 处理

错误处理（通用）：

• cookies 失败 → 去掉 --cookies-from-browser chrome 重试
• 站点不支持 → 告知用户 yt-dlp 不支持该站点
• YouTube 报 No video formats found / SABR 错误 → 提示 brew upgrade yt-dlp
• 下载超时或文件过大 → 可加 --max-filesize 500M 限制

Step 2: 处理

根据模式执行对应的处理流程。综合模式下 2A 和 2B 都要执行。

2A: 音频转录（音频模式 / 综合模式）

综合模式下，先从视频文件提取音频：

ffmpeg -i '/tmp/video-transcribe/INPUT.mp4' \
  -vn -acodec libmp3lame -q:a 5 \
  '/tmp/video-transcribe/audio.mp3' -y

后续用 audio.mp3 替代 INPUT.mp3。

检查文件大小：

FILE_SIZE=$(stat -f%z '/tmp/video-transcribe/INPUT.mp3')

若文件 <= 24MB，直接转录。若 > 24MB，切分：

ffmpeg -i '/tmp/video-transcribe/INPUT.mp3' \
  -f segment -segment_time 1200 -c copy \
  '/tmp/video-transcribe/segment_%03d.mp3' -y

调用 Groq Whisper API 转录：

若直连 Groq 返回 403 Forbidden，为转录命令临时加代理环境变量后重试：

HTTP_PROXY=http://127.0.0.1:7897 HTTPS_PROXY=http://127.0.0.1:7897 <转录命令>

单文件：

curl -s -X POST \
  https://api.groq.com/openai/v1/audio/transcriptions \
  -H "Authorization: Bearer $GROQ_API_KEY" \
  -F "file=@/tmp/video-transcribe/INPUT.mp3" \
  -F "model=whisper-large-v3" \
  -F "response_format=text" \
  -F "language=zh" \
  -o '/tmp/video-transcribe/transcript.txt'

多段（切分后）：

> /tmp/video-transcribe/transcript.txt
for f in /tmp/video-transcribe/segment_*.mp3; do
  curl -s -X POST \
    https://api.groq.com/openai/v1/audio/transcriptions \
    -H "Authorization: Bearer $GROQ_API_KEY" \
    -F "file=@$f" \
    -F "model=whisper-large-v3" \
    -F "response_format=text" \
    >> '/tmp/video-transcribe/transcript.txt'
  echo "" >> '/tmp/video-transcribe/transcript.txt'
done

参数说明：

• model=whisper-large-v3 - 最高精度模型
• response_format=text - 返回纯文本
• language=zh - 指定中文。英文用 en，不确定语言时省略此参数让模型自动检测

错误处理：

• 401：GROQ_API_KEY 无效或过期
• 403：网络受限，尝试加 HTTP_PROXY 与 HTTPS_PROXY
• 413：文件过大，需切分
• 429：速率限制，等待几秒后重试

综合模式下判断转录结果：

• 转录文本为空、极短（< 10 字符）、或内容无意义 → 判定为无有效语音，跳过音频部分，仅使用画面分析结果

2B: 画面分析（画面模式 / 综合模式）

提取关键帧：

# 获取视频时长（秒）
DURATION=$(ffprobe -v error -show_entries format=duration \
  -of csv=p=0 '/tmp/video-transcribe/INPUT.mp4' | cut -d. -f1)

# 计算采样间隔（目标 8 帧，均匀分布）
INTERVAL=$((DURATION / 8))
[ "$INTERVAL" -lt 2 ] && INTERVAL=2

# 提取关键帧
ffmpeg -i '/tmp/video-transcribe/INPUT.mp4' \
  -vf "fps=1/$INTERVAL,scale=1280:-2" \
  -frames:v 8 \
  -q:v 2 \
  '/tmp/video-transcribe/frame_%03d.jpg' -y

参数说明：

• fps=1/$INTERVAL - 根据视频时长动态调整采样率，确保帧均匀覆盖全片
• scale=1280:-2 - 宽度缩放到 1280px，高度自适应保持比例
• -frames:v 8 - 最多提取 8 帧
• -q:v 2 - JPEG 高质量（2），清晰度与文件大小平衡

如果提取帧数不足 3 张（视频过短），降低间隔重试：

ffmpeg -i '/tmp/video-transcribe/INPUT.mp4' \
  -vf "fps=2,scale=1280:-2" \
  -frames:v 8 \
  -q:v 2 \
  '/tmp/video-transcribe/frame_%03d.jpg' -y

视觉分析：

使用 Claude 自身的多模态视觉能力，用 Read 工具依次读取提取的帧图片（/tmp/video-transcribe/frame_001.jpg ~ frame_008.jpg），综合所有帧分析视频画面内容。

分析时重点关注：

• 场景变化 - 画面之间的转场和时间线推进
• 人物与物体 - 出现的人、动物、机器、物品等
• 文字与字幕 - 画面上叠加的文字、标题、水印
• 动作与事件 - 正在发生什么
• 画面风格 - 实拍/动画/对比/演示等

Step 3: 输出总结

根据模式提供对应格式的总结：

音频模式输出

1. 展示视频基本信息（标题、时长、语言）
2. 结构化总结：
   • 核心主题 - 一句话概括
   • 关键要点 - 3-5 个要点
   • 详细内容 - 按话题/章节组织的详细摘要
   • 值得关注 - 有价值的观点、数据、资源链接等

画面分析模式输出

1. 展示视频基本信息（标题、时长、提取帧数）
2. 结构化总结：
   • 画面概述 - 视频整体展示了什么
   • 关键场景 - 按时间顺序描述主要画面变化
   • 视觉要素 - 出现的人物、物体、文字、图表等
   • 画面结论 - 从视觉内容推断视频主旨

综合模式输出

1. 展示视频基本信息（标题、时长）
2. 综合总结：
   • 核心主题 - 结合画面和语音的一句话概括
   • 画面内容 - 视频展示了什么
   • 语音内容 - 说了什么（若有有效语音）
   • 关键要点 - 3-5 个要点
   • 综合分析 - 画面与语音结合的完整理解

Step 4: 清理临时文件

处理完成后，清理所有中间文件：

# 删除视频、音频、帧图片等中间文件（用 find 避免特殊字符文件名 glob 失败）
find /tmp/video-transcribe -type f \( -name '*.mp4' -o -name '*.webm' -o -name '*.mp3' -o -name '*.wav' -o -name '*.jpg' \) -delete 2>/dev/null

保留 transcript.txt 供用户后续查阅。用户不再需要时：

rm -rf /tmp/video-transcribe/

支持的站点（部分）

yt-dlp 支持 1000+ 站点，常用的包括：

• Twitter/X
• YouTube
• Bilibili（哔哩哔哩）
• Vimeo
• TikTok / 抖音
• 微博视频
• 播客平台（Apple Podcasts、Spotify 等）

完整列表: yt-dlp --list-extractors

本地模式（备选）

如果无网络或不想使用在线 API，可以使用本地 whisper-cpp 转录：

1. 安装: brew install whisper-cpp
2. 下载模型: curl -L https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin -o ~/.cache/whisper-cpp/ggml-small.bin
3. 转码为 WAV: ffmpeg -i INPUT.mp3 -ar 16000 -ac 1 -c:a pcm_s16le audio.wav -y
4. 转录: whisper-cli -m ~/.cache/whisper-cpp/ggml-small.bin -f audio.wav -l auto --no-timestamps -otxt -of transcript

本地模型精度低于 Groq whisper-large-v3，适合离线或隐私敏感场景。

注意事项

• 音频转录通过 Groq API 处理，音频会上传到 Groq 服务器
• 画面分析使用 Claude 自身视觉能力，帧图片不上传第三方服务
• 音频质量直接影响转录精度，背景噪音较大时精度会下降
• 非语音内容（纯音乐、音效）无法转录，综合模式会自动退化为画面分析
• 多语言混合内容可能需要指定主要语言（language=zh 或 language=en）
• Groq 免费额度充足，日常使用无需担心费用
• 视频下载限制 720p，画面分析足够清晰且节省带宽
• 关键帧最多 8 张，均匀覆盖视频主要内容