---
name: ck-media-processing
description: >
  Processes audio, video, and images using FFmpeg and ImageMagick pipelines.
  Activate when user says 'convert video', 'compress image', 'extract audio',
  'resize images in bulk', 'transcode media', or 'process video file'.
  Accepts file paths, format targets, quality settings, and filter specifications.
---

## Overview
Builds and executes FFmpeg and ImageMagick commands for media conversion, compression, resizing, format conversion, and pipeline processing of audio, video, and image files.

## When to Use
- Converting between video/audio formats (MP4, WebM, MOV, MP3, AAC, etc.)
- Compressing or optimizing media files for web delivery
- Bulk resizing, cropping, or converting images
- Extracting audio tracks or video frames
- Applying filters, watermarks, or overlays to media
- Generating thumbnails or animated GIFs from video

## Don't Use When
- AI-based image generation is needed (use ck-ai-artist)
- Video needs programmatic composition with React components (use ck-remotion)
- Media editing requires a GUI (recommend appropriate desktop software)
- File is DRM-protected content

## Steps / Instructions

### 1. Identify Task and Tools

| Task | Tool |
|------|------|
| Video conversion/compression | FFmpeg |
| Audio extraction/conversion | FFmpeg |
| Image resize/crop/convert | ImageMagick (`convert`) or FFmpeg |
| Bulk image processing | ImageMagick + shell loop |
| Thumbnails from video | FFmpeg |
| GIF from video clip | FFmpeg |

### 2. FFmpeg — Common Operations

**Convert video format:**
```bash
ffmpeg -i input.mov -c:v libx264 -crf 23 -c:a aac output.mp4
```

**Compress video (reduce file size):**
```bash
# CRF 18-28: lower = better quality, larger file
ffmpeg -i input.mp4 -c:v libx264 -crf 28 -preset slow -c:a aac -b:a 128k output-compressed.mp4
```

**Extract audio:**
```bash
ffmpeg -i video.mp4 -vn -c:a libmp3lame -q:a 2 audio.mp3
```

**Trim video clip:**
```bash
ffmpeg -i input.mp4 -ss 00:01:30 -to 00:02:45 -c copy clip.mp4
```

**Extract frames as images:**
```bash
# 1 frame per second
ffmpeg -i video.mp4 -vf fps=1 frames/frame_%04d.png

# Specific frame at timestamp
ffmpeg -i video.mp4 -ss 00:00:05 -vframes 1 thumbnail.png
```

**Create GIF from video:**
```bash
ffmpeg -i input.mp4 -ss 0 -t 5 -vf "fps=10,scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output.gif
```

**WebM for web (VP9):**
```bash
ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm
```

### 3. ImageMagick — Common Operations

**Resize image:**
```bash
convert input.jpg -resize 800x600 output.jpg
# Preserve aspect ratio (fit within box):
convert input.jpg -resize 800x600\> output.jpg
```

**Convert format:**
```bash
convert input.png output.webp
convert input.bmp output.jpg
```

**Compress JPEG:**
```bash
convert input.jpg -quality 80 output.jpg
```

**Bulk resize (all PNGs in directory):**
```bash
for f in *.png; do
  convert "$f" -resize 1920x1080\> "resized_$f"
done
```

**Add watermark:**
```bash
convert input.jpg -gravity SouthEast \
  \( watermark.png -resize 200x200 \) \
  -composite output.jpg
```

**Crop to specific region:**
```bash
# WxH+X+Y
convert input.jpg -crop 400x300+100+50 cropped.jpg
```

### 4. Check Output Quality

After processing:
```bash
# Inspect video metadata
ffprobe -v quiet -print_format json -show_streams output.mp4

# Check image info
identify -verbose output.jpg | grep -E "Geometry|Format|Quality|Filesize"
```

### 5. Batch Processing Script

```bash
#!/bin/bash
INPUT_DIR="./raw"
OUTPUT_DIR="./processed"
mkdir -p "$OUTPUT_DIR"

for f in "$INPUT_DIR"/*.mp4; do
  name=$(basename "$f" .mp4)
  ffmpeg -i "$f" -c:v libx264 -crf 26 -c:a aac \
    "$OUTPUT_DIR/${name}-compressed.mp4"
done
```

## Notes
- Always test on a single file before batch processing
- Keep originals — never overwrite input files in place
- FFmpeg `-c copy` is lossless stream copy (fastest, no re-encode)
- Use `-y` flag to overwrite output without prompting in scripts
- Check available encoders: `ffmpeg -encoders | grep -E "video|audio"`