Source code for speaker_helper.types

"""
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
"""

from __future__ import annotations

import io
import tempfile
import wave
from dataclasses import dataclass, field
from pathlib import Path
from typing import Literal

# A synthesis run targets one of two modes: ``offline`` optimises
# throughput/quality, ``streaming`` optimises time to first audio by splitting
# the text and emitting chunks as they are ready.
Mode = Literal["offline", "streaming"]

#: 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.
DEFAULT_SPEECH_BITRATE = "64k"


[docs] def write_audio( wav_bytes: bytes, path: str | Path, *, bitrate: str | int | None = DEFAULT_SPEECH_BITRATE, ) -> Path: """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 :data:`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 ------- pathlib.Path The path written. 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. """ target = Path(path) if target.parent != Path(""): target.parent.mkdir(parents=True, exist_ok=True) if target.suffix.lower() in ("", ".wav"): target.write_bytes(wav_bytes) return target try: import audio_helper as ah except ImportError as exc: # pragma: no cover - depends on the install raise RuntimeError( f"writing {target.name} means encoding, which audio-helper does.\n" " pip install 'audio-helper>=2.6.0'\n" "Or ask for a .wav, which needs no encoder." ) from exc with wave.open(io.BytesIO(wav_bytes), "rb") as handle: frame_rate = handle.getframerate() channels = handle.getnchannels() with tempfile.TemporaryDirectory(prefix="speaker-helper-write-") as tmp: source = Path(tmp) / "audio.wav" source.write_bytes(wav_bytes) ah.sound_converter( str(source), str(target), freq=frame_rate, channels=channels, bitrate=bitrate, overwrite=True, ) return target
[docs] @dataclass(frozen=True) class Voice: """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"``). """ voice_id: str name: str language: str gender: str = "" engine: str = ""
[docs] @dataclass class AudioResult: """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. """ wav_bytes: bytes sample_rate: int duration_s: float compute_s: float text: str voice_id: str language: str @property def rtf(self) -> float: """Real-time factor ``compute_s / duration_s`` (``inf`` if silent). Returns ------- float Below ``1.0`` means faster than real time. """ # Guard against a zero-duration (silent/empty) result: dividing would # raise, so report ``inf`` — treated as "infinitely slower than real # time" and caught as an anomaly downstream. return self.compute_s / self.duration_s if self.duration_s > 0 else float("inf")
[docs] def write_audio( self, path: str | Path, *, bitrate: str | int | None = DEFAULT_SPEECH_BITRATE ) -> Path: """Write the audio to ``path``; the extension picks the container. See :func:`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. """ return write_audio(self.wav_bytes, path, bitrate=bitrate)
[docs] @dataclass class StreamChunk: """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. """ seq: int audio: AudioResult ttfa_s: float | None = None is_final: bool = False
[docs] @dataclass class VoiceSample: """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 reference_text: str
[docs] def read_bytes(self) -> bytes: """Return the audio as bytes, reading from disk if a path was given.""" # ``audio`` is either the raw payload already, or a path to read from. if isinstance(self.audio, bytes): return self.audio from pathlib import Path return Path(self.audio).read_bytes()
[docs] def filename(self) -> str: """Return a filename to send with the upload (from the path, or a default).""" # A path-backed sample keeps its basename (helps the engine label it); # an in-memory sample has no name, so fall back to a generic one. if isinstance(self.audio, str): from pathlib import Path return Path(self.audio).name return "sample.wav"
[docs] @dataclass class VoiceList: """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] = field(default_factory=list)