A lightweight, CPU-optimized Text-to-Speech (TTS) API service combining Kokoro-82M (advanced TTS synthesis) with Gentle (precise audio alignment) for professional-grade speech generation and synchronization.
简体中文文档 | English
- Multi-language Support: Supports multiple languages including English and Chinese
- Multiple Voice Options: Various voice profiles (e.g.,
af_heart) for diverse speech synthesis - Speed Control: Adjustable speech speed parameter for customized output
- Audio Alignment: Optional integration with Gentle for precise word-level timing alignment
- CPU-Only Optimization: Designed to run efficiently on CPU-only environments
- Docker Support: Complete Docker and Docker Compose setup for easy deployment
- Base64 Audio Output: Audio returned as base64-encoded data for easy integration
- CORS Enabled: Cross-Origin Resource Sharing enabled for web applications
- FastAPI Framework: Modern, fast, and easy-to-use REST API
- Python 3.11+
- Docker & Docker Compose (for containerized deployment)
- 4GB+ RAM (recommended for smooth CPU operation)
docker-compose up -dThis will start:
- Kokoro TTS API on
http://localhost:8000 - Gentle Audio Alignment Service on
http://localhost:8765
- Install dependencies:
pip install -r requirements.txt-
(Optional) Install and run Gentle for audio alignment:
Using Docker:
docker run -d -p 8765:8765 lowerquality/gentle
Or manually:
- Clone the Gentle repository:
git clone https://github.com/lowerquality/gentle.git - Follow the installation instructions in the Gentle repository
- Run Gentle on port 8765
- Clone the Gentle repository:
-
Run the API:
uvicorn tts_api:app --host 0.0.0.0 --port 8000If Gentle is not running, the API will still work but audio alignment (align: true) will fail.
Returns service information and usage instructions.
Response:
{
"message": "Kokoro-82M TTS API is running",
"gentle_url": "http://gentle:8765/transcriptions?async=false",
"usage": "POST /tts with JSON: {text, voice, speed, lang}"
}Synthesizes text to speech.
Request Body:
{
"text": "Hello, this is a test.",
"voice": "af_heart",
"speed": 1.0,
"lang": "a",
"align": false
}Parameters:
text(string, required): The text to synthesizevoice(string, optional): Voice profile name. Default:"af_heart"speed(float, optional): Speech speed multiplier. Default:1.0lang(string, optional): Language code. Default:"a"(English). Use"z"for Chinesealign(boolean, optional): Enable audio alignment with Gentle. Default:false
Response:
{
"audio_base64": "UklGRi4A...",
"align_data": {
"words": [...],
"transcript": "Hello, this is a test."
}
}GENTLE_URL: URL of the Gentle alignment service. Default:http://gentle:8765/transcriptions?async=falseLANG_CODE: Default language code. Default:"a"(English)
"a": English"z": Chinese- Other language codes may be supported by the Kokoro model
KoGen/
├── tts_api.py # Main FastAPI application
├── Dockerfile.cpu # CPU-optimized Docker image
├── docker-compose.yml # Docker Compose configuration
├── requirements.txt # Python dependencies
├── cache/ # Model cache directory
└── data/ # Output audio and logs directory
- Format: WAV
- Sample Rate: 24000 Hz
- Encoding: Base64 (in JSON response)
- Multiple Segments: Automatically merged into a single audio file
When align: true is set, the API:
- Generates audio using Kokoro TTS
- Sends the audio to Gentle for word-level alignment
- Returns both the audio and alignment data with precise timing information
This is useful for:
- Subtitle generation
- Karaoke applications
- Precise audio-text synchronization
- Base image:
python:3.11-slim - Includes: espeak-ng, libsndfile1, ffmpeg, and other audio processing tools
- Pre-loads Kokoro model during build to reduce first-run latency
- Exposes port 8000
- kokoro: TTS API service (port 8000)
- gentle: Audio alignment service (port 8765)
curl -X POST http://localhost:8000/tts \
-H "Content-Type: application/json" \
-d '{
"text": "Hello world",
"voice": "af_heart",
"speed": 1.0,
"lang": "a",
"align": false
}'import requests
import base64
response = requests.post('http://localhost:8000/tts', json={
'text': 'Hello world',
'voice': 'af_heart',
'speed': 1.0,
'lang': 'a',
'align': False
})
data = response.json()
audio_bytes = base64.b64decode(data['audio_base64'])
# Save to file
with open('output.wav', 'wb') as f:
f.write(audio_bytes)- Ensure sufficient disk space for model cache (~2GB)
- Check that
/root/.cache/huggingfaceis properly mounted in Docker
- Verify the language code matches your input text
- Adjust the
speedparameter if audio sounds distorted - Ensure the voice profile is valid for the selected language
- Verify Gentle service is running and accessible
- Check that the transcript matches the generated audio closely
- Ensure audio quality is sufficient for alignment
This project uses the Kokoro TTS model. Please refer to the model's license for usage terms.
Contributions are welcome! Please feel free to submit issues and pull requests.
For issues and questions, please open an issue on the project repository.