Files
RLD-UVR-Opt/CONTRIBUTING.md
T

5.9 KiB

Contributing to RLD UVR-Opt

Thank you for your interest in contributing to RLD UVR-Opt! We welcome bug fixes, performance optimizations, hardware verification, and documentation improvements.

This project is a performance-optimized fork of Ultimate Vocal Remover GUI (v5.6) focusing on low-latency ONNX Runtime inference, hardware-accelerated Execution Providers (CUDA and TensorRT-RTX), and modular environment architecture for Windows x64.


TL;DR 5-Step Contribution Flow

  1. Fork & Clone: Fork the repository on GitHub and clone your fork locally:

    git clone https://github.com/<your-username>/RLD-UVR-Opt.git
    cd "RLD-UVR-Opt"
    
  2. Set Up the Environment: Run the modular PowerShell installer to configure a virtual environment:

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

    (Select A for NVIDIA CUDA, B for TensorRT-RTX, or C for CPU-only. See docs/development/setup.md for manual setup.)

  3. Create a Feature Branch: Branch from the default branch with a descriptive prefix:

    git checkout -b feat/my-optimization
    # Or fix/my-bugfix, docs/my-documentation
    
  4. Verify Locally: Run test suites and verify line endings before committing:

    # Run all Python regression tests
    .\venv\Scripts\python.exe -m unittest discover tests -v
    
    # Run PowerShell installer tests (if touching install scripts)
    powershell -NoProfile -ExecutionPolicy Bypass -Command "Invoke-Pester -Path ./install/tests"
    
  5. Submit a Pull Request: Push your branch to GitHub and open a Pull Request using our PR Template.


Before You Begin

  • Check Existing Issues: Search GitHub Issues to avoid duplicate work.
  • Discuss Major Changes First: If you plan to introduce an architectural change, rewrite chunking math, add dependencies, or alter CLI arguments, open an issue labeled RFC or Feature Request first.
  • Do Not Commit Large Files: Never commit raw model checkpoints (*.onnx, *.pth, *.ckpt), audio tracks, or temporary stems. The .gitignore file excludes model weights and output directories.

Detailed Development Guides

To keep this entry point concise, detailed documentation is organized in docs/development/:

Guide Description
Environment Setup System prerequisites, installation modes (A, B, C), verification steps, and common troubleshooting.
Architecture Overview Module tree, Execution Provider fallback ladder, inference engine decoupling, and data flow.
Coding Standards Python & PowerShell rules, lazy imports, context locking avoidance, and commit conventions.
Testing Guide Running unit tests, smoke tests, Pester suites, and testing without physical GPUs.
Benchmarking Methodology Mandatory performance profiling, telemetry capture, audio integrity verification, and report formats.
Installer Development The 5-phase installer engine (Detect -> Plan -> Verify -> Install -> Validate), -DryRun, and Pester fixtures.

Pull Request Checklist

When opening a Pull Request, ensure:

  • All tests pass via .\venv\Scripts\python.exe -m unittest discover tests.
  • Installer tests pass via Invoke-Pester -Path ./install/tests if scripts in install/ were modified.
  • No extraneous model weights, temporary stems, or private WAV files are committed.
  • Batch files maintain Windows CRLF line endings (tested via tests.test_windows_batch_files).
  • If changing inference logic or EP selection, verified benchmark results using uvr_cli bench are attached.
  • Code follows Coding Standards (lazy imports, no Tkinter dependencies in computation modules).
  • Commit messages follow Conventional Commits (e.g., feat:, fix:, docs:, refactor:).

Reporting Bugs and Hardware Benchmarks

  • Bug Reports: Open an issue using the Bug Report Template. Attach your install/install_record.json and error logs.
  • Hardware Benchmarks: We actively collect performance telemetry across diverse GPU and CPU architectures. Please submit results using the Performance Report Template.

License & Attribution

  • Core Application & GUI: Licensed under the MIT License. Upstream Ultimate Vocal Remover GUI is developed by Anjok07 and the UVR community (Copyright © 2022 Ultimate Vocal Remover). Modifications, TensorRT-RTX backend, and installer pipelines are contributed by RevLayDust and project contributors (Copyright © 2026 RevLayDust).
  • Headless CLI & Benchmark Engine (uvr_cli/): The CLI-only execution interface and benchmarking engine in uvr_cli/ is licensed under the GNU Affero General Public License v3.0 or later (SPDX-License-Identifier: AGPL-3.0-or-later, Copyright © 2026 RevLayDust). Any new contributions inside uvr_cli/ must comply with AGPL v3.
  • Third-Party Components: Model architectures (MDX-Net, Demucs, VR Arch), weights, and execution provider binaries retain their respective upstream licenses.

Community & Questions

  • Have a question or proposal? Open a discussion on GitHub Discussions or create an issue with the question label.
  • Please review and abide by our Code of Conduct in all project interactions.