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