Kokoro TTS Flask Wrapper

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

Setup

1. Install the kokoro-tts tool:

   uv tool install kokoro-tts
   

2. Install Python dependencies:

   pip install -r requirements.txt
   

3. 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
   

4. 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.