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
-
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" -
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
Afor NVIDIA CUDA,Bfor TensorRT-RTX, orCfor CPU-only. See docs/development/setup.md for manual setup.) -
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 -
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" -
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
RFCorFeature Requestfirst. - 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/testsif scripts ininstall/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 benchare 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.jsonand 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 inuvr_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 insideuvr_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
questionlabel. - Please review and abide by our Code of Conduct in all project interactions.