speaker_helper.sources module

Speech-to-speech sources: bring audio from the wild into speaker-helper.

Module summary

speaker-helper turns text into speech. To close the speech-to-speech loop — take an existing recording and re-voice it (a different voice via cloning, or simply a clean re-synthesis) — it needs to get audio first. This module wraps the AI Helpers source packages behind a uniform SourceAudio (a local audio file), then revoice() transcribes it with vocal-helper and speaks the result back through a Speaker:

source ──▶ audio file ──[vocal-helper]──▶ text ──[speaker-helper]──▶ speech

Three sources ship, each behind an optional extra so the heavy dependency is only pulled when used:

  • from_youtube() — a YouTube URL (youtube-helper, extra youtube).

  • from_podcast() — the latest episode of a podcast feed (podcast-helper, extra podcast).

  • from_microphone() — a few seconds of live capture (capture-helper, extra mic).

All third-party imports are lazy, and a clear error names the extra to install.

Usage example

>>> import asyncio
>>> from speaker_helper import Speaker, Settings
>>> from speaker_helper.sources import from_youtube, revoice
>>> async def demo() -> float:
...     src = from_youtube("https://youtu.be/…")            # needs youtube-helper
...     async with Speaker(Settings.from_mapping({"voicebox": {"port": 17600}})) as spk:
...         out = await revoice(src, spk)                    # needs vocal-helper + engine
...     return out.duration_s

Author

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

class speaker_helper.sources.SourceAudio(path, origin, title='')[source]

Bases: object

A local audio file obtained from some speech source.

Parameters:

  • path (str) – Filesystem path to the downloaded/captured audio.

  • origin (str) – Where it came from: "youtube", "podcast", or "microphone".

  • title (str) – A human-readable label (video/episode title, or "microphone").

origin: str
path: str
title: str = ''
async speaker_helper.sources.from_microphone(seconds=5.0, *, sample_rate=16000, frame_ms=20, name_substring=None, output_path=None)[source]

Capture a few seconds of live microphone audio as a SourceAudio.

Parameters:

  • seconds (float) – How long to record.

  • sample_rate (int) – Capture sample rate.

  • frame_ms (int) – Frame size of the capture stream in milliseconds.

  • name_substring (str or None) – Pick a specific input device whose name contains this substring; None uses the default device.

  • output_path (str or None) – Destination WAV file; when None, a temporary file is used.

Returns:

The captured audio written to a WAV file.

Return type:

SourceAudio

Raises:

ImportError – If capture-helper (extra mic) is not installed.

speaker_helper.sources.from_podcast(feed_url, *, output_path=None)[source]

Download the latest episode of a podcast feed as a SourceAudio.

Parameters:

  • feed_url (str) – RSS/Atom feed URL of the podcast.

  • output_path (str or None) – Destination file; when None, a temporary file is used.

Returns:

The downloaded episode audio and its title.

Return type:

SourceAudio

Raises:

  • ImportError – If podcast-helper (extra podcast) is not installed.

  • ValueError – If the latest episode carries no downloadable audio enclosure.

speaker_helper.sources.from_youtube(url, *, output_path=None, sample_rate=44100)[source]

Download a YouTube video’s audio track as a SourceAudio.

Parameters:

  • url (str) – A YouTube video URL.

  • output_path (str or None) – Where to write the audio; when None, youtube-helper picks a name.

  • sample_rate (int) – Target sample rate for the extracted audio.

Returns:

The downloaded audio file and its title.

Return type:

SourceAudio

Raises:

ImportError – If youtube-helper (extra youtube) is not installed.

async speaker_helper.sources.revoice(source, speaker, *, language=None, transcriber=None)[source]

Transcribe a source recording and speak it back through speaker.

This is the speech-to-speech step: the source audio is transcribed with vocal-helper (or an injected transcriber), then synthesised by speaker — in a cloned voice if the speaker is configured to clone, and/or in a different language.

Parameters:

  • source (SourceAudio or str) – The recording (a SourceAudio or a plain file path).

  • speaker (Speaker) – The synthesiser to speak the transcript.

  • language (str or None) – Language to synthesise in (defaults to the speaker’s configured one).

  • transcriber (callable or None) – (path, *, language) -> str. Defaults to vocal-helper’s file transcription.

Returns:

The re-voiced audio.

Return type:

AudioResult

Raises:

  • ImportError – If no transcriber is given and vocal-helper is not installed.

  • ValueError – If the transcript is empty (nothing to speak).