video-compressor
视频压缩与静默片段剪切工具。使用 FFmpeg CRF 模式压缩视频，适配屏幕录制/课件场景；支持检测并去除静默静止片段。自动检测硬件与源码率并选择最优编码方案（高码率源走 VideoToolbox 硬件加速，低码率录屏自动改用 x264 CRF 自适应编码）。本技能应在用户需要压缩视频、减小视频大小、去除视频空档时使用。不要用于：视频剪辑、音频提取、格式转换。
- Installs
- 67
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cat-xierluo/legal-skills --skill video-compressor- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads video-compressor automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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 | 因机型散热条件差异极大，须以实际探测为准（见下方实测备注） | 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 输出：所有输出文件均为 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配合：压缩后再转录，减少文件传输时间
FAQ
What does the video-compressor skill do?
视频压缩与静默片段剪切工具。使用 FFmpeg CRF 模式压缩视频，适配屏幕录制/课件场景；支持检测并去除静默静止片段。自动检测硬件与源码率并选择最优编码方案（高码率源走 VideoToolbox 硬件加速，低码率录屏自动改用 x264 CRF 自适应编码）。本技能应在用户需要压缩视频、减小视频大小、去除视频空档时使用。不要用于：视频剪辑、音频提取、格式转换。
How do I install video-compressor?
Run npx skills add https://github.com/cat-xierluo/legal-skills --skill video-compressor in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/video-compressor/ (personal) or .claude/skills/video-compressor/ (project).
Which AI agents can use video-compressor?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is video-compressor safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains video-compressor?
It is published by cat-xierluo in cat-xierluo/legal-skills. It has 67 recorded installs.
More from cat-xierluo/legal-skills
multi-search
cat-xierluo/legal-skills
智能多主题深度研究工具，支持任意材料输入，使用独立研究 Agent进行并行深度检索并生成系统化研究文档。本技能应在用户需要深度研究多个相关课题、进行系统性信息检索、整合多角度分析时使用。
douyin-batch-download
cat-xierluo/legal-skills
抖音视频批量下载工具 - 基于 F2 框架实现高效、增量的视频下载功能。支持单个/批量博主下载，自动 Cookie 管理，差量更新机制。本技能应在用户需要批量下载特定博主视频、服务器部署自动化下载、或定期更新视频库时使用。
litigation-analysis
cat-xierluo/legal-skills
判决书深度分析。本技能应在用户需要读懂一份判决书、拆解法院事实认定与裁判理由、解释判决主文或提炼文内疑点时使用。不要用于起诉状与证据初评、庭审笔录复盘、多材料综合研判或完整上诉再审决策；这些任务使用 legal-case-analysis。
md2word
cat-xierluo/legal-skills
Open the skill to read its SKILL.md instructions.
funasr-transcribe
cat-xierluo/legal-skills
Open the skill to read its SKILL.md instructions.
legal-proposal-generator
cat-xierluo/legal-skills
Open the skill to read its SKILL.md instructions.
Popular media & creative skills
hyperframes
heygen-com/hyperframes
Read first to make, edit, animate or render any video with HyperFrames (HTML rendered to video), including launch films, explainers, music videos, charts, maps, vertical clips, title cards, captions and overlays. Holds the render contract, the work loop and what each kind of video needs.
media-use
heygen-com/hyperframes
Get or make any media for a HyperFrames video - music, sound effects, images, icons, logos, voiceover, avatar and generated video, transcripts, cutouts, colour grades and looks - with HeyGen or free local tools, and mix placed audio. Also for footage that looks dark, flat or dull, or should be stylized or hidden.
hyperframes-registry
heygen-com/hyperframes
About 450 ready-made HyperFrames blocks and components installed as editable source - transitions, overlays, titles, kinetic type, captions, charts, map overlays, 3D, camera moves. Use it before hand-building any named visual (CRT scanlines, glitch, film grain, a chart); also for hyperframes add and catalog.
hyperframes-creative
heygen-com/hyperframes
Non-animation creative direction for HyperFrames videos. Use for design spec (frame.md / design.md) handling, palettes, typography, narration, beat planning, audio-reactive visuals, composition patterns, and brand / style decisions. For atomic motion patterns and scene blueprints, use hyperframes-animation.
ai-video-generation
101-skills/superpowers
Generate AI videos with Google Veo, Seedance 2.0, HappyHorse, Wan, Grok and 40+ models via inference.sh CLI. Models: Veo 3.1, Veo 3, Seedance 2.0, HappyHorse 1.0, Wan 2.5, Grok Imagine Video, OmniHuman, Fabric, HunyuanVideo. Capabilities: text-to-video, image-to-video, reference-to-video, video editing, lipsync, avatar animation, video upscaling, foley sound. Use for: social media videos, marketing content, explainer videos, product demos, AI avatars. Triggers: video generation, ai video, text to video, image to video, veo, animate image, video from image, ai animation, video generator, generate video, t2v, i2v, ai video maker, create video with ai, runway alternative, pika alternative, sora alternative, kling alternative, seedance, happyhorse
ai-image-generation
101-skills/superpowers
Generate AI images with GPT-Image-2, FLUX, Gemini, Grok, Seedream, Reve and 50+ models via inference.sh CLI. Models: GPT-Image-2, FLUX Dev LoRA, FLUX.2 Klein LoRA, Gemini 3 Pro Image, Grok Imagine, Seedream 4.5, Reve, ImagineArt. Capabilities: text-to-image, image-to-image, inpainting, LoRA, image editing, upscaling, text rendering. Use for: AI art, product mockups, concept art, social media graphics, marketing visuals, illustrations. Triggers: flux, image generation, ai image, text to image, stable diffusion, generate image, ai art, midjourney alternative, dall-e alternative, text2img, t2i, image generator, ai picture, create image with ai, generative ai, ai illustration, grok image, gemini image, gpt image, openai image, chatgpt image