Skip to content

CLAUDE.md

Latest commit

 

History

History
400 lines (288 loc) · 15.5 KB

CLAUDE.md

File metadata and controls

400 lines (288 loc) · 15.5 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Ultimate RVC is an AI voice cloning and conversion tool that extends AiCoverGen with improved features. It provides a comprehensive suite for:

  • Voice conversion: Converting vocals using RVC (Retrieval-based Voice Conversion) models
  • Song cover generation: Creating AI covers from YouTube videos or uploaded audio
  • Text-to-speech: Generating speech from text using voice models
  • Voice model training: Training custom RVC models from audio datasets
  • Audio processing: Advanced vocal extraction, noise reduction, pitch correction

The project supports both web UI (Gradio) and CLI interfaces, with GPU acceleration via CUDA/ROCm.

Development Commands

Setup and Environment

  • ./urvc install - Install all dependencies and set up environment (Linux/WSL)
  • ./urvc.ps1 install - Install dependencies (Windows PowerShell)
  • ./urvc update - Update to latest version
  • ./urvc uninstall - Clean uninstall of dependencies and data

Running the Application

  • ./urvc run - Start web UI at http://127.0.0.1:7860
  • ./urvc cli [subcommand] - Access CLI interface
  • ./urvc-web - Start web UI (when installed as PyPI package)
  • urvc - CLI interface (when installed as PyPI package)

Development Tools

  • ./urvc dev - Start in development mode with hot reloading
  • ./urvc docs [module] [output_dir] - Generate documentation using Typer
  • ./urvc uv [command] - Run arbitrary uv commands
    • Code linting: uv run ruff check (configured in pyproject.toml)
    • Type checking: uv run pyright (Pyright configuration in pyproject.toml)
    • Code formatting: uv run ruff format (Black-compatible formatting)

Testing

The project uses pytest for comprehensive testing with unit, integration, and end-to-end test coverage.

Running Tests:

# Run all tests
./urvc uv run pytest

# Run specific test file
./urvc uv run pytest tests/unit/core/test_common.py

# Run with verbose output
./urvc uv run pytest -v

# Run specific test class or method
./urvc uv run pytest tests/unit/core/test_common.py::TestDisplayProgress
./urvc uv run pytest tests/unit/core/test_common.py::TestDisplayProgress::test_display_progress_with_message_only

# Run tests matching pattern
./urvc uv run pytest -k "test_display_progress"

# Run with coverage report
./urvc uv run pytest --cov

# Run and stop on first failure
./urvc uv run pytest -x

# Run specific test categories
./urvc uv run pytest -m "not slow"     # Exclude slow tests
./urvc uv run pytest -m "network"     # Only network tests
./urvc uv run pytest -m "gpu"         # Only GPU tests

Test Structure:

  • tests/unit/ - Unit tests (isolated function testing)
  • tests/integration/ - Integration tests (module interactions)
  • tests/e2e/ - End-to-end tests (full workflows)

Test Requirements:

  • All tests must pass pre-commit hooks (linting, type checking)
  • Minimum 90% test coverage required
  • Use realistic data for integration/E2E tests, synthetic for unit tests

Critical Testing Principles:

  • NEVER change application code without EXPLICIT permission from user
  • Always test ALL cases: positive, negative, and edge cases for each function
  • Look for bugs in functions being tested - most are correct, but some may have issues
  • Report any suspected bugs but do not fix without permission
  • Test comprehensively - every function parameter, return value, and exception path

Architecture Overview

Core Structure

src/ultimate_rvc/
├── cli/           # Command-line interface using Typer
├── core/          # Core business logic
│   ├── generate/  # Audio generation pipelines
│   ├── manage/    # Model and data management  
│   └── train/     # Model training workflows
├── rvc/           # RVC model implementation
│   ├── configs/   # Sample rate configurations (32k/40k/48k)
│   ├── infer/     # Inference pipeline and models
│   ├── lib/       # Core algorithms, predictors, utilities
│   └── train/     # Training data processing and model training
├── web/           # Gradio web interface
│   ├── config/    # UI configuration management
│   └── tabs/      # Modular UI tabs (generate, manage, train)
└── stubs/         # Type stubs for external libraries

Key Components

Audio Processing Pipeline (core/generate/):

  • Vocal extraction using audio-separator with UVR models
  • Pitch extraction with FCPE/RMVPE methods
  • Voice conversion using RVC models
  • Audio effects and post-processing

Model Management (core/manage/):

  • Voice model downloading from URLs/AI Hub Discord
  • Model upload and validation
  • Pretrained model management
  • Custom configuration persistence

Training System (rvc/train/):

  • Dataset preparation and audio slicing
  • Feature extraction with different embedders (ContentVec, HuBERT variants)
  • RVC model training with configurable parameters
  • Index creation for voice similarity matching

Web Interface (web/):

  • Modular tab-based UI using Gradio 5
  • Real-time configuration updates
  • Audio preview and download capabilities
  • Multi-step generation workflows for experimentation

Technology Stack

  • Package Management: uv with Python 3.13
  • ML Framework: PyTorch 2.7+ with CUDA 12.8/ROCm support
  • Web UI: Gradio 5.25+
  • CLI: Typer with rich markup
  • Audio Processing: librosa, soundfile, audio-separator, pedalboard
  • Code Quality: Ruff (linting + formatting), Pyright (type checking)

Environment Variables

Key environment variables for customization:

  • URVC_MODELS_DIR - Model storage location
  • URVC_AUDIO_DIR - Audio file storage
  • URVC_LOGS_DIR - Log file location
  • URVC_ACCELERATOR - Hardware accelerator (cuda or rocm)
  • URVC_CONFIG - Custom configuration name to load
  • YT_COOKIEFILE - YouTube cookies for downloads

Development Notes

  • Uses lazy loading for heavy dependencies to improve startup time
  • Extensive type hinting with py.typed marker
  • Modular architecture allows independent development of components
  • Caching system reduces inference time by reusing intermediate results
  • Supports both one-click and multi-step generation workflows
  • Configuration system allows saving/loading custom UI states

Development Workflow (For Claude)

  • When user says "remember" something: ALWAYS Add it to this CLAUDE.md file

    • User instructions prefixed with "remember" should be documented here
    • This creates a persistent record of important project-specific guidance

  • ALWAYS run commands from the project root directory

    • Never run commands from subdirectories unless explicitly stated
    • This prevents path confusion and ensures consistent behavior

  • after completing a task ALWAYS

    • stage relevant files with git add
    • run pre-commit hooks to ensure code quality
    • DO NOT commit unless asked to do so.

  • IMPORTANT: When commiting always include all changes for the given task

REMEMBER: Comprehensive testing reveals implementation issues

Bug Discovery and Documentation Workflow

  • ALWAYS document implementation issues immediately when discovered during testing

    • As soon as you discover something, document it in appropriate analysis files
    • Don't wait for user to ask for implementation issues
    • Create detailed analysis with severity, category, location, impact, and recommendations
    • After testing completion, user reviews the document to decide true positives vs false positives
    • Then fix true positives and update tests accordingly
    • This workflow ensures systematic issue tracking and prevents bugs from being forgotten

  • When implementing a new feature always publish a new version to pypi

    1. use ./urvc uv version --bump [major|minor|patch] to bump version
    2. Use ./urvc uv build to build the package
    3. Use ./urvc uv publish to publish to PyPI
    • Latter will require PyPI credential

Git conventions

  • ALWAYS follow these git commit message guidelines

  • Use concise, one-line commit messages

  • Example: "Initial commit: Advent of Code 2024 Rust workspace setup"

  • NEVER include co-authoring or Claude references in commit messages

Test Development Methodology

Note: Comprehensive test plan is located in notes/test_plan.md

Test Development Order (Evidence-Based)

Based on research from Google, Microsoft, and the Testing Pyramid, ALWAYS follow this development order:

  1. Unit Tests First (70-80% of total tests)

    • Test individual functions in isolation
    • Use mocks for external dependencies
    • Focus on edge cases, error conditions, and happy paths

  2. Intra-module Integration Tests (after unit tests for each module)

    • Test how functions within the same module work together
    • Use realistic data where appropriate
    • Test module-level workflows

  3. Inter-module Integration Tests (after dependent modules are unit tested)

    • Test how different modules interact
    • Test data flow between modules
    • Test module boundary conditions

  4. System Integration Tests (after all module testing is complete)

    • Test cross-system workflows
    • Test system-wide error handling
    • Test performance at system level

  5. End-to-End Tests Last (5-10% of total tests)

    • Test complete user workflows
    • Most expensive to maintain
    • Use realistic audio and real models

Critical Testing Practices

ALWAYS Follow These Rules:

  1. Folder Structure Flexibility

    • Test folder structure is NOT set in stone and should not restrict development
    • NEVER repeat tests - if there's a better way to bundle existing tests, restructure as needed
    • Test organization should serve the tests, not the other way around

  2. Quality Assurance Process

    • ALWAYS run pre-commit hooks after finishing ANY test to ensure it works correctly
    • Alternatively, run linting and type checking directly on test files
    • Never claim tests are "fixed" or "done" without running pre-commit successfully
    • This includes both type checking (pyright) and linting (ruff) validation

  3. Test Development Process

    • Read the test plan THOROUGHLY between writing tests (located in notes/test_plan.md)
    • Don't skip ahead - understand the full context before implementing
    • Each test should align with the overall testing strategy
    • When in doubt, refer back to the plan before making decisions

  4. Parallel Task Execution

    • Use Task tool for parallel work when fixing clearly parallel tasks like separate files
    • Use Task tool when waiting for user input - spawn subworkers to continue other tasks
    • Decide whether to keep or discard subworker results based on user feedback
    • This allows continuous progress rather than blocking on user input

Test Development Principles

  • ALWAYS do in-depth analysis of each function before writing tests
  • Bottom-up approach: Test foundational modules first (dependencies)
  • Module-by-module: Complete all test types for a module before moving to next
  • Conservative mocking: Only mock external APIs, not internal logic
  • Case-by-case decisions: Audio and model mocking based on specific test needs
  • Integration/E2E tests: Use realistic audio and real models most of the time
  • Avoid test duplication: Always check existing codebase for similar tests before creating new ones
    • Especially important for integration tests at different levels (intra-module, inter-module, system)
    • Review existing test structure to avoid redundant coverage
    • Ensure each test has a unique purpose and scope

Audio/ML Testing Strategy

  • Unit tests: Synthetic audio often acceptable (decide case-by-case)
  • Integration tests: Realistic audio preferred
  • E2E tests: Always use realistic audio and real models
  • Performance tests: Use realistic data for accurate measurements
  • Training tests: Use small but realistic datasets

Code Quality Enforcement

Pre-commit Hooks (Active)

Purpose: Automatically enforce code quality standards before each commit, preventing broken or poorly formatted code from entering the repository.

Setup Instructions:

# Install development dependencies (one-time setup)
./urvc uv sync --group dev

# Install pre-commit hooks in repository (one-time setup)
./urvc uv run pre-commit install

# Test hooks manually (optional)
./urvc uv run pre-commit run --all-files

IMPORTANT - Never bypass hooks:

  • Never use git commit --no-verify unless absolutely necessary
  • If hooks fail, fix the issues rather than bypassing them
  • This maintains code quality and prevents technical debt

Common Linting/Type Errors and Fixes

  • Docstring line breaking: NEVER use # continuation in comments

    • ✅ Extend continuation lines to ~80 characters when possible unless at section end
    • ✅ Break at natural sentence/phrase boundaries for readability

  • Docstring format: If docstrings can't fit on one line (>72 chars), use proper multi-line format:

    • ✅ Correct multi-line format - BREAK THE CONTENT within the docstring:

      def function():
    \"\"\"
    Test ConfigNotFoundError with different configuration
    names.
    \"\"\"

    • ❌ NEVER use single-line docstrings that exceed 72 characters

    • ❌ NEVER shorten descriptive text to fit on one line

    • ❌ NEVER keep long content on single line within multi-line format

    WRONG APPROACH: Just putting triple quotes on separate lines but keeping long content on one line CORRECT APPROACH: Break the content itself across multiple lines

Documentation Best Practices

  • Follow Numpy-style docstrings for consistency

Standard Documentation Sections (in order)

  1. Brief description - What the function does (first paragraph)
  2. Detailed explanation (if relevant) - How it works, algorithms used, performance characteristics
  3. Parameters: Describe input parameters with types and default values if applicable
  4. Returns: Describe return values with types
  5. Raises: List exceptions that may be raised
  • Line Length Standard : 79 characters maximum If unsure of style consult existing code for examples.

Research Methodology

When user requests "ultrathink and research" or "deep research":

Phase 1: Primary Source Investigation

  • RFCs & Language Issues: Search python rfcs for design decisions and rationale
  • Library Documentation: Read actual API docs, not just descriptions
  • Community Forums: Access Python Internals, not just user forums
  • Version History: Research when features were added and why

Phase 2: Cross-Domain Analysis

  • Multiple Domains: Check game engines, scientific computing, image processing, etc..
  • Real Codebases: Examine how major libraries solve problems
  • Performance Data: Look for benchmarks and real-world measurements
  • Historical Context: Understand evolution of approaches over time

Phase 3: Evidence Quality Assessment

  • Authoritative: Language RFCs, core team discussions, library maintainer posts
  • Practical: Stack Overflow with multiple upvotes, real project examples
  • Speculative: Blog posts, opinions without backing data
  • Verify Access: Confirm you can actually read sources, not just descriptions

Phase 4: Honest Reporting

  • Qualify Claims: "Based on limited sources" vs "definitive consensus"
  • Cite Limitations: Note 403 errors, paywalls, incomplete access
  • Multiple Perspectives: Present competing viewpoints with evidence
  • Avoid Extrapolation: Don't claim "industry standard" from one example