speaker_helper.transcription module

Speech-to-text via vocal-helper — the canonical transcription path.

Module summary

speaker-helper is the inverse of vocal-helper (speech→text); when it needs to go the other way — to read what a recording says — it reuses vocal-helper rather than reinventing an ASR stack. Two places need this:

  1. Cloning. Adding a voice to clone should be as easy as pointing at a recording. Cloning engines need a transcript of that recording; when the caller does not supply one, ensure_transcript() derives it with vocal-helper and caches it in a .txt sidecar so it is computed once.

  2. Evaluation round-trip. VocalHelperTranscriber implements the evaluation layer’s Transcriber protocol, enabling WER/chrF fidelity scoring of synthesised audio.

vocal-helper (and its whisper.cpp backend) is an optional dependency: it is imported lazily, and a clear error tells the user how to proceed if it is absent.

Usage example

>>> from speaker_helper.transcription import ensure_transcript
>>> # ensure_transcript("assets/ref-malo.wav")  # -> transcript str (needs vocal-helper)

Author

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

class speaker_helper.transcription.VocalHelperTranscriber(language='fr')[source]

Bases: object

Adapter exposing vocal-helper as an evaluation Transcriber.

Parameters:

language (str) – Default language hint used when a call does not specify one.

Notes

vocal-helper’s ASR is CPU/GPU-bound and blocking, so transcribe() runs it in a worker thread to avoid stalling the event loop.

async transcribe(wav_bytes, *, language=None)[source]

Transcribe wav_bytes off the event loop; see Transcriber.

Parameters:

  • wav_bytes (bytes)

  • language (str | None)

Return type:

str

speaker_helper.transcription.ensure_transcript(audio_path, *, language='fr')[source]

Return the transcript of audio_path, caching it in a .txt sidecar.

The first call transcribes with vocal-helper and writes <audio_path>.txt; later calls read that file. This makes “add a voice to clone” a one-liner (supply only the audio) while paying the ASR cost once.

Parameters:

  • audio_path (str or Path) – The reference recording.

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

Returns:

The transcript.

Return type:

str

speaker_helper.transcription.transcribe_bytes(wav_bytes, *, language='fr')[source]

Transcribe an in-memory WAV/audio payload with vocal-helper.

Parameters:

  • wav_bytes (bytes) – Encoded audio (WAV or anything soundfile can read).

  • language (str) – ISO-639-1 language hint for ASR ("auto" to auto-detect).

Returns:

The whitespace-normalised transcript.

Return type:

str

speaker_helper.transcription.transcribe_file(path, *, language='fr')[source]

Transcribe an audio file on disk with vocal-helper.

Parameters:

  • path (str or Path) – Audio file to transcribe.

  • language (str) – ISO-639-1 language hint ("auto" to auto-detect).

Returns:

The whitespace-normalised transcript.

Return type:

str