A fancy command-line media format converter powered by FFmpeg. Interactively choose source and target formats, tweak advanced encoding settings, and watch conversions fly with real-time progress bars.
📖 Full documentation: medix.vinelabs.de — installation, guides, CLI reference, and roadmap.
Medix scans your path and presents a clean table of all discovered media files with resolution, duration, and size.
Review your settings before starting, then watch per-file and overall progress in real time.
No FFmpeg? No problem. Medix detects your OS, finds a package manager, and offers to install it for you.
| Dependency | Minimum Version | Check Command |
|---|---|---|
| Python | 3.9+ | python3 --version |
| FFmpeg | 4.4+ | ffmpeg -version |
| ffprobe | (bundled with FFmpeg) | ffprobe -version |
Note: If FFmpeg is not installed, Medix will detect your system and offer to install it automatically via your package manager (Homebrew, APT, DNF, Pacman, winget, Chocolatey, and more).
- macOS 12+ (Homebrew, MacPorts)
- Ubuntu 20.04+ / Debian 11+ (APT)
- Fedora / RHEL (DNF, YUM)
- Arch Linux (Pacman)
- Windows 10+ (winget, Chocolatey, Scoop)
Medix is on PyPI and mirrored on libraries.io. Pick whichever workflow fits you best — the full installation guide covers every option.
pip install medixpipx install medixgit clone https://github.com/vineethkrishnan/medix.git
cd medix
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .pip install "git+https://github.com/vineethkrishnan/medix.git@main"[project]
dependencies = ["medix>=1.3.0"]medix --versionMedix needs FFmpeg at runtime, but you don't have to install it first — on first run it detects your platform and offers to install it via Homebrew, APT, DNF, Pacman, winget, Chocolatey, or Scoop. See the FFmpeg Auto-Install guide for manual install commands.
# Convert a single file
medix /path/to/video.vob
# Convert all media files in a directory
medix /path/to/videos/
# Recurse into subdirectories
medix /path/to/videos/ -r
# Specify output directory
medix /path/to/videos/ -o /path/to/output/
# Dry run — see what would happen without converting
medix /path/to/videos/ --dry-run- Medix checks for FFmpeg — if missing, it offers to install it automatically.
- Scans the path and lists discovered media files with metadata (resolution, duration, size).
- If multiple source formats exist, you pick which ones to convert.
- Choose an output format (MP4, MKV, WebM, MOV, AVI, TS).
- Optionally configure advanced settings — codec, resolution, frame rate, CRF, preset, bitrate.
- Review the conversion plan and confirm.
- Watch per-file and overall progress bars in real time.
Use --dry-run (or -n) to preview the conversion plan without writing any files. Medix will show you the file mapping and the exact ffmpeg command that would be executed:
medix /path/to/videos/ --dry-runUsage: medix [OPTIONS] PATH
Medix - Convert media files between formats with style.
Options:
-o, --output PATH Output directory (default: <input>/converted/)
-r, --recursive Recurse into subdirectories
-n, --dry-run Show what would be done without converting
--version Show version and exit
-h, --help Show help and exit
VOB, MP4, MKV, AVI, MOV, WMV, FLV, MPEG, MPG, TS, WebM, M4V, 3GP, OGV, MTS, M2TS, DIVX, ASF, RM, RMVB, F4V
| Format | Default Codecs | Best For |
|---|---|---|
| MP4 | H.264 + AAC | Universal playback |
| MKV | H.264 + AAC | Flexible container |
| WebM | VP9 + Opus | Web streaming |
| MOV | H.264 + AAC | Apple ecosystem |
| AVI | H.264 + MP3 | Legacy compatibility |
| TS | H.264 + AAC | Broadcast / streaming |
When enabled, you can configure:
- Video codec — H.264, H.265, VP9, AV1, MPEG-4, or copy (no re-encode)
- Audio codec — AAC, MP3, Opus, AC3, FLAC, or copy
- Resolution — Keep original, 4K, 2K, 1080p, 720p, 480p, 360p
- Frame rate — Keep original, 24, 25, 30, 48, 60 fps
- Encoding preset — ultrafast to veryslow (H.264/H.265)
- CRF quality — 0–51 (lower = better quality, larger file)
- Audio bitrate — Auto, 96k–320k
git clone https://github.com/vineethkrishnan/medix.git
cd medix
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"# Run the full test suite
pytest
# With coverage report
pytest --cov=medix --cov-report=term-missing
# Run a specific test file
pytest tests/test_converter.pyTests cover all modules (converter, CLI, dependencies, formats) and run on every push across Python 3.9–3.13 on Linux, macOS, and Windows via CI.
python assets/generate_demos.pyThis project uses Conventional Commits and Release Please for automated versioning and changelog generation.
See CONTRIBUTING.md for guidelines and the Release Process docs for how releases are cut.
The full documentation site is at medix.vinelabs.de — built with Astro Starlight, searchable via Pagefind, and deployed to Cloudflare Pages.
| Section | What's there |
|---|---|
| Getting Started | Requirements, installation, quick start |
| Guides | CLI usage, dry-run, formats, advanced settings, FFmpeg setup |
| Reference | Complete CLI reference and supported formats matrix |
| Development | Contributing, testing, release process |
| Roadmap | What's coming in v1.4, v1.5, v1.6, and v2.0 |
To preview the docs locally:
cd docs
npm install
npm run devHighlights from the full roadmap:
- v1.4 — named presets,
.medixrcconfig file, non-interactive mode, JSON output, shell completion - v1.5 — metadata/subtitle preservation, hardware acceleration (VideoToolbox / NVENC / QuickSync / VAAPI), two-pass encoding, HDR tone-mapping, thumbnails
- v1.6 — resume support, parallel encoding, watch mode, smart skip
- v2.0 — stable Python API, plugin system, TUI mode
Vote on items or suggest new ones on the issue tracker.