video-scene-analyzer

视频场景分析器

检测视频文件中的场景边界，并生成结构化 JSON，其中包含内容摘要、制作标签以及每个场景的视觉素材库。

前提条件

需要 ffmpeg 和 ffprobe。请验证：

ffmpeg -version && ffprobe -version

如果缺少，请告知用户并停止。

此技能内置了自己的 videx 脚本，位于相对于 SKILL.md 的 scripts/videx。请解析出完整路径：

VIDEX="$(dirname "$(realpath "<path-to-SKILL.md>")")/scripts/videx"

工作流概览

分两个阶段：

1. 阶段 1 -- 概览：提取低分辨率帧，逐一查看并识别场景边界
2. 阶段 2 -- 深入分析：按场景提取高分辨率帧，生成详细元数据
3. 输出：写入 analysis.json + 对话摘要

阶段 1：概览扫描

步骤 1：获取视频元数据

ffprobe -v error -show_entries format=duration,size -show_entries stream=codec_name,width,height,r_frame_rate -of default=noprint_wrappers=1 <video>

记录时长、分辨率和 fps，以写入输出 JSON。

步骤 2：提取概览帧

根据时长选择间隔：

时长	间隔	命令
< 5 min	2s	$VIDEX overview <video> 2 320 0.5
5-30 min	5s	$VIDEX overview <video> 5 320 0.5
> 30 min	10s	$VIDEX overview <video> 10 320 0.5

使用 triplet=0.5（分布更宽），让转场清晰可见。

步骤 3：查看所有概览帧

使用 Read 工具按时间顺序查看每个 _b（中心）帧。如果帧很多，请每批查看 20-30 个。

对于 _b 帧看起来像转场（模糊、混合、淡入淡出）的时间点，也要查看 _a 和 _c 帧。

步骤 4：检测场景边界

比较连续的 _b 帧。出现以下情况时，视为存在场景边界：

• 硬切：连续帧之间的内容完全不同
• 叠化/淡化：画面显示混合，或淡入/淡出至黑色/白色
• 重大变化：主体相同，但场景、角度或构图明显不同

经验法则：不确定时，优先拆分。用户可以合并场景，但无法拆分此前漏掉的场景。

记录每个边界的以下信息：

• 大致时间戳（两个采样点之间的中点）
• 转场类型（切镜、叠化、淡入黑场、淡出黑场、淡入白场、淡出白场、划像）

第一帧始终是场景 1 的开头。最后一个采样点是最后一个场景的结尾（使用视频时长）。

步骤 5：报告场景列表

继续之前，向用户展示场景列表：

Scene 1: 0:00 - 0:04 (cut)
Scene 2: 0:04 - 0:07 (dissolve)
...

询问用户是否要调整边界，或直接继续。

阶段 2：场景深入分析

步骤 6：提取场景帧

为每个场景提取宽度为 1280 px 的帧：

$VIDEX range <video> <start>-<end> --triplet=0.2

短场景（< 2s）：添加 --fps=5 长场景（> 30s）：默认 2fps 即可。

步骤 7：分析每个场景

查看该场景提取的所有帧。确定以下内容：

内容摘要：2-4 句话。描述主体、动作、场景、道具和可见文字。

制作标签：

标签	值
camera_angle	平视、低角度、高角度、鸟瞰、荷兰角、过肩、主观视角
shot_size	极远景、远景、中远景、中景、中近景、近景、特写
camera_movement	固定、左摇、右摇、上倾、下倾、推近、拉远、前移、后移、跟拍、手持、升降、斯坦尼康
color_tone	暖色、冷色、中性、低饱和、高对比度、低对比度、单色、霓虹、柔和色调、大地色系
lighting	自然光、人造光、高调、低调、逆光、侧光、顶光、剪影、混合光
tempo	静态、缓慢、适中、快速、狂乱

文字叠加：

• placement：无、下三分之一处、居中、顶部、全屏、水印
• content：实际可见的文字；若无则为 null

转场：

• in：场景如何开始（第一个场景为 none）
• out：场景如何结束（最后一个场景为 none）

如果某个标签在场景中途发生变化，请使用占主导地位的值，并在 notes 中注明变化。

步骤 7b：构建素材库

分析场景时，整理整个视频中每个不同的视觉素材。针对每个素材，记录：

字段	说明
id	Kebab-case 格式的唯一标识符（例如，student-summer、logo-brand）
type	character、background、icon、ui-screen、photo、product、logo、decoration、text-graphic、effect
label	一行易读的描述，包含关键视觉特征
style	anime-illustration、flat-design、realistic-photo、3d-render、hand-drawn、typography、mixed
appears_in	该素材出现的场景编号数组

指南：

• 更换服装的角色应分别列出（例如，student-summer、student-winter）
• 同一图标出现在多个场景中 = 一个条目，包含所有场景编号
• 仅列出有辨识度的背景（跳过通用的白色／黑色背景）
• label 应简洁，但需包含足以辨认素材的细节（颜色、姿势、尺寸、显著特征）

完整类型参考和示例请参见 references/schema.md。

步骤 8：编写 analysis.json

根据 references/schema.md 中的架构，整理完整的 JSON。

写入：./videx-out/<video-name>/analysis.json

步骤 9：对话摘要

写入 JSON 后，提供：

1. 场景总数和视频时长
2. 每个场景一行摘要，并标注时间戳
3. 素材库摘要（总数、类型分布）
4. 视频中值得注意的制作规律

边缘情况

• < 10 秒：使用 1 秒间隔。可以只有一个场景。
• > 1 小时：使用 10 秒间隔。分批读取概览帧。
• 静态内容（幻灯片／屏幕录制）：幻灯片切换处即为场景边界。注明 camera_movement: static。
• 边界模糊：优先拆分，不要合并。

输出位置

./videx-out/<video-name>/
├── overview/          (Pass 1)
├── range_*/           (Pass 2)
└── analysis.json      (final output)