mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-17 05:40:42 -07:00
Refactor documentation structure and dependencies for migration to Fumadocs
- Updated `.gitignore` to include new build and generated content directories. - Removed outdated Mintlify configuration files and documentation. - Introduced new `MIGRATION.md` to outline the transition from Mintlify to Fumadocs. - Added `mdx-components.tsx` for MDX component configuration and compatibility. - Updated `package.json` and `next.config.mjs` for new dependencies and Next.js configuration. - Created `source.config.ts` for content source configuration. - Added OpenAPI specification in `openapi.json` for API documentation. - Removed legacy files and adjusted project structure to align with Fumadocs conventions.
This commit is contained in:
Jamie Pine
@@ -0,0 +1,477 @@
|
||||
---
|
||||
title: "Troubleshooting"
|
||||
description: "Common issues and solutions for Voicebox"
|
||||
---
|
||||
|
||||
This guide covers common issues you might encounter when using or developing Voicebox, along with solutions.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### macOS: "App is damaged and can't be opened"
|
||||
|
||||
This occurs because the app isn't signed with an Apple Developer certificate.
|
||||
|
||||
**Solution:**
|
||||
```bash
|
||||
# Remove the quarantine attribute
|
||||
xattr -cr /Applications/Voicebox.app
|
||||
```
|
||||
|
||||
### Windows: SmartScreen Warning
|
||||
|
||||
Windows SmartScreen may warn that the app is unrecognized.
|
||||
|
||||
**Solution:**
|
||||
- Click "More info"
|
||||
- Click "Run anyway"
|
||||
|
||||
<Note>
|
||||
This is expected for unsigned applications. We're working on code signing for future releases.
|
||||
</Note>
|
||||
|
||||
## Server Issues
|
||||
|
||||
### Backend Server Won't Start
|
||||
|
||||
**Symptoms:**
|
||||
- Red status indicator in bottom-left corner
|
||||
- "Failed to connect to server" error
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Port Already in Use">
|
||||
Check if port 17493 is already in use:
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
lsof -i :17493
|
||||
|
||||
# Windows
|
||||
netstat -ano | findstr :17493
|
||||
```
|
||||
|
||||
Kill the process using the port:
|
||||
```bash
|
||||
# macOS/Linux
|
||||
kill -9 <PID>
|
||||
|
||||
# Windows
|
||||
taskkill /PID <PID> /F
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Permission Issues">
|
||||
The server binary might not have execute permissions:
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
chmod +x ~/Library/Application\ Support/com.voicebox.app/backend/voicebox-server
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Check Logs">
|
||||
View server logs for errors:
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
tail -f ~/Library/Application\ Support/com.voicebox.app/logs/server.log
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```bash
|
||||
type %APPDATA%\com.voicebox.app\logs\server.log
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Connection Timeout
|
||||
|
||||
**Symptoms:**
|
||||
- Long loading times
|
||||
- "Connection timeout" errors
|
||||
|
||||
**Solution:**
|
||||
- Restart the app
|
||||
- Check your firewall settings
|
||||
- Ensure localhost is accessible
|
||||
|
||||
## Generation Issues
|
||||
|
||||
### First Generation is Very Slow
|
||||
|
||||
**Symptoms:**
|
||||
- First generation takes 2-5 minutes
|
||||
- Progress indicator stuck at "Loading model..."
|
||||
|
||||
**Explanation:**
|
||||
This is expected behavior. The first generation downloads the Qwen3-TTS model (~2-4GB) and initializes it.
|
||||
|
||||
**Solution:**
|
||||
- Wait for the initial download to complete
|
||||
- Subsequent generations will be much faster
|
||||
- Check your internet connection
|
||||
|
||||
### Poor Voice Quality
|
||||
|
||||
**Symptoms:**
|
||||
- Robotic or unnatural voice
|
||||
- Missing emotion or prosody
|
||||
- Pronunciation errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<Steps>
|
||||
<Step title="Improve Voice Samples">
|
||||
- Use 10-30 seconds of clear audio
|
||||
- Avoid background noise
|
||||
- Ensure consistent speaking tone
|
||||
- Add multiple samples from the same speaker
|
||||
</Step>
|
||||
|
||||
<Step title="Match Speaking Style">
|
||||
The generated voice will mimic the tone and style of your samples. If your sample is monotone, the generation will be too.
|
||||
</Step>
|
||||
|
||||
<Step title="Adjust Text Formatting">
|
||||
- Use proper punctuation
|
||||
- Add commas for natural pauses
|
||||
- Capitalize proper nouns
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Generation Fails with "Out of Memory"
|
||||
|
||||
**Symptoms:**
|
||||
- Generation crashes
|
||||
- "CUDA out of memory" or "RuntimeError: out of memory"
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Free GPU Memory">
|
||||
Close other GPU-intensive applications:
|
||||
- Games
|
||||
- Video editors
|
||||
- Multiple browser tabs with WebGL
|
||||
|
||||
Then restart Voicebox.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Use CPU Mode">
|
||||
If your GPU doesn't have enough VRAM (need 6GB+), use CPU mode:
|
||||
|
||||
Settings → Generation → Use CPU instead of GPU
|
||||
|
||||
<Warning>
|
||||
CPU generation is 5-10x slower but uses system RAM instead of VRAM.
|
||||
</Warning>
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Reduce Batch Size">
|
||||
For long text, split it into smaller chunks instead of generating all at once.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Audio Issues
|
||||
|
||||
### No Audio Playback
|
||||
|
||||
**Symptoms:**
|
||||
- Generated audio won't play
|
||||
- Playback button doesn't respond
|
||||
|
||||
**Solutions:**
|
||||
- Check system audio settings
|
||||
- Ensure audio output device is connected
|
||||
- Try exporting and playing in a media player
|
||||
|
||||
### Crackling or Distorted Audio
|
||||
|
||||
**Symptoms:**
|
||||
- Audio has static or distortion
|
||||
- Clipping sounds
|
||||
|
||||
**Solutions:**
|
||||
- Check if your input samples have distortion
|
||||
- Reduce playback volume
|
||||
- Re-generate with cleaner voice samples
|
||||
|
||||
## Development Issues
|
||||
|
||||
### Backend Won't Start in Dev Mode
|
||||
|
||||
**Symptoms:**
|
||||
- `bun run dev:server` fails
|
||||
- Import errors or module not found
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Python Version">
|
||||
Ensure Python 3.11 or higher:
|
||||
|
||||
```bash
|
||||
python --version
|
||||
```
|
||||
|
||||
If not, install Python 3.11+ and recreate the virtual environment.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Virtual Environment">
|
||||
Ensure venv is activated:
|
||||
|
||||
```bash
|
||||
# macOS/Linux
|
||||
source backend/venv/bin/activate
|
||||
|
||||
# Windows
|
||||
backend\venv\Scripts\activate
|
||||
```
|
||||
|
||||
You should see `(venv)` in your prompt.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Dependencies">
|
||||
Reinstall dependencies:
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
pip install -r requirements.txt
|
||||
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
|
||||
```
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Tauri Build Fails
|
||||
|
||||
**Symptoms:**
|
||||
- `bun run tauri build` fails
|
||||
- Rust compilation errors
|
||||
|
||||
**Solutions:**
|
||||
|
||||
```bash
|
||||
# Clean build artifacts
|
||||
cd tauri/src-tauri
|
||||
cargo clean
|
||||
|
||||
# Update Rust
|
||||
rustup update
|
||||
|
||||
# Try building again
|
||||
cd ../..
|
||||
bun run tauri build
|
||||
```
|
||||
|
||||
### OpenAPI Client Generation Fails
|
||||
|
||||
**Symptoms:**
|
||||
- `./scripts/generate-api.sh` fails
|
||||
- "Failed to fetch schema" error
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<Steps>
|
||||
<Step title="Ensure Backend is Running">
|
||||
```bash
|
||||
curl http://localhost:17493/openapi.json
|
||||
```
|
||||
|
||||
Should return JSON. If not, start the backend.
|
||||
</Step>
|
||||
|
||||
<Step title="Check Port">
|
||||
Ensure nothing else is using port 17493
|
||||
</Step>
|
||||
|
||||
<Step title="Regenerate Manually">
|
||||
```bash
|
||||
cd backend
|
||||
source venv/bin/activate
|
||||
uvicorn main:app --reload --port 17493
|
||||
|
||||
# In another terminal
|
||||
./scripts/generate-api.sh
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Database Issues
|
||||
|
||||
### "Database is locked" Error
|
||||
|
||||
**Symptoms:**
|
||||
- Profile or generation operations fail
|
||||
- SQLite lock errors
|
||||
|
||||
**Solutions:**
|
||||
- Close all Voicebox instances
|
||||
- Delete the lock file:
|
||||
```bash
|
||||
# macOS
|
||||
rm ~/Library/Application\ Support/com.voicebox.app/data/voicebox.db-shm
|
||||
rm ~/Library/Application\ Support/com.voicebox.app/data/voicebox.db-wal
|
||||
```
|
||||
|
||||
### Corrupted Database
|
||||
|
||||
**Symptoms:**
|
||||
- App crashes on launch
|
||||
- Data missing or corrupted
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<Warning>
|
||||
This will delete all your voice profiles and generation history. Export important profiles first if possible.
|
||||
</Warning>
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
rm ~/Library/Application\ Support/com.voicebox.app/data/voicebox.db
|
||||
|
||||
# Windows
|
||||
del %APPDATA%\com.voicebox.app\data\voicebox.db
|
||||
```
|
||||
|
||||
Restart the app to create a fresh database.
|
||||
|
||||
## Model Issues
|
||||
|
||||
### Model Download Fails
|
||||
|
||||
**Symptoms:**
|
||||
- "Failed to download model" error
|
||||
- Stuck at "Downloading..."
|
||||
|
||||
**Solutions:**
|
||||
- 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
|
||||
|
||||
### Wrong Model Version
|
||||
|
||||
**Symptoms:**
|
||||
- Generation quality suddenly degraded
|
||||
- Different voice output
|
||||
|
||||
**Solutions:**
|
||||
Clear the model cache and re-download:
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
rm -rf ~/.cache/huggingface/hub/models--Qwen*
|
||||
|
||||
# Windows
|
||||
rmdir /s %USERPROFILE%\.cache\huggingface\hub\models--Qwen*
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow Generation on GPU
|
||||
|
||||
**Symptoms:**
|
||||
- Generation slower than expected
|
||||
- GPU not being utilized
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Verify CUDA Installation">
|
||||
```bash
|
||||
nvidia-smi
|
||||
```
|
||||
|
||||
Should show your GPU. If not, install CUDA drivers.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Check GPU Selection">
|
||||
If you have multiple GPUs, ensure Voicebox is using the right one.
|
||||
|
||||
Settings → Generation → GPU Device
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Update GPU Drivers">
|
||||
Outdated drivers can cause performance issues. Update to the latest NVIDIA drivers.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### High Memory Usage
|
||||
|
||||
**Symptoms:**
|
||||
- App uses excessive RAM
|
||||
- System becomes sluggish
|
||||
|
||||
**Solutions:**
|
||||
- Close unused voice profiles
|
||||
- Clear generation history
|
||||
- Restart the app periodically
|
||||
|
||||
## Remote Mode Issues
|
||||
|
||||
### Can't Connect to Remote Server
|
||||
|
||||
**Symptoms:**
|
||||
- "Connection refused" error
|
||||
- Remote server not found
|
||||
|
||||
**Solutions:**
|
||||
|
||||
<Steps>
|
||||
<Step title="Check Server Status">
|
||||
Ensure the remote server is running:
|
||||
|
||||
```bash
|
||||
curl http://<server-ip>:17493/health
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Check Firewall">
|
||||
Ensure port 17493 is open on the remote server:
|
||||
|
||||
```bash
|
||||
# Allow port on Ubuntu/Debian
|
||||
sudo ufw allow 17493
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Verify Network">
|
||||
- Ensure both machines are on the same network (for local servers)
|
||||
- Use IP address instead of hostname
|
||||
- Try pinging the server: `ping <server-ip>`
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Still Having Issues?
|
||||
|
||||
If you're still experiencing problems:
|
||||
|
||||
1. **Check GitHub Issues:** [github.com/jamiepine/voicebox/issues](https://github.com/jamiepine/voicebox/issues)
|
||||
2. **Open a New Issue:** Provide:
|
||||
- Operating system and version
|
||||
- Voicebox version
|
||||
- Steps to reproduce
|
||||
- Error messages or logs
|
||||
3. **Join Discord:** [discord.gg/voicebox](https://discord.gg/voicebox) (coming soon)
|
||||
|
||||
## Diagnostic Information
|
||||
|
||||
When reporting issues, include this information:
|
||||
|
||||
```bash
|
||||
# Voicebox version
|
||||
# Check Help → About in the app
|
||||
|
||||
# Operating system
|
||||
uname -a # macOS/Linux
|
||||
systeminfo # Windows
|
||||
|
||||
# Python version (for dev issues)
|
||||
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