speaker_helper.types module

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

Module summary

speaker-helper turns text into speech. 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
write_audio(path, *, bitrate='64k')[source]

Write the audio to path; the extension picks the container.

See write_audio() for the rules. Prefer this over writing wav_bytes by hand: the extension is then honoured instead of being a label on a WAV file.

Parameters:
Return type:

Path

speaker_helper.types.DEFAULT_SPEECH_BITRATE = '64k'

Default bitrate when audio is written to a lossy container. Speech at 64 kb/s mono is the rate this suite ships narrations at, and it is a deliberate opinion rather than a passthrough. audio-helper carries the input’s bitrate over when asked for nothing, which is right for a conversion but says nothing here: what this package hands over is always an uncompressed WAV, so there is no bitrate to carry, and the fallback is ffmpeg’s own choice of 32 kb/s for a 24 kHz mono stream, audibly worse for a voice. audio-helper is the generic signal brick and rightly holds no opinion about speech; this one is the speech brick, so it holds one.

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 backend.

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
speaker_helper.types.write_audio(wav_bytes, path, *, bitrate='64k')[source]

Write a WAV payload to path, encoding it if path is not a WAV.

Parameters:
  • wav_bytes (bytes) – A complete WAV file (RIFF header + PCM), as every result object here carries it.

  • path (str or pathlib.Path) – Where to write. The extension decides the container: .wav writes the bytes untouched, anything else (.mp3, .m4a, .ogg) is encoded by audio-helper.

  • bitrate (str or int or None, optional) – Bitrate for a lossy container: bits per second (64000) or an ffmpeg-style string ("64k"). Defaults to DEFAULT_SPEECH_BITRATE. None hands the choice down to audio-helper, which carries the input’s bitrate over; the payload here is always an uncompressed WAV, so nothing is carried and ffmpeg decides. Meaningless for a WAV target, where it is ignored.

Returns:

The path written.

Return type:

pathlib.Path

Raises:

RuntimeError – If a lossy container is asked for and audio-helper is missing.

Notes

Callers used to write result.wav_bytes to whatever name they were given, so -o out.mp3 produced a WAV file wearing an MP3 extension, and anyone who genuinely wanted an MP3 reached for ffmpeg themselves. The encoding is not this package’s craft: it belongs to audio-helper, and is called here rather than reimplemented. audio-helper is imported lazily so the WAV path, which is most of them, pays nothing for it.

The sample rate and channel count are read from the payload’s own RIFF header rather than taken from a neighbouring field, so the conversion cannot disagree with the audio it is converting.