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'
- class speaker_helper.types.AudioResult(wav_bytes, sample_rate, duration_s, compute_s, text, voice_id, language)[source]
Bases:
objectA 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 below1.0means synthesis was faster than real time — the operating point speaker-helper aims for.- property rtf: float
Real-time factor
compute_s / duration_s(infif silent).- Returns:
Below
1.0means faster than real time.- Return type:
- 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 writingwav_bytesby hand: the extension is then honoured instead of being a label on a WAV file.
- 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-helpercarries 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-helperis 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:
objectOne 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);Noneafterwards.is_final (bool) –
Truefor the last chunk of the stream.
- audio: AudioResult
- class speaker_helper.types.Voice(voice_id, name, language, gender='', engine='')[source]
Bases:
objectA 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").
- class speaker_helper.types.VoiceList(engine, voices=<factory>)[source]
Bases:
objectVoices available for an engine.
- Parameters:
- class speaker_helper.types.VoiceSample(audio, reference_text)[source]
Bases:
objectOne reference recording used to clone a voice.
- Parameters:
Notes
Keep samples short and clean (a few seconds of clear speech). Provide several for a more robust clone.
- filename()[source]
Return a filename to send with the upload (from the path, or a default).
- Return type:
- speaker_helper.types.write_audio(wav_bytes, path, *, bitrate='64k')[source]
Write a WAV payload to
path, encoding it ifpathis 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:
.wavwrites the bytes untouched, anything else (.mp3,.m4a,.ogg) is encoded byaudio-helper.bitrate (str or int or None, optional) – Bitrate for a lossy container: bits per second (
64000) or an ffmpeg-style string ("64k"). Defaults toDEFAULT_SPEECH_BITRATE. None hands the choice down toaudio-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:
- Raises:
RuntimeError – If a lossy container is asked for and
audio-helperis missing.
Notes
Callers used to write
result.wav_bytesto whatever name they were given, so-o out.mp3produced 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 toaudio-helper, and is called here rather than reimplemented.audio-helperis 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.