mirror of
https://github.com/jamiepine/voicebox.git
synced 2026-09-18 06:10:43 -07:00
Add initial setup for Fumadocs documentation migration
- Created new directory structure for documentation under `/docs2`. - Added `.gitignore` to exclude build artifacts and dependencies. - Introduced `package.json`, `next.config.mjs`, and `postcss.config.mjs` for project configuration. - Implemented MDX components in `mdx-components.tsx` for rendering documentation. - Migrated existing documentation content and created new files for auto-updater and other features. - Established compatibility layer for Mintlify components in `mintlify-compat.tsx`. - Set up OpenAPI documentation in `openapi.json`. - Updated README and migration guide to reflect new structure and usage instructions. - Ensured all components and pages are ready for development and deployment with Fumadocs.
This commit is contained in:
Jamie Pine
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: "Building Stories"
|
||||
description: "Create multi-voice narratives with the Stories Editor"
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
The Stories Editor is perfect for creating podcasts, audiobooks, and multi-speaker content.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create Story">
|
||||
**Stories** → **+ New Story**
|
||||
</Step>
|
||||
<Step title="Add Tracks">
|
||||
Create tracks for each speaker
|
||||
</Step>
|
||||
<Step title="Add Clips">
|
||||
Generate or drag audio to tracks
|
||||
</Step>
|
||||
<Step title="Arrange">
|
||||
Position and trim clips on timeline
|
||||
</Step>
|
||||
<Step title="Export">
|
||||
Render final audio
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Use Cases
|
||||
|
||||
- Multi-host podcasts
|
||||
- Audiobook narration with character voices
|
||||
- Game dialogue scenes
|
||||
- Educational content with multiple speakers
|
||||
|
||||
## Coming Soon
|
||||
|
||||
Full timeline editor documentation will be added as features are finalized.
|
||||
@@ -0,0 +1,296 @@
|
||||
---
|
||||
title: "Creating Voice Profiles"
|
||||
description: "Advanced guide to creating high-quality voice profiles"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Voice profiles are the foundation of voice cloning in Voicebox. This guide covers best practices for creating professional-quality voice profiles.
|
||||
|
||||
## Quick Start
|
||||
|
||||
<Steps>
|
||||
<Step title="Prepare Audio">
|
||||
10-30 seconds of clear speech
|
||||
</Step>
|
||||
<Step title="Create Profile">
|
||||
**Profiles** → **+ New Profile**
|
||||
</Step>
|
||||
<Step title="Upload Sample">
|
||||
Add your audio file
|
||||
</Step>
|
||||
<Step title="Generate">
|
||||
Use the profile to generate speech
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Audio Requirements
|
||||
|
||||
### Ideal Sample Characteristics
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Duration" icon="clock">
|
||||
**10-30 seconds**
|
||||
|
||||
Too short: Poor quality
|
||||
Too long: Unnecessary
|
||||
</Card>
|
||||
<Card title="Clarity" icon="volume">
|
||||
**Clear speech**
|
||||
|
||||
No background noise
|
||||
No music or overlapping voices
|
||||
</Card>
|
||||
<Card title="Quality" icon="sparkles">
|
||||
**High fidelity**
|
||||
|
||||
44.1kHz or 48kHz sample rate
|
||||
Minimal compression
|
||||
</Card>
|
||||
<Card title="Content" icon="microphone">
|
||||
**Natural speech**
|
||||
|
||||
Conversational tone
|
||||
Complete sentences
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### File Formats
|
||||
|
||||
Supported formats:
|
||||
- **WAV** (recommended) - Lossless quality
|
||||
- **MP3** - Acceptable, minimal compression
|
||||
- **M4A** - Acceptable
|
||||
- **FLAC** - Lossless alternative
|
||||
|
||||
<Tip>
|
||||
Use WAV for best results. Avoid heavily compressed formats.
|
||||
</Tip>
|
||||
|
||||
## Recording Tips
|
||||
|
||||
### Environment
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Quiet Space">
|
||||
- Record in a quiet room
|
||||
- Turn off fans, AC, appliances
|
||||
- Close windows to reduce outside noise
|
||||
- Use soft furnishings to reduce echo
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Microphone Placement">
|
||||
- 6-12 inches from mouth
|
||||
- Slight angle to reduce plosives (p, b, t)
|
||||
- Use a pop filter if available
|
||||
- Maintain consistent distance
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Recording Settings">
|
||||
- 44.1kHz or 48kHz sample rate
|
||||
- 16-bit or 24-bit depth
|
||||
- Mono is fine (stereo will be converted)
|
||||
- Avoid automatic gain control
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Speaking
|
||||
|
||||
- **Natural pace** - Don't rush or speak too slowly
|
||||
- **Clear articulation** - Pronounce words clearly
|
||||
- **Consistent volume** - Maintain steady loudness
|
||||
- **Normal tone** - Speak as you normally would
|
||||
- **Complete sentences** - Avoid fragments or "ums"
|
||||
|
||||
## Multiple Samples
|
||||
|
||||
Adding multiple samples can significantly improve quality:
|
||||
|
||||
### Why Multiple Samples?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Robustness" icon="shield">
|
||||
Model learns a more complete representation
|
||||
</Card>
|
||||
<Card title="Versatility" icon="palette">
|
||||
Handles different speaking styles better
|
||||
</Card>
|
||||
<Card title="Quality" icon="star">
|
||||
Reduces artifacts and improves naturalness
|
||||
</Card>
|
||||
<Card title="Consistency" icon="check">
|
||||
More reliable across different texts
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Sample Variety
|
||||
|
||||
Consider adding samples with:
|
||||
|
||||
1. **Different tones**
|
||||
- Casual conversation
|
||||
- Professional/formal
|
||||
- Excited/enthusiastic
|
||||
- Calm/serious
|
||||
|
||||
2. **Different content**
|
||||
- Narratives
|
||||
- Questions
|
||||
- Statements
|
||||
- Emotions (happy, sad, neutral)
|
||||
|
||||
3. **Different recording conditions**
|
||||
- Studio quality
|
||||
- Phone call quality (if needed)
|
||||
- Room acoustics
|
||||
|
||||
<Warning>
|
||||
All samples should be from the **same speaker**. Mixing voices will produce poor results.
|
||||
</Warning>
|
||||
|
||||
## Processing Existing Audio
|
||||
|
||||
If you have existing audio (podcasts, videos, etc.):
|
||||
|
||||
### Extracting Clean Segments
|
||||
|
||||
<Steps>
|
||||
<Step title="Find Clean Speech">
|
||||
Look for segments with:
|
||||
- Just the target speaker
|
||||
- No background music
|
||||
- Minimal noise
|
||||
</Step>
|
||||
|
||||
<Step title="Use Audio Editor">
|
||||
Tools like Audacity or Adobe Audition:
|
||||
- Cut out clean 10-30s segments
|
||||
- Remove silence at start/end
|
||||
- Normalize volume if needed
|
||||
</Step>
|
||||
|
||||
<Step title="Export as WAV">
|
||||
Save as high-quality WAV file
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Noise Reduction
|
||||
|
||||
If you have light background noise:
|
||||
|
||||
```
|
||||
1. Use noise reduction in Audacity:
|
||||
- Select noise-only section
|
||||
- Get Noise Profile
|
||||
- Select full audio
|
||||
- Apply noise reduction (gentle settings)
|
||||
|
||||
2. Avoid over-processing:
|
||||
- Can introduce artifacts
|
||||
- May reduce voice quality
|
||||
```
|
||||
|
||||
## Testing & Iteration
|
||||
|
||||
### Test Your Profile
|
||||
|
||||
After creating a profile:
|
||||
|
||||
<Steps>
|
||||
<Step title="Generate Test">
|
||||
Generate a simple phrase:
|
||||
```
|
||||
"Hello, this is a test of my voice profile."
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Evaluate Quality">
|
||||
Listen for:
|
||||
- Natural tone
|
||||
- Clear pronunciation
|
||||
- Proper prosody
|
||||
- Lack of artifacts
|
||||
</Step>
|
||||
|
||||
<Step title="Iterate">
|
||||
If quality is poor:
|
||||
- Add more samples
|
||||
- Try different source audio
|
||||
- Check sample quality
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### Common Issues
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Robotic Voice">
|
||||
**Cause**: Poor quality samples or too short
|
||||
|
||||
**Fix**: Use longer, higher quality samples
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Wrong Tone">
|
||||
**Cause**: Sample tone doesn't match desired output
|
||||
|
||||
**Fix**: Record samples in the style you want to generate
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Artifacts/Glitches">
|
||||
**Cause**: Background noise or audio issues in samples
|
||||
|
||||
**Fix**: Clean up samples or re-record in quieter environment
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Advanced Tips
|
||||
|
||||
### Celebrity/Character Voices
|
||||
|
||||
For cloning public figures or characters:
|
||||
|
||||
1. **Legal considerations** - Ensure you have rights or it's fair use
|
||||
2. **Source quality** - Find high-quality interview audio or clean clips
|
||||
3. **Consistency** - Use clips where they speak similarly
|
||||
4. **Multiple samples** - Very important for recognizable voices
|
||||
|
||||
### Accent & Dialect
|
||||
|
||||
The model will preserve accent and dialect:
|
||||
|
||||
- British English will generate British English
|
||||
- Southern accent will produce Southern accent
|
||||
- Regional pronunciations will be maintained
|
||||
|
||||
### Emotion Transfer
|
||||
|
||||
The emotional tone of samples affects generation:
|
||||
|
||||
- Energetic samples → Energetic output
|
||||
- Calm samples → Calm output
|
||||
- Mix samples for versatile profile
|
||||
|
||||
## Managing Profiles
|
||||
|
||||
### Organization
|
||||
|
||||
- **Descriptive names** - "John Smith - Professional Narrator"
|
||||
- **Add descriptions** - Note recording conditions, use cases
|
||||
- **Language tags** - Mark the primary language
|
||||
- **Archive unused** - Keep profile list manageable
|
||||
|
||||
### Export/Import
|
||||
|
||||
- **Export** profiles to share or backup
|
||||
- **Import** from colleagues or teammates
|
||||
- Profiles include voice embeddings, not original audio
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Generate Speech" icon="waveform" href="/overview/generating-speech">
|
||||
Use your profile to generate speech
|
||||
</Card>
|
||||
<Card title="Build Stories" icon="film" href="/overview/building-stories">
|
||||
Create multi-voice narratives
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
title: "Generating Speech"
|
||||
description: "Generate high-quality speech from text"
|
||||
---
|
||||
|
||||
## Basic Generation
|
||||
|
||||
<Steps>
|
||||
<Step title="Select Profile">
|
||||
Choose a voice profile from the dropdown
|
||||
</Step>
|
||||
<Step title="Enter Text">
|
||||
Type or paste your text
|
||||
</Step>
|
||||
<Step title="Generate">
|
||||
Click **Generate** and wait a few seconds
|
||||
</Step>
|
||||
<Step title="Play & Export">
|
||||
Preview and download the result
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Text Formatting Tips
|
||||
|
||||
The way you format text affects the output quality.
|
||||
|
||||
### Punctuation
|
||||
|
||||
Use proper punctuation for natural pauses:
|
||||
|
||||
```
|
||||
Good: "Hello! How are you today? I'm doing great."
|
||||
Bad: "Hello how are you today Im doing great"
|
||||
```
|
||||
|
||||
### Emphasis
|
||||
|
||||
Use formatting to suggest emphasis:
|
||||
|
||||
```
|
||||
- ALL CAPS for louder/emphasized: "That was AMAZING!"
|
||||
- Italics for subtle emphasis: "I *really* enjoyed that"
|
||||
- Bold for strong emphasis: "This is **very** important"
|
||||
```
|
||||
|
||||
<Note>
|
||||
The model interprets these hints but results may vary.
|
||||
</Note>
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Batch Generation
|
||||
|
||||
For long-form content, split into smaller chunks for better control and faster processing.
|
||||
|
||||
### Voice Caching
|
||||
|
||||
Voicebox caches voice prompts for faster re-generation with the same profile.
|
||||
|
||||
## Coming Soon
|
||||
|
||||
- Real-time streaming
|
||||
- Word-level timing control
|
||||
- Emotion and style controls
|
||||
- SSML support
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
title: "Generation History"
|
||||
description: "Track and manage all your generated audio"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Voicebox keeps a complete history of all generated audio, making it easy to find, reuse, and manage your creations.
|
||||
|
||||
## Features
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Full History" icon="clock">
|
||||
Every generation is automatically saved
|
||||
</Card>
|
||||
<Card title="Search & Filter" icon="search">
|
||||
Find by text, voice, or date
|
||||
</Card>
|
||||
<Card title="Re-generate" icon="rotate">
|
||||
Regenerate any past generation with one click
|
||||
</Card>
|
||||
<Card title="Export" icon="download">
|
||||
Download individual or batch exports
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Viewing History
|
||||
|
||||
Navigate to the **History** tab to see all your generations.
|
||||
|
||||
Each entry shows:
|
||||
- Generated text
|
||||
- Voice profile used
|
||||
- Timestamp
|
||||
- Audio duration
|
||||
- Language
|
||||
|
||||
## Actions
|
||||
|
||||
### Play
|
||||
Click any generation to play it immediately.
|
||||
|
||||
### Re-generate
|
||||
Regenerate with the same settings or modify the text/voice.
|
||||
|
||||
### Download
|
||||
Export as WAV, MP3, or M4A.
|
||||
|
||||
### Delete
|
||||
Remove unwanted generations to free up space.
|
||||
|
||||
### Add to Story
|
||||
Drag generations to the Stories Editor timeline.
|
||||
|
||||
## Search & Filter
|
||||
|
||||
<Tabs>
|
||||
<Tab title="By Text">
|
||||
Search for specific text content
|
||||
```
|
||||
"Hello world"
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="By Voice">
|
||||
Filter by voice profile
|
||||
```
|
||||
Select from dropdown
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="By Date">
|
||||
Filter by date range
|
||||
```
|
||||
Last 7 days, Last 30 days, Custom range
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## Storage
|
||||
|
||||
History is stored locally:
|
||||
|
||||
- **macOS**: `~/Library/Application Support/com.voicebox.app/data/`
|
||||
- **Windows**: `%APPDATA%/com.voicebox.app/data/`
|
||||
- **Linux**: `~/.config/com.voicebox.app/data/`
|
||||
|
||||
<Warning>
|
||||
Deleting the data directory will remove all history. Export important files first.
|
||||
</Warning>
|
||||
@@ -0,0 +1,119 @@
|
||||
---
|
||||
title: "Installation"
|
||||
description: "Download and install Voicebox on macOS, Windows, or Linux"
|
||||
---
|
||||
|
||||
## Download
|
||||
|
||||
Voicebox is available for macOS and Windows, with Linux builds coming soon.
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="macOS" icon="apple">
|
||||
Download for Apple Silicon or Intel Macs
|
||||
</Card>
|
||||
<Card title="Windows" icon="windows">
|
||||
Download MSI installer or Setup executable
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### macOS
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Apple Silicon">
|
||||
Download: [voicebox_aarch64.app.tar.gz](https://github.com/jamiepine/voicebox/releases/latest/download/voicebox_aarch64.app.tar.gz)
|
||||
|
||||
```bash
|
||||
# Extract the archive
|
||||
tar -xzf voicebox_aarch64.app.tar.gz
|
||||
|
||||
# Move to Applications
|
||||
mv Voicebox.app /Applications/
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Intel">
|
||||
Download: [voicebox_x64.app.tar.gz](https://github.com/jamiepine/voicebox/releases/latest/download/voicebox_x64.app.tar.gz)
|
||||
|
||||
```bash
|
||||
# Extract the archive
|
||||
tar -xzf voicebox_x64.app.tar.gz
|
||||
|
||||
# Move to Applications
|
||||
mv Voicebox.app /Applications/
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Windows
|
||||
|
||||
<Tabs>
|
||||
<Tab title="MSI Installer">
|
||||
Download: [voicebox_x64_en-US.msi](https://github.com/jamiepine/voicebox/releases/latest/download/voicebox_x64_en-US.msi)
|
||||
|
||||
Double-click the MSI file and follow the installation wizard.
|
||||
</Tab>
|
||||
<Tab title="Setup Executable">
|
||||
Download: [voicebox_x64-setup.exe](https://github.com/jamiepine/voicebox/releases/latest/download/voicebox_x64-setup.exe)
|
||||
|
||||
Run the executable and follow the installation wizard.
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Linux
|
||||
|
||||
<Note>
|
||||
Linux builds are coming soon. Currently blocked by GitHub runner disk space limitations.
|
||||
</Note>
|
||||
|
||||
## First Launch
|
||||
|
||||
When you launch Voicebox for the first time:
|
||||
|
||||
1. **Model Download** — Qwen3-TTS model (~2-4GB) will download automatically on first use
|
||||
2. **Data Directory** — Voice profiles and generated audio are stored in:
|
||||
- macOS: `~/Library/Application Support/com.voicebox.app/`
|
||||
- Windows: `%APPDATA%/com.voicebox.app/`
|
||||
- Linux: `~/.config/com.voicebox.app/`
|
||||
|
||||
3. **Backend Server** — The bundled Python server starts automatically
|
||||
|
||||
<Tip>
|
||||
First generation will be slower due to model downloads. Subsequent runs use cached models.
|
||||
</Tip>
|
||||
|
||||
## System Requirements
|
||||
|
||||
### Minimum
|
||||
|
||||
- **OS:** macOS 11+, Windows 10+, or Linux
|
||||
- **RAM:** 8GB
|
||||
- **Storage:** 5GB free space (for models and data)
|
||||
- **CPU:** Modern multi-core processor
|
||||
|
||||
### Recommended
|
||||
|
||||
- **RAM:** 16GB+
|
||||
- **GPU:** CUDA-capable NVIDIA GPU (for faster generation)
|
||||
- **Storage:** 10GB+ free space
|
||||
|
||||
<Note>
|
||||
CPU inference is supported but significantly slower than GPU. A CUDA-capable GPU is highly recommended for real-time workflows.
|
||||
</Note>
|
||||
|
||||
## Verification
|
||||
|
||||
After installation, verify everything works:
|
||||
|
||||
1. Launch Voicebox
|
||||
2. Check the server status indicator in the bottom-left corner (should be green)
|
||||
3. Navigate to **Profiles** and create a test profile
|
||||
4. Generate a short audio clip to verify the TTS engine works
|
||||
|
||||
<Check>
|
||||
If you see a green status indicator and can generate audio, you're all set!
|
||||
</Check>
|
||||
|
||||
## Next Steps
|
||||
|
||||
<Card title="Quick Start Guide" icon="rocket" href="/overview/quick-start">
|
||||
Create your first voice profile and generate speech
|
||||
</Card>
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: "Introduction"
|
||||
description: "Welcome to Voicebox - the open-source voice synthesis studio"
|
||||
---
|
||||
|
||||
## What is Voicebox?
|
||||
|
||||
Voicebox is a **local-first voice cloning studio** with DAW-like features for professional voice synthesis. Think of it as the **Ollama for voice** — download models, clone voices, and generate speech entirely on your machine.
|
||||
|
||||
<Frame>
|
||||
<img src="/images/app-screenshot-1.webp" alt="Voicebox App Screenshot" />
|
||||
</Frame>
|
||||
|
||||
Unlike cloud services that lock your voice data behind subscriptions, Voicebox gives you:
|
||||
|
||||
- **Complete privacy** — models and voice data stay on your machine
|
||||
- **Professional tools** — multi-track timeline editor, audio trimming, conversation mixing
|
||||
- **Model flexibility** — currently powered by Qwen3-TTS, with support for XTTS, Bark, and other models coming soon
|
||||
- **API-first** — use the desktop app or integrate voice synthesis into your own projects
|
||||
- **Native performance** — built with Tauri (Rust), not Electron
|
||||
|
||||
Download a voice model, clone any voice from a few seconds of audio, and compose multi-voice projects with studio-grade editing tools. No Python install required, no cloud dependency, no limits.
|
||||
|
||||
## Key Features
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Voice Cloning" icon="microphone">
|
||||
Instant cloning from just a few seconds of audio with Qwen3-TTS
|
||||
</Card>
|
||||
<Card title="Stories Editor" icon="film">
|
||||
Multi-track timeline for creating conversations and narratives
|
||||
</Card>
|
||||
<Card title="Full API" icon="code">
|
||||
REST API for integrating voice synthesis into your apps
|
||||
</Card>
|
||||
<Card title="Local-First" icon="shield">
|
||||
Everything runs on your machine - complete privacy
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Game Development** — Generate dynamic dialogue for characters
|
||||
- **Content Creation** — Produce podcasts and video voiceovers
|
||||
- **Accessibility** — Build text-to-speech tools
|
||||
- **Voice Assistants** — Create custom voice interfaces
|
||||
- **Production Pipelines** — Automate voiceover workflows
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Installation" icon="download" href="/overview/installation">
|
||||
Download and install Voicebox on your machine
|
||||
</Card>
|
||||
<Card title="Quick Start" icon="rocket" href="/overview/quick-start">
|
||||
Get up and running in 5 minutes
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -0,0 +1,17 @@
|
||||
{
|
||||
"title": "Overview",
|
||||
"pages": [
|
||||
"introduction",
|
||||
"installation",
|
||||
"quick-start",
|
||||
"voice-cloning",
|
||||
"stories-editor",
|
||||
"recording-transcription",
|
||||
"generation-history",
|
||||
"remote-mode",
|
||||
"creating-voice-profiles",
|
||||
"generating-speech",
|
||||
"building-stories",
|
||||
"troubleshooting"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,154 @@
|
||||
---
|
||||
title: "Quick Start"
|
||||
description: "Get started with Voicebox in 5 minutes"
|
||||
---
|
||||
|
||||
This guide will walk you through creating your first voice profile and generating speech.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Make sure you have [installed Voicebox](/overview/installation) and launched the app.
|
||||
|
||||
## Step 1: Create a Voice Profile
|
||||
|
||||
Voice profiles are the foundation of Voicebox. Each profile contains voice samples that the AI uses to clone the voice.
|
||||
|
||||
<Steps>
|
||||
<Step title="Navigate to Profiles">
|
||||
Click the **Profiles** tab in the sidebar
|
||||
</Step>
|
||||
|
||||
<Step title="Create New Profile">
|
||||
Click the **+ New Profile** button
|
||||
|
||||
Fill in the details:
|
||||
- **Name:** A descriptive name (e.g., "John Smith")
|
||||
- **Language:** Select the primary language
|
||||
- **Description:** Optional notes about the voice
|
||||
</Step>
|
||||
|
||||
<Step title="Add Voice Sample">
|
||||
You have two options:
|
||||
|
||||
**Option A: Upload Audio**
|
||||
- Click **Upload Sample**
|
||||
- Select an audio file (WAV, MP3, or M4A)
|
||||
- Ideal length: 10-30 seconds of clear speech
|
||||
|
||||
**Option B: Record Live**
|
||||
- Click **Record Sample**
|
||||
- Speak clearly for 10-30 seconds
|
||||
- Click stop when finished
|
||||
</Step>
|
||||
|
||||
<Step title="Save Profile">
|
||||
Click **Create Profile** to save
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
For best results, use clean audio with minimal background noise and consistent speaking tone.
|
||||
</Tip>
|
||||
|
||||
## Step 2: Generate Speech
|
||||
|
||||
Now let's use your new voice profile to generate speech.
|
||||
|
||||
<Steps>
|
||||
<Step title="Go to Generation">
|
||||
Click the **Generate** tab in the sidebar
|
||||
</Step>
|
||||
|
||||
<Step title="Select Voice Profile">
|
||||
Choose your newly created profile from the dropdown
|
||||
</Step>
|
||||
|
||||
<Step title="Enter Text">
|
||||
Type or paste the text you want to generate:
|
||||
|
||||
```
|
||||
Hello! This is my first voice generation with Voicebox.
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Generate">
|
||||
Click **Generate** and wait a few seconds
|
||||
|
||||
<Note>
|
||||
First generation may take longer due to model initialization. Subsequent generations will be faster.
|
||||
</Note>
|
||||
</Step>
|
||||
|
||||
<Step title="Play & Download">
|
||||
- Click **Play** to preview the audio
|
||||
- Click **Download** to save the audio file
|
||||
- The generation is also saved to your **History**
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Step 3: Build a Story (Optional)
|
||||
|
||||
The Stories Editor lets you create multi-voice narratives with a timeline-based interface.
|
||||
|
||||
<Steps>
|
||||
<Step title="Create New Story">
|
||||
Navigate to **Stories** and click **+ New Story**
|
||||
</Step>
|
||||
|
||||
<Step title="Add Voice Tracks">
|
||||
Click **+ Add Track** to create tracks for different speakers
|
||||
</Step>
|
||||
|
||||
<Step title="Add Audio Clips">
|
||||
- Drag generated audio from your History
|
||||
- Or generate new clips directly in the timeline
|
||||
- Arrange clips on the timeline
|
||||
</Step>
|
||||
|
||||
<Step title="Edit & Export">
|
||||
- Trim clips by dragging edges
|
||||
- Adjust timing and spacing
|
||||
- Click **Export** to render the final audio
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## What's Next?
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Voice Cloning Guide" icon="microphone" href="/overview/creating-voice-profiles">
|
||||
Learn advanced techniques for high-quality voice cloning
|
||||
</Card>
|
||||
<Card title="API Integration" icon="code" href="/api/overview">
|
||||
Integrate Voicebox into your own applications
|
||||
</Card>
|
||||
<Card title="Stories Editor" icon="film" href="/overview/stories-editor">
|
||||
Master the multi-track timeline editor
|
||||
</Card>
|
||||
<Card title="Remote Mode" icon="server" href="/overview/remote-mode">
|
||||
Connect to a GPU server for faster generation
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Tips for Success
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Getting the Best Voice Quality">
|
||||
- Use 10-30 seconds of clear, consistent speech
|
||||
- Avoid background noise and echo
|
||||
- Multiple samples from the same speaker improve quality
|
||||
- Match the speaking style you want to generate
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Improving Generation Speed">
|
||||
- Use a CUDA-capable GPU for 5-10x faster generation
|
||||
- Enable voice prompt caching for repeated generations
|
||||
- Consider running the backend on a remote GPU server
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Troubleshooting Common Issues">
|
||||
- **Server won't start:** Check if port 17493 is available
|
||||
- **Poor audio quality:** Try adding more voice samples
|
||||
- **Slow generation:** Verify GPU acceleration is enabled
|
||||
- See the full [Troubleshooting Guide](/overview/troubleshooting) for more
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "Recording & Transcription"
|
||||
description: "Record audio and transcribe speech with Whisper"
|
||||
---
|
||||
|
||||
## Recording
|
||||
|
||||
Voicebox includes built-in recording capabilities for creating voice samples and capturing audio.
|
||||
|
||||
### Features
|
||||
|
||||
- **Microphone input** - Record from any audio input device
|
||||
- **System audio capture** - Record desktop audio (macOS/Windows)
|
||||
- **Waveform visualization** - See audio levels in real-time
|
||||
- **Multiple formats** - Export as WAV, MP3, or M4A
|
||||
|
||||
### How to Record
|
||||
|
||||
<Steps>
|
||||
<Step title="Select Input">
|
||||
Choose your microphone or system audio
|
||||
</Step>
|
||||
<Step title="Start Recording">
|
||||
Click the record button and speak clearly
|
||||
</Step>
|
||||
<Step title="Stop & Save">
|
||||
Click stop when finished
|
||||
</Step>
|
||||
<Step title="Use or Export">
|
||||
Use as voice sample or export to file
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Transcription
|
||||
|
||||
Automatic speech-to-text powered by OpenAI's Whisper model.
|
||||
|
||||
### Features
|
||||
|
||||
- **High accuracy** - Industry-leading speech recognition
|
||||
- **Multiple languages** - Supports 50+ languages
|
||||
- **Automatic detection** - Language auto-detection
|
||||
- **Timestamps** - Word-level timing information
|
||||
|
||||
### How to Transcribe
|
||||
|
||||
<Steps>
|
||||
<Step title="Select Audio">
|
||||
Choose a recording or upload an audio file
|
||||
</Step>
|
||||
<Step title="Choose Language">
|
||||
Select language or use auto-detect
|
||||
</Step>
|
||||
<Step title="Transcribe">
|
||||
Click transcribe and wait for processing
|
||||
</Step>
|
||||
<Step title="Review & Export">
|
||||
Review text and export as needed
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Tip>
|
||||
Transcription is useful for creating voice samples from existing audio or generating subtitles.
|
||||
</Tip>
|
||||
@@ -0,0 +1,138 @@
|
||||
---
|
||||
title: "Remote Mode"
|
||||
description: "Connect to a GPU server for faster generation"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Remote Mode allows you to run the Voicebox backend on a separate machine (like a GPU server) while using the desktop app on your local machine.
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **No local GPU** - Use a cloud GPU or remote workstation
|
||||
- **Faster generation** - Leverage powerful remote hardware
|
||||
- **Shared infrastructure** - Multiple users connect to one server
|
||||
- **Laptop workflows** - Keep your laptop cool and battery-efficient
|
||||
|
||||
## Architecture
|
||||
|
||||
In Remote Mode, the Voicebox desktop app (running on your local machine) communicates with the backend server (running on a remote machine) via HTTP. The local app provides only the user interface, while the remote server handles all the heavy processing including the TTS models, API endpoints, and audio generation.
|
||||
|
||||
## Setting Up Remote Mode
|
||||
|
||||
### On the Server
|
||||
|
||||
<Steps>
|
||||
<Step title="Install Dependencies">
|
||||
```bash
|
||||
# Clone the repo
|
||||
git clone https://github.com/jamiepine/voicebox.git
|
||||
cd voicebox/backend
|
||||
|
||||
# Install Python dependencies
|
||||
pip install -r requirements.txt
|
||||
pip install git+https://github.com/QwenLM/Qwen3-TTS.git
|
||||
```
|
||||
</Step>
|
||||
|
||||
<Step title="Start the Server">
|
||||
```bash
|
||||
# Allow external connections
|
||||
uvicorn main:app --host 0.0.0.0 --port 17493
|
||||
```
|
||||
|
||||
<Warning>
|
||||
This exposes the server to your network. Use a firewall or VPN for security.
|
||||
</Warning>
|
||||
</Step>
|
||||
|
||||
<Step title="Open Firewall">
|
||||
```bash
|
||||
# Ubuntu/Debian
|
||||
sudo ufw allow 17493
|
||||
|
||||
# Or use your cloud provider's firewall settings
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### On the Client
|
||||
|
||||
<Steps>
|
||||
<Step title="Open Settings">
|
||||
In Voicebox, go to **Settings → Server**
|
||||
</Step>
|
||||
|
||||
<Step title="Enable Remote Mode">
|
||||
Toggle **Use Remote Server**
|
||||
</Step>
|
||||
|
||||
<Step title="Enter Server URL">
|
||||
```
|
||||
http://<server-ip>:17493
|
||||
```
|
||||
|
||||
Replace `<server-ip>` with your server's IP address
|
||||
</Step>
|
||||
|
||||
<Step title="Test Connection">
|
||||
Click **Test Connection** to verify
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Cloud Deployment
|
||||
|
||||
### AWS EC2
|
||||
|
||||
```bash
|
||||
# Launch a GPU instance (e.g., g4dn.xlarge)
|
||||
# Install dependencies
|
||||
# Start server with --host 0.0.0.0
|
||||
```
|
||||
|
||||
### Vast.ai
|
||||
|
||||
```bash
|
||||
# Rent a GPU instance
|
||||
# SSH in and clone repo
|
||||
# Start server
|
||||
```
|
||||
|
||||
### RunPod
|
||||
|
||||
```bash
|
||||
# Deploy a pod with CUDA support
|
||||
# Install Voicebox backend
|
||||
# Expose port 17493
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
<Warning>
|
||||
The API currently has no authentication. Only use on trusted networks or with a VPN.
|
||||
</Warning>
|
||||
|
||||
**Best Practices:**
|
||||
- Use a VPN (WireGuard, Tailscale) instead of exposing to the internet
|
||||
- Run behind a reverse proxy with authentication (nginx + basic auth)
|
||||
- Use HTTPS with SSL certificates
|
||||
- Firewall rules to limit access to specific IPs
|
||||
|
||||
## Performance
|
||||
|
||||
Expected performance on various GPUs:
|
||||
|
||||
| GPU | Generation Speed |
|
||||
|-----|------------------|
|
||||
| RTX 4090 | ~2-3s per 10 words |
|
||||
| RTX 3090 | ~3-4s per 10 words |
|
||||
| RTX 3060 | ~5-7s per 10 words |
|
||||
| CPU (12-core) | ~20-30s per 10 words |
|
||||
|
||||
<Tip>
|
||||
A GPU with 8GB+ VRAM is recommended for best performance.
|
||||
</Tip>
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
See the [Troubleshooting Guide](/guides/troubleshooting#remote-mode-issues) for common remote mode issues.
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: "Stories Editor"
|
||||
description: "Create multi-voice narratives with a timeline-based editor"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Stories Editor is a DAW-like timeline interface for creating multi-voice narratives, podcasts, and conversations.
|
||||
|
||||
## Features
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Multi-Track Timeline" icon="timeline">
|
||||
Arrange multiple voice tracks in parallel
|
||||
</Card>
|
||||
<Card title="Inline Editing" icon="scissors">
|
||||
Trim and split clips directly in the timeline
|
||||
</Card>
|
||||
<Card title="Auto-Playback" icon="play">
|
||||
Preview with synchronized playhead
|
||||
</Card>
|
||||
<Card title="Voice Mixing" icon="users">
|
||||
Build conversations with multiple speakers
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
## Creating a Story
|
||||
|
||||
<Steps>
|
||||
<Step title="Create New Story">
|
||||
Navigate to **Stories** and click **+ New Story**
|
||||
</Step>
|
||||
<Step title="Add Tracks">
|
||||
Create separate tracks for each voice/speaker
|
||||
</Step>
|
||||
<Step title="Add Clips">
|
||||
- Drag from generation history
|
||||
- Generate new clips inline
|
||||
- Upload audio files
|
||||
</Step>
|
||||
<Step title="Arrange & Edit">
|
||||
- Position clips on timeline
|
||||
- Trim clip edges
|
||||
- Adjust spacing and timing
|
||||
</Step>
|
||||
<Step title="Export">
|
||||
Render the final mixed audio
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Podcasts**: Multi-host conversations
|
||||
- **Audiobooks**: Narrator + character voices
|
||||
- **Game Dialogue**: Character interactions
|
||||
- **Video Voiceovers**: Multiple speakers
|
||||
- **Audio Drama**: Full voice casts
|
||||
|
||||
## Coming Soon
|
||||
|
||||
- Word-level editing
|
||||
- Crossfades and transitions
|
||||
- Audio effects (reverb, EQ)
|
||||
- Real-time collaboration
|
||||
@@ -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.
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: "Voice Cloning"
|
||||
description: "Clone any voice from just a few seconds of audio"
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Voicebox uses **Qwen3-TTS** from Alibaba to achieve near-perfect voice cloning from just a few seconds of audio. The model captures prosody, emotion, and natural cadence.
|
||||
|
||||
## How It Works
|
||||
|
||||
<Steps>
|
||||
<Step title="Upload or Record Sample">
|
||||
Provide 10-30 seconds of clear speech from the target voice
|
||||
</Step>
|
||||
<Step title="Model Analysis">
|
||||
Qwen3-TTS analyzes vocal characteristics, tone, and speaking patterns
|
||||
</Step>
|
||||
<Step title="Voice Profile Created">
|
||||
The model generates a voice embedding for synthesis
|
||||
</Step>
|
||||
<Step title="Generate Speech">
|
||||
Use the profile to generate any text in the cloned voice
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Sample Quality
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Do" icon="check">
|
||||
- Use 10-30 seconds of audio
|
||||
- Clear, consistent speaking
|
||||
- Minimal background noise
|
||||
- Natural speaking pace
|
||||
</Card>
|
||||
<Card title="Don't" icon="xmark">
|
||||
- Very short clips (< 5 seconds)
|
||||
- Heavy background noise
|
||||
- Music or overlapping voices
|
||||
- Heavily processed audio
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
### Multiple Samples
|
||||
|
||||
Adding multiple samples from the same speaker can improve quality:
|
||||
|
||||
- Different speaking styles (casual, formal)
|
||||
- Different emotions (happy, serious)
|
||||
- Different recording conditions
|
||||
|
||||
<Tip>
|
||||
The model will learn a more robust representation from diverse samples.
|
||||
</Tip>
|
||||
|
||||
## Supported Languages
|
||||
|
||||
Currently supported:
|
||||
- English
|
||||
- Chinese (Mandarin)
|
||||
|
||||
More languages coming soon.
|
||||
|
||||
## Limitations
|
||||
|
||||
<Warning>
|
||||
Voice cloning should only be used with consent. Ensure you have permission to clone someone's voice.
|
||||
</Warning>
|
||||
|
||||
- Quality depends on sample clarity
|
||||
- Works best with consistent speaking tone
|
||||
- May struggle with extreme accents or speech impediments
|
||||
- Background noise reduces quality
|
||||
Reference in New Issue
Block a user