speaker_helper.cloning module

Voice-cloning defaults and sample resolution.

Module summary

Cloning a voice means “here is a recording of the voice I want, use it”. This module makes that easy and uniform across the library, CLI, and REST API by turning a small, permissive clone configuration into a concrete list of VoiceSample.

A ready-to-use default ships with the project: assets/ref-malo.wav and its transcript assets/ref-malo.txt (produced with vocal-helper). So enabling cloning with no further input clones that reference voice; any field can be overridden.

The clone configuration is a plain mapping (mirroring settings.clone) so it travels unchanged through YAML, environment, CLI flags, and JSON request bodies:

  • name — profile name for the clone (idempotency key). Default ref-malo.

  • audio — path to a reference recording. Default the bundled ref-malo file.

  • reference_text — transcript of audio. Default the bundled transcript.

  • samples — an explicit list of {audio, reference_text} objects; when present it takes precedence over the single audio/reference_text pair (use it to clone from several recordings).

Usage example

>>> from speaker_helper.cloning import resolve_samples
>>> samples = resolve_samples({})          # the bundled ref-malo reference
>>> samples[0].reference_text[:11]
'Je m'appell'

Author

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

speaker_helper.cloning.clone_name(clone)[source]

Return the profile name for a clone configuration (default ref-malo).

Parameters:

clone (dict[str, Any])

Return type:

str

speaker_helper.cloning.default_reference_text()[source]

Return the bundled ref-malo transcript, or "" if it is missing.

Return type:

str

speaker_helper.cloning.prepare_samples(samples, *, language='fr', max_seconds=28.0)[source]

Make samples engine-ready: trim over-long audio and fill transcripts.

This is the canonical “add a voice to clone” path — supply only a recording and it just works:

  • Trim. Audio longer than max_seconds is trimmed to that length so it clears the engine’s reference-length cap. Because trimming changes what is said, the transcript is then re-derived from the trimmed audio.

  • Transcribe. Any sample still lacking a transcript is transcribed with vocal-helper (cached in a .txt sidecar for file-backed samples).

Parameters:

  • samples (list of VoiceSample) – Reference samples (audio as bytes or a file path).

  • language (str) – ISO-639-1 language hint passed to ASR.

  • max_seconds (float) – Maximum reference-audio length; longer audio is trimmed.

Returns:

Samples with in-memory audio (bytes) and a matching, non-empty reference_text.

Return type:

list of VoiceSample

Notes

soundfile and vocal-helper are imported lazily so importing this module stays cheap and vocal-helper is only required when a transcript must actually be derived.

speaker_helper.cloning.resolve_samples(clone)[source]

Turn a clone configuration mapping into concrete voice samples.

Parameters:

clone (dict) – The clone configuration (see the module docstring). An empty mapping yields the single bundled ref-malo reference.

Returns:

One or more samples ready to upload to a cloning engine.

Return type:

list of VoiceSample

Raises:

ValueError – If an explicit samples entry lacks an audio field, or if the resolved default reference audio does not exist on disk.

Notes

A sample’s reference_text falls back to the bundled default transcript only for the bundled default audio; a custom audio with no transcript keeps an empty string (the engine may reject it — supply the transcript).