video-analysis

视频分析

使用原生模型理解或帧提取 + 转录分析视频文件。

⚠️ 输入是 URL（YouTube / TikTok / IG / Apple Podcasts / Spotify / 任意链接）？ 此技能接受本地文件路径。如果输入的是链接，切勿下载媒体。 按输入类型依次处理，并在首次获得文本后停止：

1. 播客单集链接或单集名称（Apple Podcasts、Spotify、Overcast、 发布方网站，或仅说“a16z 关于 X 的那期节目”）→ 使用 web_search 搜索 发布方的单集页面 / 节目说明 / 转录页面，然后调用 web-crawler.scrape_markdown(url) 读取。大多数主流节目都会发布文本。
2. 视频 URL → web-crawler.youtube_video(url) / youtube_transcript(url) （云端字幕，约 1 秒，无需下载；TikTok 可使用 tiktok_transcript）。
3. web_fetch 返回空结果（empty_extraction，由 JS 渲染的页面）→ 使用 web-crawler.scrape_markdown 重试同一 URL —— 它会渲染 JS。 不要仅凭普通抓取结果为空就断定“没有转录文本”。
4. 没有找到内容 → 如实报告这一点并提出询问。只有在用户明确要求下载 媒体，或提供了文件时，才运行本地下载 + analyze_video()。这不是备用方案： 数据中心 IP 会遇到机器人验证，拉取 100 MB 音频需要几分钟，而且通常会失败。

转录文本仅包含语音内容——不能仅凭转录文本判断说话者身份（参见 web-crawler 的元数据优先规则）。

工作原理

analyze_video(path, question)
      │
      ├─ file_size ≤ threshold (default 20MB)
      │     → Send video to a supports_video model (default Gemini 3.1 Flash Lite)
      │     → Model sees full video natively (best quality)
      │
      └─ file_size > threshold
            → ffmpeg extracts keyframes (scene detection for long videos)
            → Whisper transcribes audio track
            → Returns frame image paths + transcript text
            → Agent feeds these to the current chat model

快速开始

⚠️ 调用方式——不要使用带点号的导入。 目录名称包含连字符 （video-analysis），因此 from skills.video-analysis.exports import ... 是 Python 语法错误（- 会被解析为减号）。所有带连字符的技能都如此，不只是此技能。 请使用以下两种模式之一。

模式 A —— 从工作区根目录运行（脚本推荐）：

cd /data/workspace/skills/video-analysis && \
  python3 -c "from exports import analyze_video; \
    import json; \
    print(json.dumps(analyze_video('output/videos/clip.mp4', \
      question='What happens in this video?'), ensure_ascii=False))"

注意：传入的视频路径应为相对于工作区的路径（analyze.py 会将其解析为 相对于 WORKSPACE_DIR 的路径），即使你已切换到技能目录也是如此。

模式 B —— 在 starchild-clawd 脚本中运行：

from core.skill_tools import video_analysis
result = video_analysis.analyze_video("output/videos/clip.mp4",
                                      question="What happens in this video?")

❌ 不要使用 exec(open('skills/video-analysis/analyze.py').read())——analyze.py 在导入时会使用 __file__，而 exec 环境中未定义该变量，因此会崩溃。 如果必须避免上述两种模式，请使用 importlib.util.spec_from_file_location 按文件路径加载。

# result keys (same for both patterns):
# Analyze a video — auto-selects native or extraction mode
# result = analyze_video("output/videos/clip.mp4", question="What happens in this video?")

# result keys:
#   success: bool
#   mode: "native" | "extraction"
#
# If mode == "native":
#   analysis: str (model's text response)
#   model: str (which model was used)
#   tokens: {input, output, video, audio}
#
# If mode == "extraction":
#   frame_paths: list[str] (workspace-relative paths to keyframe JPEGs)
#   transcript: str | None (Whisper transcription text)
#   frame_count: int
#   duration_sec: float

使用导出项

from core.skill_tools import video_analysis

# Full analysis (auto-selects mode)
result = video_analysis.analyze_video("output/videos/my_video.mp4", question="Describe this video")

# Check current config
config = video_analysis.get_config()

# Get video metadata without analyzing
info = video_analysis.get_video_info("output/videos/my_video.mp4")
# → {"duration": 45.2, "size": 12345678, "width": 1920, "height": 1080, "has_audio": true}

原生模式（较短的视频）

对于低于大小阈值的视频，此技能会将完整视频发送给支持原生视频输入的模型。 模型会查看每一帧并听取音频。

默认模型： google/gemini-3.1-flash-lite —— 视频分析中性价比最佳。

模型基准测试（6MB 片段，与 gemini-3.1-pro-preview 基准模型对比）：

模型	等级	成本	耗时	准确率	备注
google/gemini-3.1-flash-lite	经济型	~$0.0014	8.1s	~88%	⭐ 默认——最便宜、最快
google/gemini-3.5-flash	标准型	~$0.0152	11.8s	~85%	细节更多，成本更高
qwen/qwen3.6-plus	经济型	~$0.0058	44.2s	~95%	准确但较慢
qwen/qwen3.6-flash	经济型	~$0.0027	16.6s	~80%	有时会误读主体
google/gemini-3.1-pro-preview	标准型	~$0.0199	19.7s	100%	基准（效果最好、成本最高）

与 Pro 基准模型相比，flash-lite 能以低约 14 倍的成本正确识别完整场景、动作序列和转场。 若要获得最高准确率（角色名称准确、细节丰富），请在 config/video-analysis.yaml 中将 default_model 切换为 gemini-3.1-pro-preview 或 gemini-3.5-flash。

提取模式（大型视频）

对于超过大小阈值的视频，技能会提取关键帧并转录音频：

• 短视频（≤60s）： 每隔 N 秒提取一帧（默认：2s）
• 长视频（>60s）： 通过场景变化检测选取视觉上差异明显的帧
• 音频： 提取后发送给 Whisper 转录
• 最大帧数： 上限为 30（可配置），以控制成本

Agent 会收到帧图片路径和转录文本，然后将它们作为图片附件和上下文文本 提供给当前聊天模型。

配置

在工作区中编辑 config/video-analysis.yaml 进行自定义。此文件 会在首次使用时自动创建，只需包含要覆盖的键，并且 不会因技能更新而被覆盖。

请勿编辑 skills/video-analysis/config.yaml — 该文件是出厂默认配置， 每次技能自动更新时都会被覆盖。用户配置文件会在其基础上叠加。

独立技能和聊天中的“发送视频”流程都会读取同一份配置， 因此只需编辑一次，就能更改各处使用的模型。可用的键：

# Model for native video understanding
default_model: google/gemini-3.1-flash-lite

# Size threshold: native (≤) vs extraction (>)
# Set to 0 → always extraction. Set to 100 → always native.
native_size_limit_mb: 20

# Frame extraction settings
extraction:
  max_frames: 30                  # Max keyframes to extract
  short_video_interval_sec: 2     # Frame interval for ≤60s videos
  scene_threshold: 0.3            # Scene detection sensitivity (0.0-1.0)
  transcribe_audio: true          # Whether to Whisper-transcribe audio

可用的视频模型

模型	别名	层级	备注
google/gemini-3.1-flash-lite	flash31	经济型	⭐ 默认，性价比最高
google/gemini-3.5-flash	gemini35	标准型	细节更多，成本更高
google/gemini-3.1-flash-lite	flash31	经济型	价格最低的选项
google/gemini-3.1-pro-preview	gemini	标准型	质量最高
qwen/qwen3.6-flash	qwenf	经济型	不错的替代选项
qwen/qwen3.6-plus	qwen	经济型	—
minimax/minimax-m3	mm3	标准型	—
meta-llama/llama-4-maverick	maverick	标准型	—
meta-llama/llama-4-scout	scout	经济型	—
xiaomi/mimo-v2.5	mimo	标准型	—
z-ai/glm-5v-turbo	glm5v	标准型	—
minimax/minimax-m2.7	mm27	经济型	仅音频，不支持图片

Agent 行为

当用户提供视频文件（通过上传或文件路径），且当前 聊天模型不支持视频时：

1. 调用 analyze_video(path, question)。
2. 如果结果模式为 "native" → 直接返回 result["analysis"]。
3. 如果结果模式为 "extraction" → 将 result["frame_paths"] 作为图片 引用，并将 result["transcript"] 作为上下文，然后让当前模型根据帧图片和转录文本进行分析。

当当前模型支持视频时，后端会通过 Phase 1（注入 base64 内容块）原生处理视频 — 无需使用此技能。

故障排除

问题	解决方法
"File not found"	检查路径是否为相对于工作区的路径（例如 output/videos/x.mp4）
原生模式返回错误	检查 config/video-analysis.yaml 中的 default_model 是否有效
没有音频转录	视频可能没有音轨；检查结果中的 has_audio
提取的帧太少	降低 config/video-analysis.yaml 中的 scene_threshold（例如 0.15）
帧太多／成本太高	减少 max_frames 或提高 scene_threshold