视频分析

使用本技能可将已授权的视频文件或直接视频 URL 转换为带时间戳、可审计的分析报告。远程模型**不会接收原始 MP4/WebM 流**。该工作流在本地解码视频，提取带时间戳的 JPEG 帧与语音转录文本；仅当显式配置后，才将帧发送至选定的视觉模型提供商，将文本证据发送至选定的合成模型提供商。

仅接受已授权输入

支持以下任意一种输入：

• 用户已被授权分析的本地视频文件。
• 公开可访问的、直接的 http:// 或 https:// 媒体 URL，例如公开的 .mp4 或 .webm 资源。
• 启用 --allow-platform 参数后，支持公开的视频平台页面（例如 Bilibili 或 YouTube 的 watch 链接）。该技能通过 yt-dlp 获取其中唯一的公开视频，并在本地进行后续处理。

平台页面抓取能力被刻意限制，且这些限制**不得放宽**：

• 仅限公开、匿名可访问的视频。禁止发送 Cookie、密码或任何需身份验证的请求头；禁止执行登录操作；禁止访问会员专属、私有、仅好友可见或年龄限制内容。
• 不绕过 DRM 保护。受 DRM 保护的流媒体将被明确拒绝，并返回诚实的错误提示，而非尝试解密。
• 每次运行仅处理单个视频（--no-playlist）；禁止批量爬取、播放列表或频道内容。
• 用户须自行遵守目标平台的服务条款，并确保自身具备分析该内容的合法授权。

若平台视频需登录或会员权限，请勿尝试绕过：应请用户提供已授权的原始文件、直接导出的公开版本，或平台官方 API/导出路径。

URL 抓取器会屏蔽本地地址、私有地址、链路本地地址（link-local）、保留地址及元数据服务地址。请勿弱化此类检查。

工作流

1. 安装或运行流水线前，请先执行预检检查：

   python "$HOME/.claude/skills/video-analysis/scripts/preflight.py" --json
   

   Windows 系统下，若当前 Shell 无法展开 $HOME，请使用完整路径。

2. 如缺少必要依赖，请明确说明，而非静默安装包或添加密钥。流水线需依赖 ffmpeg 和 ffprobe；完整语音转录需 faster-whisper；远程语义处理阶段需官方 openai Python SDK 及用户指定的提供商对应环境变量密钥；启用 --allow-platform 进行平台页面抓取时，还需 yt-dlp。

3. 选择模型提供商。远程处理阶段默认禁用；但若用户提供 OpenAI 兼容端点，则是最简配置：只需提供 API 密钥、基础 URL 和模型名称即可。通过 CUSTOM_API_KEY 环境变量（或使用 --custom-api-key-env 指定其他变量名）传入密钥，并配合 --custom-base-url 和 --custom-model 参数。当三者均存在且未指定其他提供商标志时，流水线将自动为视觉与合成两个阶段选用该自定义提供商。任何支持图像输入的模型均可使用；流水线会在批量发送帧前，先用单张测试图像验证模型是否真正支持图像输入；若所选模型仅支持文本输入，则自动降级为生成诚实的本地报告，而非报错失败。

   否则请显式指定提供商：

   • --vision-provider {none,openai,xai,custom} 控制帧理解阶段。custom 表示使用用户提供的 OpenAI 兼容端点，并需显式指定模型名称；该模型必须支持图像输入。
   • --synthesis-provider {none,openai,xai,deepseek,custom} 控制文本报告生成阶段。DeepSeek 托管 API 为纯文本接口，**永不接收图像**。
   • API 密钥仅从环境变量读取：OPENAI_API_KEY、XAI_API_KEY、DEEPSEEK_API_KEY 或 CUSTOM_API_KEY（变量名可通过 --custom-api-key-env 自定义）。

   运行分析器。建议优先从本地文件启动：

   python scripts/analyze_video.py 
     --input "C:\videos\demo.mp4" 
     --output-dir "C:\video-results\demo" 
     --frame-interval 3 
     --vision-provider openai 
     --synthesis-provider deepseek 
     --keep-artifacts
   

   针对已授权的直接 URL：

   python scripts/analyze_video.py 
     --url "https://media.example.com/public-demo.mp4" 
     --output-dir "./video-results/public-demo" 
     --max-download-bytes 262144000 
     --vision-provider xai 
     --synthesis-provider openai
   

   针对公开视频平台页面（单个公开视频，无需登录/无 Cookie；需已安装 yt-dlp）：

   python scripts/analyze_video.py 
     --url "https://www.bilibili.com/video/BVxxxxxxxxxx/" 
     --output-dir "./video-results/platform-demo" 
     --allow-platform 
     --language zh 
     --skip-vision
   

   针对自定义 OpenAI 兼容端点（密钥、端点与模型均由用户提供）。若用户直接向您提供 API 密钥，请在命令行中以内联方式设置，切勿持久化存储，且绝不可将其回显至报告中：

   CUSTOM_API_KEY="<用户提供的密钥>" python scripts/analyze_video.py 
     --input "C:\videos\demo.mp4" 
     --output-dir "C:\video-results\demo" 
     --custom-base-url https://api.relay.example/v1 
     --custom-model gpt5.6-luna
   

   --custom-model 同时应用于两个阶段；当密钥已设置时，自定义提供商将自动用于视觉与合成阶段。若需为各阶段指定不同模型，请显式声明：--vision-provider custom --vision-model <名称> --synthesis-provider custom --synthesis-model <名称>。

   PowerShell 中请改用：$env:CUSTOM_API_KEY="<密钥>"; python scripts/analyze_video.py ...。若密钥已存在于其他命名的环境变量中，请使用 --custom-api-key-env OTHER_VAR。视觉阶段所用模型必须支持图像输入；流水线将在批量发送帧前，先提交一张测试图像以验证模型兼容性。

4. 从输出目录中读取 analysis.json 和 report.md。描述视频内容时请引用具体时间范围。若报告中列出缺失的模态（modality），请如实陈述该限制，切勿虚构内容。

运行时行为

• ffprobe 在处理前检查视频时长与媒体流信息。
• 启用 --allow-platform 后，若 URL 返回 HTML 页面而非直接媒体资源，则通过 yt-dlp（启用 --no-playlist、施加大小与时长上限、绝不使用 Cookie 或登录）获取其中唯一的公开视频。对需登录、会员专属、私有或受 DRM 保护的内容，将明确拒绝并注明限制原因，而非尝试绕过。报告的来源（provenance）字段将记录该媒体源自平台提取。
• ffmpeg 输出 16 kHz 单声道 WAV 音频与限定数量的关键帧 JPEG 图像。默认采样间隔为每 3 秒一帧，适用于典型短视频；UI/PPT 教程类视频建议设为 1–2 秒；访谈类“讲话人”视频建议设为 3–5 秒。
• faster-whisper 生成带时间戳的语音转录片段。ASR 失败可报告但非致命：流水线将写入空的 transcript.json 并继续使用可用的视觉证据进行后续处理。
• 当启用 --vision-provider openai 或 --vision-provider xai 时，官方 openai Python SDK 将 JPEG 帧以 Base64 编码的 data URL 形式分批发送至所选模型。每个返回的观测结果均强制映射回本地生成的原始时间戳。
• 当启用 --vision-provider custom 时，用户提供的 OpenAI 兼容端点将通过 Chat Completions 的 image_url 内容部分接收相同 JPEG 帧。在批量发送前，流水线会先提交一张测试图像，确认所命名模型确实支持图像输入；若端点拒绝该测试请求，则中止帧理解流程，并明确标注该限制，而非让后续每一批次都失败。
• 当同时提供自定义基础 URL、模型名称（--custom-model 或按阶段分别指定）及自定义 API 密钥，且未显式指定提供商标志时，两个阶段将自动选用该自定义提供商；该自动选择行为将在报告的限制说明与来源信息中明确披露。
• 当启用 --synthesis-provider openai、xai、deepseek 或 custom 时，**仅将文本时间线证据**发送至该提供商。DeepSeek 与自定义合成服务**永不接收图像**。
• 若所选提供商调用失败，则自动降级为确定性的本地报告；**绝不会静默切换至其他供应商，也绝不将中间产物发送至其他位置**。
• 流水线将语音转录与视觉观测结果对齐，划分为五分钟的时间窗口，并最终生成 JSON 报告与可读的 Markdown 报告。
• 默认最大视频时长为 10 分钟。对于更长的已授权源视频，请主动增大 --max-duration 参数值，并配合使用 --segment-seconds 300；报告仍将按时间窗口划分。请勿尝试逐帧处理。

离线与分阶段验证

同时使用两个跳过标志，可在无模型凭证或 ASR 模型的情况下验证解码与输出流程：

python scripts/analyze_video.py 
  --input sample.mp4 
  --output-dir ./video-results/offline-check 
  --skip-asr --skip-vision

这是离线媒体流水线检查，而非视频理解结果。它将生成 media.json、frames.json、timeline.json、analysis.json 与 report.md，并将音频与视觉理解标记为不可用。

输出契约

输出目录包含以下文件：

• media.json —— ffprobe 元数据与源信息。
• transcript.json —— ASR 生成的带时间戳片段（仅当启用 ASR 时生成）。
• frames.json —— 关键帧路径与估算的源时间戳。
• vision.json —— 提供商返回的帧观测结果与批次错误（仅当启用视觉分析时生成）。
• timeline.json —— 合并后的时间窗口。
• analysis.json —— 标题、摘要、章节、关键时刻、限制说明与来源信息。
• report.md —— 面向用户的可读报告。

临时下载的媒体文件、WAV 音频与 JPEG 帧在处理完成后将被自动删除，除非指定 --keep-artifacts。由调用方提供的本地源视频文件**永远不会被删除**。

失败处理

• 将 URL 被拦截、下载失败、平台抓取被拒（因需登录/会员/DRM）、ffprobe 错误、ASR 失败、视觉分析失败及合成失败，视为彼此独立的、可报告的错误类型。
• 若后续阶段失败，仍应保留此前已成功生成的 JSON 中间产物。
• 若任一模态（modality）被跳过、不可用或失败，不得声称端到端分析已成功完成。
• 在真实外部 URL 运行前，请提前告知用户：该操作将下载媒体资源，并可能消耗 ASR 计算资源及用户显式选定的 OpenAI、xAI、DeepSeek 或自定义提供商的额度。