S4daharu/Kokoro-TTS

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

API

This Space exposes stable Gradio API endpoints designed to work well with audioreader (VoxBook).

1. 1./generate
2. 2.Inputs: text, voice, speed, format (optional: wav (default), mp3, opus)
3. 3.Outputs: audio file, JSON metadata
4. 4.Notes:
5. 5.Rejects empty input and text longer than 4000 chars.
6. 6.Automatically sanitizes control characters to prevent model crashes.

1. 1./generate_batch
2. 2.Inputs: texts (JSON array), voice, speed, format
3. 3.Outputs: list of audio files, JSON metadata
4. 4.Notes:
5. 5.Graceful Failures: If a single text chunk fails, the endpoint no longer crashes the entire batch. Instead, the metadata includes an errors array ([{"index": i, "error": "msg"}]) and returns None for failed audio slots.

1. 1./generate_stream [NEW]
2. 2.Inputs: text, voice, speed
3. 3.Outputs: Stream of raw WAV files (yielded sequentially per sentence)
4. 4.Notes: Drops Time-To-First-Byte (TTFB) to near zero, perfect for real-time playback.

1. 1./manifest [NEW]
2. 2.Inputs: text, voice, speed
3. 3.Outputs: JSON array of phoneme boundaries mapping sentence indices to exact phoneme_count, char_start, and char_end.
4. 4.Notes: Useful for precision UI text highlighting.

1. 1./voices and /previews/{voice_id}.wav
2. 2.GET /voices: Returns JSON dictionary of all loaded voices and their metadata.
3. 3.GET /previews/{voice_id}.wav: Returns a static HTTP audio file preview of the requested voice.

1. 1./health & /metrics
2. 2.GET /health: Returns runtime metadata (status, cache limits, voice counts) useful for client restart-detection.
3. 3.GET /metrics: Exposes Prometheus-style plaintext metrics (kokoro_cache_hit_total, kokoro_generate_latency_seconds_sum, kokoro_queue_depth).

Performance & Resilience

• —Rate Limiting: Enforces a token-bucket rate limit (10 requests + 10/min) keyed on the Authorization: Bearer hf_... token to prevent abuse.
• —Bandwidth Optimization: Requesting format="opus" or format="mp3" dramatically reduces network payload size (up to 90%) at a marginal latency cost.
• —Caching: Generated audio is cached on disk by normalized text + voice + speed + format. Bounded by LRU size/count limits.
• —Lazy Loading: Voice packs load lazily on first use and stay cached in memory.

audioreader (VoxBook) Compatibility

• —SSE Protocol: Uses /gradio_api/call/generate (and _batch, _stream) via Server-Sent Events (SSE) protocol.
• —Streaming Mode: The client connects to _stream and uses a ConcatenatingAudioSource to pipe raw PCM into playback instantly.
• —Audio Formats: MP3/Opus formats are actively used by the client's Settings to minimize offline download storage footprint.
• —Authentication: A huggingface token (e.g. hf_...) is strictly required.