The Problem

Users who need a private, locally‑run voice‑AI workflow must stitch together separate TTS services, a dictation hook, and post‑processing tools. Existing cloud‑only products expose audio and text, require subscriptions, and cannot be customised with user‑owned voice profiles.

What This Does

voicebox ships a self‑contained studio that clones voices, generates speech in 23 languages, and captures dictation via a global hotkey. The repo is a portfolio of six independent projects:

  • app – the main React/Next UI (197 files). Entry point app/index.html loads app/src/App.tsx, which pulls API helpers from app/src/lib/api/index.ts.
  • backend – a Python service (128 files) exposing REST endpoints for TTS, voice cloning, and audio effects. The server starts in backend/app.py, which imports the hub backend/__init__.py.
  • landing – a static marketing site (87 files).
  • tauri – a Rust‑based desktop wrapper (105 files) that launches the UI in a native window.
  • web – a minimal web‑only front‑end (12 files).
  • scripts – helper utilities (10 files).

Common techniques across the projects include Tailwind styling, Docker orchestration, and use of Hugging‑Face Transformers for model inference.

How It Is Wired

Execution begins in the UI layer:

  1. Frontend start – npm run dev (derived from app/package.json) launches Vite, which serves app/index.html. app/src/App.tsx mounts the React tree.
  2. API calls – UI components import from app/src/lib/api/index.ts, which re‑exports service classes such as DefaultService (found in app/src/lib/api/services/DefaultService.ts). Each service issues HTTP requests to the backend (/api/v1/...).
  3. Backend entry – backend/app.py creates a FastAPI (or Flask) app, registers routes defined in backend/routes/__init__.py. The route module imports the hub backend/__init__.py, which in turn pulls database utilities (backend/database/__init__.py) and service factories (backend/services/__init__.py).
  4. Core processing – request handlers call into backend/backends/__init__.py, the most connected module (36 outgoing imports). This module selects a TTS engine, runs the model via transformers, and applies post‑processing defined in backend/services/__init__.py.
  5. Data persistence – optional SQLite or file‑based storage is accessed through backend/database/__init__.py.
  6. Desktop wrapper – the Tauri Rust crate (tauri/src/main.rs) spawns the UI as a webview and proxies API calls to the local backend, allowing the whole stack to run as a native app.

The import graph shows 23 modules in circular dependencies, most notably backend/backends/__init__.py ↔ backend/app.py. These cycles increase the blast radius of any change to the hub modules. The DefaultService class has the highest outgoing edge count (16) and thus is a primary integration point for new APIs.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/voicebox
cd voicebox

# Build and run with Docker (Dockerfile and docker‑compose.yml are present)
docker compose up --build   # starts both backend and UI services

# Or run locally without containers
# Frontend
cd app
npm ci                     # installs exact versions from lockfile
npm run dev                # Vite dev server at http://localhost:5173

# Backend
cd ../backend
pip install -r requirements.txt   # or `uv pip install -r requirements.txt`
python -m backend.app             # starts the API server (default port 8000)

Configuration files such as backend/pyproject.toml and backend/requirements.txt list required Python packages; no additional environment variables are referenced in the source tree.

Real‑World Use

A developer can embed Voicebox in a private‑assistant pipeline: the assistant sends a text prompt to http://localhost:8000/api/v1/tts, receives a wav file, and streams it to the OS audio stack. Because all models run locally, no user data leaves the machine, satisfying strict privacy requirements for healthcare or finance chatbots.

Code Health & Issues

Repo‑level hygiene (9 findings)

  • HIGH – Pin GitHub Actions to commit SHAs (.github/workflows/*.yml).
  • MEDIUM – Declare least‑privilege GITHUB_TOKEN permissions (ci.yml).
  • MEDIUM – Add Dependabot/Renovate (.github/dependabot.yml).
  • MEDIUM – Pin Docker base images by digest (Dockerfile).
  • MEDIUM – Add a dependency‑vulnerability scan step (.github/workflows).
  • MEDIUM – Set persist-credentials: false on the Windows checkout step.
  • MEDIUM – Run containers as non‑root (Dockerfile).
  • LOW – Define job timeouts (build-windows.yml).
  • LOW – Add convention files (.editorconfig, .gitattributes, formatter config).

Static analysis findings (153 total)

  • HIGH – Import cycles (23 modules, e.g., backend/backends/__init__.py, backend/app.py).
  • HIGH – Hub modules with 30‑+ dependents (backend/__init__.py, backend/database/__init__.py).
  • HIGH – Oversized files (backend/backends/__init__.py, app/src/components/VoiceProfiles/ProfileForm.tsx).
  • HIGH – Deep nesting (up to 7 levels in backend/backends/base.py).
  • HIGH – Duplicated UI blocks across multiple components.
  • MEDIUM – Broad exception handling (backend/utils/audio.py etc.).
  • MEDIUM – Files opened without context manager (backend/server.py).
  • MEDIUM – High branching density (backend/utils/platform_detect.py).

All findings are deterministic outputs of the analysis pipeline; no additional subjective issues are listed.

The Bottom Line

Voicebox delivers a functional, locally‑hosted voice‑AI studio with a clear separation between UI, backend, and desktop wrappers. The codebase works but suffers from import cycles, large hub modules, and duplicated UI logic that will increase maintenance effort. It is suitable for teams comfortable with Python, TypeScript, and Docker who need a privacy‑first voice pipeline and are prepared to address the identified health concerns.