"""
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()}