Kokoro TTS Flask Wrapper

A simple Flask server that wraps the kokoro TTS functionality to convert text to speech asynchronously.

Setup

Install the kokoro-tts tool:
```
uv tool install kokoro-tts
```
Install Python dependencies:
```
pip install -r requirements.txt
```

For full audio merging functionality (recommended for production), install sox:

# On macOS
brew install sox

# On Ubuntu/Debian
sudo apt-get install sox

# On CentOS/RHEL/Fedora
sudo yum install sox

Run the server:
```
python app.py
```

Usage

Text-to-Speech Endpoint

POST /tts

Convert text to speech using kokoro with speaker-specific voice assignments.

Request Body (JSON)

{
  "text": "Alex: Hello world\nJamie: This is a test",
  "title": "conversation"
}

The text should follow the format:

<Speaker Name>: <Speech text>

For each unique speaker name, the system will match them to a certain voice and reuse that voice during the entire exchange.

Response

{
  "file_path": "/path/to/output/conversation.wav",
  "message": "Audio generation completed successfully"
}

Features

Speaker-specific voice assignment: Each speaker gets assigned a unique voice (bm_fable, bm_lewis, or bm_george) and that voice is reused throughout their contribution
Asynchronous audio generation (doesn't block the HTTP request)
Random voice selection for each speaker
Audio merging functionality: Combines multiple speaker audio files into a single output file using sox
Health check endpoint
Secure filename handling

Environment Variables

OUTPUT_DIR: Directory to store generated audio files (default: "output")
PORT: Port to run the Flask server on (default: 5010)
TTS_COMMAND: Command to execute for TTS (default: "kokoro-tts")

Audio Merging Implementation

The system supports merging multiple WAV files into a single output file. In production environments with sox installed, audio files are properly concatenated using the sox command-line utility. For systems without sox or with limited dependencies, the implementation provides a fallback that uses the last generated audio file as the output.

Example Usage

curl -X POST http://localhost:5010/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "Alex: Hello world\nJamie: This is a test", "title": "sample"}'

This will generate a WAV file with both speakers using their assigned voices.

2.5 KiB Raw Permalink Blame History