ffmpeg-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

FFmpeg-Tools Skill

FFmpeg-Tools 技能

Production-grade video and audio processing using FFmpeg with comprehensive error handling, progress tracking, and safety constraints.

基于FFmpeg的生产级音视频处理工具，具备全面的错误处理、进度跟踪和安全限制功能。

When to Use

使用场景

✅ USE this skill when:

Converting video formats (MOV to MP4, AVI to WebM, etc.)
Compressing videos to target file sizes
Trimming video segments
Extracting audio from video files
Merging multiple media files
Resizing videos while maintaining aspect ratio
Getting detailed media information

❌ DON'T use this skill when:

Complex video editing (effects, transitions) → Use dedicated video editor
Live streaming operations → Use streaming tools
Video playback → Use media player
Frame-by-frame video analysis → Use video-frames skill

✅ 适合使用本技能的场景：

转换视频格式（如MOV转MP4、AVI转WebM等）
将视频压缩至目标文件大小
剪辑视频片段
从视频文件中提取音频
合并多个媒体文件
调整视频尺寸并保持宽高比
获取详细的媒体文件信息

❌ 不适合使用本技能的场景：

复杂视频编辑（添加特效、转场）→ 使用专业视频编辑器
直播操作→使用直播工具
视频播放→使用媒体播放器
逐帧视频分析→使用video-frames技能

Prerequisites

前置条件

bash

undefined

bash

undefined

Install FFmpeg

安装FFmpeg

macOS

macOS系统

brew install ffmpeg

Ubuntu/Debian

Ubuntu/Debian系统

sudo apt update && sudo apt install ffmpeg

Verify installation

验证安装

ffmpeg -version ffprobe -version

undefined

ffmpeg -version ffprobe -version

undefined

Commands

命令说明

1. Convert Media Format

1. 转换媒体格式

Convert between video/audio formats with quality control.

bash

undefined

支持带质量控制的音视频格式转换。

bash

undefined

Basic conversion

基础转换

{baseDir}/ffmpeg.js convert input.mov --output output.mp4

With quality settings

带质量设置的转换

{baseDir}/ffmpeg.js convert input.mov --output output.mp4 --quality high {baseDir}/ffmpeg.js convert input.wav --output output.mp3 --quality medium

Force specific format (ignores extension)

强制指定格式（忽略文件扩展名）

{baseDir}/ffmpeg.js convert input.mkv --output output.webm --format mp4


**Supported Formats:**

| Format | Video Codec | Audio Codec | Notes |
|--------|-------------|-------------|-------|
| MP4 | libx264 | AAC | Best compatibility |
| MOV | libx264 | AAC | Apple formats |
| WebM | libvpx-vp9 | Opus | Web optimized |
| MKV | libx264 | AAC | Matroska container |
| AVI | libx264 | AAC | Older format support |
| MP3 | - | libmp3lame | Audio only |
| AAC | - | AAC | Apple audio |
| OGG | - | libvorbis | Open format |
| FLAC | - | FLAC | Lossless audio |
| WAV | - | pcm_s16le | Uncompressed |

**Quality Levels:**

| Level | CRF | Preset | Bitrate | Best For |
|-------|-----|--------|---------|----------|
| `low` | 28 | ultrafast | 800k | Archival/quick encode |
| `medium` | 23 | fast | 2M | Default/general use |
| `high` | 18 | slow | 5M | Quality preservation |
| `lossless` | 0 | veryslow | unlimited | Maximum quality |

{baseDir}/ffmpeg.js convert input.mkv --output output.webm --format mp4


**支持的格式：**

| 格式 | 视频编码 | 音频编码 | 说明 |
|--------|-------------|-------------|-------|
| MP4 | libx264 | AAC | 最佳兼容性 |
| MOV | libx264 | AAC | Apple格式 |
| WebM | libvpx-vp9 | Opus | 网页优化格式 |
| MKV | libx264 | AAC | Matroska容器格式 |
| AVI | libx264 | AAC | 支持旧格式 |
| MP3 | - | libmp3lame | 仅音频 |
| AAC | - | AAC | Apple音频格式 |
| OGG | - | libvorbis | 开源格式 |
| FLAC | - | FLAC | 无损音频 |
| WAV | - | pcm_s16le | 无压缩格式 |

**质量等级：**

| 等级 | CRF | 预设 | 比特率 | 适用场景 |
|-------|-----|--------|---------|----------|
| `low` | 28 | ultrafast | 800k | 归档/快速编码 |
| `medium` | 23 | fast | 2M | 默认/通用场景 |
| `high` | 18 | slow | 5M | 画质保留 |
| `lossless` | 0 | veryslow | unlimited | 最高画质 |

2. Compress Video

2. 压缩视频

Achieve target file sizes with intelligent bit rate calculation.

bash

undefined

通过智能比特率计算实现目标文件大小。

bash

undefined

Compress with quality preset

使用质量预设压缩

{baseDir}/ffmpeg.js compress video.mp4 --output compressed.mp4 --quality low {baseDir}/ffmpeg.js compress video.mp4 --output compressed.mp4 --quality medium

Compress to specific size

压缩至指定大小

{baseDir}/ffmpeg.js compress video.mp4 --size 10MB --output small.mp4 {baseDir}/ffmpeg.js compress video.mp4 --size 100MB --output shareable.mp4

高级尺寸目标 {baseDir}/ffmpeg.js compress video.mp4 --size 500KB --output tiny.mp4 {baseDir}/ffmpeg.js compress video.mp4 --size 2.5GB --output archive.mp4


**尺寸计算逻辑：**

工具会自动为目标大小计算最优比特率：
- 考虑音频轨道（128kbps AAC）
- 预留8%的空间用于容器开销
- 验证最低比特率的可行性
- 如果目标大小不可行，自动 fallback 到基于CRF的压缩方式

Advanced size targets

3. 剪辑视频片段

{baseDir}/ffmpeg.js compress video.mp4 --size 500KB --output tiny.mp4 {baseDir}/ffmpeg.js compress video.mp4 --size 2.5GB --output archive.mp4


**Size Calculation:**

The tool automatically calculates optimal bit rates for target sizes:
- Accounts for audio track (128kbps AAC)
- Leaves 8% headroom for container overhead
- Validates minimum bit rate feasibility
- Falls back to CRF-based compression if size target is infeasible

提取精准的视频片段。

bash

undefined

3. Trim Video Segment

按开始时间和时长剪辑

Extract precise video segments.

bash

undefined

{baseDir}/ffmpeg.js trim video.mp4 --start 00:01:30 --duration 60 --output clip.mp4 {baseDir}/ffmpeg.js trim video.mp4 --start 90 --duration 60 --output clip.mp4

Trim by start and duration

按开始和结束时间剪辑

{baseDir}/ffmpeg.js trim video.mp4 --start 00:01:30 --duration 60 --output clip.mp4 {baseDir}/ffmpeg.js trim video.mp4 --start 90 --duration 60 --output clip.mp4

{baseDir}/ffmpeg.js trim video.mp4 --start 00:02:00 --end 00:03:00 --output segment.mp4 {baseDir}/ffmpeg.js trim video.mp4 --start 1:00 --end 2:30 --output segment.mp4

Trim by start and end time

毫秒精度剪辑

{baseDir}/ffmpeg.js trim video.mp4 --start 00:02:00 --end 00:03:00 --output segment.mp4 {baseDir}/ffmpeg.js trim video.mp4 --start 1:00 --end 2:30 --output segment.mp4

{baseDir}/ffmpeg.js trim video.mp4 --start 5.5 --duration 10.25 --output precise.mp4


**支持的时间格式：**
- 秒：`30`, `90.5`
- 分:秒：`1:30`, `2:45.5`
- 时:分:秒：`01:30:00`, `00:02:15`

Millisecond precision

4. 提取音频

{baseDir}/ffmpeg.js trim video.mp4 --start 5.5 --duration 10.25 --output precise.mp4


**Time Formats Supported:**
- Seconds: `30`, `90.5`
- Minutes:Seconds: `1:30`, `2:45.5`
- Hours:Minutes:Seconds: `01:30:00`, `00:02:15`

提取音频轨道并支持格式选择。

bash

undefined

4. Extract Audio

提取为MP3格式

Extract audio tracks with format options.

bash

undefined

{baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.mp3 {baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.mp3 --format mp3

Extract to MP3

提取为其他格式

{baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.mp3 {baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.mp3 --format mp3

{baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.aac --format aac {baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.ogg --format ogg {baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.flac --format flac {baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.wav --format wav

Extract to other formats

指定音频质量

{baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.mp3 --format mp3 --quality 320k

undefined

With specific quality

5. 合并媒体文件

{baseDir}/ffmpeg.js extract-audio video.mp4 --output audio.mp3 --format mp3 --quality 320k

undefined

将多个文件拼接为一个文件。

bash

undefined

5. Merge Media Files

合并两个视频

Concatenate multiple files into one.

bash

undefined

{baseDir}/ffmpeg.js merge video1.mp4 video2.mp4 --output combined.mp4

Merge two videos

合并多个视频

{baseDir}/ffmpeg.js merge video1.mp4 video2.mp4 --output combined.mp4

{baseDir}/ffmpeg.js merge intro.mp4 main.mp4 outro.mp4 --output final.mp4

Merge multiple videos

合并目录下所有视频

{baseDir}/ffmpeg.js merge intro.mp4 main.mp4 outro.mp4 --output final.mp4

{baseDir}/ffmpeg.js merge clips/*.mp4 --output full-video.mp4


**要求：**
- 所有输入文件必须使用相同的编码和分辨率
- 音频流必须兼容
- 文件将按提供的顺序拼接

Merge all in directory

6. 调整视频尺寸

{baseDir}/ffmpeg.js merge clips/*.mp4 --output full-video.mp4


**Requirements:**
- All inputs must have same codec and resolution
- Audio streams must be compatible
- Files will be concatenated in order provided

缩放视频并保持宽高比。

bash

undefined

6. Resize Video

按宽度缩放（高度自动计算）

Scale videos while maintaining aspect ratio.

bash

undefined

{baseDir}/ffmpeg.js resize video.mp4 --width 1280 --output resized.mp4 {baseDir}/ffmpeg.js resize video.mp4 --width 640 --output mobile.mp4 {baseDir}/ffmpeg.js resize video.mp4 --width 1920 --output 1080p.mp4

Scale by width (height auto)

按高度缩放（宽度自动计算）

{baseDir}/ffmpeg.js resize video.mp4 --height 720 --output resized.mp4

Scale by height (width auto)

按比例缩放

{baseDir}/ffmpeg.js resize video.mp4 --height 720 --output resized.mp4

{baseDir}/ffmpeg.js resize video.mp4 --scale 0.5 --output half-size.mp4 {baseDir}/ffmpeg.js resize video.mp4 --scale 0.25 --output quarter-size.mp4


**缩放选项：**
- `--width <像素>`：按宽度缩放，高度自动计算
- `--height <像素>`：按高度缩放，宽度自动计算
- `--scale <比例>`：按比例缩放（0.5表示缩小一半）

Scale by factor

7. 获取媒体信息

{baseDir}/ffmpeg.js resize video.mp4 --scale 0.5 --output half-size.mp4 {baseDir}/ffmpeg.js resize video.mp4 --scale 0.25 --output quarter-size.mp4


**Scaling Options:**
- `--width <pixels>`: Scale to width, height calculated automatically
- `--height <pixels>`: Scale to height, width calculated automatically
- `--scale <factor>`: Scale both dimensions (0.5 = half size)

显示详细的文件元数据。

bash

undefined

7. Get Media Information

人类可读格式输出

Display detailed file metadata.

bash

undefined

{baseDir}/ffmpeg.js info video.mp4

Human-readable output

JSON格式输出

{baseDir}/ffmpeg.js info video.mp4

{baseDir}/ffmpeg.js info video.mp4 --json {baseDir}/ffmpeg.js info audio.mp3 --json > info.json


**示例输出：**

媒体信息：

格式：mov,mp4,m4a,3gp,3g2,mj2 时长：00:12:34 大小：1.23 GB 比特率：14,372 kbps

视频流：编码：h264 分辨率：1920x1080 帧率：29.97 fps

音频流：编码：aac 采样率：48000 Hz 声道：立体声

undefined

JSON output

进度跟踪

{baseDir}/ffmpeg.js info video.mp4 --json {baseDir}/ffmpeg.js info audio.mp3 --json > info.json


**Sample Output:**

Media Information:

Format: mov,mp4,m4a,3gp,3g2,mj2 Duration: 00:12:34 Size: 1.23 GB Bitrate: 14,372 kbps

Video Stream: Codec: h264 Resolution: 1920x1080 Frame Rate: 29.97 fps

Audio Stream: Codec: aac Sample Rate: 48000 Hz Channels: Stereo

undefined

在交互式终端中运行时，所有操作都会显示实时进度：

⏳ 转换进度：45.2% | 当前帧1247@23.5fps | 已耗时：00:00:53 | 预计剩余时间：00:01:04

进度字段说明：

完成百分比（已知时长时显示）
当前帧编号
编码帧率
已耗时
预计剩余时间（ETA）

Progress Tracking

安全特性

—

1. 输入验证

All operations display real-time progress when run in interactive terminals:

⏳ Converting: 45.2% | Frame 1247@23.5fps | Elapsed: 00:00:53 | ETA: 00:01:04

Progress fields:

Percentage complete (when duration known)
Current frame number
Encoding FPS
Elapsed time
Estimated time remaining (ETA)

处理前验证文件是否存在
最大输入文件大小：10GB
最大时长：24小时
处理前检测文件是否损坏

Safety Features

2. 磁盘空间保护

1. Input Validation

—

Files must exist before processing
Maximum input size: 10GB
Maximum duration: 24 hours
Malformed files are detected before processing

处理前需要至少100MB可用空间
大型操作前自动检查
磁盘空间不足时显示清晰的错误信息

2. Disk Space Protection

3. 超时限制

Minimum 100MB free space required before processing
Automatic checks before large operations
Clear error messages if disk space is insufficient

最大操作时长：2小时
防止转换进程失控
支持信号处理，实现优雅中断

3. Timeouts

4. 信号处理

Maximum operation time: 2 hours
Prevents runaway conversions
Signal handling for graceful interruption

按下Ctrl+C可优雅中断操作
自动清理未完成的文件
不会遗留孤立的临时文件

4. Signal Handling

错误处理

—

错误代码

Press Ctrl+C to gracefully interrupt operations
Partial files are cleaned up automatically
No orphaned temporary files

代码	名称	描述
0	SUCCESS	操作成功完成
1	INVALID_INPUT	参数缺失或无效
2	FILE_NOT_FOUND	输入文件不存在
3	PERMISSION_DENIED	无法读取/写入文件
4	DISK_FULL	磁盘空间不足
5	INVALID_FORMAT	指定了不支持的格式
6	FFMPEG_ERROR	FFmpeg执行失败
7	TIMEOUT	操作超出时长限制
8	INTERRUPTED	被用户信号中断
9	VALIDATION_FAILED	操作前验证检查失败
99	UNKNOWN	发生未知错误

Error Handling

常见错误及解决方案

Error Codes

—

Code	Name	Description
0	SUCCESS	Operation completed successfully
1	INVALID_INPUT	Missing or invalid parameters
2	FILE_NOT_FOUND	Input file does not exist
3	PERMISSION_DENIED	Cannot read/write files
4	DISK_FULL	Insufficient disk space
5	INVALID_FORMAT	Unsupported format specified
6	FFMPEG_ERROR	FFmpeg execution failed
7	TIMEOUT	Operation exceeded time limit
8	INTERRUPTED	Interrupted by user signal
9	VALIDATION_FAILED	Pre-operation validation check failed
99	UNKNOWN	Unexpected error occurred

"文件过大"

文件超过10GB大小限制
解决方案：分割为较小的片段

"时长过长"

视频超过24小时时长限制
解决方案：分段处理

"磁盘空间不足"

可用空间不足100MB
解决方案：释放磁盘空间

"目标大小过小"

请求的大小需要极低的比特率，无法实现
解决方案：使用更大的目标大小或基于CRF的压缩方式

"无效的剪辑范围"

开始/结束时间超出视频时长
解决方案：使用
```
info
```
命令查看视频时长

Common Errors and Solutions

技术架构

—

质量设置系统

"File too large"

File exceeds 10GB size limit
Solution: Split into smaller segments

"Duration too long"

Video exceeds 24 hour limit
Solution: Process in segments

"Insufficient disk space"

Less than 100MB available
Solution: Free up disk space

"Target size too small"

Requested size would require impossibly low bit rate
Solution: Use larger target size or CRF-based compression

"Invalid trim range"

Start/end times exceed video duration
Solution: Check video duration with
```
info
```
command

使用恒定速率因子（CRF）编码：

CRF 0-17：视觉无损
CRF 18-23：高质量（默认范围）
CRF 23-28：画质良好，文件更小
CRF 28+：较低画质，适合归档

Technical Architecture

编码预设

Quality Settings System

—

Uses Constant Rate Factor (CRF) encoding:

CRF 0-17: Visually lossless
CRF 18-23: High quality (default range)
CRF 23-28: Good quality, smaller files
CRF 28+: Lower quality, archival use

在编码速度和效率之间取得平衡：

ultrafast：最快速度，文件较大
superfast：快速编码
veryfast：标准快速模式
faster：良好平衡
fast：标准画质模式
medium：默认平衡模式
slow：更好的压缩率
slower：高效压缩
veryslow：最大压缩率

Encoding Presets

音频编码

Balance between encoding speed and efficiency:

ultrafast: Fastest, larger files
superfast: Fast encoder
veryfast: Standard fast mode
faster: Good balance
fast: Standard quality mode
medium: Default balance
slow: Better compression
slower: High efficiency
veryslow: Maximum compression

格式	编码	说明
MP3	LAME	-q:a 2 参数对应320kbps可变比特率
AAC	Apple/AAC	极佳的兼容性
Opus	libopus	最佳压缩质量
Vorbis	libvorbis	开源格式替代方案
FLAC	FLAC	无损归档格式

Audio Codecs

性能优化建议

—

1. 快速转换

Format	Codec	Notes
MP3	LAME	-q:a 2 for 320kbps VBR
AAC	Apple/AAC	Excellent compatibility
Opus	libopus	Best compression quality
Vorbis	libvorbis	Open format alternative
FLAC	FLAC	Lossless archival

使用低质量预设实现更快的编码：

bash

{baseDir}/ffmpeg.js convert video.mov --output out.mp4 --quality low

Performance Tips

2. 批量处理

1. Fast Conversions

—

Use lower quality presets for faster encoding:

bash

{baseDir}/ffmpeg.js convert video.mov --output out.mp4 --quality low

使用shell循环处理多个文件：

bash

for f in *.mov; do
  {baseDir}/ffmpeg.js convert "$f" --output "${f%.mov}.mp4" --quality medium
done

2. Batch Processing

3. 并行操作

Process multiple files with shell loops:

bash

for f in *.mov; do
  {baseDir}/ffmpeg.js convert "$f" --output "${f%.mov}.mp4" --quality medium
done

⚠️ 注意：注意CPU/磁盘I/O限制

bash

undefined

3. Parallel Operations

并行运行2个转换任务

⚠️ Warning: Be mindful of CPU/disk I/O limits

bash

undefined

{baseDir}/ffmpeg.js convert video1.mov --output out1.mp4 & {baseDir}/ffmpeg.js convert video2.mov --output out2.mp4 & wait

undefined

Run 2 conversions in parallel

4. 输出命名

{baseDir}/ffmpeg.js convert video1.mov --output out1.mp4 & {baseDir}/ffmpeg.js convert video2.mov --output out2.mp4 & wait

undefined

工具支持灵活的输出命名：

bash

undefined

4. Output Naming

自动处理扩展名

The tool supports flexible output naming:

bash

undefined

{baseDir}/ffmpeg.js convert video.mov --output video.mp4

Auto-extension handling

支持完整路径

{baseDir}/ffmpeg.js convert video.mov --output video.mp4

{baseDir}/ffmpeg.js convert /data/in.mov --output /data/out.mp4

undefined

Full path support

示例

—

完整工作流：网页视频处理

{baseDir}/ffmpeg.js convert /data/in.mov --output /data/out.mp4

undefined

bash

undefined

Examples

步骤1：压缩视频用于分享

Complete Workflow: Video for Web

—

bash

undefined

{baseDir}/ffmpeg.js compress conference.mp4 --size 50MB --output for-share.mp4

Step 1: Compress for sharing

步骤2：提取音频

{baseDir}/ffmpeg.js compress conference.mp4 --size 50MB --output for-share.mp4

{baseDir}/ffmpeg.js extract-audio for-share.mp4 --output audio.mp3

Step 2: Create thumbnail

步骤3：获取视频信息用于文档

{baseDir}/ffmpeg.js extract-audio for-share.mp4 --output audio.mp3

{baseDir}/ffmpeg.js info for-share.mp4 --json > specs.json

undefined

Step 3: Get info for documentation

提取精彩片段

{baseDir}/ffmpeg.js info for-share.mp4 --json > specs.json

undefined

bash

undefined

Extract Highlights

提取第一分钟

bash

undefined

{baseDir}/ffmpeg.js trim video.mp4 --start 0 --duration 60 --output intro.mp4

Extract first minute

提取最后30秒

{baseDir}/ffmpeg.js trim video.mp4 --start 0 --duration 60 --output intro.mp4

{baseDir}/ffmpeg.js info video.mp4 --json > info.json DURATION=$(cat info.json | jq -r '.format.duration') {baseDir}/ffmpeg.js trim video.mp4 --start $(($DURATION - 30)) --duration 30 --output outro.mp4

Extract last 30 seconds

合并精彩片段

{baseDir}/ffmpeg.js merge intro.mp4 outro.mp4 --output highlights.mp4

undefined

Merge highlights

批量转换为网页优化格式

{baseDir}/ffmpeg.js merge intro.mp4 outro.mp4 --output highlights.mp4

undefined

bash

#!/bin/bash
for video in *.mov *.avi; do
  [ -f "$video" ] || continue
  base="${video%.*}"
  echo "正在转换: $video"
  {baseDir}/ffmpeg.js convert "$video" --output "${base}.webm" --quality low
done

Batch Convert to Web-Optimized Format

注意事项

bash

#!/bin/bash
for video in *.mov *.avi; do
  [ -f "$video" ] || continue
  base="${video%.*}"
  echo "Converting: $video"
  {baseDir}/ffmpeg.js convert "$video" --output "${base}.webm" --quality low
done

进度指示器需要交互式终端（TTY）
非交互式使用仅显示最终结果
临时文件会自动清理
所有输出文件创建后会进行验证
JSON输出支持程序化集成
跨平台支持：可在macOS、Linux、Windows（通过WSL）上运行

Notes

—

Progress indicators require interactive terminal (TTY)
Non-interactive usage shows final results only
Temporary files are automatically cleaned up
All output files are verified after creation
JSON output enables programmatic integration
Cross-platform: Works on macOS, Linux, Windows (with WSL)

—