RevLayDust 9949774608 chore(license): relicense uvr_cli to GNU AGPL v3 with SPDX headers and test coverage
- Add official GNU Affero General Public License v3.0 to uvr_cli/LICENSE

- Add SPDX-License-Identifier: AGPL-3.0-or-later and Copyright (C) 2026 RevLayDust headers to all uvr_cli modules

- Document multi-license architecture in root README.md and uvr_cli/README.md

- Add automated regression tests in tests/test_uvr_cli.py verifying license file and module SPDX headers
2026-10-12 06:23:27 +07:00
2026-08-21 16:51:19 +07:00
2026-08-21 16:51:19 +07:00
2026-08-21 16:51:19 +07:00

RLD UVR-Opt: Ultimate Vocal Remover GUI (Optimized)

Release License: MIT Python: 3.11+ Platform: Windows Acceleration: CUDA, TensorRT-RTX & CPU

High-performance, memory-optimized distribution of Ultimate Vocal Remover GUI (UVR v5.6).
Focused on accelerated ONNX Runtime inference, lower hardware VRAM usage, and faster CLI startup.


RLD UVR-Opt Performance Demo

Up to ~5.3x Faster Inference  |  ~77% Lower VRAM Usage

~3.5x faster & ~52% lower VRAM on stable CUDA EP. Up to ~5.3x faster & ~77% lower VRAM with experimental TensorRT-RTX EP (see Verified Benchmarks).

Prerequisites & Installation \cdot Usage & Quick Start \cdot Key Features \cdot Verified Benchmarks \cdot Roadmap \cdot Credits


Installation & Prerequisites

1. System Requirements & Platform Support

Important

Platform Support: RLD UVR-Opt is actively tested and optimized exclusively for Windows 10 / 11 (64-bit).

  • Compute Device:
    • NVIDIA GPU (CUDA EP - Stable): NVIDIA GeForce RTX 20 Series (Turing) or higher with at least 6GB VRAM (8GB+ VRAM recommended for optimal performance).
    • NVIDIA GPU (TensorRT-RTX EP - Experimental): NVIDIA GeForce RTX 30 Series (Ampere) or higher (RTX 30, 40, 50 series, RTX Ada/Blackwell). (Note: Turing / RTX 20-series GPUs are not supported by the TensorRT-RTX execution provider; RTX 20 users should use the stable CUDA EP).
    • CPU: Multi-core modern 64-bit x86 processor (fully supported via multi-threaded CPU inference).
    • (Note: Hardware focus is strictly on GPU and CPU).
  • Python: Optional (the automated installer automatically bootstraps a standalone Python 3.11 environment via uv). Installing system Python 3.11+ (64-bit) is only required if you plan on manual setup, development, or debugging.

2. Model & Architecture Scope

Note

ONNX Model Priority:
RLD UVR-Opt's core acceleration pipeline is built around ONNX Runtime for .onnx models.
Officially supported and tested: .onnx models from the MDX-Net family on the documented CUDA and CPU paths. Legacy/Experimental: non-.onnx models may still load through existing UVR components, but they are currently untested and may not function as expected.


3. One-Click Automated Installation (Windows)

RLD UVR-Opt provides an automated setup script that handles your entire environment setup from start to finish:

Step 1: Clone or Download the Repository

git clone https://github.com/revlaydust/rld-uvr-opt.git
cd rld-uvr-opt

(Or Download the ZIP and extract it to a folder).

Step 2: Run the Automated Installer

Simply double-click install\install_packages.bat in File Explorer, or run in terminal:

.\install\install_packages.bat

Step 3: Run the GUI

Important

If you installed the GPU version, you must follow these steps:

  1. Open UVR using run_uvr.bat or python UVR.py.

  2. Go to Main Settings (to the left of the Start Processing button with the wrench icon) → Additional Settings → Change GPU Device from the default setting to your GPU using the dropdown menu.

  3. Still in Additional Settings, choose an Execution Provider (directly below GPU Device):

    • The Execution Provider dropdown stays locked (greyed out) until a GPU Device has been selected in step 2.
    • Once unlocked, UVR lists only the providers that are actually available for your GPU:
      • CUDAExecutionProvider — default and stable baseline for all supported NVIDIA GPUs (RTX 20 series / Turing and newer).
      • NvTensorRTRTXExecutionProvider — experimental and faster. Requires NVIDIA RTX 30 series (Ampere) or newer. It is only listed if you chose the TensorRT-RTX EP option in the installer and your GPU meets the hardware requirement (Turing / RTX 20 series users should select CUDAExecutionProvider).
    • If your installation only supports CPUExecutionProvider, both GPU Device and Execution Provider are hidden and disabled.

    Important

    You MUST restart UVR every time you change the Execution Provider. The provider is applied when UVR starts, so a change made while UVR is running does not take effect until you restart. Use the Restart Application button in the settings menu, or close and re-open UVR.

  4. Go back to the main menu, then enable GPU Conversions.

  5. Re-open UVR.

  6. Done! You can now start using it!

If you installed the CPU version, simply launch UVR using run_uvr.bat, python UVR.py, or by double-clicking run_uvr.bat in File Explorer.

If you encounter any specific issues, feel free to open an issue!

What the One-Click Installer automates for you:

  • Hardware & Driver Detection: Automatically identifies your GPU architecture (NVIDIA RTX 20/30/40/50 series) and selects PyTorch CUDA 12.8 or optimized CPU fallback.
  • Python Environment Management: Automatically bootstraps uv and provisions an isolated Python 3.11 virtual environment (venv).
  • Fast Dependency Installation: Pulls and configures all required packages, including PyTorch and ONNX Runtime GPU/CPU.
  • Visual C++ Redistributable Auto-Install: Checks whether Microsoft Visual C++ 2015–2022 Redistributable (x64) is installed. If missing or outdated, it automatically downloads and silently installs the official runtime to ensure native C-extensions and runtime DLLs load without errors.
  • Automated Media Binaries: Detects existing system installations of FFmpeg and rubberband-cli. If either is missing, it automatically downloads and extracts portable binaries into the application folder—zero manual downloading required!
  • Smoke Test Verification: Runs an immediate runtime sanity check on tensor operations and ONNX execution providers before launching.
🛠️ Manual Installation via Astral uv (Click to Expand for Advanced Users)

If you prefer to configure your environment manually instead of running install\install_packages.bat, use Astral uv for lightning-fast setup:

  1. Install Astral uv (if not already installed):

    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
    
  2. Create Python 3.11 Virtual Environment via uv:

    uv venv venv --python 3.11
    .\venv\Scripts\activate
    
  3. Install PyTorch & ONNX Runtime with uv pip:

    • For NVIDIA GPU (CUDA 12.8):
      uv pip install torch==2.11.0 torchvision==0.26.0 torchaudio==2.11.0 --index-url https://download.pytorch.org/whl/cu128
      
    • For CPU Only Fallback:
      uv pip install torch==2.11.0 torchvision==0.26.0 torchaudio==2.11.0 --index-url https://download.pytorch.org/whl/cpu
      
  4. Install Base Dependencies with uv pip:

    • For NVIDIA GPU (CUDA):
      uv pip install -r .\install\reqs\requirements.txt
      
    • For NVIDIA GPU (TensorRT-RTX)
      uv pip install -r .\install\reqs\requirements_trt_rtx.txt
      
    • For CPU Only:
      uv pip install -r .\install\reqs\requirements_cpu.txt
      
  5. Place External Media Binaries:

    • Place ffmpeg.exe in the application root folder (or ensure it is in your system PATH).
    • Place rubberband.exe and sndfile.dll in the application root folder (or ensure it is in your system PATH).

Usage / Quick Start

Get from zero to audio separation in seconds:

A. Launch the GUI

Simply run the included launcher batch file or start via Python:

.\run_uvr.bat

Or via terminal:

python UVR.py

B. UVR Command-Line Interface (UVR-CLI)

RLD UVR-Opt provides a dedicated, lightweight CLI designed for automation and headless environments. Run it with the project's virtual environment:

# 1. View all available commands instantly
venv\Scripts\python.exe -m uvr_cli --help

# 2. List installed models
venv\Scripts\python.exe -m uvr_cli list-models

# 3. Run high-performance separation with MDX-Net Inst_HQ_4 (default device: cuda:0)
venv\Scripts\python.exe -m uvr_cli run --audio "path/to/song.wav" --model "UVR-MDX-NET-Inst_HQ_4.onnx" --output-dir "output_stems"

# 4. High-throughput separation with custom overlap and segment size
venv\Scripts\python.exe -m uvr_cli run -a "song.wav" -m "UVR-MDX-NET-Inst_HQ_4.onnx" --overlap 0.50 --segment-size 4000 -o "output_stems"

# 5. Choose the execution device: CUDA, TensorRT-RTX, or CPU
venv\Scripts\python.exe -m uvr_cli run -a "song.wav" -m "UVR-MDX-NET-Inst_HQ_4.onnx" --device cuda:0
venv\Scripts\python.exe -m uvr_cli run -a "song.wav" -m "UVR-MDX-NET-Inst_HQ_4.onnx" --device trt_rtx:0
venv\Scripts\python.exe -m uvr_cli run -a "song.wav" -m "UVR-MDX-NET-Inst_HQ_4.onnx" --device cpu

# 6. Benchmark and smoke test
venv\Scripts\python.exe -m uvr_cli bench -a "song.wav" -m "UVR-MDX-NET-Inst_HQ_4.onnx" --device trt_rtx:0 --rounds 3 --warmup 1
venv\Scripts\python.exe -m uvr_cli smoke-test --device cuda:0
Command Description
list-models List all installed MDX-Net, VR, and Demucs models.
run Separate an audio file without the GUI.
bench Run a multi-round benchmark with hardware telemetry and JSON/CSV export.
smoke-test Run an end-to-end check using generated synthetic audio.

Device selection (--device / -d) is available on run, bench, and smoke-test:

Value Execution Provider Notes
cuda[:N] CUDAExecutionProvider Default (cuda:0). Stable choice for all NVIDIA GPUs (RTX 20+ / Turing or newer).
trt_rtx[:N] NvTensorRTRTXExecutionProvider Experimental. Requires the TensorRT-RTX EP install option and an RTX 30-series (Ampere) or newer GPU. Automatically falls back to CUDA EP if unavailable or on Turing (RTX 20) GPUs.
cpu CPUExecutionProvider Runs without a GPU.

An invalid value is rejected with an error that lists the valid choices. If CUDA is unavailable, the CLI falls back to CPU and prints a warning. See uvr_cli/README.md for the full option reference.


Key Features

  • Accelerated ONNX Inference: Optimized tensor pipelines and buffer handling reduce unnecessary overhead during chunk processing.
  • In-Memory FP16 Conversion: FP16 conversion is performed in memory without requiring persistent .fp16.onnx files.
  • Memory & Session Management: Improved session and allocation handling helps reduce unnecessary resource usage across runs.
  • Faster CLI Startup: Deferred loading of heavy runtime modules reduces startup work before inference is requested.
  • Benchmark Telemetry: Built-in measurements and metadata help compare inference performance across controlled test runs.

Verified Benchmarks

All metrics were gathered using the built-in isolated benchmark suite on identical test audio (48.34s stereo WAV, model: UVR-MDX-NET-Inst_HQ_4.onnx, Ultra Quality FP32). The results below reflect the documented test configuration and are not a universal performance guarantee.

Test Hardware: NVIDIA GeForce RTX 5060 Ti  |  AMD Ryzen 5 5600 6-Core Processor  |  32 GB RAM  |  Windows 11

1. GPU Inference Performance (CUDA)

Configuration Metric UVR v5.6 (Legacy) RLD UVR-Opt Improvement
Overlap 0.75
(Segment: 4000)
Inference Time
Processing Speed
Peak Device VRAM
PyTorch VRAM Alloc
13.52 s
3.58x Realtime
8,210 MB
6,360 MB
3.85 s
12.54x Realtime
3,941 MB
177.5 MB
~3.5x Faster
+250% Throughput
-52.0% VRAM Usage (4.2 GB Saved)
-97.2% PyTorch VRAM Allocation
Overlap 0.50
(Segment: 4000)
Inference Time
Processing Speed
Peak Device VRAM
7.99 s
6.05x Realtime
8,214 MB
2.06 s
23.44x Realtime
3,893 MB
~3.87x Faster
+287% Throughput
-52.6% VRAM Usage (4.3 GB Saved)

2. CPU Inference Performance

Configuration Metric UVR v5.6 (Legacy) RLD UVR-Opt Improvement
Overlap 0.50
(Segment: 4000)
Inference Time
Processing Speed
Peak System RAM
79.84 s
0.61x Realtime
8,928 MB
32.17 s
1.50x Realtime
3,210 MB
~2.48x Faster
+146% Throughput
-64.0% RAM Usage (5.7 GB Saved)

3. GPU Inference Performance (TensorRT-RTX EP, Experimental)

Same audio, model, and settings as above (Overlap 0.75, Segment 4000, Ultra Quality FP32), comparing UVR v5.6 (Legacy) against RLD UVR-Opt running on the TensorRT-RTX Execution Provider.

Configuration Metric UVR v5.6 (Legacy) RLD UVR-Opt (TensorRT-RTX) Improvement
Overlap 0.75
(Segment: 4000)
Inference Time
Processing Speed
Peak Device VRAM
PyTorch VRAM Alloc
13.52 s
3.58x Realtime
8,210 MB
6,360 MB
2.55 s
18.94x Realtime
1,897 MB
177.5 MB
~5.3x Faster
+429% Throughput
-76.9% VRAM Usage (6.2 GB Saved)
-97.2% PyTorch VRAM Allocation

To isolate the effect of the Execution Provider, the table below compares CUDA EP and TensorRT-RTX EP on the same software stack (ONNX Runtime 1.24.4, same machine, same commit):

Configuration Metric RLD UVR-Opt (CUDA EP) RLD UVR-Opt (TensorRT-RTX EP) Improvement
Overlap 0.75
(Segment: 4000)
Inference Time
Processing Speed
Peak Device VRAM
3.60 s
13.44x Realtime
3,755 MB
2.55 s
18.94x Realtime
1,897 MB
~1.41x Faster
+41% Throughput
-49.5% VRAM Usage

Note

How to read these numbers:

  • The TensorRT-RTX results use ONNX Runtime 1.24.4, while the CUDA results in table 1 used ONNX Runtime 1.22.0. Use the same-stack comparison above for a like-for-like view of the Execution Provider itself.
  • Each result is the mean of 9 measured rounds after 1 warmup round. The first (warmup) TensorRT-RTX run was slower at 5.40 s (8.95x Realtime), so expect a slower first run before the faster steady-state speed.
  • Only Overlap 0.75 has been measured for TensorRT-RTX so far.
  • TensorRT-RTX is experimental. Results are from a single test machine and are not a universal performance guarantee.

Note

Raw per-round session logs and metric datasets are preserved in benchmark_results/ (summary.csv and summary_legacy.csv). The TensorRT-RTX run is session session_20261010_123555_d732c2, and the same-stack CUDA run is session session_20261010_123503_8cf4dd.


Roadmap

  • Accelerated ONNX inference pipeline and buffer optimizations.
  • In-memory FP16 downcasting (e.g., FP32 \rightarrow FP16) and cache lifecycle management.
  • TensorRT-RTX Execution Provider (via ONNX Runtime): Evaluate optional acceleration for NVIDIA RTX GPUs (Ampere+), with CUDA EP retained as the stable fallback.
  • In-memory BF16/FP8 E4M3FN downcasting.
  • Windows ML Execution Provider (via ONNX Runtime): Evaluate acceleration path for non-NVIDIA hardware (AMD, Intel) on Windows 11 (24H2+).
  • Support for Newer Model Architectures.
  • UI/UX Overhaul.

Credits & Acknowledgments

RLD UVR-Opt Maintainer

  • RevLayDust — Core architecture optimizations, ONNX pipeline acceleration, CLI engine, and memory lifecycle management.

Core UVR Developers

  • Anjok07 — UVR Creator & Core Developer.
  • aufr33 — UVR Core Developer & AI Model Architect.

Special Thanks & Upstream Contributors

  • ZFTurbo — Created & trained weights for MDX23C models.
  • DilanBoskan — Essential contributions at the start of the UVR project.
  • Bas Curtiz — Designed the official UVR logo, icon, banner, and splash screen.
  • tsurumeso — Developed the original VR Architecture code.
  • Kuielab & Woosung Choi — Developed the original MDX-Net AI code.
  • Adefossez & Demucs — Core developer of Facebook's Demucs Music Source Separation.
  • KimberleyJSN — Advised and aided implementation of training scripts for MDX-Net and Demucs.
  • Hv — Helped implement chunk processing into MDX-Net AI code.
  • Audio Separation & CC Karaoke Discord Communities — For continuous testing, feedback, and support.

License & References

The Ultimate Vocal Remover GUI and RLD UVR-Opt core distribution is open-source and released under the MIT License.

Copyright (c) 2022 Ultimate Vocal Remover
Copyright (c) 2026 RevLayDust

The CLI and benchmarking suite (uvr_cli) is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

Copyright (C) 2026 RevLayDust

Academic References

  • [1] Takahashi et al., "Multi-scale Multi-band DenseNets for Audio Source Separation", arXiv:1706.09588
Languages
Python 66.4%
Tcl 26.6%
PowerShell 6.9%