94 lines
2.5 KiB
Markdown
94 lines
2.5 KiB
Markdown
# 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:
|
|
```bash
|
|
uv tool install kokoro-tts
|
|
```
|
|
|
|
2. Install Python dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. For full audio merging functionality (recommended for production), install sox:
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Text-to-Speech Endpoint
|
|
|
|
**POST /tts**
|
|
|
|
Convert text to speech using kokoro with speaker-specific voice assignments.
|
|
|
|
#### Request Body (JSON)
|
|
|
|
```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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```bash
|
|
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. |