antigravity-claudekit/skills/ck-media-processing/SKILL.md

name, description

name	description
ck-media-processing	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:

ffmpeg -i input.mov -c:v libx264 -crf 23 -c:a aac output.mp4

Compress video (reduce file size):

# 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:

ffmpeg -i video.mp4 -vn -c:a libmp3lame -q:a 2 audio.mp3

Trim video clip:

ffmpeg -i input.mp4 -ss 00:01:30 -to 00:02:45 -c copy clip.mp4

Extract frames as images:

# 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:

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

ffmpeg -i input.mp4 -c:v libvpx-vp9 -crf 30 -b:v 0 -c:a libopus output.webm

3. ImageMagick — Common Operations

Resize image:

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

Convert format:

convert input.png output.webp
convert input.bmp output.jpg

Compress JPEG:

convert input.jpg -quality 80 output.jpg

Bulk resize (all PNGs in directory):

for f in *.png; do
  convert "$f" -resize 1920x1080\> "resized_$f"
done

Add watermark:

convert input.jpg -gravity SouthEast \
  \( watermark.png -resize 200x200 \) \
  -composite output.jpg

Crop to specific region:

# WxH+X+Y
convert input.jpg -crop 400x300+100+50 cropped.jpg

4. Check Output Quality

After processing:

# 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

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