README.md

---
title: Matcha TTS API
emoji: 🗣️
colorFrom: blue
colorTo: red
sdk: docker
app_port: 7860
pinned: false
---

# Matcha TTS Space

A Hugging Face Space deployment of **Matcha-TTS** for fast, high-quality text-to-speech synthesis on CPU Basic.

## Features

- **Fast**: Real-time factor (RTF) ~0.1-0.15 on CPU Basic
- **High Quality**: Natural-sounding speech with good prosody
- **Simple API**: REST endpoint for TTS synthesis
- **CPU Optimized**: Uses ONNX runtime for efficient inference
- **Configurable**: Supports different Matcha-TTS models via environment variable

## API Endpoints

### POST `/tts`
Synthesize speech from text.

**Request Body:**
```json
{
  "text": "Hello world",
  "language": "en",
  "speaker_id": 0,
  "noise_scale": 0.667,
  "noise_scale_w": 0.8,
  "length_scale": 1.0
}
```

**Returns:** WAV audio file (24kHz, 16-bit PCM)

### GET `/health`
Health check endpoint.

### GET `/`
API information and usage example.

## Usage Example (curl)

```bash
curl -X POST "https://your-username-your-space.hf.space/tts" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello, this is Matcha TTS!"}' \
  -o output.wav
```

## Model

Default: `matcha-tts/matcha-v1.0` (English)

To use a different model, set the `MATCHA_MODEL` environment variable in Space Settings.

## Performance

On Hugging Face CPU Basic:
- Startup time: ~10-15 seconds (model loading)
- Synthesis RTF: ~0.1-0.15 (1 second of audio in 100-150ms)
- Concurrent requests: Limited by CPU, recommend sequential processing

## Deployment

This Space is built from:
- `Dockerfile`: Container definition
- `requirements.txt`: Python dependencies
- `main.py`: FastAPI application

Built and deployed automatically on pushes to the main branch.