{"id":50418855,"url":"https://github.com/chyinan/uvr-headless-runner","last_synced_at":"2026-05-31T07:30:23.246Z","repository":{"id":336371354,"uuid":"1148822917","full_name":"chyinan/uvr-headless-runner","owner":"chyinan","description":"Production-ready UVR5 CLI \u0026 Docker image. Run SOTA separation models (Roformer, SCNet, MDX, Demucs, VR Architecture) on headless GPU servers without dependency hell.","archived":false,"fork":false,"pushed_at":"2026-02-07T11:52:49.000Z","size":2379,"stargazers_count":86,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-18T16:09:55.453Z","etag":null,"topics":["automated","batch-processing","cli","command-line","command-line-interface","command-line-tool","demucs","docker","headless","mdx","mdx-net","pytorch","roformer","scnet","ultimate-vocal-remover","uvr","uvr-cli","uvr5","vr-architecture"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chyinan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-03T12:08:22.000Z","updated_at":"2026-03-30T16:59:31.000Z","dependencies_parsed_at":null,"dependency_job_id":"ef8f6ebd-dc3c-4b14-ac1c-a92654fa1b42","html_url":"https://github.com/chyinan/uvr-headless-runner","commit_stats":null,"previous_names":["chyinan/uvr-headless-runner"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/chyinan/uvr-headless-runner","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chyinan%2Fuvr-headless-runner","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chyinan%2Fuvr-headless-runner/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chyinan%2Fuvr-headless-runner/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chyinan%2Fuvr-headless-runner/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chyinan","download_url":"https://codeload.github.com/chyinan/uvr-headless-runner/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chyinan%2Fuvr-headless-runner/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33723548,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automated","batch-processing","cli","command-line","command-line-interface","command-line-tool","demucs","docker","headless","mdx","mdx-net","pytorch","roformer","scnet","ultimate-vocal-remover","uvr","uvr-cli","uvr5","vr-architecture"],"created_at":"2026-05-31T07:30:22.498Z","updated_at":"2026-05-31T07:30:23.224Z","avatar_url":"https://github.com/chyinan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://readme-typing-svg.demolab.com?font=Fira+Code\u0026weight=700\u0026size=28\u0026duration=3000\u0026pause=1000\u0026color=A78BFA\u0026center=true\u0026vCenter=true\u0026width=500\u0026lines=%F0%9F%8E%B5+UVR+Headless+Runner;Audio+Source+Separation+CLI\"\u003e\n    \u003cimg alt=\"UVR Headless Runner\" src=\"https://readme-typing-svg.demolab.com?font=Fira+Code\u0026weight=700\u0026size=28\u0026duration=3000\u0026pause=1000\u0026color=7C3AED\u0026center=true\u0026vCenter=true\u0026width=500\u0026lines=%F0%9F%8E%B5+UVR+Headless+Runner;Audio+Source+Separation+CLI\"\u003e\n  \u003c/picture\u003e\n\u003c/p\u003e\n\n\u003ch3 align=\"center\"\u003e🎧 Separate vocals, instruments, drums, bass \u0026 more from any audio\u003c/h3\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eCommand-line audio source separation powered by UVR\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/chyinan/uvr-headless-runner/blob/master/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License: MIT\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/python-3.9+-green.svg\" alt=\"Python 3.9+\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pytorch.org/\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg\" alt=\"PyTorch\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/chyinan/uvr-headless-runner\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/platform-Windows%20|%20Linux%20|%20macOS-lightgrey.svg\" alt=\"Platform\"\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://pypi.org/project/uvr-headless-runner/\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/uvr-headless-runner.svg?color=blue\" alt=\"PyPI\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README_CN.md\"\u003e🇨🇳 中文\u003c/a\u003e | \u003cstrong\u003e🇬🇧 English\u003c/strong\u003e | \u003ca href=\"DOCKER_README.md\"\u003e🐳 Docker\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## ✨ Features\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\"\u003e\n\n### 🎸 MDX-Net Runner\n- MDX-Net / MDX-C models\n- **Roformer** (MelBandRoformer, BSRoformer)\n- **SCNet** (Sparse Compression Network)\n- ONNX \u0026 PyTorch checkpoints\n\n\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\n\n### 🥁 Demucs Runner\n- Demucs v1 / v2 / v3 / v4\n- **htdemucs** / **htdemucs_ft**\n- **6-stem separation** (Guitar, Piano)\n- Auto model download\n\n\u003c/td\u003e\n\u003ctd width=\"33%\"\u003e\n\n### 🎤 VR Runner\n- VR Architecture models\n- **VR 5.1** model support\n- Window size / Aggression tuning\n- TTA \u0026 Post-processing\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n### 🚀 Highlights\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003cth width=\"50%\"\u003eFeature\u003c/th\u003e\n\u003cth width=\"50%\"\u003eDescription\u003c/th\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e🎯 \u003cb\u003eGUI-Identical\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eExactly replicates UVR GUI behavior\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e⚡ \u003cb\u003eGPU Accelerated\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eNVIDIA CUDA \u0026 AMD DirectML support\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e🔧 \u003cb\u003eZero Config\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eAuto-detect model parameters\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e📦 \u003cb\u003eBatch Ready\u003c/b\u003e\u003c/td\u003e\u003ctd\u003ePerfect for automation \u0026 pipelines\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e🎚️ \u003cb\u003eBit Depth Control\u003c/b\u003e\u003c/td\u003e\u003ctd\u003e16/24/32-bit PCM, 32/64-bit float\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e📥 \u003cb\u003eAuto Download\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eOfficial UVR model registry with auto-download\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e🛡️ \u003cb\u003eRobust Error Handling\u003c/b\u003e\u003c/td\u003e\u003ctd\u003eGPU fallback, retry, fuzzy matching\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e🔗 \u003cb\u003eUnified CLI\u003c/b\u003e\u003c/td\u003e\u003ctd\u003e\u003ccode\u003euvr mdx\u003c/code\u003e / \u003ccode\u003euvr demucs\u003c/code\u003e / \u003ccode\u003euvr vr\u003c/code\u003e — one command for all\u003c/td\u003e\u003c/tr\u003e\n\u003ctr\u003e\u003ctd\u003e📦 \u003cb\u003ePyPI Ready\u003c/b\u003e\u003c/td\u003e\u003ctd\u003e\u003ccode\u003epip install uvr-headless-runner\u003c/code\u003e — instant setup\u003c/td\u003e\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📖 Design Philosophy\n\n\u003e \u003cimg src=\"https://img.shields.io/badge/IMPORTANT-red?style=flat-square\" alt=\"Important\"/\u003e\n\u003e \n\u003e **This project is a headless automation layer for [Ultimate Vocal Remover](https://github.com/Anjok07/ultimatevocalremovergui).**\n\u003e \n\u003e It does **NOT** reimplement any separation logic.  \n\u003e It **EXACTLY REPLICATES** UVR GUI behavior — model loading, parameter fallback, and auto-detection.\n\u003e \n\u003e **✅ If a model works in UVR GUI, it works here — no extra config needed.**\n\n---\n\n## 🤔 Why uvr-headless-runner?\n\n\u003e Built for maximum flexibility. Load any custom model without waiting for upstream updates.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" align=\"center\"\u003e\n\n### 🎨 Full Custom Model Support\n\nDirectly load any `.pth` or `.ckpt` file.  \n**Perfect for testing new finetunes or experimental models immediately.**\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" align=\"center\"\u003e\n\n### 🖥️ Headless \u0026 Remote Ready\n\nBuilt for seamless integration into  \n**web services or automation scripts.**\n\n\u003c/td\u003e\n\u003ctd width=\"33%\" align=\"center\"\u003e\n\n### 👥 By Users, For Users\n\nDesigned by audio enthusiasts who  \n**prioritize complete control and native UVR compatibility.**\n\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 📋 Requirements\n\n| Component | Requirement |\n|-----------|-------------|\n| **Python** | 3.9.x (3.10+ not fully tested) |\n| **GPU** | NVIDIA CUDA or AMD DirectML *(optional)* |\n| **OS** | Windows / Linux / macOS |\n\n---\n\n## 🔧 Installation\n\n\u003cdetails open\u003e\n\u003csummary\u003e\u003cb\u003e🚀 Option 1: pip install from PyPI (Recommended)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Install from PyPI\npip install uvr-headless-runner\n\n# GPU support (NVIDIA)\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124\n\n# ONNX GPU (optional)\npip install onnxruntime-gpu\n```\n\nAfter installation, you get the **`uvr` unified CLI** — no need to clone the repo!\n\n```bash\nuvr mdx -m \"UVR-MDX-NET Inst HQ 3\" -i song.wav -o output/\nuvr demucs -m htdemucs -i song.wav -o output/\nuvr vr -m \"UVR-De-Echo-Normal\" -i song.wav -o output/\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📦 Option 2: Poetry (from source)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Clone repository\ngit clone https://github.com/chyinan/uvr-headless-runner.git\ncd uvr-headless-runner\n\n# Install dependencies\npoetry install\n\n# GPU support (NVIDIA)\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124\n\n# ONNX GPU (optional)\npip install onnxruntime-gpu\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📦 Option 3: pip + venv (from source)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Clone repository\ngit clone https://github.com/chyinan/uvr-headless-runner.git\ncd uvr-headless-runner\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # Linux/macOS\n# venv\\Scripts\\activate   # Windows\n\n# Install dependencies\npip install -r requirements.txt\n\n# GPU support (NVIDIA)\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🔴 AMD GPU (DirectML)\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Install DirectML support\npip install torch-directml\n\n# Use with --directml flag\npython mdx_headless_runner.py -m model.ckpt -i song.wav -o output/ --directml\n```\n\n\u003e ⚠️ DirectML is experimental. NVIDIA CUDA recommended for best performance.\n\n\u003c/details\u003e\n\n### ✅ Verify Installation (Native Python Only)\n\n```bash\npython -c \"import torch; print(f'PyTorch: {torch.__version__}'); print(f'CUDA: {torch.cuda.is_available()}')\"\n```\n\n\u003e 💡 Skip this if using Docker - the container includes all dependencies.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e🐳 Option 4: Docker Hub (No Build Required!)\u003c/b\u003e\u003c/summary\u003e\n\n**Fastest way to get started - just pull and run!**\n\n```bash\n# Pull pre-built image from Docker Hub\ndocker pull chyinan/uvr-headless-runner:latest\n\n# Run directly (GPU mode)\ndocker run --rm --gpus all \\\n  -v ~/.uvr_models:/models \\\n  -v $(pwd):/data \\\n  chyinan/uvr-headless-runner:latest \\\n  uvr-mdx -m \"UVR-MDX-NET Inst HQ 3\" -i /data/song.wav -o /data/output/\n\n# Run directly (CPU mode)\ndocker run --rm \\\n  -v ~/.uvr_models:/models \\\n  -v $(pwd):/data \\\n  chyinan/uvr-headless-runner:latest \\\n  uvr-mdx -m \"UVR-MDX-NET Inst HQ 3\" -i /data/song.wav -o /data/output/ --cpu\n```\n\n**Or install CLI wrappers for native experience:**\n\n```bash\n# One-click install (auto-detects GPU)\n./docker/install.sh      # Linux/macOS\n.\\docker\\install.ps1     # Windows\n\n# Then use like native commands\nuvr-mdx -m \"UVR-MDX-NET Inst HQ 3\" -i song.wav -o output/\nuvr-demucs -m htdemucs -i song.wav -o output/\nuvr-vr -m \"UVR-De-Echo-Normal\" -i song.wav -o output/\n```\n\n📖 **[Full Docker Guide →](DOCKER_README.md)**\n\n\u003c/details\u003e\n\n---\n\n## 🎼 Quick Start\n\n### Unified CLI (pip install / Docker)\n\nAfter installing via `pip install uvr-headless-runner` or Docker, you can use the **short commands**:\n\n```bash\n# MDX-Net / Roformer separation\nuvr mdx -m \"UVR-MDX-NET Inst HQ 3\" -i song.wav -o output/ --gpu\n\n# Demucs separation\nuvr demucs -m htdemucs -i song.wav -o output/ --gpu\n\n# VR Architecture separation\nuvr vr -m \"UVR-De-Echo-Normal\" -i song.wav -o output/ --gpu\n\n# List all available models\nuvr list all\n\n# Download a model\nuvr download \"UVR-MDX-NET Inst HQ 3\" --arch mdx\n\n# Show system info\nuvr info\n```\n\n\u003e 💡 You can also use standalone commands: `uvr-mdx`, `uvr-demucs`, `uvr-vr`\n\n### MDX-Net / Roformer / SCNet\n\n```bash\n# Basic separation\npython mdx_headless_runner.py -m \"model.ckpt\" -i \"song.flac\" -o \"output/\" --gpu\n\n# Vocals only (24-bit)\npython mdx_headless_runner.py -m \"model.ckpt\" -i \"song.flac\" -o \"output/\" --gpu --vocals-only --wav-type PCM_24\n```\n\n### Demucs\n\n```bash\n# All 4 stems\npython demucs_headless_runner.py --model htdemucs --input \"song.flac\" --output \"output/\" --gpu\n\n# Vocals only\npython demucs_headless_runner.py --model htdemucs --input \"song.flac\" --output \"output/\" --gpu --stem Vocals --primary-only\n```\n\n### VR Architecture\n\n```bash\n# Basic separation (model in database)\npython vr_headless_runner.py -m \"model.pth\" -i \"song.flac\" -o \"output/\" --gpu\n\n# Custom model (not in database)\npython vr_headless_runner.py -m \"model.pth\" -i \"song.flac\" -o \"output/\" --gpu \\\n    --param 4band_v3 --primary-stem Vocals\n```\n\n---\n\n## 📥 Model Download Center\n\nAll runners now include **automatic model downloading** from official UVR sources - just like the GUI!\n\n### List Available Models\n\n```bash\n# List all MDX-Net models\npython mdx_headless_runner.py --list\n\n# List only installed models\npython mdx_headless_runner.py --list-installed\n\n# List models not yet downloaded\npython mdx_headless_runner.py --list-uninstalled\n\n# Same for Demucs and VR\npython demucs_headless_runner.py --list\npython vr_headless_runner.py --list\n```\n\n### Download Models\n\n```bash\n# Download a specific model (without running inference)\npython mdx_headless_runner.py --download \"UVR-MDX-NET Inst HQ 3\"\npython demucs_headless_runner.py --download \"htdemucs_ft\"\npython vr_headless_runner.py --download \"UVR-De-Echo-Normal by FoxJoy\"\n```\n\n### Auto-Download on Inference\n\n```bash\n# Just use the model name - it will download automatically if not installed!\npython mdx_headless_runner.py -m \"UVR-MDX-NET Inst HQ 3\" -i \"song.flac\" -o \"output/\" --gpu\n\n# Demucs models auto-download too\npython demucs_headless_runner.py --model htdemucs_ft --input \"song.flac\" --output \"output/\" --gpu\n```\n\n### Model Info \u0026 Fuzzy Matching\n\n```bash\n# Get detailed info about a model\npython mdx_headless_runner.py --model-info \"UVR-MDX-NET Inst HQ 3\"\n\n# Typo? Get suggestions!\npython mdx_headless_runner.py --model-info \"UVR-MDX Inst HQ\"\n# Output: Did you mean: UVR-MDX-NET Inst HQ 1, UVR-MDX-NET Inst HQ 2, ...\n```\n\n### Features\n\n| Feature | Description |\n|---------|-------------|\n| 🌐 **Official Registry** | Syncs with UVR's official model list |\n| 🔄 **Resume Downloads** | Interrupted downloads can be resumed |\n| ⏱️ **Retry with Backoff** | Automatic retry on network errors |\n| 💾 **Disk Space Check** | Pre-checks available space before download |\n| 🔍 **Fuzzy Matching** | Suggests similar model names on typos |\n| ✅ **Integrity Check** | Validates downloaded files |\n\n---\n\n## 🛡️ Error Handling \u0026 GPU Fallback\n\nAll runners include **robust error handling** with automatic GPU-to-CPU fallback:\n\n```bash\n# If GPU runs out of memory, automatically falls back to CPU\npython mdx_headless_runner.py -m \"model.ckpt\" -i \"song.flac\" -o \"output/\" --gpu\n\n# Output on GPU error:\n# ============================================================\n# ERROR: GPU memory exhausted\n# ============================================================\n# Suggestion: Try: (1) Use --cpu flag, (2) Reduce --batch-size...\n#\n# Attempting to fall back to CPU mode...\n```\n\n### Error Messages\n\nErrors now include clear explanations and suggestions:\n\n| Before | After |\n|--------|-------|\n| `FileNotFoundError` | `Audio file not found: song.wav` |\n| `CUDA out of memory` | `GPU memory exhausted. Try: --cpu or reduce --batch-size` |\n| `Model not found` | `Model 'xyz' not found. Did you mean: UVR-MDX-NET...?` |\n\n---\n\n## 📊 CLI Progress Display\n\nAll runners feature a **professional CLI progress system** with real-time feedback:\n\n```\n╭──────────────────────────────────────────────────────────────────────────╮\n│                          UVR Audio Separation                            │\n├──────────────────────────────────────────────────────────────────────────┤\n│  Model         │ UVR-MDX-NET Inst HQ 3                                   │\n│  Input         │ song.flac                                               │\n│  Output        │ ./output/                                               │\n│  Device        │ CUDA:0                                                  │\n│  Architecture  │ MDX-Net                                                 │\n╰──────────────────────────────────────────────────────────────────────────╯\n\n⠹ Downloading model: UVR-MDX-NET Inst HQ 3\n  ████████████████████████████████████████ 100% • 245.3 MB • 12.5 MB/s • 0:00:00\n\n✓ Model downloaded\n\n⠹ Running inference\n  ████████████████░░░░░░░░░░░░░░░░░░░░░░░░  42% • 0:01:23 • 0:01:52\n\n✓ Inference complete\n\n╭──────────────────────────────────────────────────────────────────────────╮\n│              ✓ Processing completed in 3:15                              │\n╰──────────────────────────────────────────────────────────────────────────╯\n\nOutput files:\n  • output/song_(Vocals).wav\n  • output/song_(Instrumental).wav\n```\n\n### Features\n\n| Feature | Description |\n|---------|-------------|\n| 📥 **Download Progress** | Real-time speed, ETA, and transfer stats for model downloads |\n| 🎯 **Inference Progress** | Chunk-based progress tracking during audio processing |\n| ⏱️ **Time Estimates** | Elapsed time and remaining time (ETA) display |\n| 🎨 **Rich Output** | Beautiful terminal UI with `rich` library |\n| 🐳 **Docker Compatible** | Works seamlessly inside containers |\n| 📉 **Graceful Fallback** | Falls back to basic output if `rich` unavailable |\n\n### Progress Library Support\n\nThe system automatically selects the best available library:\n\n1. **`rich`** (preferred) - Full-featured progress bars with colors\n2. **`tqdm`** (fallback) - Standard progress bars\n3. **Basic** (no deps) - Simple text-based progress\n\nInstall `rich` for the best experience:\n```bash\npip install rich\n```\n\n### Quiet Mode\n\nDisable progress output for scripting:\n```bash\npython mdx_headless_runner.py -m model.ckpt -i song.wav -o output/ --quiet\n```\n\n---\n\n## 🎛️ MDX-Net Runner\n\n### Command Line Arguments\n\n| Argument | Short | Default | Description |\n|----------|-------|---------|-------------|\n| `--model` | `-m` | **Required** | Model file path (.ckpt/.onnx) |\n| `--input` | `-i` | **Required** | Input audio file |\n| `--output` | `-o` | **Required** | Output directory |\n| `--gpu` | | Auto | Use NVIDIA CUDA |\n| `--directml` | | | Use AMD DirectML |\n| `--overlap` | | `0.25` | MDX overlap (0.25-0.99) |\n| `--overlap-mdxc` | | `2` | MDX-C/Roformer overlap (2-50) |\n| `--wav-type` | | `PCM_24` | Output: PCM_16/24/32, FLOAT, DOUBLE |\n| `--vocals-only` | | | Output vocals only |\n| `--instrumental-only` | | | Output instrumental only |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 All Arguments\u003c/b\u003e\u003c/summary\u003e\n\n| Argument | Description |\n|----------|-------------|\n| `--name` `-n` | Output filename base |\n| `--json` | Model JSON config |\n| `--cpu` | Force CPU |\n| `--device` `-d` | GPU device ID |\n| `--segment-size` | Segment size (default: 256) |\n| `--batch-size` | Batch size (default: 1) |\n| `--primary-only` | Save primary stem only |\n| `--secondary-only` | Save secondary stem only |\n| `--stem` | MDX-C stem select |\n| `--quiet` `-q` | Quiet mode |\n\n\u003c/details\u003e\n\n### Examples\n\n```bash\n# Roformer with custom overlap\npython mdx_headless_runner.py \\\n    -m \"MDX23C-8KFFT-InstVoc_HQ.ckpt\" \\\n    -i \"song.flac\" -o \"output/\" \\\n    --gpu --overlap-mdxc 8\n\n# 32-bit float output\npython mdx_headless_runner.py \\\n    -m \"model.ckpt\" -i \"song.flac\" -o \"output/\" \\\n    --gpu --wav-type FLOAT\n```\n\n---\n\n## 🥁 Demucs Runner\n\n### Supported Models\n\n| Model | Version | Stems | Quality |\n|-------|---------|-------|---------|\n| `htdemucs` | v4 | 4 | ⭐⭐⭐ |\n| `htdemucs_ft` | v4 | 4 | ⭐⭐⭐⭐ Fine-tuned |\n| `htdemucs_6s` | v4 | 6 | ⭐⭐⭐⭐ +Guitar/Piano |\n| `hdemucs_mmi` | v4 | 4 | ⭐⭐⭐ |\n| `mdx_extra_q` | v3 | 4 | ⭐⭐⭐ |\n\n### Command Line Arguments\n\n| Argument | Short | Default | Description |\n|----------|-------|---------|-------------|\n| `--model` | `-m` | **Required** | Model name or path |\n| `--input` | `-i` | **Required** | Input audio file |\n| `--output` | `-o` | **Required** | Output directory |\n| `--gpu` | | Auto | Use NVIDIA CUDA |\n| `--segment` | | Default | Segment size (1-100+) |\n| `--shifts` | | `2` | Time shifts |\n| `--stem` | | | Vocals/Drums/Bass/Other/Guitar/Piano |\n| `--wav-type` | | `PCM_24` | Output bit depth |\n| `--primary-only` | | | Output primary stem only |\n\n### Stem Selection\n\n| GUI Action | CLI Command |\n|------------|-------------|\n| All Stems | *(no --stem)* |\n| Vocals only | `--stem Vocals --primary-only` |\n| Instrumental only | `--stem Vocals --secondary-only` |\n\n### Examples\n\n```bash\n# 6-stem separation\npython demucs_headless_runner.py \\\n    --model htdemucs_6s \\\n    --input \"song.flac\" --output \"output/\" \\\n    --gpu\n\n# High quality with custom segment\npython demucs_headless_runner.py \\\n    --model htdemucs_ft \\\n    --input \"song.flac\" --output \"output/\" \\\n    --gpu --segment 85\n```\n\n---\n\n## 🎤 VR Architecture Runner\n\n### Command Line Arguments\n\n| Argument | Short | Default | Description |\n|----------|-------|---------|-------------|\n| `--model` | `-m` | **Required** | Model file path (.pth) |\n| `--input` | `-i` | **Required** | Input audio file |\n| `--output` | `-o` | **Required** | Output directory |\n| `--gpu` | | Auto | Use NVIDIA CUDA |\n| `--directml` | | | Use AMD DirectML |\n| `--window-size` | | `512` | Window size (320/512/1024) |\n| `--aggression` | | `5` | Aggression setting (0-50+) |\n| `--wav-type` | | `PCM_16` | Output: PCM_16/24/32, FLOAT, DOUBLE |\n| `--primary-only` | | | Output primary stem only |\n| `--secondary-only` | | | Output secondary stem only |\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e📋 All Arguments\u003c/b\u003e\u003c/summary\u003e\n\n| Argument | Description |\n|----------|-------------|\n| `--name` `-n` | Output filename base |\n| `--param` | Model param name (e.g., 4band_v3) |\n| `--primary-stem` | Primary stem name (Vocals/Instrumental) |\n| `--nout` | VR 5.1 nout parameter |\n| `--nout-lstm` | VR 5.1 nout_lstm parameter |\n| `--cpu` | Force CPU |\n| `--device` `-d` | GPU device ID |\n| `--batch-size` | Batch size (default: 1) |\n| `--tta` | Enable Test-Time Augmentation |\n| `--post-process` | Enable post-processing |\n| `--post-process-threshold` | Post-process threshold (default: 0.2) |\n| `--high-end-process` | Enable high-end mirroring |\n| `--list-params` | List available model params |\n\n\u003c/details\u003e\n\n### Model Parameters\n\nWhen the model hash is not found in the database, you need to provide parameters manually:\n\n```bash\n# List available params\npython vr_headless_runner.py --list-params\n\n# Use custom params\npython vr_headless_runner.py -m \"model.pth\" -i \"song.flac\" -o \"output/\" \\\n    --param 4band_v3 --primary-stem Vocals\n\n# VR 5.1 model with nout/nout_lstm\npython vr_headless_runner.py -m \"model.pth\" -i \"song.flac\" -o \"output/\" \\\n    --param 4band_v3 --primary-stem Vocals --nout 48 --nout-lstm 128\n```\n\n### Examples\n\n```bash\n# High quality with TTA\npython vr_headless_runner.py \\\n    -m \"UVR-MDX-NET-Voc_FT.pth\" \\\n    -i \"song.flac\" -o \"output/\" \\\n    --gpu --tta --window-size 1024\n\n# Aggressive separation\npython vr_headless_runner.py \\\n    -m \"model.pth\" -i \"song.flac\" -o \"output/\" \\\n    --gpu --aggression 15 --post-process\n\n# 24-bit output\npython vr_headless_runner.py \\\n    -m \"model.pth\" -i \"song.flac\" -o \"output/\" \\\n    --gpu --wav-type PCM_24\n```\n\n---\n\n## 📁 Output Structure\n\n```\noutput/\n├── song_(Vocals).wav        # Vocals\n├── song_(Instrumental).wav  # Instrumental (MDX)\n├── song_(Drums).wav         # Drums (Demucs)\n├── song_(Bass).wav          # Bass (Demucs)\n├── song_(Other).wav         # Other (Demucs)\n├── song_(Guitar).wav        # Guitar (6-stem)\n└── song_(Piano).wav         # Piano (6-stem)\n```\n\n---\n\n## 🐍 Python API\n\n```python\nfrom mdx_headless_runner import run_mdx_headless\nfrom demucs_headless_runner import run_demucs_headless\nfrom vr_headless_runner import run_vr_headless\n\n# MDX separation\nrun_mdx_headless(\n    model_path='model.ckpt',\n    audio_file='song.wav',\n    export_path='output',\n    use_gpu=True,\n    verbose=True  # Print progress\n)\n# Output: output/song_(Vocals).wav, output/song_(Instrumental).wav\n\n# Demucs separation (vocals only)\nrun_demucs_headless(\n    model_path='htdemucs',\n    audio_file='song.wav',\n    export_path='output',\n    use_gpu=True,\n    demucs_stems='Vocals',  # or 'All Stems' for all\n    primary_only=True,\n    verbose=True\n)\n# Output: output/song_(Vocals).wav\n\n# VR Architecture separation\nrun_vr_headless(\n    model_path='model.pth',\n    audio_file='song.wav',\n    export_path='output',\n    use_gpu=True,\n    window_size=512,\n    aggression_setting=5,\n    is_tta=False,\n    # For unknown models, provide params manually:\n    # user_vr_model_param='4band_v3',\n    # user_primary_stem='Vocals'\n)\n# Output: output/song_(Vocals).wav, output/song_(Instrumental).wav\n```\n\n\u003e 💡 **Note**: Functions process audio and save to `export_path`. Check output directory for results.\n\n---\n\n## 🔍 Troubleshooting\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ GPU not detected\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Check CUDA\npython -c \"import torch; print(torch.cuda.is_available())\"\n\n# Reinstall PyTorch with CUDA\npip uninstall torch torchvision torchaudio\npip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Model not found\u003c/b\u003e\u003c/summary\u003e\n\n**Option 1: Use automatic download (recommended)**\n```bash\n# List available models\npython mdx_headless_runner.py --list\n\n# Download the model\npython mdx_headless_runner.py --download \"UVR-MDX-NET Inst HQ 3\"\n\n# Or just use it - auto-downloads!\npython mdx_headless_runner.py -m \"UVR-MDX-NET Inst HQ 3\" -i song.wav -o output/\n```\n\n**Option 2: Manual download**\n\nDefault locations:\n- **MDX**: `./models/MDX_Net_Models/`\n- **Demucs**: `./models/Demucs_Models/v3_v4_repo/`\n- **VR**: `./models/VR_Models/`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Network/Download errors\u003c/b\u003e\u003c/summary\u003e\n\n```bash\n# Force refresh model registry\npython model_downloader.py --sync\n\n# Check network connectivity\npython -c \"import urllib.request; urllib.request.urlopen('https://github.com')\"\n```\n\nThe downloader includes:\n- Automatic retry (3 attempts with exponential backoff)\n- Resume interrupted downloads\n- Fallback to cached registry\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ VR model hash not found\u003c/b\u003e\u003c/summary\u003e\n\nIf your VR model isn't in the database, provide parameters manually:\n\n```bash\n# List available params\npython vr_headless_runner.py --list-params\n\n# Specify param and primary stem\npython vr_headless_runner.py -m \"model.pth\" -i \"song.wav\" -o \"output/\" \\\n    --param 4band_v3 --primary-stem Vocals\n```\n\nCommon params: `4band_v3`, `4band_v2`, `1band_sr44100_hl512`, `3band_44100`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003e❌ Poor output quality\u003c/b\u003e\u003c/summary\u003e\n\n- Try increasing `--overlap` or `--overlap-mdxc`\n- For Demucs, increase `--segment` (e.g., 85)\n- Ensure correct model config with `--json`\n\n\u003c/details\u003e\n\n---\n\n## 🙏 Acknowledgments\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://github.com/Anjok07/ultimatevocalremovergui\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/UVR-Ultimate%20Vocal%20Remover-purple?style=for-the-badge\" alt=\"UVR\"/\u003e\n\u003c/a\u003e\n\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003eAnjok07\u003c/b\u003e \u0026 \u003cb\u003eaufr33\u003c/b\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://github.com/facebookresearch/demucs\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Meta-Demucs-blue?style=for-the-badge\" alt=\"Demucs\"/\u003e\n\u003c/a\u003e\n\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003eFacebook Research\u003c/b\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://github.com/kuielab\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Kuielab-MDX--Net-green?style=for-the-badge\" alt=\"MDX-Net\"/\u003e\n\u003c/a\u003e\n\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003eWoosung Choi\u003c/b\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd align=\"center\"\u003e\n\u003ca href=\"https://github.com/tsurumeso/vocal-remover\"\u003e\n\u003cimg src=\"https://img.shields.io/badge/Tsurumeso-VR%20Architecture-orange?style=for-the-badge\" alt=\"VR Architecture\"/\u003e\n\u003c/a\u003e\n\u003cbr/\u003e\n\u003csub\u003e\u003cb\u003etsurumeso\u003c/b\u003e\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nSpecial thanks to **[ZFTurbo](https://github.com/ZFTurbo)** for MDX23C \u0026 SCNet.\n\n---\n\n## 📄 License\n\n```\nMIT License\n\nCopyright (c) 2022 Anjok07 (Ultimate Vocal Remover)\nCopyright (c) 2026 UVR Headless Runner Contributors\n```\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003eView Full License\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n## Contributing \u0026 Support\n\n**Pull Requests** and **Issues** are welcome! Whether it's bug reports, feature suggestions, or code contributions, we greatly appreciate them all.\n\nIf you find this project helpful, please give us a **Star** ⭐ - it's the best support for us!\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003csub\u003eMade with ❤️ for the audio separation community\u003c/sub\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchyinan%2Fuvr-headless-runner","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchyinan%2Fuvr-headless-runner","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchyinan%2Fuvr-headless-runner/lists"}