Media Processing
Tools and workflows for working with images, audio, and video in a repeatable, scriptable way using standard CLI tools (FFmpeg, ImageMagick) and Python helpers.
When to Use
- Working with image batches (thumbnails, resizing, format conversion)
- Converting media between formats (video ↔ audio ↔ image)
- Optimizing video size while maintaining acceptable quality
- Preparing assets for web, mobile, or archival use
- Designing or refining CLI workflows around FFmpeg/ImageMagick
Key Principles
- CLI-first workflows: Prefer command-line tools (FFmpeg, ImageMagick) and scripts that can be automated in CI or local tooling.
- Deterministic scripts: Scripts should be safe to run repeatedly with predictable output paths and options.
- Non-destructive defaults: Default to writing outputs to new files/directories rather than overwriting originals.
- Cross-platform friendly: Keep examples and scripts usable on Linux, macOS, and Windows where possible.
- Agent-agnostic: Guidance should work with any coding agent (Cursor, Claude, Copilot, etc.), not one specific environment.
Capabilities
- Image workflows
- Batch resize and thumbnail generation - Aspect-ratio–aware resizing (fit, fill, cover, exact) - Optional watermarking - Format conversion (e.g., PNG → WebP, JPEG)
- Media conversion
- Detects media type (video, audio, image) from extension - Uses FFmpeg for video/audio, ImageMagick for images - Quality presets for web, archive, and mobile use cases - Batch conversion with dry-run and verbose modes
- Video optimization
- Resolution and frame-rate adjustments - Single-pass (CRF) or two-pass encoding - Audio bitrate tuning - Basic before/after comparison (size, bitrate, resolution, FPS)
Scripts
Scripts live in scripts/ and are intended to be run directly from a shell:
batch_resize.py
- Batch image resizing with multiple strategies (fit, fill, cover, exact, thumbnail) - Optional watermark overlay - Supports parallel processing and dry-run mode
media_convert.py
- Unified conversion tool for video, audio, and images - Automatically picks FFmpeg or ImageMagick - Uses quality presets (web, archive, mobile) - Supports batch conversion and format changes (e.g., .mov → .mp4, .wav → .mp3)
video_optimize.py
- Focused on video size/quality trade-offs - Resolution caps, FPS reduction, CRF tuning, optional two-pass encoding - Optional comparison summary between original and optimized outputs
See scripts/requirements.txt for environment expectations (Python 3.10+, FFmpeg, ImageMagick) and system installation hints.
Usage Guidelines
- Check dependencies first
- Ensure ffmpeg and ffprobe are installed and on PATH for video/audio tasks. - Ensure magick (ImageMagick) is installed and on PATH for image tasks.
- Prefer dry-runs when exploring
- Use --dry-run and/or --verbose flags on scripts to inspect generated commands before running them.
- Keep originals
- Point outputs to a separate directory on first runs (e.g., --output./out/) to avoid accidental overwrites.
- Document workflows
- When you find good command lines or script invocations, promote them into project scripts (e.g., just, npm scripts, or CI jobs) so they’re repeatable.
References
For deeper tool-specific notes (placeholders for now, extend as needed), see:
references/ffmpeg-encoding.md– FFmpeg encoding patterns and flagsreferences/ffmpeg-filters.md– Common filter graphs (scale, crop, audio filters)references/ffmpeg-streaming.md– Streaming-friendly settings and HLS/DASH tipsreferences/format-compatibility.md– Container/codec compatibility notes (web, mobile, desktop)references/imagemagick-batch.md– Batch image processing patterns with ImageMagickreferences/imagemagick-editing.md– Image editing operations (crop, resize, composite, text, etc.)