medix 1.4.0

A fancy CLI media format converter powered by FFmpeg

Medix

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.vineethnk.in — installation, guides, CLI reference, and roadmap.

---

Demo

File Discovery

Medix scans your path and presents a clean table of all discovered media files with resolution, duration, and size.

Conversion Plan & Progress

Review your settings before starting, then watch per-file and overall progress in real time.

Auto-Install Prerequisites

No FFmpeg? No problem. Medix detects your OS, finds a package manager, and offers to install it for you.

Completion Summary

---

Requirements

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

Supported Platforms

• macOS 12+ (Homebrew, MacPorts)
• Ubuntu 20.04+ / Debian 11+ (APT)
• Fedora / RHEL (DNF, YUM)
• Arch Linux (Pacman)
• Windows 10+ (winget, Chocolatey, Scoop)

---

Installation

Medix is on PyPI and mirrored on libraries.io. Pick whichever workflow fits you best — the full installation guide covers every option.

From PyPI (recommended)

pip install medix

With pipx (isolated global install)

pipx install medix

From source

git clone https://github.com/vineethkrishnan/medix.git
cd medix
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

From a Git tag or branch directly

pip install "git+https://github.com/vineethkrishnan/medix.git@main"

As a dependency in pyproject.toml

[project]
dependencies = ["medix>=1.3.0"]

Verify

medix --version

FFmpeg

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

---

Usage

# 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

What Happens

1. Medix checks for FFmpeg — if missing, it offers to install it automatically.
2. Scans the path and lists discovered media files with metadata (resolution, duration, size).
3. If multiple source formats exist, you pick which ones to convert.
4. Choose an output format (MP4, MKV, WebM, MOV, AVI, TS).
5. Optionally configure advanced settings — codec, resolution, frame rate, CRF, preset, bitrate.
6. Review the conversion plan and confirm.
7. Watch per-file and overall progress bars in real time.

Dry Run

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-run

CLI Reference

Usage: 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

---

Supported Formats

Input (20+)

VOB, MP4, MKV, AVI, MOV, WMV, FLV, MPEG, MPG, TS, WebM, M4V, 3GP, OGV, MTS, M2TS, DIVX, ASF, RM, RMVB, F4V

Output

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

Advanced Settings

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

---

Development

git clone https://github.com/vineethkrishnan/medix.git
cd medix
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Running Tests

# 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.py

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

Re-generate demo screenshots

python assets/generate_demos.py

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

---

Documentation

The full documentation site is at medix.vineethnk.in — 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 dev

---

Roadmap

Highlights from the full roadmap:

• v1.4 — named presets, .medixrc config 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.

---

License

MIT — see LICENSE for details.