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