media-format-convert

A small, dependency-free command-line tool that wraps ffmpeg to batch-convert media files in a folder. Point it at a directory, tell it the source and target extension, and it converts every matching file.

Common conversions ship with sensible presets:

From	To	Preset
mov	mp4	H.264 (libx264) video + AAC audio, preset fast, -crf 22 (light file, good quality)
oga	mp3	stereo, 44.1 kHz, 192 kbit/s (libmp3lame)
ogg	mp3	stereo, 44.1 kHz, 192 kbit/s (libmp3lame)
ogg	wav	PCM (ffmpeg defaults)
oga	wav	PCM (ffmpeg defaults)

Any other extension pair also works — it falls back to ffmpeg's defaults for that container/codec.

The problem it solves

ffmpeg can convert anything, but nobody remembers the exact flags for a clean H.264 MP4 or a 192 kbit/s MP3 — and running it file by file over a folder is tedious. This wraps the flags I actually use into named presets and applies them to a whole directory in one command.

Requirements

• Python 3.9+
• ffmpeg available on your PATH. This tool does not bundle or install ffmpeg; it calls the system binary via subprocess.

Install ffmpeg with your platform's package manager:

# macOS
brew install ffmpeg

# Debian / Ubuntu
sudo apt install ffmpeg

# Windows: download from https://ffmpeg.org/download.html and add to PATH

Install

From the project root:

pip install .

Or for development (editable install):

pip install -e .

This exposes the media-format-convert command.

Usage

media-format-convert FOLDER --from EXT --to EXT [--out DIR] [--dry-run] [--no-overwrite]

Convert every .oga file in a folder to stereo MP3:

media-format-convert ./recordings --from oga --to mp3

Convert .mov clips to light .mp4, writing into a chosen folder:

media-format-convert ./clips --from mov --to mp4 --out ./encoded

Preview the exact ffmpeg commands without running anything:

media-format-convert ./clips --from mov --to mp4 --dry-run

Don't overwrite files that already exist in the output directory:

media-format-convert ./recordings --from ogg --to wav --no-overwrite

Options

Option	Description
FOLDER	Folder to scan for input files (non-recursive).
--from EXT	Source extension to match (case-insensitive, e.g. mov).
--to EXT	Target extension (e.g. mp4).
--out DIR	Output directory. Defaults to a sibling folder <folder>_<to>.
--dry-run	Print the planned ffmpeg commands and exit without converting.
--no-overwrite	Pass -n to ffmpeg so existing outputs are kept.

Output location

If you don't pass --out, results are written to a sibling folder named after the input folder plus the target extension. For example, converting the folder recordings to mp3 produces a recordings_mp3 folder next to it. Output file names keep the original stem with the new extension (note.oga -> note.mp3).

How it works

The tool discovers matching files, builds an ffmpeg argument vector per file (ffmpeg -y -i <src> <preset args...> <dst>), then runs each one through subprocess. ffmpeg is located with shutil.which; if it's missing you get a clear error (or a warning in --dry-run, since the planned commands are still worth inspecting).

Roadmap

Honest next steps:

• Recursive folder scanning (currently top-level only).
• Parallel conversion with a --workers flag for large folders.
• Per-pair quality flags (e.g. configurable CRF / bitrate).

License

MIT. See LICENSE.