speaker_helper.profiles module

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

run_multilang_eval() measures each language; LanguageProfile.with_measurement() records that result back onto the profile, and 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

class speaker_helper.profiles.LanguageProfile(language, engine='kokoro', voice_id='', normalize=True, first_chunk_sentences=1, stream_concurrency=1, measured_rtf=None, measured_quality=None)[source]

Bases: object

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.

apply(settings=None)[source]

Return settings (or fresh defaults) with this profile applied.

Parameters:

settings (Settings or None) – Base configuration to derive from; None uses defaults.

Returns:

A copy carrying this profile’s language, engine, voice, and producer granularity. stream_concurrency is a Speaker argument, not a Settings field, so pass it separately (see from_profile()).

Return type:

Settings

engine: str = 'kokoro'
first_chunk_sentences: int = 1
language: str
measured_quality: float | None = None
measured_rtf: float | None = None
normalize: bool = True
stream_concurrency: int = 1
voice_id: str = ''
with_measurement(report)[source]

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:

A copy carrying the measured operating point.

Return type:

LanguageProfile

speaker_helper.profiles.profile_for(language)[source]

Return the profile for language (a default profile if none is defined).

Parameters:

language (str)

Return type:

LanguageProfile

async speaker_helper.profiles.tune_profiles(base_settings, languages, **eval_kwargs)[source]

Measure a set of languages and return profiles carrying the results.

A thin convenience over run_multilang_eval(): it runs the evaluation per language and folds each report’s RTF/quality into the corresponding LanguageProfile.

Parameters:

  • base_settings (Settings) – Base configuration (backend, engine, connection).

  • languages (list of str) – Language codes to measure and profile.

  • **eval_kwargs – Forwarded to run_multilang_eval() (e.g. thresholds, transcriber, warmup).

Returns:

Mapping language -> LanguageProfile with measured RTF/quality.

Return type:

dict