speaker_helper.types module

Typed data structures exchanged across speaker-helper’s public surface.

Module summary

speaker-helper turns text into speech through the Voicebox engine. The values that cross its API boundaries are described here as dataclasses so callers never guess dictionary shapes and editors can autocomplete. Audio is carried as an in-memory bytes WAV payload plus the metadata a caller needs to save, stream, or measure it (sample rate, duration, real-time factor).

Usage example

>>> from speaker_helper.types import Voice
>>> v = Voice(voice_id="ff_siwis", name="Siwis", language="fr", gender="female")
>>> v.language
'fr'

Author

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

class speaker_helper.types.AudioResult(wav_bytes, sample_rate, duration_s, compute_s, text, voice_id, language)[source]

Bases: object

A synthesised audio payload and its measured metadata.

Parameters:

  • wav_bytes (bytes) – The complete WAV file contents (RIFF header + PCM), ready to write to disk or stream to a client.

  • sample_rate (int) – Sample rate of the audio in Hz.

  • duration_s (float) – Audio duration in seconds.

  • compute_s (float) – Wall-clock seconds spent producing this audio (network + synthesis).

  • text (str) – The text that was synthesised.

  • voice_id (str) – The voice used.

  • language (str) – The language used.

Notes

rtf (real-time factor) is derived, not stored: compute_s / duration_s. A value below 1.0 means synthesis was faster than real time — the operating point speaker-helper aims for.

compute_s: float
duration_s: float
language: str
property rtf: float

Real-time factor compute_s / duration_s (inf if silent).

Returns:

Below 1.0 means faster than real time.

Return type:

float

sample_rate: int
text: str
voice_id: str
wav_bytes: bytes
class speaker_helper.types.StreamChunk(seq, audio, ttfa_s=None, is_final=False)[source]

Bases: object

One chunk of a streaming synthesis (one sentence-sized unit).

Parameters:

  • seq (int) – Zero-based index of this chunk within the stream.

  • audio (AudioResult) – The synthesised audio for this chunk.

  • ttfa_s (float | None) – Time-to-first-audio in seconds, set only on the first chunk (seq == 0); None afterwards.

  • is_final (bool) – True for the last chunk of the stream.

audio: AudioResult
is_final: bool = False
seq: int
ttfa_s: float | None = None
class speaker_helper.types.Voice(voice_id, name, language, gender='', engine='')[source]

Bases: object

A preset voice offered by a Voicebox engine.

Parameters:

  • voice_id (str) – Engine-specific identifier (e.g. "ff_siwis" for kokoro French).

  • name (str) – Human-readable display name.

  • language (str) – ISO-639-1 language code the voice speaks (e.g. "fr", "en").

  • gender (str) – Reported voice gender, or "" when the engine does not expose one.

  • engine (str) – Engine the voice belongs to (e.g. "kokoro").

engine: str = ''
gender: str = ''
language: str
name: str
voice_id: str
class speaker_helper.types.VoiceList(engine, voices=<factory>)[source]

Bases: object

Voices available for an engine.

Parameters:

  • engine (str) – The engine the voices belong to.

  • voices (list[Voice]) – The preset voices, possibly empty.

engine: str
voices: list[Voice]
class speaker_helper.types.VoiceSample(audio, reference_text)[source]

Bases: object

One reference recording used to clone a voice.

Parameters:

  • audio (bytes or str) – The reference audio: raw bytes, or a filesystem path to an audio file.

  • reference_text (str) – A transcript of exactly what is said in audio. Cloning engines align the audio to this text, so it must match the recording.

Notes

Keep samples short and clean (a few seconds of clear speech). Provide several for a more robust clone.

audio: bytes | str
filename()[source]

Return a filename to send with the upload (from the path, or a default).

Return type:

str

read_bytes()[source]

Return the audio as bytes, reading from disk if a path was given.

Return type:

bytes

reference_text: str