mirror of https://github.com/jamiepine/voicebox.git synced 2026-09-15 12:50:42 -07:00

Files

T

James Pine fe19a9ca47 add style guide, ruff config, generation service extraction, remove Makefile

- Add backend/STYLE_GUIDE.md covering formatting, imports, types, docstrings,
  comments, error handling, async, logging, and naming conventions
- Add pyproject.toml with ruff linter/formatter config (ERA, FIX, isort, pyupgrade)
- Extract generation service (Phase 3): unified run_generation() replaces three
  duplicated closures, serial queue moved to services/task_queue.py
- Delete Makefile in favor of justfile; update all references
- Add Python lint/format/test commands to justfile (check-python, fix-python, test)
- Install ruff, pytest, pytest-asyncio as dev tools in setup-python
- Update REFACTOR_PLAN.md with Phase 3 and Phase 7 completion

2026-03-16 01:35:59 -07:00

1.8 KiB

Raw Blame History

Voicebox Offline Mode Fix

Problem

Voicebox crashes when generating speech if HuggingFace is unreachable, even when models are fully cached locally.

Root Cause:

Voicebox downloads mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16 (MLX optimized version)
But mlx_audio.tts.load() tries to fetch config.json from original repo Qwen/Qwen3-TTS-12Hz-1.7B-Base
This network request fails → server crashes with RemoteDisconnected

Related Issues:

Issue #150: "Internet connection required, even though models are downloaded?"
Issue #151: "API Stability Issues: Model Loading Hangs and Server Crashes"

Solution

Two-part fix:

1. Monkey-patch huggingface_hub (`backend/utils/hf_offline_patch.py`)

Intercepts cache lookup functions
Forces offline mode early (before mlx_audio imports)
Adds debug logging for cache hits/misses

2. Symlink original repo to MLX version (`ensure_original_qwen_config_cached()`)

When original Qwen/Qwen3-TTS-12Hz-1.7B-Base cache doesn't exist
But MLX mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16 does exist
Creates a symlink so cache lookups succeed

Files Changed

backend/backends/mlx_backend.py - Added patch imports at top
backend/utils/hf_offline_patch.py - New patch module

Testing

To test this fix:

Build Voicebox from source: just build
Disconnect from internet
Try generating speech
Should work without network requests

Build Instructions

# Install dependencies
just setup

# Build the app
just build

# Or build just the server
just build-server

Notes

The patch is applied automatically when mlx_backend.py is imported
Set VOICEBOX_OFFLINE_PATCH=0 to disable the patch
The symlink approach works because the config.json is compatible between versions

Patch contributed by community

1.8 KiB Raw Blame History