FFmpeg-Tools Skill

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

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

Prerequisites

Install FFmpeg

macOS

brew install ffmpeg

Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg

Verify installation

ffmpeg -version ffprobe -version

Commands

1. Convert Media Format

Convert between video/audio formats with quality control.

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

2. Compress Video

Achieve target file sizes with intelligent bit rate calculation.

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

Advanced size targets

{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

3. Trim Video Segment

Extract precise video segments.

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

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

Millisecond precision

{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

4. Extract Audio

Extract audio tracks with format options.

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

Extract to other formats

{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

With specific quality

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

5. Merge Media Files

Concatenate multiple files into one.

Merge two videos

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

Merge multiple videos

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

Merge all in directory

{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

6. Resize Video

Scale videos while maintaining aspect ratio.

Scale by width (height auto)

{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 height (width auto)

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

Scale by factor

{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)

7. Get Media Information

Display detailed file metadata.

Human-readable output

{baseDir}/ffmpeg.js info video.mp4

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

Progress Tracking

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)

Safety Features

1. Input Validation

• Files must exist before processing

• Maximum input size: 10GB

• Maximum duration: 24 hours

• Malformed files are detected before processing

2. Disk Space Protection

• Minimum 100MB free space required before processing

• Automatic checks before large operations

• Clear error messages if disk space is insufficient

3. Timeouts

• Maximum operation time: 2 hours

• Prevents runaway conversions

• Signal handling for graceful interruption

4. Signal Handling

• Press Ctrl+C to gracefully interrupt operations

• Partial files are cleaned up automatically

• No orphaned temporary files

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

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

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

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

Audio Codecs

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

Performance Tips

1. Fast Conversions

Use lower quality presets for faster encoding:

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

2. Batch Processing

Process multiple files with shell loops:

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

3. Parallel Operations

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

Run 2 conversions in parallel

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

4. Output Naming

The tool supports flexible output naming:

Auto-extension handling

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

Full path support

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

Examples

Complete Workflow: Video for Web

Step 1: Compress for sharing

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

Step 2: Create thumbnail

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

Step 3: Get info for documentation

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

Extract Highlights

Extract first minute

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

Extract last 30 seconds

{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

Merge highlights

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

Batch Convert to Web-Optimized Format

#!/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

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)