/video-compressor

name: video-compressor
description: 视频压缩与静默片段剪切工具。使用 FFmpeg CRF 模式压缩视频，适配屏幕录制/课件场景；支持检测并去除静默静止片段。自动检测硬件与源码率并选择最优编码方案（高码率源走 VideoToolbox 硬件加速，低码率录屏自动改用 x264 CRF 自适应编码）。本技能应在用户需要压缩视频、减小视频大小、去除视频空档时使用。不要用于：视频剪辑、音频提取、格式转换。
author: 杨卫薪律师（微信ywxlaw）
homepage: https://github.com/cat-xierluo/legal-skills
version: "1.5.2"
license: MIT

video-compressor — 视频压缩工具

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

适用场景

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

功能模式

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

模式一：压缩（默认）

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

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

检测并去除视频中**同时满足**以下条件的片段： 1. **音频静默**（无声） 2. **画面静止**（连续帧几乎无变化，如休息时无操作、黑屏）

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

默认工作流（压缩模式）

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 | 因机型散热条件差异极大，**须以实际探测为准**（见下方实测备注） | HEVC/H.265 | 自动使用硬件编码 | | Apple Silicon (备用) | h264_videotoolbox | 同上 | H.264 | HEVC 不可用时的回退 | | 其他平台 | libx264 | 1x 实时 | H.264 | 标准软件编码 |

> **实测参考（MacBook Air M1 无风扇，8GB）：** > - x264 veryfast CRF28 软编：约 **5–7× 实时**（单进程）；4–6 并发时约 **10× 实时**（已达该机型热降频天花板），更多并发反而下降 > - HandBrake `vt_h264`：比 x264 快约 **15%**，但输出体积大 **60%**，收益不高 > - **brew ffmpeg 内置 VideoToolbox 硬解链路不可用**（`hwaccel_output_format=videotoolbox` 报 `Unrecognised hwaccel output format`，brew 构建未含 VT 硬件帧输出） > - `preset` 升降档（ultrafast ↔ veryfast）对 x264 速度影响可忽略，不值得为提速降 preset

> 速度提示：上述数值为实际测试参考范围，实际速度受分辨率、帧率、画质参数、系统负载影响。**并发吞吐测试必须校验每个子进程的 rc**（return code）；进程秒退会留下"高速"的假象，必须在运行时检查实际输出文件大小和编码耗时。录屏/课件源码率特征为 ≤3Mbps，压缩前先 `ffprobe -v error -show_entries format=bit_rate -of csv=p=0 <file>` 确认。

> 录屏/课件源码率陷阱（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 输出**：所有输出文件