Files

7.3 KiB

Environment Setup & Installation Guide

This guide describes how to configure a reproducible development environment for RLD UVR-Opt.


1. Prerequisites

Requirement Specification Notes
Operating System Windows 10 / 11 64-bit (x64 / AMD64) Primary target platform for installer, CUDA, and TensorRT-RTX. (Linux/macOS contributors can test CPU-only headless CLI).
Python Python 3.11.x (64-bit) Python 3.11.9 recommended. 32-bit and ARM64 architectures are unsupported.
Shell Windows PowerShell 5.1 Built into Windows 10/11. PowerShell 7 is supported but not required.
Git Git 2.30+ Required for version control and submodule handling.
Privileges Standard User Administrator privileges are only required if Visual C++ Redistributable needs system-level installation.

2. Cloning the Repository

Clone your fork of the repository into a directory path without non-ASCII characters:

git clone https://github.com/<your-username>/RLD-UVR-Opt.git
cd "RLD-UVR-Opt"

3. Automated Setup via PowerShell Installer

The repository includes a modern 5-phase installer pipeline (install/Install-UVR.ps1). Run the script selecting the mode matching your hardware:

Option A: NVIDIA GPU (CUDA Execution Provider)

Recommended for all NVIDIA GPUs (RTX 20-series / Turing or newer, including GTX 16-series):

powershell -NoProfile -ExecutionPolicy Bypass -File .\install\Install-UVR.ps1 -Mode A

Option B: NVIDIA GPU (TensorRT-RTX Execution Provider, Experimental)

Designed for NVIDIA RTX 30-series (Ampere), RTX 40-series (Ada Lovelace), and newer (Compute Capability \ge 8.0):

powershell -NoProfile -ExecutionPolicy Bypass -File .\install\Install-UVR.ps1 -Mode B

Option C: CPU Only (Fallback)

For non-NVIDIA GPUs (AMD, Intel) or systems without a dedicated GPU:

powershell -NoProfile -ExecutionPolicy Bypass -File .\install\Install-UVR.ps1 -Mode C

Installer Pipeline Behavior

When running, the installer executes the following deterministic phases:

  1. Detect: Inspects hardware via CIM controllers and nvidia-smi, validates Python 64-bit, and inspects .dist-info packages.
  2. Plan: Formulates an action plan (Keep, Install, Replace, Remove) without modifying files.
  3. Verify: Read-only verification gate checking driver version (\ge 570), disk space (\ge 5\text{ GB}), network connectivity, and running process locks.
  4. Install: Creates or reuses .venv, records rollback snapshots, removes variant conflicts, and installs packages via Astral uv.
  5. Validate: Submits an in-memory test ONNX model to the active Execution Provider, validates tensor allocation, and writes install/install_record.json.

4. Manual Setup (Alternative with Astral uv)

If you prefer configuring your virtual environment manually without running the orchestrator:

# 1. Install or update Astral uv
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Create the virtual environment
uv venv --python 3.11 venv
.\venv\Scripts\activate.ps1

# 3. Install PyTorch stack using definitions from install/lib/Config.ps1
# Query configuration from the single source of truth:
$cfg = & powershell -NoProfile -Command ". .\install\lib\Config.ps1; Get-InstallerConfig"

# For GPU (Options A and B):
uv pip install $cfg.Torch.Packages --index-url $cfg.Torch.Cu128IndexUrl

# For CPU (Option C):
uv pip install $cfg.Torch.Packages --index-url $cfg.Torch.CpuIndexUrl

# 4. Pre-install local binary wheels (provided in install/wheels/)
uv pip install (Get-ChildItem .\install\wheels\*.whl).FullName --no-deps

# 5. Install requirements based on target mode
# Option A (CUDA):
uv pip install -r .\install\reqs\requirements.txt
# Option B (TensorRT-RTX):
uv pip install -r .\install\reqs\requirements_trt_rtx.txt
# Option C (CPU):
uv pip install -r .\install\reqs\requirements_cpu.txt

5. External Media Binaries

The application requires ffmpeg.exe, rubberband.exe, and sndfile.dll.

  • FFmpeg: Place ffmpeg.exe in the application root directory or ensure it is accessible in your system PATH.
  • Rubber Band & Libsndfile: Ensure rubberband.exe and sndfile.dll are located in the repository root (both are provided in the repo root).

Verify external binary availability:

.\ffmpeg.exe -version
.\rubberband.exe --version

6. Verifying the Setup

Run these verification steps before writing code:

  1. Run Unit Tests:

    .\venv\Scripts\python.exe -m unittest discover tests -v
    

    Expected result: All tests passing (OK).

  2. Run Headless Smoke Test:

    # Test inference with synthetic sine wave audio
    .\venv\Scripts\python.exe -m uvr_cli smoke-test --device cpu
    # Or --device cuda:0 / --device trt_rtx:0 if GPU hardware is present
    

    Expected result: [OK] Smoke test passed.

  3. Launch the Graphical Interface:

    .\run_uvr.bat
    

    Expected result: UVR GUI window opens.


7. Troubleshooting Real Failures

1. PowerShell Script Execution Disabled

  • Symptom: File Install-UVR.ps1 cannot be loaded because running scripts is disabled on this system.
  • Fix: Launch PowerShell and set execution policy for the process:
    Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
    

2. Missing Visual C++ Runtime (VCRedist)

  • Symptom: ImportError: DLL load failed while importing onnxruntime_pybind11_state or sndfile.dll.
  • Fix: Install the latest official Microsoft Visual C++ 2015-2022 Redistributable (x64) from aka.ms/vs/17/release/vc_redist.x64.exe.

3. File Lock During Installation / Package Update

  • Symptom: PermissionError: [WinError 5] Access is denied: ... python.exe or DLL in use.
  • Fix: Close any open instances of Ultimate Vocal Remover GUI or background python.exe processes holding files in venv/:
    Get-Process | Where-Object { $_.Path -like "*\venv\*" } | Stop-Process -Force
    

4. GPU Architecture Mismatch on Option B

  • Symptom: Installer reports Adjusted from Option B to Option A.
  • Explanation: TensorRT-RTX Execution Provider requires Compute Capability \ge 8.0 (Ampere / RTX 30-series or newer). Turing GPUs (RTX 20-series, GTX 16-series, CC 7.5) are automatically redirected to Option A (CUDA EP).