Back to Details

compress-video

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Video Compress

视频压缩

Compress a video using quality-based (CRF) or size-based (2-pass) encoding.
基于质量（CRF）或基于大小（双-pass）编码来压缩视频。

Process

流程

1. Obtain input file

1. 获取输入文件

If the user did not provide a file path, ask for it with AskUserQuestion before proceeding.
如果用户未提供文件路径，请先通过AskUserQuestion询问用户，再继续后续操作。

2. Probe the source

2. 探测源文件

bash
ffprobe -v quiet -print_format json -show_streams -show_format "$INPUT"
Extract: duration (seconds), file size (bytes), existing video codec, audio bitrate. If ffprobe fails (file not found, not a valid video), report the error and stop — do not attempt encoding.
bash
ffprobe -v quiet -print_format json -show_streams -show_format "$INPUT"
提取信息：时长（秒）、文件大小（字节）、现有视频编码、音频比特率。如果ffprobe执行失败（文件未找到、非有效视频），请报告错误并停止操作——不要尝试编码。

3. Determine mode from user intent

3. 根据用户意图确定模式

  • CRF mode (quality-based): user says "without losing quality", "good quality", "make it smaller", or gives no size target
  • 2-pass mode (size-based): user specifies a target ("under 50MB", "around 20MB", "fit on X")
  • CRF模式（基于质量）：用户提到“不损失画质”“高质量”“让视频变小”，或未指定目标大小
  • 双-pass模式（基于大小）：用户指定了目标（“小于50MB”“约20MB”“适配X”）

4. Choose codec

4. 选择编码格式

H.264 is the safe default: universally device-compatible and fast to encode. Use H.265 only when the size reduction justifies the slower encode time and narrower device support.
  • H.265 / libx265: target is ≤50% of original size, or user asks for "maximum compression" / "HEVC"
  • H.264 / libx264: otherwise — faster encode, wider device compatibility, safe default
H.264是安全的默认选项：具备广泛的设备兼容性，且编码速度快。仅当尺寸缩减幅度足以弥补编码速度较慢和设备支持范围较窄的缺点时，才使用H.265。
  • H.265 / libx265：目标大小≤原大小的50%，或用户要求“最大压缩”/“HEVC”
  • H.264 / libx264：其他情况——编码速度更快，设备兼容性更广，安全默认选项

5. Construct command

5. 构建命令

CRF mode:
bash
ffmpeg -i "$INPUT" -c:v libx264 -crf 23 -c:a copy -movflags +faststart "$OUTPUT"
CRF模式：
bash
ffmpeg -i "$INPUT" -c:v libx264 -crf 23 -c:a copy -movflags +faststart "$OUTPUT"

CRF scale: 18=near-lossless, 23=default quality, 28=aggressive (visible loss)

CRF范围：18=近乎无损，23=默认画质，28=高压缩（可见画质损失）

-movflags +faststart moves moov atom to front — enables progressive web playback

-movflags +faststart将moov原子移至文件开头——支持网页渐进式播放


**2-pass mode** — calculate video bitrate first:
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/compress-video/scripts/calc_bitrate.py "$INPUT" --target-mb "$TARGET_MB"

**双-pass模式**——先计算视频比特率：
```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/compress-video/scripts/calc_bitrate.py "$INPUT" --target-mb "$TARGET_MB"

Outputs: VIDEO_BITRATE_KBPS (integer)

输出：VIDEO_BITRATE_KBPS（整数）

Formula: (target_mb * 8192 / duration_s) - audio_bitrate_kbps

公式：(target_mb * 8192 / duration_s) - audio_bitrate_kbps

Typical audio budget: 128 kbps

典型音频预算：128 kbps

Exit 1 = target too small (bitrate would go negative); report the error and ask for a larger target before retrying.

返回值1表示目标过小（比特率为负）；请报告错误并要求用户提供更大的目标后重试。

Pass 1 — video analysis only, no output file:

第一阶段——仅分析视频，不生成输出文件：

ffmpeg -y -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 1 -an -f null /dev/null
ffmpeg -y -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 1 -an -f null /dev/null

Pass 2 — final encode with audio:

第二阶段——带音频的最终编码：

ffmpeg -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 2
-c:a aac -b:a 128k -movflags +faststart "$OUTPUT"
undefined
ffmpeg -i "$INPUT" -c:v libx264 -b:v ${VIDEO_BITRATE_KBPS}k -pass 2
-c:a aac -b:a 128k -movflags +faststart "$OUTPUT"
undefined

6. Confirm with user

6. 与用户确认

Show: input file size, chosen codec, mode (CRF value or calculated bitrate), output path. Wait for approval before running.
展示：输入文件大小、所选编码格式、模式（CRF值或计算出的比特率）、输出路径。等待用户批准后再执行。

7. Run and report

7. 执行并报告

After completion: input size → output size, compression ratio (e.g., "73.2 MB → 18.4 MB, 75% reduction").
完成后：输入大小→输出大小、压缩比例（例如：“73.2 MB → 18.4 MB，缩减75%”）。

Key Decisions

关键决策

  • In CRF mode, use 
    -c:a copy
    to preserve audio losslessly. In 2-pass mode, audio must be re-encoded (AAC 128k) because pass 1 is video-only — no audio stream is processed.
  • If input is already H.264 and the user only wants to trim or remux, recommend 
    convert-video
    with 
    -c copy
    instead — instant and lossless.
  • For H.265 output, substitute 
    libx265
    and add 
    -tag:v hvc1
    for Apple device compatibility.
  • Clean up 
    ffmpeg2pass-0.log
    and 
    ffmpeg2pass-0.log.mbtree
    after 2-pass encoding completes.
  • 在CRF模式下，使用
    -c:a copy
    无损保留音频。在双-pass模式下，必须重新编码音频（AAC 128k），因为第一阶段仅处理视频——未处理音频流。
  • 如果输入文件已为H.264编码，且用户仅需裁剪或重新封装，建议使用
    convert-video
    并添加
    -c copy
    参数——即时且无损。
  • 若输出为H.265，替换为
    libx265
    并添加
    -tag:v hvc1
    以兼容Apple设备。
  • 双-pass编码完成后，清理
    ffmpeg2pass-0.log
    和
    ffmpeg2pass-0.log.mbtree
    文件。