conv

Mac-native universal file and media converter for developers who want one command, adaptive defaults, and benchmark-backed ffmpeg flags instead of hand-tuned conversion scripts.

conv input.any output.any

conv routes video, audio, image, and document conversions through the fastest available local tool for your Mac. It detects Apple Silicon vs Intel, RAM tier, VideoToolbox support, and safe parallelism, then applies defaults learned from 55+ local benchmarks.

🚀 Quickstart · 🎬 Try it · 🗺️ Tool map · ⚙️ Profiles · 🔒 Limits

Quickstart

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Supersynergy/conv/main/install.sh)"
source ~/.zshrc
conv_info

Expected result: conv_info prints your detected profile and conv --help is available in the current shell.

Prefer to inspect first:

git clone https://github.com/Supersynergy/conv
cd conv
sed -n '1,140p' install.sh

Uninstall:

curl -fsSL https://raw.githubusercontent.com/Supersynergy/conv/main/uninstall.sh | bash

Try It

conv movie.mkv movie.mp4        # remux to MP4 when copy is safe
conv photo.heic photo.jpg       # native HEIC to JPEG through sips
conv voice.wav voice.mp3        # speech-friendly MP3 defaults
conv design.png design.jxl      # JPEG XL compression
conv notes.md notes.pdf         # Markdown to PDF through pandoc/typst

Typical benchmark examples from the included M4 Max run:

📋 Show 5 entries

• MKV to MP4 remux
  Result: 0.18s

• HEIC to JPEG
  Result: 0.20s

• WAV voice to MP3 V2
  Result: 0.21s, 95% smaller

• PNG to JXL q85
  Result: 0.49s, 98.4% smaller

• Typst to PDF
  Result: 0.22s

See docs/benchmarks/BENCHMARKS.md for the full data and caveats.

Why It Exists

Raw ffmpeg is powerful, but the defaults are easy to get wrong. On the benchmark input, this one missing bitrate flag changed the output size by an order of magnitude:

ffmpeg -c:v h264_videotoolbox            1791% output ratio
ffmpeg -c:v h264_videotoolbox -b:v 6000k  744% output ratio
ffmpeg -c:v h264_videotoolbox -b:v 4000k  496% output ratio
ffmpeg -c:v h264_videotoolbox -b:v 2000k  277% output ratio

conv keeps the useful part of ffmpeg and removes the repeated decision work: format routing, hardware profile, bitrate, encoder preset, image optimizer, and batch safety.

Tool Map

📋 Show 7 entries

• conv <input> <output>
  Use: Convert one file with automatic routing

• conv_info
  Use: Show detected CPU, RAM, VideoToolbox, and defaults

• convall <src> <dst>
  Use: Batch convert files in the current directory

• optimg <files...>
  Use: Optimize PNG/JPG files in place

• optall
  Use: Recursively optimize images in parallel

• smartencode <video> [low/med/high/lossless/auto]
  Use: Encode video with named quality targets

• resize <image> <width>
  Use: Resize through vips or sips depending on profile

Powered by ffmpeg, vips, gifski, oxipng, pngquant, jpegoptim, cjxl, avifenc, cwebp, typst, pandoc, sox, sips, ImageMagick, ab-av1, and mediainfo.

Adaptive Profiles

conv initializes once per shell and exports conversion defaults for your machine.

📋 Show 5 entries

• Ultra
  Hardware: M-series Ultra
  H.264: 6000k
  H.265: 5000k
  AV1: p6
  AVIF: s4
  Parallel: 8
  Resize: vips

• Max
  Hardware: M-series Max
  H.264: 4000k
  H.265: 3000k
  AV1: p8
  AVIF: s6
  Parallel: 6
  Resize: vips

• Pro
  Hardware: M-series Pro
  H.264: 4000k
  H.265: 3000k
  AV1: p8
  AVIF: s6
  Parallel: 4
  Resize: vips

• Base
  Hardware: M1/M2/M3/M4
  H.264: 3000k
  H.265: 2500k
  AV1: p10
  AVIF: s8
  Parallel: 2
  Resize: sips

• Intel
  Hardware: Intel Mac
  H.264: libx264 -crf 23
  H.265: libx265 -crf 28
  AV1: p12
  AVIF: s9
  Parallel: 2
  Resize: sips

Overrides:

CONV_H264_BR=8000k conv in.mov out.mp4
CONV_SOUND=0 conv in.wav out.mp3
CONV_KONAMI=1 conv in.mkv out.mp4

Repository Layout

📋 Show 6 entries

• converter.sh
  Purpose: Main shell implementation

• install.sh
  Purpose: Homebrew dependency install and shell wiring

• uninstall.sh
  Purpose: Removes installed files and shell hook

• skill/universal-media-converter.md
  Purpose: Agent skill for Claude Code / GG Coder style workflows

• docs/benchmarks/BENCHMARKS.md
  Purpose: Benchmark table and Pareto findings

• CONTRIBUTING.md
  Purpose: Benchmark and PR guide

Agent Integration

The installer copies the bundled skill into ~/.gg/skills/ when that directory exists. Agents can then call conv instead of inventing raw ffmpeg commands.

Skip skill installation:

CONV_SKILL_DIR=/dev/null /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Supersynergy/conv/main/install.sh)"

Agent instructions for this repository live in AGENTS.md.

Development

brew install shellcheck ffmpeg pandoc imagemagick webp libavif jpeg-xl
shellcheck converter.sh install.sh uninstall.sh
source ./converter.sh
conv_info
conv --help

The GitHub Actions suite runs ShellCheck on Ubuntu and smoke conversions on macOS.

Limits

• macOS only.
• Benchmarks are from one M4 Max system; your files and hardware will differ.
• The CatBoost note is about ranking tested configs, not predicting universal outcomes.
• pipe | bash is convenient but always deserves inspection. Read install.sh if you are unsure.

Contributing

The highest-value contribution is a benchmark from a real Mac. M1 base, M2 Pro, M3 Ultra, Intel, and unusual media files are especially useful. See CONTRIBUTING.md.

License

MIT © Supersynergy.