YouTube 视频分析器 — 多模态

该技能通过双信息通道对 YouTube 视频执行深度分析：

• 音频通道：带时间戳的字幕文本（“说了什么”）
• 视觉通道：关键帧提取 + 图像分析（“展示了什么”）

大多数 YouTube 相关技能仅提取字幕文本。本技能通过将视觉帧与语音内容同步弥补了这一缺口，从而可生成准确的分步操作指南——例如，“点击右上角的蓝色按钮”这一指令，将严格匹配实际截图中对应按钮的位置。

工作流概览

YouTube URL
    |
    +---> 1. 获取元数据（标题、时长、视频 ID）
    |
    +---> 2. 提取字幕（yt-dlp --dump-json + curl）
    |         -> 带时间戳的字幕片段
    |
    +---> 3. 提取帧（yt-dlp + ffmpeg）
    |         -> 按策略性时间间隔提取关键帧
    |
    +---> 4. 同步帧 <-> 字幕
    |         -> 基于时间戳将帧匹配至对应语音内容
    |
    +---> 5. 多模态分析
              -> 逐帧读取图像，并结合字幕文本进行联合理解
              -> 生成结构化输出

步骤 1：设置工作目录

VIDEO_URL=""
WORK_DIR=$(mktemp -d /tmp/yt-analysis-XXXXXX)
mkdir -p "$WORK_DIR/frames"

步骤 2：获取视频元数据

yt-dlp --print title --print duration --print id "$VIDEO_URL" 2>/dev/null

该命令返回三行内容：标题、以秒为单位的时长、视频 ID。请保存这些值供后续使用。

步骤 3：提取字幕

重要提示：通过 --write-sub 直接下载字幕常触发 YouTube 限流（HTTP 429 错误）。请改用以下可靠两步法。

步骤 3a：从视频 JSON 中获取字幕 URL

yt-dlp --dump-json "$VIDEO_URL" 2>/dev/null | python3 -c "
import json, sys
data = json.load(sys.stdin)
auto = data.get('automatic_captions', {})
subs = data.get('subtitles', {})

# 优先级：人工字幕 > 自动字幕；优先匹配用户语言，依次降级。
for source in [subs, auto]:
    for lang in ['en', 'de', 'en-orig', 'fr', 'es']:
        if lang in source:
            for fmt in source[lang]:
                if fmt.get('ext') == 'json3':
                    print(fmt['url'])
                    sys.exit(0)

# 降级方案：取首个可用自动字幕，提取其 json3 URL
for lang in sorted(auto.keys()):
    for fmt in auto[lang]:
        if fmt.get('ext') == 'json3':
            url = fmt['url']
            # 移除翻译参数，还原原始语言
            import re
            url = re.sub(r'&tlang=[^&]+', '', url)
            print(url)
            sys.exit(0)

print('NO_SUBS', file=sys.stderr)
sys.exit(1)
" > "$WORK_DIR/sub_url.txt"

步骤 3b：下载并解析字幕

curl -s "$(cat "$WORK_DIR/sub_url.txt")" -o "$WORK_DIR/transcript.json3"

验证其是否为有效 JSON（而非 HTML 错误页）：

head -c 20 "$WORK_DIR/transcript.json3"
# 应以 { 开头；若以 
步骤 3c：将 json3 解析为可读的时间戳字幕片段
python3 -c "
import json

with open('$WORK_DIR/transcript.json3') as f:
    data = json.load(f)

for event in data.get('events', []):
    segs = event.get('segs', [])
    if not segs:
        continue
    start_ms = event.get('tStartMs', 0)
    duration_ms = event.get('dDurationMs', 0)
    text = ''.join(s.get('utf8', '') for s in segs).strip()
    if not text or text == 'n':
        continue
    s = start_ms / 1000
    e = (start_ms + duration_ms) / 1000
    print(f'[{int(s//60):02d}:{int(s%60):02d} - {int(e//60):02d}:{int(e%60):02d}] {text}')
" > "$WORK_DIR/transcript.txt"

查看 $WORK_DIR/transcript.txt 即可获得带时间戳的完整字幕文本。
降级方案：无任何字幕可用
若视频完全无字幕，请告知用户，并继续执行纯视觉分析。
步骤 4：下载视频并提取帧
步骤 4a：下载视频（720p 已足够用于帧分析）
yt-dlp -f "bestvideo[height<=720]+bestaudio/best[height<=720]" 
       -o "$WORK_DIR/video.mp4" "$VIDEO_URL"

步骤 4b：获取精确时长
DURATION=$(ffprobe -v quiet -show_entries format=duration -of csv=p=0 "$WORK_DIR/video.mp4")

步骤 4c：采用自适应时间间隔策略提取帧
根据视频时长选择间隔：



时长
间隔
约提取帧数
依据



< 5 分钟
10 秒
20–30
密度足够支撑细节分析


5–20 分钟
20 秒
15–60
覆盖率与数据量的良好平衡


20–60 分钟
30–45 秒
30–120
聚焦关键节点


> 60 分钟
60 秒
60–120+
询问用户是否希望聚焦特定时间段或章节


# 示例：针对 5–20 分钟视频（间隔=20 秒）
ffmpeg -i "$WORK_DIR/video.mp4" -vf "fps=1/20" -q:v 3 "$WORK_DIR/frames/frame_%04d.jpg" 2>&1

针对场景变化检测（软件教程、UI 演示）：
ffmpeg -i "$WORK_DIR/video.mp4" 
       -vf "select='gt(scene,0.3)',showinfo" 
       -vsync vfr -q:v 3 "$WORK_DIR/frames/scene_%04d.jpg" 2>&1

步骤 4d：计算每帧对应的时间戳
对于固定间隔提取：第 N 帧的时间戳为 (N-1) * 间隔 秒。
frame_0001.jpg -> 0:00
frame_0002.jpg -> 0:20
frame_0003.jpg -> 0:40
...

步骤 5：帧与字幕同步
对每个已提取的帧执行以下操作：

计算该帧在视频中的时间戳（单位：秒）
定位覆盖该时间戳的字幕片段
构建同步数据对：{timestamp, transcript_text, frame_path}

此过程可通过人工判断或简单查表完成，无需额外脚本。
步骤 6：多模态分析
步骤 6a：逐帧读取与分析
使用 Read 工具（或 view 工具）查看每张帧图像。对每帧需关注：

UI 元素：可见的按钮、菜单、对话框、设置面板等
屏幕文字：代码、标签、错误信息、URL、终端输出等
图表/图形：折线图、流程图、架构图等
物理动作：手部位置、工具使用方式（适用于实体操作类教程）
变化：与前一帧相比发生了哪些变化？

步骤 6b：融合双通道信息
对每个关键节点，整合音频与视觉内容：
片段 [TIMESTAMP]：
  SAID: “点击右上角的蓝色按钮”
  SHOWN: 设置页面截图，右上角高亮显示蓝色 “Save” 按钮，
         鼠标光标正指向该按钮
  SYNTHESIS: -> 在设置页面中，点击右上角的蓝色 “Save” 按钮

步骤 6c：识别纯视觉信息
标记视觉通道提供但音频未提及的信息点：

具体按钮名称、菜单路径、UI 精确位置
屏幕上展示但未朗读的代码
屏幕上可见的错误信息
前后对比画面

输出格式
根据用户请求生成相应格式：
格式 A：分步操作指南（最常用）
# [视频标题] — 操作指南

## 步骤 1：[操作]（00:15）
[基于字幕与帧分析生成的描述]
> 视觉：[该时刻屏幕/图像所呈现的内容]

## 步骤 2：[操作]（00:42）
[...]

格式 B：含视觉锚点的综合摘要
# [视频标题] — 摘要

## 概述
[2–3 句概括整段视频核心内容]

## 关键章节

### [章节名称]（00:00 – 02:30）
[本章节摘要]
- 关键视觉：[画面内容描述]
- 关键引述：“[重要语音内容]”

### [章节名称]（02:30 – 05:00）
[...]

## 核心要点
- [要点 1]
- [要点 2]

格式 C：技术细节分析
分别分析双通道，并检测不一致项：
# [视频标题] — 技术分析

## 音频通道分析
[语音内容、关键点、逻辑结构]

## 视觉通道分析
[画面内容、UI 流程、代码、图表]

## 通道同步分析
[音频与视觉互补的具体位置]

## 纯视觉信息
[仅在帧中可见、语音未提及的重要细节]

错误处理与边界情况



问题
解决方案



字幕下载返回 HTTP 429
使用 --dump-json 方法（步骤 3a）；若 curl 亦被拦截，等待 10–15 秒后重试，并更换 User-Agent


完全无字幕可用
继续纯视觉分析，并通知用户


原始音频语言未出现在自动字幕列表中
原始语言即为源语言——自动字幕均为翻译结果；从任意自动字幕 URL 中移除 &tlang=XX 参数即可还原原始语言


transcript.json3 内容为 HTML 而非 JSON
YouTube 返回了错误页。等待 10 秒后重试： curl -s --user-agent "Mozilla/5.0 (Windows NT 10.0; Win64; x64)" "$URL"


视频时长 > 60 分钟
询问用户是否希望聚焦特定时间段或章节


视频质量差 / 帧模糊
缩短帧提取间隔，增加帧数以补偿


视频受年龄限制或设为私密
告知用户无法访问该视频；如用户有权限，建议使用 --cookies-from-browser


yt-dlp 下载失败
尝试替代格式：-f "best[height<=720]"（不分离音视频流）


清理
分析完成后，删除临时文件：
rm -rf "$WORK_DIR"

提升效果最佳实践

软件教程类：启用场景变化检测——UI 切换会形成清晰的视觉断点
实体操作类：采用更密集的帧间隔（10–15 秒）——肢体动作变化更细微
先通读字幕：在提取帧之前，先识别字幕中“值得关注的时间戳”。重点关注诸如 “as you can see here”、“let me show you”、“on the screen” 等提示性语句，它们往往预示着重要视觉时刻
上下文感知的帧分析：分析某帧时，务必结合对应字幕上下文。讲话者通常会提前说明即将展示的内容
批量读取帧：每次连续读取 8–10 帧，有助于维持跨帧上下文连贯性，并识别视觉变化
并行提取双通道：在处理字幕的同时启动视频下载，节省整体耗时