mirror of
https://github.com/RevLayDust/RLD-UVR-Opt.git
synced 2026-11-20 13:07:58 +09:00
99 lines
5.9 KiB
Markdown
99 lines
5.9 KiB
Markdown
# 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](https://github.com/Anjok07/ultimatevocalremovergui) (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:
|
|
```powershell
|
|
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
|
|
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](docs/development/setup.md) for manual setup.)*
|
|
|
|
3. **Create a Feature Branch**: Branch from the default branch with a descriptive prefix:
|
|
```powershell
|
|
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:
|
|
```powershell
|
|
# 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](.github/PULL_REQUEST_TEMPLATE.md).
|
|
|
|
---
|
|
|
|
## Before You Begin
|
|
|
|
- **Check Existing Issues**: Search [GitHub Issues](https://github.com/RevLayDust/RLD-UVR-Opt/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](.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**](docs/development/setup.md) | System prerequisites, installation modes (A, B, C), verification steps, and common troubleshooting. |
|
|
| [**Architecture Overview**](docs/development/architecture.md) | Module tree, Execution Provider fallback ladder, inference engine decoupling, and data flow. |
|
|
| [**Coding Standards**](docs/development/coding-standards.md) | Python & PowerShell rules, lazy imports, context locking avoidance, and commit conventions. |
|
|
| [**Testing Guide**](docs/development/testing.md) | Running unit tests, smoke tests, Pester suites, and testing without physical GPUs. |
|
|
| [**Benchmarking Methodology**](docs/development/benchmarking.md) | Mandatory performance profiling, telemetry capture, audio integrity verification, and report formats. |
|
|
| [**Installer Development**](docs/development/installer.md) | 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](docs/development/coding-standards.md) (lazy imports, no Tkinter dependencies in computation modules).
|
|
- [ ] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (e.g., `feat:`, `fix:`, `docs:`, `refactor:`).
|
|
|
|
---
|
|
|
|
## Reporting Bugs and Hardware Benchmarks
|
|
|
|
- **Bug Reports**: Open an issue using the [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.yml). 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](.github/ISSUE_TEMPLATE/performance_report.yml).
|
|
|
|
---
|
|
|
|
## License & Attribution
|
|
|
|
- **Core Application & GUI**: Licensed under the [MIT License](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](uvr_cli/__init__.py) (`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](https://github.com/RevLayDust/RLD-UVR-Opt/discussions) or create an issue with the `question` label.
|
|
- Please review and abide by our [Code of Conduct](CODE_OF_CONDUCT.md) in all project interactions.
|
|
|