media-processing

# 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 flags
- `references/ffmpeg-filters.md` – Common filter graphs (scale, crop, audio filters)
- `references/ffmpeg-streaming.md` – Streaming-friendly settings and HLS/DASH tips
- `references/format-compatibility.md` – Container/codec compatibility notes (web, mobile, desktop)
- `references/imagemagick-batch.md` – Batch image processing patterns with ImageMagick
- `references/imagemagick-editing.md` – Image editing operations (crop, resize, composite, text, etc.)