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

media-processing

NPX Install

Tags

SKILL.md Content