mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-18 22:30:40 -07:00
fix(landing): API example + new /download page (no more dumping users on GitHub) (#487)
* fix(landing): use qwen_custom_voice in API example (instruct is CustomVoice-only) The curl snippet showed engine: "qwen" alongside an instruct field, but base Qwen3-TTS has no instruct path — that's a Qwen CustomVoice feature. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(landing): use a realistic UUID for profile_id in API example Profile IDs are str(uuid.uuid4()), not slugs (see backend/services/profiles.py:175). Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * feat(landing): add polished /download page — no more dumping users on GitHub Users were clicking download, landing on the GitHub releases page, and filing confused comments along the lines of "I ended up on some blog site called GitHub." We now route every download CTA through a dedicated /download page that auto-triggers the platform-specific download and gives users a polished post-click experience with donate + docs + AI help prompts. - New /download page: - Big app logo + "Your download has started" messaging. - Auto-detects platform from ?platform=X or navigator.userAgent. - Programmatically clicks a hidden anchor to trigger the file download without leaving the page. - Platform-specific buttons as a visible fallback for "download not working" / manual-pick. - Personal donate spiel + Buy Me a Coffee button. - Resources grid: docs, DeepWiki ("got questions? ask AI"), GitHub. - Landing page download section cards now link to /download?platform=X instead of the asset URL directly. - /download/[platform] (used by README/docs links) now redirects to the /download page rather than straight to the asset or to GitHub on error. - Drops unused downloadLinks state from the landing page. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(landing): use official platform brand icons via simple-icons The hand-rolled Linux SVG path wasn't actually Tux — it was a symmetric placeholder shape. Apple/Windows were close but not canonical either. - Apple + Linux: pulled from @icons-pack/react-simple-icons (SiApple, SiLinux). - Windows: simple-icons drops the Microsoft mark over trademark policy, so the Windows 11 flag is inlined from Microsoft's public brand guidance. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(landing): route Download CTAs to /download page, not the section anchor Hero CTA, navbar link, and footer link were all scrolling to #download (the section at the bottom of the page) instead of going to the new /download page that triggers the actual download. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * chore(landing): run dev server on Node instead of Bun runtime Bun runtime + Next 16 Turbopack dev server intermittently trips a JavaScriptCore allocator panic ('pas panic: deallocation did fail ... Alloc bit not set') after a few requests. Dropping --bun keeps Bun as the package manager but runs next dev on Node, which is stable. Build + start keep --bun since one-shot invocations don't exhibit the allocator drift. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * fix(landing): route Linux users to /linux-install instead of attempting download No prebuilt Linux binary exists yet (see /linux-install for build-from-source instructions). The /download page previously treated Linux like the other platforms — auto-triggering a non-existent AppImage and offering a dead manual button. - /download page: if platform resolves to 'linux' via ?platform or UA detect, window.location.replace('/linux-install') — never try to auto-download. - Manual Linux card: label changed to "Build from source" and links to /linux-install (no download attribute, no asset URL). - /download/linux pretty URL: 307s straight to /linux-install. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * docs: consolidate troubleshooting into the MDX docs site + status updates - 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) <[email protected]> * fix(landing): address PR #487 review feedback - Preserve canonical camelCase platform aliases (macArm, macIntel) in the /download/[platform] redirect so those URLs don't lose their platform param. - Add accessible title + role="img" to the inline Windows SVG so it passes Biome's a11y rule and announces to screen readers. - On /api/releases fetch failure, show an explicit error state with a single intentional link to GitHub releases — no more silent GitHub fallback or disabled-button UX lie. Keeps normies off GitHub unless they opt in. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> --------- Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
This commit is contained in:
Jamie Pine
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
d3a44338a2
commit
27a5a62581
@@ -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.
|
||||
</Callout>
|
||||
|
||||
### 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.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### `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):**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Ignore it (recommended)">
|
||||
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.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Install flash-attn on Linux">
|
||||
```bash
|
||||
pip install flash-attn --no-build-isolation
|
||||
```
|
||||
|
||||
Requires a matching CUDA toolkit. Build can take 20+ minutes.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Install flash-attn on Windows (community wheels)">
|
||||
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.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Connection Timeout
|
||||
|
||||
**Symptoms:**
|
||||
@@ -174,6 +228,34 @@ This is expected behavior. The first generation downloads the selected TTS engin
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 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:**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Rebuild the Server Binary">
|
||||
```bash
|
||||
just build-server
|
||||
```
|
||||
|
||||
The build script bundles MLX Metal shader libraries on Apple Silicon automatically.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reinstall MLX Dependencies">
|
||||
```bash
|
||||
pip install -r backend/requirements-mlx.txt
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Verify Backend Detection">
|
||||
Check Settings → Server Status. Should show **Backend: MLX** on Apple Silicon. If it shows **Backend: PYTORCH**, MLX isn't installed correctly.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 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*
|
||||
<Accordion title="Update GPU Drivers">
|
||||
Outdated drivers can cause performance issues. Update to the latest NVIDIA drivers.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Apple Silicon: Confirm MLX Backend">
|
||||
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)".
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### 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.
|
||||
|
||||
Reference in New Issue
Block a user