README.md

metadata

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:

{
  "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)

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.