speaker_helper.api module

REST API server for speaker-helper.

Module summary

A thin FastAPI façade over Speaker, suitable for running as a Docker service. It exposes:

  • GET  /health — liveness plus the upstream engine health.

  • GET  /voices — preset voices for the configured (or requested) engine.

  • POST /synth — synthesise {"text": ..., "language": ...} and return a audio/wav body (offline: whole text in one response).

  • POST /synth/stream — same body, but stream Server-Sent Events, one per sentence-sized chunk, as soon as each is ready (low time-to-first-audio). Each event’s data is JSON with seq, duration_s, rtf, ttfa_s (first chunk only), is_final, and base64 audio (WAV).

  • POST /clone — multipart upload of reference audio (plus optional transcripts) to clone a voice; missing transcripts come from vocal-helper. The clone becomes the server’s active voice for subsequent /synth calls.

When fastapi-mcp is installed, a Model Context Protocol server is also mounted at /mcp, exposing these endpoints as MCP tools so an assistant can synthesise, stream, clone, and list voices directly.

This module imports FastAPI/pydantic/uvicorn at import time, so it is only ever imported behind the server extra (the CLI imports it lazily, and the core package never imports it). Keeping the request model at module scope lets FastAPI correctly resolve it as a request body rather than query params.

Usage example

speaker-helper serve --host 0.0.0.0 --port 8080
curl -s -X POST localhost:8080/synth -H 'content-type: application/json' \
     -d '{"text": "Bonjour."}' -o out.wav

Author

Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui

class speaker_helper.api.RouteRequestBody(*, condition, language='fr', rtf_ceiling=0.8, rtf_budget=None, quality_floor=None)[source]

Bases: BaseModel

Request body for POST /route.

Parameters:

  • condition (str) – "online_realtime" (delay-bounded streaming) or "offline" (quality-only batch).

  • language (str) – ISO-639-1 target language driving the candidate catalogue.

  • rtf_ceiling (float) – Online only: the mean_rtf an engine must beat to keep up (default 0.8).

  • rtf_budget (float or None) – Offline only: optional patience cap on mean_rtf.

  • quality_floor (float or None) – Reject candidates below this quality in either condition.

condition: str
language: str
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

quality_floor: float | None
rtf_budget: float | None
rtf_ceiling: float
class speaker_helper.api.SynthRequest(*, text, language=None)[source]

Bases: BaseModel

Request body for POST /synth.

Parameters:

  • text (str) – Text to synthesise (non-empty).

  • language (str or None) – Optional override of the configured target language.

language: str | None
model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

text: str
speaker_helper.api.create_app(settings=None, *, enable_mcp=True)[source]

Build the FastAPI application.

Parameters:

  • settings (Settings or None) – Configuration; defaults to Settings.load().

  • enable_mcp (bool) – When True (default) and fastapi-mcp is installed, mount a Model Context Protocol server at /mcp that exposes the REST endpoints as MCP tools — so an MCP client (an assistant) can synthesise, clone, and list voices directly. Silently skipped if fastapi-mcp is absent.

Returns:

The configured application. A single shared Speaker is created at startup and closed at shutdown.

Return type:

fastapi.FastAPI

speaker_helper.api.serve(settings=None, *, host='127.0.0.1', port=8080)[source]

Run the API server with uvicorn (blocking).

Parameters:

  • settings (Settings or None) – Configuration; defaults to Settings.load().

  • host (str) – Bind address.

  • port (int) – Bind port.

Return type:

None