From a179b826cd052d84e1725c8a1358df6ca5dd39de Mon Sep 17 00:00:00 2001 From: James Pine Date: Sat, 18 Apr 2026 23:20:35 -0700 Subject: [PATCH] docs: consolidate troubleshooting into the MDX docs site + status updates MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Delete docs/TROUBLESHOOTING.md; the canonical troubleshooting guide now lives under docs/content/docs/overview/troubleshooting.mdx so it's served from docs.voicebox.sh alongside the rest of the docs. - CONTRIBUTING.md + README.md: repoint "Troubleshooting" references to the new MDX path. README gets a top-level callout so users hit the guide before filing an issue. - PROJECT_STATUS.md: refresh issue/PR counts, document the flash-attn warning (cosmetic on all platforms; CUDA-only, fallback is PyTorch SDPA which is near-FA2 on Ampere+) with per-platform context + community Windows wheels + SageAttention/xformers alternatives, add WebAudio audio-session bug note (tracked separately in PR #486), and expand the Qwen 0.6B→1.7B MLX fallback explanation for triage. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 4 +- README.md | 5 +- docs/PROJECT_STATUS.md | 54 ++- docs/content/docs/TROUBLESHOOTING.md | 311 ------------------ .../content/docs/overview/troubleshooting.mdx | 130 +++++++- 5 files changed, 177 insertions(+), 327 deletions(-) delete mode 100644 docs/content/docs/TROUBLESHOOTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f7ea583a..b4a3b0ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -359,7 +359,7 @@ Releases are managed by maintainers: ## Troubleshooting -See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues and solutions. +See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/troubleshooting.mdx) for common issues and solutions. **Quick fixes:** @@ -372,7 +372,7 @@ See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues and sol - Open an issue for bugs or feature requests - Check existing issues and discussions - Review the codebase to understand patterns -- See [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) for common issues +- See [docs/content/docs/overview/troubleshooting.mdx](docs/content/docs/overview/troubleshooting.mdx) for common issues ## Additional Resources diff --git a/README.md b/README.md index 1ee08c33..8d220202 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,8 @@ Docs • Download • Features • - API + API • + Troubleshooting


@@ -91,6 +92,8 @@ Voicebox is a **local-first voice cloning studio** — a free and open-source al > **Linux** — Pre-built binaries are not yet available. See [voicebox.sh/linux-install](https://voicebox.sh/linux-install) for build-from-source instructions. +> **Having trouble?** See the [Troubleshooting Guide](docs/content/docs/overview/troubleshooting.mdx) for common install, generation, model-download, and GPU issues. + --- ## Features diff --git a/docs/PROJECT_STATUS.md b/docs/PROJECT_STATUS.md index d6a1daff..cb12ef2e 100644 --- a/docs/PROJECT_STATUS.md +++ b/docs/PROJECT_STATUS.md @@ -1,6 +1,6 @@ # Voicebox Project Status & Roadmap -> Last updated: 2026-04-18 | Current version: **v0.4.1** | ~155 open issues | 12 open PRs +> Last updated: 2026-04-18 | Current version: **v0.4.1** | 232 open issues | 12 open PRs --- @@ -224,6 +224,8 @@ POST /generate - **Blackwell (RTX 50-series) CUDA**: cu128 + sm_120 kernel support shipped (PR #401, #316), but users still report `cudaErrorNoKernelImageForDevice` (#417, #400, #396, #395, #390, #362) — likely a stale CUDA binary on upgraded installs. Needs a follow-up diagnostic / forced re-download path. - **Long text 50k character limit** (#464, #365, #354): Still hit on GPU despite chunking (PR #266). Chunking reliability needs another pass. - **ROCm on RDNA 3/4** (#469): `HSA_OVERRIDE_GFX_VERSION` is hardcoded and harms newer cards. +- **`flash-attn is not installed` warning on every platform (cosmetic, common user complaint)**: Our transformer-based engines (Chatterbox / Qwen) emit `Warning: flash-attn is not installed. Will only run the manual PyTorch version. Please install flash-attn for faster inference.` on every startup, on every platform — we don't pin `flash-attn` in requirements because installing it is fragile and version-sensitive. Fallback is PyTorch SDPA, which is near-FA2 throughput on Ampere+ and is what actually runs. **Per-platform reality:** (a) **macOS/Apple Silicon** — FlashAttention is CUDA-only, irrelevant here; MLX has its own attention kernels. (b) **Linux** — `pip install flash-attn --no-build-isolation` works but takes 20+ min to compile. (c) **Windows** — no official support (Dao-AILab README still says only "Might work"; source builds routinely fail on recent CUDA/MSVC, issues #1715, #1828, #2395). Windows users can install community prebuilt wheels from `kingbri1/flash-attention` or `bdashore3/flash-attention` (latest v2.8.3, Aug 2025; `win_amd64` wheels for CUDA 12.4/12.8, Torch 2.6–2.9, Python 3.10–3.13) matching their exact CUDA/Torch/Python, or use WSL2. **Native-Windows alternatives worth considering as a build-time swap:** SageAttention (thu-ml, Apache 2.0, claims 2–5× over FA2) and xformers (official Windows wheels). **Action for us:** troubleshooting doc now covers it (see `docs/content/docs/overview/troubleshooting.mdx`), and we should optionally suppress the warning via `logging.getLogger(...).setLevel(ERROR)` at backend import since the fallback is functionally fine. +- **WebAudio playback dies after audio-session interruption** (#41, plus an internal repro where the app is backgrounded long enough): WaveSurfer's `AudioContext` gets suspended by macOS — either because another app grabs the audio output, or because the WKWebView throttles when backgrounded. `play()` resolves and `timeupdate` can still fire, but no audio reaches the output. Only app restart fixes it. **Things already tried that didn't work:** (a) swapping WaveSurfer backend away from WebAudio — introduced more bugs, not an option; (b) remount hook on the player — doesn't help because a freshly-created `AudioContext` is born suspended and only resumes on a user gesture. PR #293 was a prior partial fix that doesn't cover this path. **Next thing to try** (not yet attempted — confirmed via grep of `AudioPlayer.tsx`): call `wavesurfer.getMediaElement().getGainNode().context.resume()` on the play button click (the click itself is a valid user gesture), plus a `visibilitychange` + `statechange` listener as belt-and-suspenders. The `ctx.resume()` pattern already exists in the codebase at `useStoryPlayback.ts:52` — just not wired into the main player. --- @@ -303,9 +305,15 @@ POST /generate Still reported. Users get stuck downloads, can't resume, offline mode edge cases. -**Key issues:** #475 (MAC CustomVoice install error), #449 (infinite loading macOS), #445 (can't download CustomVoice), #462 (Qwen requires internet even when loaded — regression from #150), #434 (infinite retry loop offline — PR #443 open), #432 (storage location change hangs when empty — partly fixed by PR #439/#433), #181, #180. +**Key issues:** #475 (MAC CustomVoice install error), #449 (infinite loading macOS), #445 (can't download CustomVoice), #462 (Qwen requires internet even when loaded — regression from #150), #434 (infinite retry loop offline — PR #443 open), #432 (storage location change hangs when empty — partly fixed by PR #439/#433), #348 (TADA 3B Multilingual download fails), #336 (TADA model not listed in app), #275 (`No module named 'chatterbox'` on download), #304 (whisper-base feature extractor load error), #287 (macOS ARM `check_model_inputs` ImportError on new version), #181, #180. -**Fix path:** PR #443 addresses infinite offline retry. CustomVoice-specific download failures (#475, #445) need triage — likely related to frozen-binary import fixes in PR #438. +**Fix path:** PR #443 addresses infinite offline retry. CustomVoice-specific download failures (#475, #445) need triage — likely related to frozen-binary import fixes in PR #438. TADA cluster (#336, #348) and macOS ARM import regressions (#287, #275, #304) need a dedicated triage pass. + +**Qwen 0.6B-downloads-1.7B reports:** **#485** (2026-04-19), **#423** (macOS M1), **#329**. Platform-dependent: + +- **On MLX (Apple Silicon) — not a bug.** `mlx-community` only publishes 1.7B-Base-bf16 weights, so the 0.6B Base option intentionally resolves to the same repo (`backend/backends/__init__.py:180` — `# 0.6B not available in MLX, falls back`). UX gap: the selector offers a size that doesn't exist on the active backend. Fix: (a) hide the 0.6B option on MLX, or (b) label it "0.6B (uses 1.7B on Apple Silicon)". +- **On PyTorch (Windows/Linux/CUDA/ROCm/XPU/CPU) — real bug if reported.** Both 0.6B and 1.7B have distinct repos (`Qwen/Qwen3-TTS-12Hz-0.6B-Base` vs `-1.7B-Base`). Triage each report by platform before merging into the MLX cluster. +- **Qwen CustomVoice (either platform)** — no fallback, both sizes always have dedicated repos. ### Language Requests (ongoing) @@ -364,6 +372,9 @@ Notable: - **#383** — Concatenate partial reference audio into generated audio - **#382** — Lightning.ai support - **#376** — Remote mode +- **#353** — Audio transcoding +- **#317** — Voice pitch control +- **#189** — "Auto" language option - **#173** — Vocal intonation/inflection control - **#165, #270** — Audiobook mode (PR #154 open) - **#242** — Seed value pinning @@ -371,17 +382,40 @@ Notable: - **#235** — Finetuned Qwen3-TTS tokenizer (PR #253 open) - **#144** — Copy text to clipboard +### Housekeeping / Triage Needed + +| Issue | Reason | +|-------|--------| +| **#431**, **#408** | Spam — Chinese "free Claude API" promos. Close. | +| **#398** ("Excelente") | Non-issue. Close. | +| **#357** | Informational — project featured in Awesome MLX. Close after acknowledgement. | +| **#374**, **#377** | Version-release questions, no bug. Close. | +| **#306** ("voice model"), **#389** ("New model"), **#473** ("New functionality") | Title-only issues, no content. Request details or close. | +| **#309** | Uninstall/cleanup question. Answer and close. | +| **#241** | "How to use in Colab" — support question, not a bug. | +| **#423** / **#485** / **#329** | Platform-dependent. On MLX: not a bug (0.6B weights don't exist upstream, fallback is intentional — fix UX). On PyTorch: real bug if reproducible. Classify each by reporter's platform before deduping. | +| **#336** / **#348** | TADA download/registration cluster — triage together. | +| **#287** / **#275** / **#304** | macOS ARM import regressions on new version — likely one root cause. | +| **#292**, **#349** | Possibly already fixed by merged PRs (#321/#412 and #345). Verify + close. | + +**~70 older issues (pre-#170) not individually categorized above.** Most are long-tail support questions or duplicates of problems now addressed by the multi-engine / model-registry work. A dedicated backlog-sweep pass is overdue. + ### Bugs (ongoing) | Category | Issues | |----------|--------| -| Generation failures | #476, #467, #452, #459 (voice clone fetch error), #468 (tada-1b marked error), #437, #282 | -| Audio quality | #456 (clipping errors v0.4.0), #436 (emotion labels), #333 (pitch/echo), #307 (by-model breakdown) | -| File ops | #477 (spacy_pkuseg dict missing on frozen Windows build), #472 (storage location change) | -| Windows | #466 (install problem), #273 (port 8000 conflict) | -| Linux | #471 (thread-safe PULSE_SOURCE), #413 (Arch build), #409 (Kubuntu build), #341 | -| macOS | #441 (older macOS), #369 (malware flag), #171 (ARM64 binary won't open) | -| Profile/UI | #360 (Kokoro profile hides others — partly addressed by auto-switch), #299 (drag-drop on Win11), #329 (size selector state bug) | +| Generation failures | #476, #467, #452, #459 (voice clone fetch error), #468 (tada-1b marked error), #437, #300, #301, #282 | +| Audio quality | #456 (clipping errors v0.4.0), #436 (emotion labels), #333 (pitch/echo), #307 (by-model breakdown), #340 (all generations say "www...") | +| Transcription | #371 (fails every time), #291 (extract transcription from generated audio) | +| Effects / presets | #349 ("Failed to save" when creating effects presets — possibly fixed by merged #345) | +| File ops | #477 (spacy_pkuseg dict missing on frozen Windows build), #472 (storage location change), #283 (allow longer files for voice creation + in-app trim), #350 (failed to add sample) | +| History | #292 (can't delete failed generations — possibly fixed by merged #321/#412) | +| Windows | #466 (install problem), #375 (WinError 5 access denied), #273 (port 8000 conflict), #201 (model doesn't stay loaded) | +| Linux | #471 (thread-safe PULSE_SOURCE), #413 (Arch build), #409 (Kubuntu build), #351, #341 | +| macOS | #441 (older macOS), #369 (malware flag), #334 (microphone permission), #287 (`check_model_inputs` ImportError — regression), #171 (ARM64 binary won't open) | +| Profile/UI | #360 (Kokoro profile hides others — partly addressed by auto-switch), #299 (drag-drop on Win11), #329 (size selector state bug), #393 (stuck loading screen after reinstall to new dir) | +| Integrations | #397 (SAMMI-bot 422 Unprocessable Entity) | +| Audio playback / session | **#41** (macOS: Voicebox goes silent after another app takes audio output; restart restores it) — see deep-dive below | | Database | #174 (sqlite3 IntegrityError) | --- diff --git a/docs/content/docs/TROUBLESHOOTING.md b/docs/content/docs/TROUBLESHOOTING.md deleted file mode 100644 index d9a5584e..00000000 --- a/docs/content/docs/TROUBLESHOOTING.md +++ /dev/null @@ -1,311 +0,0 @@ ---- -title: "Troubleshooting Guide" -description: "Common issues and solutions for Voicebox" ---- - -Common issues and solutions for Voicebox. - -## Installation Issues - -### macOS: "Voicebox cannot be opened because it is from an unidentified developer" - -**Solution:** -1. Right-click the `.dmg` file -2. Select "Open" -3. Click "Open" in the security dialog -4. Alternatively, go to System Settings → Privacy & Security → Allow Voicebox - -### Windows: "Windows protected your PC" - -**Solution:** -1. Click "More info" -2. Click "Run anyway" -3. Windows Defender may flag new software; this is normal for unsigned apps - -### Linux: AppImage won't run - -**Solution:** -```bash -chmod +x voicebox-*.AppImage -./voicebox-*.AppImage -``` - -## Runtime Issues - -### Server won't start - -**Symptoms:** App opens but shows "Server not connected" - -**Solutions:** -1. **Check Python installation** - ```bash - python --version # Should be 3.11+ - ``` - -2. **Check server binary exists** - - Look in `tauri/src-tauri/binaries/` for your platform - - Binary should match your system architecture - -3. **Check permissions** - ```bash - # macOS/Linux - chmod +x tauri/src-tauri/binaries/voicebox-server-* - ``` - -4. **Check logs** - - macOS: Open Console.app and search for "voicebox" - - Linux: Check `~/.local/share/voicebox/` for logs - - Windows: Check Event Viewer - -### "Model download failed" - -**Symptoms:** First generation fails with download error - -**Solutions:** -1. **Check internet connection** - - Models download from HuggingFace Hub (~2-4GB) - - First download may take several minutes - -2. **Check disk space** - - Models are cached in `~/.cache/huggingface/` - - Ensure at least 5GB free space - -3. **Manual download** (if automatic fails) - ```bash - pip install huggingface_hub - huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base - ``` - -### "Out of memory" errors - -**Symptoms:** Generation fails with CUDA/VRAM errors - -**Solutions:** -1. **Use smaller model** - - Switch to 0.6B model instead of 1.7B - - Settings → Model Management → Load 0.6B - -2. **Close other applications** - - Free up GPU memory - - Close browser tabs, other ML apps - -3. **Use CPU mode** - - Slower but works without GPU - - Backend automatically falls back to CPU - -### MLX "Failed to load the default metallib" error (Apple Silicon) - -**Symptoms:** Generation fails with "library not found" or "metallib" errors - -**Solutions:** -1. **Rebuild server binary** - ```bash - just build-server - ``` - The build script automatically includes MLX Metal shader libraries on Apple Silicon. - -2. **Check MLX installation** - ```bash - pip install -r backend/requirements-mlx.txt - ``` - -3. **Verify backend detection** - - Check server logs for "Backend: MLX" - - If showing "Backend: PYTORCH", MLX may not be installed correctly - -### Audio playback issues - -**Symptoms:** Generated audio won't play - -**Solutions:** -1. **Check audio format** - - Audio is saved as WAV files - - Ensure your system supports WAV playback - -2. **Try downloading audio** - - Right-click → Download - - Play in external player - -3. **Check browser permissions** (web version) - - Allow audio autoplay in browser settings - -### Slow generation - -**Symptoms:** Generation takes >30 seconds - -**Solutions:** -1. **Check backend type** (Apple Silicon) - - Check Settings → Server Status - - Should show "Backend: MLX" on Apple Silicon - - If showing "Backend: PYTORCH", install MLX: `pip install -r backend/requirements-mlx.txt` - - MLX provides 4-5x faster inference on Apple Silicon - -2. **Use GPU** (if available) - - Check Settings → Server Status - - Should show "GPU available: true" - - Apple Silicon: Should show "Metal (Apple Silicon via MLX)" - - Windows/Linux: Should show "CUDA" if GPU available - -3. **Enable caching** - - Voice prompts are cached automatically - - Second generation with same voice should be faster - -4. **Use smaller model** - - 0.6B model is faster than 1.7B - - Quality difference is minimal for most voices - -5. **Check system resources** - - Close other CPU/GPU intensive apps - - Ensure adequate RAM (8GB+ recommended) - -## API Issues - -### "Connection refused" when using API - -**Solutions:** -1. **Check server is running** - ```bash - curl http://localhost:17493/health - ``` - -2. **Check remote mode** - - If connecting remotely, ensure server is started with `--host 0.0.0.0` - - Check firewall settings - -3. **Check port availability** - - The current local app and dev workflow uses port 17493 by default - - Ensure no other service is using it - -### CORS errors in browser - -**Solutions:** -1. **Use desktop app** (recommended) - - Desktop app doesn't have CORS restrictions - -2. **Configure CORS** (for web deployment) - - Update `backend/main.py` CORS settings - - Add your domain to allowed origins - -## Update Issues - -### "Update check failed" - -**Solutions:** -1. **Check internet connection** - - Updates are fetched from GitHub releases - -2. **Check GitHub access** - - Ensure `github.com` is accessible - - Check firewall/proxy settings - -3. **Manual update** - - Download latest release from GitHub - - Install manually - -### "Invalid signature" error - -**Solutions:** -1. **Re-download installer** - - Signature may be corrupted - - Download fresh copy from GitHub - -2. **Check release integrity** - - Verify `.sig` file matches installer - - Report issue if signature is invalid - -## Data Issues - -### Profiles disappeared - -**Solutions:** -1. **Check data directory** - - macOS: `~/Library/Application Support/sh.voicebox.app/` - - Windows: `%APPDATA%/sh.voicebox.app/` - - Linux: `~/.config/sh.voicebox.app/` - -2. **Check database** - - Database: `data/voicebox.db` - - Ensure file exists and is readable - -3. **Restore from backup** - - Profiles can be exported/imported - - Check for backup files - -### "Database locked" error - -**Solutions:** -1. **Close other instances** - - Ensure only one Voicebox instance is running - -2. **Restart app** - - Close and reopen Voicebox - -3. **Check file permissions** - - Ensure database file is writable - - Check directory permissions - -## Development Issues - -### Build fails - -**Solutions:** -1. **Check Rust installation** - ```bash - rustc --version - rustup update - ``` - -2. **Check Tauri dependencies** - ```bash - cd tauri - bun install - ``` - -3. **Clean build** - ```bash - cd tauri/src-tauri - cargo clean - cd ../.. - just build - ``` - -### API client generation fails - -**Solutions:** -1. **Start backend server** - ```bash - just dev-backend - ``` - -2. **Check OpenAPI endpoint** - ```bash - curl http://localhost:17493/openapi.json - ``` - -3. **Regenerate client** - ```bash - just generate-api - ``` - -## Still Having Issues? - -1. **Check existing issues** - - Search GitHub issues for similar problems - - Check closed issues for solutions - -2. **Create new issue** - - Include: - - OS and version - - Voicebox version - - Steps to reproduce - - Error messages/logs - - Screenshots (if applicable) - -3. **Get help** - - Check documentation in `docs/` - - Review `backend/README.md` for API details - - See `CONTRIBUTING.md` for development help - ---- - -For more help, open an issue on [GitHub](https://github.com/jamiepine/voicebox/issues). diff --git a/docs/content/docs/overview/troubleshooting.mdx b/docs/content/docs/overview/troubleshooting.mdx index ff087955..59e759fb 100644 --- a/docs/content/docs/overview/troubleshooting.mdx +++ b/docs/content/docs/overview/troubleshooting.mdx @@ -29,6 +29,14 @@ Windows SmartScreen may warn that the app is unrecognized. This is expected for unsigned applications. We're working on code signing for future releases. +### Linux: AppImage Won't Run + +**Solution:** +```bash +chmod +x voicebox-*.AppImage +./voicebox-*.AppImage +``` + ## Server Issues ### Backend Server Won't Start @@ -85,6 +93,52 @@ Windows SmartScreen may warn that the app is unrecognized. +### `flash-attn is not installed` Warning in Server Logs + +**Symptoms:** +``` +Warning: flash-attn is not installed. Will only run the manual PyTorch version. +Please install flash-attn for faster inference. +``` + +**This is harmless.** The warning is emitted by our transformer-based engines (Chatterbox / Qwen) on every startup. FlashAttention is an optional acceleration library — when it's not present, PyTorch's built-in scaled-dot-product attention (SDPA) runs instead, which is near-FA2 throughput on modern GPUs. Generation works normally. + +**Why it shows up on every platform:** +- **Windows:** `flash-attn` has no official Windows support. The upstream project (Dao-AILab/flash-attention) still only says it *might* work, and source builds typically fail on recent CUDA/MSVC combinations. +- **macOS (Apple Silicon):** FlashAttention is CUDA-only and doesn't apply here at all. MLX has its own optimized attention kernels. +- **Linux:** It's not pinned in our requirements because installing it is fragile and version-sensitive; users who want it install it themselves. + +**Solutions (all optional):** + + + + PyTorch SDPA is what actually runs the model, and on Ampere/Ada/Hopper GPUs it's within a few percent of FA2 for our workloads. You won't notice a meaningful speed difference. + + + + ```bash + pip install flash-attn --no-build-isolation + ``` + + Requires a matching CUDA toolkit. Build can take 20+ minutes. + + + + Official builds don't exist, but community maintainers publish prebuilt wheels: + + - [kingbri1/flash-attention releases](https://github.com/kingbri1/flash-attention/releases) + - [bdashore3/flash-attention releases](https://github.com/bdashore3/flash-attention/releases) + + Pick the wheel matching your exact CUDA + PyTorch + Python combination. Example: + + ```bash + pip install https://github.com/kingbri1/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu128torch2.8.0cxx11abiFALSE-cp312-cp312-win_amd64.whl + ``` + + Alternatively, run Voicebox's backend inside WSL2 and use the standard Linux wheels. + + + ### Connection Timeout **Symptoms:** @@ -174,6 +228,34 @@ This is expected behavior. The first generation downloads the selected TTS engin +### MLX "Failed to load the default metallib" (Apple Silicon) + +**Symptoms:** +- Generation fails with "library not found" or "metallib" errors +- Server logs reference missing Metal shader libraries + +**Solutions:** + + + + ```bash + just build-server + ``` + + The build script bundles MLX Metal shader libraries on Apple Silicon automatically. + + + + ```bash + pip install -r backend/requirements-mlx.txt + ``` + + + + Check Settings → Server Status. Should show **Backend: MLX** on Apple Silicon. If it shows **Backend: PYTORCH**, MLX isn't installed correctly. + + + ## Audio Issues ### No Audio Playback @@ -357,7 +439,26 @@ Restart the app to create a fresh database. - Check your internet connection - Check HuggingFace Hub status - Try using a VPN if HuggingFace is blocked in your region -- Manually download and place in cache directory +- Manually download via the HuggingFace CLI and place in the cache directory: + + ```bash + pip install huggingface_hub + huggingface-cli download Qwen/Qwen3-TTS-12Hz-1.7B-Base + ``` + +### Qwen 0.6B Downloads the Same Files as 1.7B on Apple Silicon + +**Symptoms:** +- You select Qwen 0.6B on an Apple Silicon Mac and the download is the same size as 1.7B +- Generation speed and VRAM usage match 1.7B, not the expected smaller model + +**Explanation:** +This is intentional, not a bug. The MLX community only publishes `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16` — there is no 0.6B MLX build. Voicebox's model registry falls back to the 1.7B weights when 0.6B is selected on MLX (see `backend/backends/__init__.py`). + +**Solution:** +- On Apple Silicon, both size options use the 1.7B model — pick either. +- If you specifically need a smaller model, switch to **Kokoro 82M** (~350 MB) or **LuxTTS** (~300 MB) — both CPU-realtime. +- On Windows/Linux with PyTorch, 0.6B and 1.7B are distinct repos and behave differently. ### Wrong Model Version @@ -404,6 +505,16 @@ rmdir /s %USERPROFILE%\.cache\huggingface\hub\models--Qwen* Outdated drivers can cause performance issues. Update to the latest NVIDIA drivers. + + + Check Settings → Server Status. Should show **Backend: MLX** on Apple Silicon — MLX is 4–5× faster than PyTorch here. If it shows **Backend: PYTORCH**, reinstall MLX: + + ```bash + pip install -r backend/requirements-mlx.txt + ``` + + GPU availability should read "Metal (Apple Silicon via MLX)". + ### High Memory Usage @@ -417,6 +528,21 @@ rmdir /s %USERPROFILE%\.cache\huggingface\hub\models--Qwen* - Clear generation history - Restart the app periodically +## Update Issues + +### "Update Check Failed" + +**Solutions:** +- Confirm your internet connection — updates are fetched from GitHub releases. +- Ensure `github.com` is accessible and not blocked by a firewall or proxy. +- As a fallback, download the latest release from GitHub and install manually. + +### "Invalid Signature" Error + +**Solutions:** +- Re-download the installer — the signature may have been corrupted in transit. +- Verify the `.sig` file matches the installer; if it doesn't, file an issue. + ## Remote Mode Issues ### Can't Connect to Remote Server @@ -482,5 +608,3 @@ python --version # GPU info (if generation issues) nvidia-smi # NVIDIA GPUs ``` - -For more detailed troubleshooting, see the [TROUBLESHOOTING.md](https://github.com/jamiepine/voicebox/blob/main/docs/TROUBLESHOOTING.md) file in the repository.