Source code for speaker_helper.profiles

"""
Per-language operating profiles: hyperparameters plus a measured operating point.

Module summary
--------------
A single engine speaks many languages, but the *best settings* differ per
language — which voice, and how to run the streaming producer/consumer (how
small to make the first chunk for low time-to-first-audio, how many chunks to
synthesise in parallel). A :class:`LanguageProfile` bundles those knobs for one
language, together with the **quality** and **RTF** measured for it, so the
operating point is chosen from data rather than guessed.

Streaming in speaker-helper is a producer/consumer pipeline: a *producer* splits
the text into sentence-sized chunks and *consumers* synthesise them under a
bounded concurrency while emission stays in order (see
:meth:`~speaker_helper.speaker.Speaker.stream`). ``first_chunk_sentences``
(producer granularity) and ``stream_concurrency`` (consumer parallelism) are the
two hyperparameters that trade time-to-first-audio against throughput; they live
here, per language.

:func:`~speaker_helper.eval.multilang.run_multilang_eval` measures each language;
:meth:`LanguageProfile.with_measurement` records that result back onto the
profile, and :func:`tune_profiles` builds measured profiles for a set of
languages in one call.

Usage example
-------------
>>> from speaker_helper.profiles import profile_for
>>> profile_for("en").engine
'kokoro'
>>> profile_for("en").first_chunk_sentences
1

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

from __future__ import annotations

import dataclasses
from dataclasses import dataclass

from speaker_helper.config import Settings


[docs] @dataclass(frozen=True) class LanguageProfile: """Hyperparameters and a measured operating point for one language. Parameters ---------- language : str ISO-639-1 code this profile targets. engine : str Engine/model id to use for this language. voice_id : str Preset voice id; empty means "auto-pick a voice for the language". normalize : bool Ask the engine to loudness-normalise the output. first_chunk_sentences : int Streaming *producer* granularity — sentences in the first emitted chunk. ``1`` minimises time-to-first-audio. stream_concurrency : int Streaming *consumer* parallelism — chunks synthesised at once. ``1`` is a strict pipeline (lowest first-audio latency). measured_rtf : float or None Mean real-time factor measured for this language, or ``None`` if untuned. measured_quality : float or None Quality score in ``[0, 1]`` measured for this language, or ``None``. """ language: str engine: str = "kokoro" voice_id: str = "" normalize: bool = True first_chunk_sentences: int = 1 stream_concurrency: int = 1 measured_rtf: float | None = None measured_quality: float | None = None
[docs] def apply(self, settings: Settings | None = None) -> Settings: """Return ``settings`` (or fresh defaults) with this profile applied. Parameters ---------- settings : Settings or None Base configuration to derive from; ``None`` uses defaults. Returns ------- Settings A copy carrying this profile's language, engine, voice, and producer granularity. ``stream_concurrency`` is a :class:`Speaker` argument, not a :class:`Settings` field, so pass it separately (see :meth:`~speaker_helper.speaker.Speaker.from_profile`). """ base = settings if settings is not None else Settings() return dataclasses.replace( base, language=self.language, engine=self.engine, voice_id=self.voice_id, normalize=self.normalize, first_chunk_sentences=self.first_chunk_sentences, )
[docs] def with_measurement(self, report: object) -> LanguageProfile: """Return a copy with ``measured_rtf``/``measured_quality`` from a report. Parameters ---------- report : EvalReport A report for this language (duck-typed: needs ``mean_rtf`` and ``quality``). Returns ------- LanguageProfile A copy carrying the measured operating point. """ return dataclasses.replace( self, measured_rtf=getattr(report, "mean_rtf", None), measured_quality=getattr(report, "quality", None), )
# Sensible defaults per language. Voice is left to auto-pick (empty) so the # engine chooses one matching the language; the streaming knobs favour low # time-to-first-audio. # # ``measured_rtf`` / ``measured_quality`` are *reference* operating points for # kokoro — recalibrate for your host with ``tune_profiles``. Both axes are # measured per language, and the two were measured by different runs, so they # carry their provenance separately rather than being presented as one sweep: # # * **RTF** — re-measured 2026-10-25 on Apple M2 Max with # ``speaker-helper eval --languages fr,en,es`` against the *in-process* ONNX # engine, warmed up. The numbers these replaced were taken against the REST # engine removed in 0.8.0 (an MLX build on the Apple GPU); that engine is not # in this package any more, so keeping its timings here would have attributed # someone else's measurement to this code. See ``BENCHMARKS.md``, which keeps # the old figures in a dated historical section. # * **quality** — a **UTMOSv2 naturalness MOS** sweep in the ``speak`` study # (kokoro sounds most natural in en 0.65, then fr 0.59, then es 0.55 — all # below the old 0.75 prior). Not re-run here, and not re-labelled. # # Languages without a row ship their hyperparameters only (measured fields # ``None``). _MEASURED_KOKORO: dict[str, tuple[float, float]] = { # language: (mean RTF, quality) # RTF: in-process kokoro-onnx on CPU, M2 Max, 2026-10-25, warmed. # quality: measured UTMOSv2 MOS on [0,1] (see MEASURED_MOS + the speak study). "fr": (0.223, 0.59), "en": (0.237, 0.65), "es": (0.206, 0.55), } # A note on what does NOT live here, and why. The speak study's A/B bench # (out/ab_voices.json, 2026-10-26) also produced UTMOSv2/WER/RTF numbers for # kyutai and chatterbox — and the project owner REJECTED UTMOSv2 as the # offline-quality criterion after reading them: it predicts a generic # anonymous-panel "naturalness" (trained on English MOS panels), which is # neither the brief ("réaliste et vivante", to the owner's ear) nor reliable # in French. Those numbers stay recorded in the study (and STUDY.md §8 bis); # they do not drive routing. The offline quality axis is the owner's # editorial choice (the per-language priors below and in eval/priors.py) # until a HUMAN pairwise-listening measurement replaces it — automatic # metrics remain as guardrails only (WER floor, anomaly gate, F0 gender # check), never as the ranking. # (engine -> languages) whose ``measured_quality`` is a real UTMOSv2 MOS rather # than the engine prior. The router reads this to stamp ``quality_source`` as # ``"measured_mos"`` vs ``"prior"`` on a per-language decision. MEASURED_MOS: dict[str, set[str]] = { "kokoro": {"fr", "en", "es"}, } # Measured mean RTF per (engine, language) on the reference host (Apple # M2 Max), from the speak study's STREAMING bench (exp_streaming_voices.py, # sustained RTF through Speaker.stream — the number that decides whether # playback underruns). The PERFORMANCE axis was never in dispute: these are # the numbers the online condition's feasibility gate consumes. kokoro's own # RTFs live on its per-language profile above; this table carries the other # engines. Host-dependent like every RTF — re-measure on your machine. # Values: speak's exp_streaming_voices.py, 2026-10-26, 8-sentence paragraph # through Speaker.stream, engines warm. kyutai at its q8 default (q4 measured # 0.892 — no gain: the model is memory-bound, not compute-bound); chatterbox # through its auto variant (Turbo for en, Multilingual for fr). MEASURED_RTF: dict[str, dict[str, float]] = { "kyutai": {"fr": 0.880, "en": 0.945}, "chatterbox": {"fr": 5.599, "en": 2.289}, } DEFAULT_PROFILES: dict[str, LanguageProfile] = { lang: LanguageProfile( language=lang, measured_rtf=_MEASURED_KOKORO.get(lang, (None, None))[0], measured_quality=_MEASURED_KOKORO.get(lang, (None, None))[1], ) for lang in ("fr", "en", "es", "it", "pt", "de") }
[docs] def profile_for(language: str) -> LanguageProfile: """Return the profile for ``language`` (a default profile if none is defined).""" return DEFAULT_PROFILES.get(language, LanguageProfile(language=language))
[docs] async def tune_profiles( base_settings: Settings, languages: list[str], **eval_kwargs: object, ) -> dict[str, LanguageProfile]: """Measure a set of languages and return profiles carrying the results. A thin convenience over :func:`~speaker_helper.eval.multilang.run_multilang_eval`: it runs the evaluation per language and folds each report's RTF/quality into the corresponding :class:`LanguageProfile`. Parameters ---------- base_settings : Settings Base configuration (backend, engine, connection). languages : list of str Language codes to measure and profile. **eval_kwargs Forwarded to :func:`run_multilang_eval` (e.g. ``thresholds``, ``transcriber``, ``warmup``). Returns ------- dict Mapping ``language -> LanguageProfile`` with measured RTF/quality. """ from speaker_helper.eval.multilang import run_multilang_eval reports = await run_multilang_eval(base_settings, languages, **eval_kwargs) # type: ignore[arg-type] return {lang: profile_for(lang).with_measurement(report) for lang, report in reports.items()}