README.md

metadata

title: Pocket TTS
emoji: 🎤
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false

PocketTTS OpenAI-Compatible Server

An OpenAI-compatible Text-to-Speech API server powered by Pocket-TTS. Drop-in replacement for OpenAI's TTS API with support for streaming, custom voices, and voice cloning.

Tested and working fully with WingmanAI by Shipbit. Due to low resource use, can be used for real time local text to speech even while playing intensive video games (even in VR!) with WingmanAI.

Key Features:

• 🎯 OpenAI API Compatible - Works with any OpenAI TTS client
• 🚀 Real-time Streaming - Low-latency audio generation
• 🎤 150+ Community Voices - Ready-to-use voice library included
• 🎭 Voice Cloning - Clone any voice from a short audio sample
• 🐳 Docker Ready - One-command deployment
• 💻 Cross-platform - Runs on Windows, macOS, and Linux
• ⚡ CPU Optimized - No GPU required
• 🎤 Text pre-processing - Clean text for words and symbols TTS usually has difficulty with, automatically

Quick Start

Option 1: Docker (Recommended)

# Clone the repository
git clone https://github.com/teddybear082/pocket-tts-openai_streaming_server.git
cd pocket-tts-openai_streaming_server

# Start the server
docker compose up -d

# View logs
docker compose logs -f

The server will be available at http://localhost:49112

Custom Configuration:

# Change port
POCKET_TTS_PORT=8080 docker compose up -d

# Use custom voices directory
POCKET_TTS_VOICES_DIR=/path/to/my/voices docker compose up -d

Option 2: Python (from source)

# Clone the repository
git clone https://github.com/teddybear082/pocket-tts-openai_streaming_server.git
cd pocket-tts-openai_streaming_server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Start the server
python server.py

Command Line Options:

python server.py --help

# Custom port and voices
python server.py --port 8080 --voices-dir ./my_voices

# Enable streaming by default
python server.py --stream

# Enable text preprocessing
python server.py --text-preprocess

Option 3: Windows Executable

1. Download the latest release from Releases
2. Extract the ZIP file
3. Double-click PocketTTS-Server.exe to run with defaults
4. Or run run_pocket_tts_server_exe.bat for custom configuration

Web Interface

Open http://localhost:49112 in your browser to access the built-in web UI:

• Select from available voices
• Enter text to synthesize
• Listen to generated audio directly

API Usage

Generate Speech

Endpoint: POST /v1/audio/speech

curl http://localhost:49112/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "Hello world! This is a test.",
    "voice": "alba"
  }' \
  --output speech.mp3

Python Client

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:49112/v1",
    api_key="not-needed"  # No authentication required
)

# Generate and save audio
response = client.audio.speech.create(
    model="tts-1",
    voice="alba",
    input="Hello world! This is a test."
)
response.stream_to_file("output.mp3")

# Streaming
with client.audio.speech.with_streaming_response.create(
    model="tts-1",
    voice="alba",
    input="This is streaming audio.",
    response_format="pcm"
) as response:
    for chunk in response.iter_bytes():
        # Process audio chunks in real-time
        pass

API Reference

Endpoint	Method	Description
/	GET	Web interface
/health	GET	Health check for container orchestration
/v1/voices	GET	List available voices
/v1/audio/speech	POST	Generate speech audio

Speech Parameters:

Parameter	Type	Required	Default	Description
model	string	No	-	Ignored (for OpenAI compatibility)
input	string	Yes	-	Text to synthesize
voice	string	No	alba	Voice ID (see /v1/voices)
response_format	string	No	mp3	Output format: mp3, wav, pcm, opus, aac, flac
stream	boolean	No	false	Enable streaming response

Custom Voices

Using Custom Voice Files

1. Create a voices directory with your audio files (.wav, .mp3, .flac)

2. Configure the server to use your directory:

   Docker:

   POCKET_TTS_VOICES_DIR=/path/to/voices docker compose up -d
   

   Python:

   python server.py --voices-dir /path/to/voices
   

   Windows EXE: Use the batch launcher and specify the voices directory when prompted.

3. Use your voice by filename:

   { "voice": "my_voice.wav", "input": "Hello!" }
   

Voice File Guidelines

• Duration: 3-15 seconds of clear speech works best
• Quality: Clean audio without background noise
• Format: WAV, MP3, or FLAC
• Tip: Use Adobe Podcast Enhance to clean noisy samples

Built-in Voices

The following voices are available by default: alba, marius, javert, jean, fantine, cosette, eponine, azelma

The voices/ directory includes 150+ community-contributed voices.

Configuration

Environment Variables

Variable	Default	Description
POCKET_TTS_HOST	0.0.0.0	Server bind address
POCKET_TTS_PORT	49112	Server port
POCKET_TTS_VOICES_DIR	./voices	Custom voices directory
POCKET_TTS_MODEL_PATH	-	Custom model path
POCKET_TTS_STREAM_DEFAULT	true	Enable streaming by default
POCKET_TTS_TEXT_PREPROCESS_DEFAULT	true	Enable text preprocessing by default
POCKET_TTS_LOG_LEVEL	INFO	Log level: DEBUG, INFO, WARNING, ERROR
POCKET_TTS_LOG_DIR	./logs	Log files directory
HF_TOKEN	-	Hugging Face token (for voice cloning)

Docker Compose Options

See docker-compose.yml for all available options including:

• Volume mounts for custom voices
• Resource limits
• Health check configuration
• HuggingFace cache persistence

Project Structure

pocket-tts-openai_streaming_server/
├── app/                    # Application modules
│   ├── __init__.py        # Flask app factory
│   ├── config.py          # Configuration management
│   ├── logging_config.py  # Logging setup
│   ├── routes.py          # API endpoints
│   └── services/          # Business logic
│       ├── audio.py       # Audio conversion
│       └── tts.py         # TTS service
|       |-- preprocess.py  # Text preprocessor
├── static/                 # Web UI assets
├── templates/              # HTML templates
├── voices/                 # Voice files
├── server.py              # Main entry point
├── Dockerfile             # Container build
├── docker-compose.yml     # Container orchestration
└── requirements.txt       # Python dependencies

Development

Dependencies

File	Purpose
requirements.txt	Runtime dependencies only (Flask, torch, pocket-tts)
requirements-dev.txt	Adds dev tools: ruff (linting), pytest (testing)

Running Locally

# Install runtime dependencies only
pip install -r requirements.txt

# Or install with dev tools (recommended for contributors)
pip install -r requirements-dev.txt

# Run with debug logging
python server.py --log-level DEBUG

Linting

pip install ruff
ruff check .
ruff format .

Building Windows EXE

pip install pyinstaller
pyinstaller --onefile --name PocketTTS-Server \
  --add-data "static;static" \
  --add-data "templates;templates" \
  --add-data "voices;voices" \
  --add-data "app;app" \
  server.py

Troubleshooting

Model Loading Takes Long

First run downloads the model (~500MB). Subsequent runs use cached model.

Docker: Model cache is persisted in a Docker volume.

Voice Cloning Requires HF Token

For voice cloning, you may need a Hugging Face token:

1. Get token from https://huggingface.co/settings/tokens
2. Set HF_TOKEN environment variable

Port Already in Use

# Use a different port
python server.py --port 8080

# Or with Docker
POCKET_TTS_PORT=8080 docker compose up -d

Credits

• Pocket-TTS by Kyutai Labs
• Community voice contributors (see voices/credits.txt)

License

This project is licensed under the MIT License - see LICENSE for details.

Pocket-TTS is subject to its own license terms.