Video Processing

Smart video processor with automatic single-file and batch operation detection, modern codec support, and platform-specific presets.

Quick Start

Process videos with optimal defaults:

cd ~/.claude/scripts/media-tools bun run video video.mov --Resolution 1080p --Format mp4

Intelligent Behavior

Automatically detects input type and adjusts processing:

Input Behavior

Single file (video.mp4 ) Process that file

Directory (./videos/ ) Process all videos in directory

Glob pattern (*.mov ) Process matching files

Multiple files Process each file

CLI Options

Option Default Options Description

Resolution original

original, 4K, 1440p, 1080p, 720p, 480p, custom Target resolution

Format mp4

original, mp4, webm, mov, gif Output format

Quality medium

high, medium, low, web Quality preset

FPS original

original, 60, 30, 24, 15 Target frame rate

Trim full

full, custom Trim video to clip

Audio keep

keep, remove, extract Audio handling

Output same

same, subfolder, custom Output location

Features

Format Support:

• MP4/H.264 - Universal compatibility (recommended)

• WebM/VP9 - Better compression, web-optimized

• MOV - Apple ecosystem

• GIF - Animated preview

Smart Processing:

• Preserves original files (creates new output)

• Auto-selects optimal codec settings

• Handles batch operations with progress tracking

• Shows estimated output size before processing

Supported Input Formats: mp4, mov, avi, mkv, webm, m4v, flv, wmv, mts

Usage Examples

Single file - compress

bun run video video.mov --Resolution 1080p --Format mp4 --Quality medium

Single file - convert to web format

bun run video video.mov --Format webm --Quality web

Single file - extract clip

bun run video video.mp4 --Trim custom --Resolution 720p

Prompts for timing:

Enter start time (HH:MM:SS or seconds): 00:01:30 Enter duration (HH:MM:SS or seconds, or 'end' for rest): 00:00:30

Single file - create GIF preview

bun run video video.mp4 --Format gif --Resolution 480p --FPS 15

Batch - compress folder

bun run video ./raw/ --Resolution 1080p --Format mp4 --Output subfolder

Shows preview before processing:

Found 8 videos to process:

• intro.mov (1:24, 4K, 2.1 GB)
• clip1.mp4 (0:45, 1080p, 340 MB)
• clip2.mp4 (2:10, 1080p, 890 MB)
• ... and 5 more

Total duration: 12:34 Total size: 5.8 GB

Settings:

• Resolution: 1080p
• Format: mp4 (H.264)
• Quality: medium (CRF 23)
• FPS: original
• Audio: keep

Estimated output: ~1.2 GB (80% smaller)

Proceed? [Yes/No]

Batch - convert all MOV to MP4

bun run video "*.mov" --Format mp4 --Quality medium

Remove audio from videos

bun run video ./videos/ --Audio remove --Format mp4

Extract audio tracks

bun run video ./videos/ --Audio extract

Outputs .m4a files alongside videos.

Platform Presets

Platform Resolution Format Quality FPS Use Case

YouTube upload 1080p mp4 high original High quality

Twitter/X 720p mp4 medium 30 Short clips

Instagram Reel 1080p mp4 medium 30 Vertical video

TikTok 1080p mp4 medium 30 Short form

Web background 720p webm low 24 Hero videos

Email attachment 480p mp4 low 24 Small size

GIF preview 480p gif

15 Animated preview

Archival original mp4 high original Preservation

Quality Settings

Maps quality presets to codec parameters:

Quality H.264 CRF VP9 CRF Description

high 18 24 Archival, minimal loss

medium 23 30 Balanced (default)

low 28 36 Smaller files

web 30 38 Streaming optimized

CRF (Constant Rate Factor): Lower = better quality, larger file

Resolution Mapping

Preset Width Height Aspect Ratio

4K 3840 2160 16:9

1440p 2560 1440 16:9

1080p 1920 1080 16:9

720p 1280 720 16:9

480p 854 480 16:9

Processing Commands

MP4 (H.264) - Standard

ffmpeg -i input.mov
-vf "scale=1920:-2"
-c:v libx264
-crf 23
-preset medium
-c:a aac -b:a 128k
output.mp4

WebM (VP9) - Web Optimized

ffmpeg -i input.mov
-vf "scale=1920:-2"
-c:v libvpx-vp9
-crf 30 -b:v 0
-c:a libopus -b:a 128k
output.webm

With Trim

ffmpeg -ss 00:01:30 -t 00:00:30 -i input.mp4
-vf "scale=1920:-2"
-c:v libx264
-crf 23
-preset medium
-c:a aac -b:a 128k
output.mp4

Remove Audio

ffmpeg -i input.mp4 -an
-vf "scale=1920:-2"
-c:v libx264
-crf 23
output.mp4

Extract Audio Only

ffmpeg -i input.mp4
-vn
-c:a aac
-b:a 192k
output.m4a

Processing Results

Shows real-time progress for each file:

[1/8] intro.mov → intro.mp4 4K → 1080p | 2.1 GB → 245 MB (88% smaller) ████████████████████████████░░ 90% | ETA: 0:15

[2/8] clip1.mp4 → clip1_compressed.mp4 1080p → 1080p | 340 MB → 89 MB (74% smaller) ...

✓ Processed 8 videos

Summary:

• Total input: 5.8 GB
• Total output: 1.1 GB
• Compression: 81% smaller
• Time: 4m 32s

Output: ./processed/

Best Practices

• Use MP4/H.264 - Universal compatibility across all devices

• Quality "medium" - Best balance for most use cases

• Keep originals - Tool never modifies source files

• Test on sample - Process one file first to verify settings

• Trim before compressing - Reduces processing time

• Match platform specs - Use presets for target platform

• Audio bitrate 128k - Sufficient for most speech/music

Audio Handling

Option Behavior Use Case

keep

Preserve audio track Standard videos

remove

Strip audio completely Silent background videos

extract

Save audio as separate file Audio-only content

Requirements

• FFmpeg - With libx264, libvpx-vp9, libopus codecs

• Install: brew install ffmpeg

Verify codecs:

ffmpeg -codecs | grep -E "h264|vp9|opus"

Related Files

• Command: plugins/media-tools/commands/video.md

• Media Processor: plugins/media-tools/skills/media-processor/

• GIF Creation: plugins/media-tools/skills/gif-creation/

• Image Processing: plugins/media-tools/skills/image-processing/