docs/DEPENDENCIES.md

Dependency Management Guide

Note: As of V3.0, VoiceForge uses Poetry for dependency management. Legacy requirements.txt is maintained for compatibility but Poetry is recommended.

📦 Critical Constraints

Numpy & PyTorch Lock

Status: ⚠️ Strictly Pinned

• Numpy: 1.26.4 (Last stable 1.x version)
• Torch: 2.3.1 (Compatible with Numpy 1.x)
• Reason: pyannote.audio==3.1.1 requires numpy<2.0.0. Upgrading to Numpy 2.0+ will break speaker diarization until pyannote is updated.

Audio Libraries

• Pyannote Audio: 3.1.1 (Strict pin)
• Transformers: 4.42.4 (Pinned for stable MarianMT translation)
• MeloTTS: 0.1.2 (Requires C++ build tools only if installing from source)

---

🛠️ Managing Dependencies with Poetry

1. Installation

pip install poetry

2. Adding a Package

# Add a production dependency
poetry add package_name

# Add a development dependency
poetry add --group dev package_name

3. Updating Dependencies

# Update all packages (respecting constraints)
poetry update

# Update a specific package
poetry update package_name

4. Running the App

poetry run uvicorn app.main:app --reload

---

🐳 Docker Note

The Dockerfile uses Poetry to install dependencies.

• It generates a clean environment based on poetry.lock.
• This ensures that the Docker build matches your local environment exactly (if you use Poetry locally).

⚠️ Troubleshooting

"Failed to build melotts"

• Cause: Missing C++ Build Tools (common on Windows).
• Solution:
  • Option A (Easy): Ignore it. VoiceForge automatically falls back to EdgeTTS if MeloTTS is missing.
  • Option B (Fix): Install "Desktop development with C++" workload via Visual Studio Installer.
  • Option C (Docker): Use Docker, which runs Linux and handles the build automatically.

"SolverProblemError"

• Cause: Conflicting version constraints.
• Solution: Check pyproject.toml for incompatible pins. Ensure you aren't trying to force numpy>=2.0 while pyannote.audio is installed.