Video Analysis Skill
分析视频文件的属性与特征，输出基础参数 + 卡顿检测结果。
功能
-
基础属性提取（通过 ffprobe）：
- 码率（bit_rate，bps 与 Mbps）
- 帧率（标称帧率 + 实际平均帧率）
- 分辨率（宽 x 高）
- 文件大小（字节 + 可读格式）
- 时长
- 视频编码格式、音频编码格式 -
卡顿检测（基于 PTS 时间戳序列分析）：
- 突发卡顿：某帧 PTS 间隔 > 正常间隔的 2.5 倍（阈值可配）
- 持续卡顿：实际平均帧率 < 标称帧率的 85%，判定为整体帧率不足
- 卡顿可能有 1 个或多个，以列表记录，含卡顿起始时间点、持续时长、间隔值
入口脚本: video_analysis.py
用法
命令行
python skills/video-analysis-skill/scripts/video_analysis.py --video <视频路径> [--threshold 2.5] [--output <结果目录>]
参数
| 参数 | 说明 | 默认值 |
|---|---|---|
--video / -v |
待分析视频文件路径（必填） | 无 |
--threshold |
突发卡顿判定倍数（相邻帧间隔 > 正常间隔×此值 视为卡顿） | 2.5 |
输出
{
"video_path": "C:/Users/admin/Downloads/1.mp4",
"basic_info": {
"duration_s": 30.6,
"duration_readable": "00:00:30.60",
"size_bytes": 5511421,
"size_readable": "5.26 MB",
"bit_rate_bps": 1440894,
"bit_rate_mbps": 1.44,
"video_codec": "hevc",
"audio_codec": "aac",
"width": 2304,
"height": 1296,
"nominal_fps": 20.0,
"actual_fps": 15.0,
"frame_count": 459
},
"stutter_detection": {
"detected": true,
"type": "frame_rate_insufficient",
"summary": "实际帧率(15.0fps)低于标称帧率(20.0fps)的85%，判定为持续卡顿",
"normal_interval_s": 0.05,
"threshold_multiplier": 2.5,
"stutters": [
{
"index": 145,
"time_s": 7.25,
"interval_s": 0.1,
"duration_s": 0.1,
"reason": "帧间隔(0.10s)超过正常间隔(0.05s)的2.5倍"
}
]
},
"result": {
"passed": true,
"messages": "视频分析完成：分辨2304x1296, 码率1.44Mbps, 帧率15.0fps, 检测到卡顿2处"
},
"test_time": "2026-08-19 16:00:00"
}
结果字段
| 字段 | 类型 | 说明 |
|---|---|---|
video_path |
str | 视频文件路径 |
basic_info |
dict | 视频基础属性（见上） |
stutter_detection |
dict | 卡顿检测结果 |
stutter_detection.detected |
bool | 是否检测到卡顿 |
stutter_detection.type |
str | 卡顿类型（burst_single / frame_rate_insufficient / both / none） |
stutter_detection.stutters |
list | 卡顿事件列表（可多个） |
result.passed |
bool | 整体执行结果（分析成功即 true） |
result.messages |
str | 结果描述 |
test_time |
str | 测试时间 |
输出目录
结果 JSON 写入：workspace/test_output/video-analysis-skill/（文件名：<时间戳>.json，如 20260819_161508.json）
> 说明：本技能不接入三层唯一ID / 测试套件调度，结果文件使用纯时间戳命名。
依赖
ffprobe（FFmpeg 套件）必须在系统 PATH 中- Python 3.6+
变更记录
- v1.0.0 (2026-08-19): 初始版本，视频属性提取 + 卡顿检测技能
