nodes/diodiogod-TTS-Audio-Suite
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
codex/audio-cpp-integration
diodiogod-TTS-Audio-Suite/docs/Dev reports/DEPENDENCY_MANAGEMENT_GUIDE.md
T

9.7 KiB
Raw Permalink Blame History

Dependency Management Guide

TTS Audio Suite - Complete dependency compatibility documentation

This document tracks all package dependencies, conflicts, solutions, and constraints implemented in the install script for universal compatibility across Python versions and platforms.

Quick Reference

Package Version Constraint Reason Solution
torch >=2.6.0 for security CVE-2025-32434 (Higgs Audio) Smart CUDA detection + upgrade
numpy >=2.2.0,<2.3.0 Numba compatibility Version constraints
numba >=0.61.2 NumPy 2.2+ support Auto-upgrade from 0.61.0
librosa --no-deps Forces NumPy downgrade Isolated installation
descript-audiotools --no-deps Protobuf 3.19 conflict Isolated installation
faiss-cpu >=1.7.4 Cross-platform compatibility Linux: try GPU, Windows: CPU

Critical Dependencies & Conflicts

Python 3.13 Audio-Separator + Resampy Issue

Problem: Audio-Separator v0.36.1 claims Python 3.13 support, but dependency resampy 0.4.3 fails

  • Audio-Separator loads successfully ✅
  • resampy compilation fails with numba in Python 3.13 ❌
  • NUMBA_DISABLE_JIT=1 doesn't prevent resampy from attempting compilation

Impact: Certain UVR models fail with Audio-Separator, force RVC fallback

Failed in nopython mode pipeline (step: nopython frontend)
Untyped global name '_resample_loop_s': Cannot determine Numba type of <class 'function'>

Root Cause: resampy 0.4.3 has incomplete Python 3.13 + numba support despite Audio-Separator's claims

Current Solution:

  • Audio-Separator fails → RVC fallback works for compatible models (UVR v2/v3 architecture)
  • Some models (e.g., UVR-DeNoise.pth) incompatible with both engines
  • Clean error messages implemented to avoid confusion

Model Compatibility:

  • ✅ Working Models: UVR-DeEcho-DeReverb.pth, 6_HP-Karaoke-UVR.pth (via RVC fallback)
  • ❌ Broken Models: UVR-DeNoise.pth, models requiring Audio-Separator-specific architectures

Future Fix: Wait for resampy or Audio-Separator to fix Python 3.13 numba compilation

1. NumPy + Numba Compatibility Crisis

Problem: Different numba versions support different NumPy ranges

  • numba 0.61.0: Supports NumPy ≤ 2.1.x ❌
  • numba 0.61.2+: Supports NumPy 2.2.x ✅

Impact: Core engine loading failures

❌ ChatterboxTTS not available: Numba needs NumPy 2.1 or less. Got NumPy 2.2.
❌ F5-TTS not available: Numba needs NumPy 2.1 or less. Got NumPy 2.2.

Solution: Smart version detection and upgrade

# Detect numba version and upgrade if needed
if numba_version == "0.61.0" or numba_version == "0.61.1":
    pip install --upgrade "numba>=0.61.2"

Constraint: numpy>=2.2.0,<2.3.0 + numba>=0.61.2

2. PyTorch Security Vulnerability (CVE-2025-32434)

Problem: Higgs Audio engine requires PyTorch 2.6+ for security

  • PyTorch < 2.6: transformers blocks torch.load() due to CVE
  • PyTorch 2.6+: Security issue resolved

Impact: Higgs Audio fails to load models

ValueError: Due to a serious vulnerability issue in torch.load...

Solution: Smart CUDA detection and upgrade

  • Detect system CUDA version (12.8 → cu124)
  • Install PyTorch 2.6+ with correct CUDA support
  • Force reinstall if switching CPU↔CUDA variants

Constraint: torch>=2.6.0 with appropriate CUDA index

3. Librosa Dependency Hell

Problem: librosa forces NumPy downgrades

  • librosa dependencies conflict with our NumPy constraints
  • Causes cascade of package downgrades

Impact: Breaks carefully balanced dependency tree

Solution: --no-deps installation

pip install librosa --no-deps
# Then manually install librosa's actual dependencies

Dependencies manually installed:

  • lazy_loader>=0.1, msgpack>=1.0, pooch>=1.1
  • soxr>=0.3.2, decorator>=4.3.0, joblib>=1.0
  • scikit-learn>=1.1.0, audioread>=2.1.9

4. descript-audiotools Protobuf Conflict

Problem: Forces protobuf downgrade 6.x → 3.19.x

  • Breaks other packages expecting modern protobuf
  • Cascading compatibility issues

Solution: --no-deps installation with manual dependencies

pip install descript-audiotools --no-deps

Dependencies manually installed:

  • flatten-dict, ffmpy, importlib-resources
  • randomname, markdown2, pyloudnorm
  • pystoi, torch-stoi, ipython, tensorboard

5. FAISS Platform Compatibility

Problem: faiss-gpu availability varies by platform

  • Linux: faiss-gpu-cu12, faiss-gpu-cu11 available ✅
  • Windows: No GPU version available via pip ❌

Solution: Platform-specific installation

if not is_windows and cuda_detected:
    try:
        pip install faiss-gpu-cu12  # Linux + CUDA
    except:
        pip install faiss-cpu      # Fallback
else:
    pip install faiss-cpu          # Windows/CPU-only

Python Version Compatibility

Python 3.13 Specific Issues

Package Issue Solution Status
MediaPipe Binary incompatible OpenSeeFace fallback ✅ Working
numba JIT compilation issues Disable JIT in Python 3.13 ✅ Working
audioop packages Not available Remove from dependencies ✅ Fixed
resampy Numba compilation fails in Audio-Separator RVC fallback works for compatible models ⚠️ Partial

Python 3.12 Compatibility

Package Issue Solution Status
All engines NumPy/numba mismatch Smart version detection ✅ Working
PyTorch CUDA CPU vs CUDA variants Force reinstall detection ✅ Working

Install Script Logic Flow

1. Environment Detection

- Python version (3.12, 3.13+)
- Platform (Windows, Linux, macOS)  
- CUDA availability (nvidia-smi detection)
- CUDA version (12.8 → cu124, 11.8 → cu118)

2. PyTorch Installation

- Check existing version and CUDA support
- Upgrade if needed (security + compatibility)
- Platform-specific CUDA index selection

3. Core Dependencies

- Smart package checking (skip if satisfied)
- Safe packages installed normally
- Sub-dependencies for --no-deps packages

4. NumPy + Numba Resolution

- Detect numba version compatibility
- Upgrade numba if needed (0.61.0 → 0.61.2+)
- Install constrained NumPy (>=2.2.0,<2.3.0)

5. Problematic Package Isolation

- Install with --no-deps to prevent conflicts
- Manually install required sub-dependencies
- Maintain compatibility with main dependency tree

Package Categories

✅ SAFE Packages (Normal installation)

  • transformers>=4.46.3, accelerate, datasets
  • soundfile>=0.12.0, sounddevice>=0.4.0
  • jieba, pypinyin, unidecode
  • conformer>=0.3.2, x-transformers, vocos
  • s3tokenizer>=0.1.7, resemble-perth

⚠️ PROBLEMATIC Packages (--no-deps required)

  • librosa - Forces NumPy downgrade
  • descript-audiotools - Protobuf conflicts
  • descript-audio-codec - Dependency conflicts
  • cached-path - Forces package downgrades
  • torchcrepe - Conflicts via librosa
  • onnxruntime - Forces NumPy 2.3.x (Python 3.13 only)

🎯 VERSION-CRITICAL Packages

  • torch>=2.6.0 - Security requirement
  • numpy>=2.2.0,<2.3.0 - Numba compatibility
  • numba>=0.61.2 - NumPy 2.2+ support
  • transformers>=4.46.3 - Higgs Audio compatibility

Testing Matrix

Verified Working Combinations

Python Platform PyTorch NumPy Numba Status
3.12.6 Windows 2.7.1+cu126 2.2.6 0.61.2 ✅ All engines
3.13.x Windows 2.8.0+cpu 2.2.6 0.61.2 ✅ All engines
3.12.6 Linux 2.6.0+cu121 2.2.6 0.61.2 ✅ All engines

Known Broken Combinations

Python Platform PyTorch NumPy Numba Issue
3.12.6 Windows Any 2.2.6 0.61.0 ❌ Engine loading
Any Any <2.6.0 Any Any ❌ Higgs Audio CVE

Troubleshooting Guide

Engine Loading Failures

❌ ChatterboxTTS not available: Numba needs NumPy 2.1 or less

Cause: numba 0.61.0 with NumPy 2.2+
Fix: Run install script to upgrade numba to 0.61.2+

Higgs Audio Model Loading

❌ CVE-2025-32434 vulnerability error

Cause: PyTorch < 2.6.0
Fix: Run install script to upgrade PyTorch 2.6+

Windows CUDA Issues

AssertionError: Torch not compiled with CUDA enabled

Cause: CPU PyTorch on CUDA system
Fix: Install script detects and reinstalls CUDA PyTorch

Maintenance Notes

When Adding New Dependencies

  1. Check conflicts with existing constraints
  2. Test with problematic packages (librosa, descript-*)
  3. Update this documentation
  4. Add to appropriate category (Safe/Problematic/Critical)

When Supporting New Python Versions

  1. Test numba compatibility with NumPy constraints
  2. Check for binary package availability
  3. Update compatibility matrix
  4. Add version-specific workarounds if needed

When Updating Major Dependencies

  1. Review cascade effects on sub-dependencies
  2. Test with --no-deps packages
  3. Update version constraints
  4. Verify cross-platform compatibility

Last updated: Version 4.8.19 - Python 3.13 Audio-Separator + resampy compatibility issues documented

Reference in New Issue View Git Blame Copy Permalink