Qwen3-TTS-streaming/QUICKSTART_API.md

# Qwen3-TTS API - Quick Start Guide

Get the API and Gradio demo running in minutes!

## Prerequisites

- Python 3.9+
- CUDA 11.8+ (optional, for GPU acceleration)
- 8GB+ RAM (16GB+ recommended)

## Installation

### 1. Clone and Install

```bash
# Navigate to the repository
cd Qwen3-TTS-streaming

# Install the package with API dependencies
pip install -e .
# Or just the API extras:
pip install -e ".[api]"
```

### 2. Start the API and Demo

**Option A: Using the startup script (Recommended)**
```bash
python start_api.py
```

**Option B: Start services separately**

Terminal 1 - Start API:
```bash
python -m api.main
# or
uvicorn api.main:app --host 0.0.0.0 --port 8000
```

Terminal 2 - Start Gradio Demo:
```bash
python -m api.gradio_demo
```

### 3. Access the Services

- **Gradio Demo**: http://localhost:7860
- **API Server**: http://localhost:8000
- **API Documentation**: http://localhost:8000/docs

## Voice Cloning Setup (Optional)

To use voice cloning, place reference files in `assets/voice_cloning/`:

```bash
# Create reference files
mkdir -p assets/voice_cloning

# Copy or create your reference audio (must be WAV format)
cp your_voice.wav assets/voice_cloning/ref_audio.wav

# Create reference text file with the transcription
echo "Your reference text transcription here..." > assets/voice_cloning/ref_text.txt
```

The API will automatically load these files on startup.

## First Test

### Using the Gradio Demo (Easy)

1. Open http://localhost:7860 in your browser
2. Enter text to synthesize
3. Select language and options
4. Click "Generate Speech 🎵"

### Using cURL (Command Line)

```bash
curl -X POST "http://localhost:8000/v1/audio/speech" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, this is a test.",
    "language": "English"
  }'
```

### Using Python

```python
import requests
import base64
from io import BytesIO
import soundfile as sf

# Make request
response = requests.post(
    "http://localhost:8000/v1/audio/speech",
    json={
        "text": "Hello, world!",
        "language": "English"
    }
)

# Decode and save audio
data = response.json()
audio_bytes = base64.b64decode(data["audio_base64"])
audio, sr = sf.read(BytesIO(audio_bytes))
sf.write("output.wav", audio, sr)
print(f"✅ Saved audio: {data['duration']:.2f}s at {sr} Hz")
```

## API Endpoints

### Health & Models
```
GET /v1/health              # Check API status
GET /v1/models              # List available models
```

### Text-to-Speech
```
POST /v1/audio/speech       # Generate audio
POST /v1/audio/speech/stream # Stream audio (real-time)
```

## Streaming Audio

The streaming endpoint returns WAV frames with length prefixes for real-time audio:

```python
import requests

response = requests.post(
    "http://localhost:8000/v1/audio/speech/stream",
    json={
        "text": "This is a streaming test.",
        "language": "English",
        "stream_options": {
            "emit_every_frames": 8,
            "decode_window_frames": 80,
            "overlap_samples": 512
        }
    },
    stream=True
)

# Process streaming chunks
for chunk in response.iter_content(chunk_size=65536):
    # Parse: [frame_length: 4 bytes][frame_data: frame_length bytes]
    frame_len = int.from_bytes(chunk[:4], byteorder='big')
    frame_data = chunk[4:4 + frame_len]
    # Play or process frame_data...
```

## Voice Cloning Usage

Once reference files are in `assets/voice_cloning/`:

```python
response = requests.post(
    "http://localhost:8000/v1/audio/speech",
    json={
        "text": "New text in cloned voice",
        "language": "English",
        "voice_clone_mode": "reference_audio"  # Enable voice cloning
    }
)
```

## Supported Languages

- English
- Russian
- Chinese (Simplified)
- Japanese
- Korean
- Auto (automatic detection)

## Performance Tips

### GPU Usage
The API automatically uses CUDA if available:
- Monitor GPU: `nvidia-smi`
- Requires: CUDA 11.8+ and cuDNN

### Faster Streaming
Adjust streaming options:
```python
"stream_options": {
    "emit_every_frames": 4,      # Lower = faster first chunk
    "decode_window_frames": 40,  # Lower = faster, less quality
    "overlap_samples": 512
}
```

### Lower Memory Usage
```bash
# Use CPU only
python start_api.py --device cpu

# Or manually in code (api/main.py):
model_state.device = "cpu"
```

## Troubleshooting

### API won't start
```
ModuleNotFoundError: No module named 'fastapi'
→ pip install fastapi uvicorn
```

### GPU out of memory
```
CUDA out of memory
→ Use CPU: python start_api.py --device cpu
→ Or reduce batch size/model size
```

### Voice cloning not working
```
→ Check files exist: assets/voice_cloning/ref_audio.wav
→ Check files exist: assets/voice_cloning/ref_text.txt
→ Ensure ref_text matches the audio content
→ Check API logs for error details
```

### Slow first response
```
→ First request loads model (~30-60 seconds)
→ Subsequent requests are fast (2-5 seconds)
→ Streaming gives first chunk in ~1-2 seconds
```

## Interactive Documentation

Visit `http://localhost:8000/docs` for:
- **Swagger UI**: Full API documentation with "Try it out"
- **ReDoc**: Alternative documentation view
- **API schema**: OpenAPI 3.0.2 specification

## Next Steps

1. **Integrate with your app**
   - Use the Python client code above
   - Or use any HTTP client in your language

2. **Deploy to production**
   - Use Gunicorn: `gunicorn -w 4 api.main:app`
   - Or Docker (guidelines in main API README)

3. **Customize the API**
   - Edit `api/models.py` for request/response schemas
   - Edit `api/main.py` for endpoint logic
   - Add more models to `api/models.py` enum

## More Information

- **API Documentation**: See `api/README.md`
- **Voice Cloning Setup**: See `assets/voice_cloning/README.md`
- **Examples**: Check `examples/` directory

## Support

For issues or questions:
1. Check logs in the terminal
2. Visit `/docs` endpoint for API details
3. Review the comprehensive `api/README.md`
4. Check `assets/voice_cloning/README.md` for voice cloning issues

---

**Happy synthesizing! 🎵**