video-compressor — 视频压缩工具

使用 FFmpeg 将视频文件压缩为低比特率 MP4，减小文件体积的同时保留清晰的音频。自动检测硬件并选择最优编码方案（Apple Silicon 默认使用 VideoToolbox 硬件加速）。

适用场景

视频文件过大，只需保留音频信息，视频画面作为辅助参考
批量压缩目录下多个视频文件
降低视频比特率以节省存储空间
去除视频中间的静默静止片段（如休息时间、黑屏、无声空档），同时保留被剪片段供复查

功能模式

本技能支持两种工作模式：

模式一：压缩（默认）

将视频压缩为低比特率 MP4，减小文件体积。

模式二：静默/静止片段剪切

检测并去除视频中同时满足以下条件的片段：

音频静默（无声）
画面静止（连续帧几乎无变化，如休息时无操作、黑屏）

适用于：课程录制中途休息、会议室无人时的静默等待等无效内容。

默认工作流（压缩模式）

1. 确认输入

确认用户提供的文件路径或目录路径。支持以下视频格式：

.mp4 .mov .avi .mkv .webm .flv .wmv .ts

2. 确认参数

默认配置（大多数场景无需调整）：

参数	默认值	说明
CRF 质量值	23	自适应质量，越小质量越高（仅软件编码）
最大码率	2500k	VBV 码率上限
音频比特率	96k	AAC 语音音质
编码预设	veryfast	速度与压缩比平衡（仅软件编码）
编码器	自动检测	Apple Silicon 默认 HEVC VT，其他 x264
并发线程	自动	VideoToolbox 默认 1（共享硬件编码器，多并发反而慢），软件编码默认 ≤8
输出后缀	`_compressed`	输出文件名后缀

详细配置说明见 references/config.md。

3. 执行压缩

# 单个文件
python3 scripts/compress.py -i <文件路径>

# 多个文件（并发压缩）
python3 scripts/compress.py -i <文件1> <文件2> <文件3>

# 整个目录
python3 scripts/compress.py -i <目录路径>

# 混合：文件 + 目录
python3 scripts/compress.py -i <文件1> <目录路径> <文件2>

指定自定义参数：

python3 scripts/compress.py -i <文件1> <文件2> --crf 28 -a 64k --preset medium -j 2

4. 输出报告

压缩完成后输出每个文件的结果：

文件名                    原始大小    压缩后大小   压缩比
video1.mp4                120.5 MB    28.3 MB     76.5%
─────────────────────────────────────────────────
合计                       205.7 MB    47.4 MB     77.0%

静默/静止片段剪切工作流

何时使用

当用户提到以下场景时使用此模式：

视频中间有休息时间，需要剪掉
视频有长时间静止/无声的片段
去除录制中的空档、静默、黑屏

1. 执行剪切

python3 scripts/trim_silences.py -i <视频文件路径>

使用默认参数（同时检测静音+静止，最短3秒才计入）。

指定自定义参数：

# 仅检测静音片段（不考虑画面是否静止）
python3 scripts/trim_silences.py -i <路径> --mode silence

# 仅检测画面静止片段（不考虑是否有声音）
python3 scripts/trim_silences.py -i <路径> --mode static

# 自定义阈值：更严格的静默检测
python3 scripts/trim_silences.py -i <路径> --noise-db -40 --min-duration 5

模式选择建议

视频类型	推荐模式	说明
课程录制休息时	`both`	同时满足静音+静止，不误剪
会议无人时段	`both` 或 `static`	若全程有空调白噪声用 `both`
比赛/电影解说（全程有声音）	`static`	仅剪画面静止部分
监控录像（画面固定）	`static`	几乎不需要音频

2. 理解输出

剪切完成后，输出：

文件	说明
`原文件名_trimmed.mp4`	精剪版（去除了目标片段）
`原文件名_cuts/`	存放被剪片段的目录
`原文件名_cuts/_report.json`	被剪片段的时间戳报告

被剪片段目录中，每个片段保存为一个独立的 MP4 文件，文件名包含起止时间，方便复查。

3. 参数说明

参数	默认值	说明
`--noise-db`	-30	静默检测分贝阈值，越小越严格
`--scene-threshold`	0.05	画面静止阈值 0~1，越小越严格（轻微页面变化可接受）
`--min-duration`	120	最短片段时长(秒)，默认2分钟，仅剪掉长片段
`--mode`	both	检测模式：both=同时静音+静止，silence=仅静音，static=仅画面静止
`--crf`	23	CRF 质量值
`--maxrate`	2500k	最大码率限制
`--bufsize`	2500k	VBV 缓冲区大小
`--audio-bitrate`	96k	输出音频比特率
`--preset`	veryfast	编码预设
`--codec`	自动检测	编码器选择（hevc_vt / h264_vt / x264 / x265 / x264_fast）

硬件加速

本工具自动检测系统硬件并选择最优编码方案：

平台	编码器	速度提升（实测）	输出格式	说明
Apple Silicon (M1/M2/M3/M4)	hevc_videotoolbox	2-5x（1080p60） / 5-15x（720p30）	HEVC/H.265	自动使用硬件编码
Apple Silicon (备用)	h264_videotoolbox	2-4x（1080p60） / 4-10x（720p30）	H.264	HEVC 不可用时的回退
其他平台	libx264	1x 实时	H.264	标准软件编码

速度提示：上述数值为实际测试参考范围，实际速度受分辨率、帧率、画质参数、系统负载影响。1080p60 高帧率场景下 VideoToolbox 实际约 2-5x 实时（而非 5-15x），3 小时视频约需 50 分钟。

录屏/课件源码率陷阱（v1.5.0 已自动化）：压缩前先 ffprobe 查源文件 bit_rate。硬件路径（hevc_vt/h264_vt）在 hw_detect.py 中写死目标码率 2000k 且忽略 --crf/--maxrate 参数；源总码率 ≤3 Mbps（录屏/课件特征）时脚本自动选用 x264 CRF 自适应编码并打印提示，高码率源仍走硬件路径，--codec 显式指定可覆盖自动选择。CRF 自适应对静止画面几乎不耗码率，实测录屏压缩比 80-88%、速度 12-20x 实时。手动估算可用 60 秒采样：ffmpeg -ss <中段> -t 60 -i 输入 -c:v libx264 -crf 23 ... 看采样大小推算全片。

启动时自动打印检测结果，如：

硬件检测: Apple Silicon (10 核 / 64 GB)
编码器: HEVC VideoToolbox (硬件加速) — 实际 1080p60 约 2-5x 实时
FFmpeg: 9.0 (VideoToolbox 支持: H.264 + HEVC)

手动指定编码器：

python3 scripts/compress.py -i <路径> --codec hevc_vt   # 强制 HEVC 硬件编码
python3 scripts/compress.py -i <路径> --codec h264_vt   # 强制 H.264 硬件编码
python3 scripts/compress.py -i <路径> --codec x264      # 强制软件编码
python3 scripts/compress.py -i <路径> --codec x265      # 软件 HEVC 编码（高压缩）

可选编码器：hevc_vt h264_vt x264 x265 x264_fast

长视频与 detach 模式

对超过 30 分钟的视频，建议加 --detach 启动：

python3 scripts/compress.py -i <长视频.mp4> --codec hevc_vt --detach

--detach 行为：

脚本启动 ffmpeg 后立即返回 PID，不等待完成
ffmpeg 进程脱离脚本会话组（start_new_session），脚本被杀不影响编码
日志写入 /tmp/ffmpeg_<视频名>_<时间戳>.log，可用 tail -f 跟踪

故障排查

ffmpeg 二进制启动崩溃（dyld Library not loaded）

症状：脚本启动后立即报"dyld Symbol not found"或"Library not loaded"。

原因：典型场景是 brew upgrade 升级某个依赖库（如 x265）后，ffmpeg 未重新链接；ffmpeg 二进制仍在引用旧版本符号。

修复：

brew upgrade ffmpeg        # 让 ffmpeg 重新链接到新依赖
# 或
brew reinstall ffmpeg      # 完全重装

新版脚本会在启动时主动检测 ffmpeg 健全性，崩溃时立即输出诊断和修复命令，不再静默 fallback。

完整 stderr 日志

失败时完整 ffmpeg 日志保存在 /tmp/ffmpeg_<视频名>_<时间戳>.log，不再被截断丢失关键诊断信息。

硬约束

不覆盖原文件：输出文件始终添加后缀
不静默覆盖旧输出：输出文件已存在时自动改用 _compressed_2 等序号递增，--overwrite 才允许覆盖
输出到同目录：精剪版和被剪片段目录都与原文件在同一目录
保留音频质量：音频使用 AAC 编码，默认 96k
固定 MP4 输出：所有输出文件均为 MP4 格式（硬件编码 HEVC/H.264 + AAC，软件编码 x264 + AAC）
长视频一律 --detach：预期超过几分钟的编码必须加 --detach（ffmpeg 脱离进程组，会话超时/终止不影响编码）；同步模式或终端托管后台都实测被杀过，残缺输出无 moov atom 不可播放

依赖

依赖	版本要求	安装方式
`ffmpeg`	≥ 5.0（推荐 ≥ 7.0 for VideoToolbox `-q:v`）	`brew install ffmpeg`
`Python`	≥ 3.9（脚本已兼容系统自带 python3）	系统自带或 `brew install python`

与其他技能配合

可与 universal-media-downloader 配合：下载视频后压缩节省空间
可与 local-asr / tingwu-asr 配合：压缩后再转录，减少文件传输时间

/video-compressor

SKILL.md