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.

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.NarrateRequest(*, segments, language=None, voice=None, read_math=None)[source]

Bases: BaseModel

Request body for POST /narrate.

Parameters:

  • segments (list) – The document’s blocks. Each is an object with text and optionally say (what to pronounce, when it differs from what the page shows), pause_before_ms, pause_after_ms, pace and emotion. Plain strings are accepted for the simple case.

  • language (str or None) – Override the configured target language.

  • voice (str or None) – Override the configured voice.

  • read_math (str or None) – Language in which to speak any notation the blocks contain. The cues keep the page’s own text either way — that is the point of the pair.

language: str | None
model_config = {}

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

read_math: str | None
segments: list
voice: str | None
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)[source]

Build the FastAPI application.

Parameters:

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

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