"""
Command-line interface for speaker-helper.
Module summary
--------------
One command line, built with `click <https://click.palletsprojects.com>`_:
``speaker-helper``. It exposes the library as a terminal tool whose
sub-commands cover the three jobs the package exists for and the operations
around them:
* ``synth`` — speak text (or stdin) into a ``.wav``, offline or streaming,
printing the measured duration and real-time factor.
* ``narrate`` — read a document aloud and write the WebVTT cues beside the
audio, so a page can follow the reading.
* ``voices`` — list an engine's preset voices.
* ``clone`` — register a cloned voice from reference audio (default: the
bundled ref-fr-female) and print its id; a missing transcript comes from
``vocal-helper``.
* ``speak-from`` — re-voice audio from a YouTube URL, a podcast feed or the
microphone; see :mod:`speaker_helper.sources`.
* ``route`` — choose engine + mode from measured quality↔speed evidence.
* ``eval`` — measure the engine against a dataset and gate on versioned
thresholds (exit ``0`` pass / ``1`` fail); see :mod:`speaker_helper.eval`.
* ``install-voice`` — fetch an engine's weights before anything depends on them.
* ``health`` — report whether the configured backend can run, and exit
non-zero when it cannot.
* ``serve`` — run the REST API server; see :mod:`speaker_helper.api`.
Global options (``--backend``, ``--engine``, ``--language``, the ``--clone``
family, …) sit on the top-level **group**, so they precede the sub-command:
``speaker-helper --backend mock synth "hi"``, ``speaker-helper --engine kokoro
voices``. They are stashed on the click context and merged into the flag bag
each command handler reads.
Each ``_cmd_*`` handler takes that bag and returns a process exit code, so the
command logic stays testable without a terminal; the click layer above it only
parses.
Usage example
-------------
.. code-block:: bash
speaker-helper synth "Bonjour le monde." -o hello.wav --engine kokoro
echo "Texte depuis stdin." | speaker-helper synth -o out.wav
speaker-helper --engine kokoro voices
speaker-helper route --condition online_realtime --language fr
speaker-helper serve --bind-host 0.0.0.0 --bind-port 8080
Author
------
Warith HARCHAOUI — https://linkedin.com/in/warith-harchaoui
"""
from __future__ import annotations
import asyncio
import sys
from pathlib import Path
from types import SimpleNamespace
from typing import TYPE_CHECKING
import click
import os_helper as osh
from speaker_helper import __version__
from speaker_helper.config import Settings
from speaker_helper.speaker import Speaker
from speaker_helper.types import DEFAULT_SPEECH_BITRATE
if TYPE_CHECKING:
# Imported only for type-checking so the runtime import path stays lazy
# (these pull in optional/heavier modules used by a subset of commands).
from speaker_helper.eval import Thresholds
from speaker_helper.transcription import VocalHelperTranscriber
def _settings_from_args(args: SimpleNamespace) -> Settings:
"""Load settings from ``--config`` and apply CLI overrides."""
# Start from the file/defaults, then let any explicitly-passed flag win.
# `getattr(..., None)` guards flags that only exist on some sub-commands.
settings = Settings.load(args.config)
if getattr(args, "backend", None):
settings.backend = args.backend
if getattr(args, "engine", None):
settings.engine = args.engine
if getattr(args, "voice", None):
settings.voice = args.voice
if getattr(args, "voice_sample", None):
settings.voice_sample = args.voice_sample
if getattr(args, "language", None):
settings.language = args.language
# Any --clone* flag (or the `clone` command) enables a cloned voice.
clone_requested = (
getattr(args, "clone", False)
or getattr(args, "clone_audio", None)
or getattr(args, "clone_name", None)
or args.command == "clone"
)
if clone_requested:
# Copy the settings' clone mapping so per-invocation flag overrides do
# not mutate the loaded configuration in place.
clone: dict[str, object] = dict(settings.clone)
if getattr(args, "clone_name", None):
clone["name"] = args.clone_name
if getattr(args, "clone_audio", None):
clone["audio"] = args.clone_audio
if getattr(args, "clone_text", None):
clone["reference_text"] = args.clone_text
settings.clone = clone
return settings
def _cmd_synth(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``synth`` sub-command; return a process exit code."""
# Text comes from the positional argument, or stdin when it is omitted.
text = args.text if args.text is not None else sys.stdin.read()
# Refuse to synthesise nothing: a blank input is a usage error (exit 2).
if not text or not text.strip():
osh.error("no text provided (argument or stdin)")
return 2
if args.stream:
# --stream is the streaming cell of the matrix, whatever mode the
# configuration names: kokoro under `auto`, not chatterbox.
from speaker_helper.engine import for_streaming
settings = for_streaming(settings)
async def run() -> int:
"""Drive one synthesis (streaming or offline) and write the WAV.
Returns
-------
int
``0`` on success; exceptions propagate to :func:`asyncio.run`.
"""
async with Speaker(settings) as spk:
if args.stream:
# Streaming path: collect per-sentence chunks as they arrive,
# tracking time-to-first-audio and total duration for the report.
first_ttfa: float | None = None
total_audio = 0.0
buffers: list[bytes] = []
async for chunk in spk.stream(text):
# The first chunk carries the TTFA measurement; keep it.
if chunk.ttfa_s is not None:
first_ttfa = chunk.ttfa_s
total_audio += chunk.audio.duration_s
buffers.append(chunk.audio.wav_bytes)
osh.info(
"chunk %d: %.2fs audio (RTF %.2f)",
chunk.seq,
chunk.audio.duration_s,
chunk.audio.rtf,
)
# Stitch the streamed chunks into a single output WAV.
_concat_wavs(buffers, args.out)
osh.info(
"streamed %.2fs audio to %s (TTFA %.2fs)",
total_audio,
args.out,
first_ttfa or 0.0,
)
else:
# Offline path: one call yields the whole audio at once.
result = await spk.say(text)
result.write_audio(
args.out, bitrate=getattr(args, "bitrate", DEFAULT_SPEECH_BITRATE)
)
osh.info(
"wrote %s (%.2fs audio, RTF %.2f)", args.out, result.duration_s, result.rtf
)
return 0
return asyncio.run(run())
def _cmd_narrate(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``narrate`` sub-command; return a process exit code.
Writes two files, not one. The WAV is the obvious half; the ``.vtt``
beside it is what lets a page highlight the block being read, and it costs
nothing to produce because the offsets were already computed to lay the
audio out.
"""
import json
from speaker_helper.narration import coerce_segments, resolve_spoken_math
raw = json.loads(args.segments.read_text(encoding="utf-8"))
if not isinstance(raw, list):
sys.stderr.write("the segments file must hold a JSON list\n")
return 2
segments = coerce_segments(raw)
if args.read_math:
segments = resolve_spoken_math(segments, args.read_math)
async def run() -> int:
async with Speaker(settings) as spk:
result = await spk.narrate(segments)
result.write_audio(args.out, bitrate=getattr(args, "bitrate", DEFAULT_SPEECH_BITRATE))
cues_path = args.out.with_suffix(".vtt")
cues_path.write_text(result.to_vtt(), encoding="utf-8")
sys.stdout.write(
f"{args.out}\t{result.duration_s:.2f}s\t{len(result.cues)} cues\t"
f"rtf {result.rtf:.2f}\n{cues_path}\n"
)
if result.ignored_hints:
# Not a failure, and not silent either: the document asked for
# something this engine has no dial for.
sys.stderr.write(
f"note: this backend has no dial for {', '.join(result.ignored_hints)}\n"
)
return 0
return asyncio.run(run())
def _cmd_install_voice(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``install-voice`` sub-command; return a process exit code."""
from speaker_helper.install import install_engine
return install_engine(args.engine, force=args.force)
def _cmd_health(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``health`` sub-command; return a process exit code.
Exits non-zero when the backend could not synthesise, so this works as a
gate in a script rather than only as something to read.
"""
import json
async def run() -> int:
async with Speaker(settings) as spk:
report = await spk.engine.health()
sys.stdout.write(json.dumps(report, indent=2, sort_keys=True) + "\n")
return 0 if report.get("status") == "ok" else 1
return asyncio.run(run())
def _cmd_voices(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``voices`` sub-command; return a process exit code."""
async def run() -> int:
"""List the engine's preset voices, one per tab-separated line.
Returns
-------
int
``0`` on success.
"""
async with Speaker(settings) as spk:
listing = await spk.voices(args.engine)
# This is user-facing CLI output, so writing to stdout is correct.
for voice in listing.voices:
sys.stdout.write(
f"{voice.voice_id}\t{voice.language}\t{voice.gender}\t{voice.name}\n"
)
return 0
return asyncio.run(run())
def _cmd_serve(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``serve`` sub-command; return a process exit code."""
from speaker_helper.api import serve
serve(settings, host=args.bind_host, port=args.bind_port)
return 0
def _cmd_route(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``route`` sub-command; print the chosen operating point.
Parameters
----------
args : types.SimpleNamespace
Parsed CLI flags (``condition``, ``language``, ``rtf_ceiling``,
``rtf_budget``, ``quality_floor``, ``json_out``).
settings : Settings
Unused for the decision itself (kept for a uniform handler signature).
Returns
-------
int
``0`` on a successful decision, ``2`` when the request is infeasible
(e.g. no engine keeps up online).
"""
import json
from speaker_helper.router import RouteRequest, route
# Build the request straight from the flags; the router validates the
# condition and constraints and raises on an infeasible ask.
try:
decision = route(
RouteRequest(
condition=args.condition,
language=args.language,
rtf_ceiling=args.rtf_ceiling,
rtf_budget=args.rtf_budget,
quality_floor=args.quality_floor,
)
)
except ValueError as exc:
# An infeasible/invalid request is a usage error, not a crash.
osh.error("routing failed: %s", exc)
return 2
# Optional machine-readable dump before the human summary.
if args.json_out is not None:
args.json_out.write_text(
json.dumps(decision.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8"
)
osh.info("wrote decision JSON to %s", args.json_out)
# User-facing verdict on stdout: the headline choice plus the justification.
# No RTF on an offline verdict. Speed is not an objective there, so the
# router hands us mean_rtf=None; printing "mean_rtf=n/a" would still put the
# word in front of the reader and invite them to wonder what it would have
# been. The pair appears only for the condition that ranks on it.
rtf_part = (
""
if decision.mean_rtf is None
else f"mean_rtf={decision.mean_rtf:.3f} ({decision.rtf_source}) "
)
sys.stdout.write(
f"condition={decision.condition} engine={decision.engine} mode={decision.mode}\n"
f"quality={decision.quality:.3f} ({decision.quality_source}) "
f"{rtf_part}".rstrip()
# An arbitration is headline news: without this the summary line reads
# like the engine won on the numbers, which is exactly what it did not do.
+ (" owner_ratified=True" if decision.owner_ratified else "")
+ f"\n{decision.justification}\n"
)
return 0
def _cmd_clone(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``clone`` sub-command; register a voice and print its id."""
async def run() -> int:
"""Register the configured clone and emit its voice id.
Returns
-------
int
``0`` on success.
"""
async with Speaker(settings) as spk:
# Uses the clone reference resolved from settings (default ref-fr-female).
voice_id = await spk.clone_voice()
# User-facing: print the id so it can be captured / reused.
sys.stdout.write(voice_id + "\n")
return 0
return asyncio.run(run())
def _build_transcriber(args: SimpleNamespace) -> VocalHelperTranscriber | None:
"""Return a fidelity transcriber when ``--transcribe`` was passed, else ``None``.
Parameters
----------
args : types.SimpleNamespace
Parsed CLI flags; only ``transcribe`` and ``language`` are read.
Returns
-------
VocalHelperTranscriber or None
A vocal-helper-backed transcriber enabling the WER/chrF round-trip, or
``None`` when fidelity was not requested.
Notes
-----
Imported lazily so ``vocal-helper`` stays optional (the ``stt`` extra): it is
only needed when the user opts into ``--transcribe``.
"""
# No fidelity requested: keep vocal-helper out of the import path entirely.
if not getattr(args, "transcribe", False):
return None
# Build the adapter in the configured language (defaults to French).
from speaker_helper.transcription import VocalHelperTranscriber
return VocalHelperTranscriber(getattr(args, "language", None) or "fr")
def _cmd_eval_multilang(args: SimpleNamespace, settings: Settings, thresholds: Thresholds) -> int:
"""Run the evaluation across ``--languages`` and print a matrix; gate on all.
Parameters
----------
args : types.SimpleNamespace
Parsed CLI flags (``languages``, ``json_out``, ``transcribe``).
settings : Settings
Base configuration; language/voice are overridden per language.
thresholds : Thresholds
Pass/fail bar applied to every language.
Returns
-------
int
``0`` when every language passes, ``1`` otherwise.
"""
import json
from speaker_helper.eval import format_matrix, run_multilang_eval
# Split "fr,en,es" into a clean list, dropping empty entries.
languages = [lang.strip() for lang in args.languages.split(",") if lang.strip()]
# Optional fidelity round-trip, shared across every language.
transcriber = _build_transcriber(args)
async def run() -> int:
"""Evaluate every requested language, print the matrix, gate on all.
Returns
-------
int
``0`` only if every language passes its threshold bar, else ``1``.
"""
# Measure each language against the shared thresholds in one pass.
reports = await run_multilang_eval(
settings, languages, thresholds=thresholds, transcriber=transcriber
)
# Human-readable per-language matrix on stdout.
sys.stdout.write(format_matrix(reports) + "\n")
# Optional machine-readable dump for CI artifacts / dashboards.
if args.json_out is not None:
args.json_out.write_text(
json.dumps(
{lang: r.to_dict() for lang, r in reports.items()}, ensure_ascii=False, indent=2
),
encoding="utf-8",
)
osh.info("wrote JSON matrix to %s", args.json_out)
return 0 if all(r.passed for r in reports.values()) else 1
return asyncio.run(run())
def _cmd_speak_from(args: SimpleNamespace, settings: Settings) -> int:
"""Handle ``speak-from``: transcribe a source and re-voice it to a WAV file."""
from speaker_helper.sources import (
from_microphone,
from_podcast,
from_youtube,
revoice,
)
async def run() -> int:
"""Resolve the requested source, re-voice it, and write the WAV.
Returns
-------
int
``0`` on success, ``2`` when a required ``--url`` is missing.
"""
# youtube/podcast sources need a URL; the mic source does not.
if args.source in ("youtube", "podcast") and not args.url:
osh.error("--url is required for the %s source", args.source)
return 2
# Build the source adapter matching the requested origin.
if args.source == "youtube":
src = from_youtube(args.url)
elif args.source == "podcast":
src = from_podcast(args.url)
else:
src = await from_microphone(args.seconds)
async with Speaker(settings) as spk:
result = await revoice(src, spk)
result.write_audio(args.out, bitrate=getattr(args, "bitrate", DEFAULT_SPEECH_BITRATE))
osh.info(
"re-voiced %s -> %s (%.2fs audio, RTF %.2f)",
src.origin,
args.out,
result.duration_s,
result.rtf,
)
return 0
return asyncio.run(run())
def _cmd_eval(args: SimpleNamespace, settings: Settings) -> int:
"""Handle the ``eval`` sub-command; return 0 if the gate passes, 1 if not."""
import json
from speaker_helper.eval import Thresholds, load_dataset, run_eval
thresholds = Thresholds.load(args.thresholds)
if getattr(args, "languages", None):
return _cmd_eval_multilang(args, settings, thresholds)
cases = load_dataset(args.dataset)
# Optional fidelity round-trip (WER/chrF) via vocal-helper; None otherwise.
transcriber = _build_transcriber(args)
async def run() -> int:
"""Run the single-language evaluation and print the pass/fail verdict.
Returns
-------
int
``0`` if the report passes the threshold bar, ``1`` otherwise.
"""
# Evaluate every dataset case against the engine under the thresholds.
async with Speaker(settings) as spk:
report = await run_eval(spk, cases, thresholds=thresholds, transcriber=transcriber)
# Optional machine-readable dump before the human summary.
if args.json_out is not None:
args.json_out.write_text(
json.dumps(report.to_dict(), ensure_ascii=False, indent=2), encoding="utf-8"
)
osh.info("wrote JSON report to %s", args.json_out)
# User-facing verdict on stdout so it is greppable / pipeable.
sys.stdout.write(
f"backend={report.backend} engine={settings.engine} cases={report.n_cases}\n"
f"mean_rtf={report.mean_rtf} p95_rtf={report.p95_rtf} "
f"anomaly_rate={report.anomaly_rate} "
f"quality={report.quality} ({report.quality_source})\n"
f"{'PASS' if report.passed else 'FAIL'}"
+ ("" if report.passed else ": " + "; ".join(report.failures))
+ "\n"
)
return 0 if report.passed else 1
return asyncio.run(run())
def _concat_wavs(buffers: list[bytes], out: Path) -> None:
"""Concatenate streamed WAV chunks into one file via ``audio-helper``.
Each in-memory chunk is written to a temporary file and stitched together
with :func:`audio_helper.audio_concatenation`, which handles heterogeneous
encodings robustly — the ecosystem's audio path rather than a hand-rolled
numpy concat.
"""
# Imported lazily so a plain `synth` (offline) never pulls in audio-helper.
import audio_helper as ah
import os_helper as osh
# Spill each in-memory chunk to a temp file so audio-helper can stitch them.
with osh.temporary_folder() as tmp:
parts: list[str] = []
for i, buf in enumerate(buffers):
# Zero-pad the index so lexical order matches playback order.
part = osh.join(tmp, f"chunk_{i:04d}.wav")
Path(part).write_bytes(buf)
parts.append(part)
# Concatenate through the ecosystem's robust encoder-aware path.
ah.audio_concatenation(parts, output_audio_filename=str(out), overwrite=True)
# Every sub-command name, mapped to the handler that runs it. Keeping the table
# explicit rather than dispatching on the click function's own name is what
# lets a test assert that no command is reachable without a handler behind it.
_HANDLERS = {
"synth": _cmd_synth,
"voices": _cmd_voices,
"clone": _cmd_clone,
"eval": _cmd_eval,
"speak-from": _cmd_speak_from,
"route": _cmd_route,
"serve": _cmd_serve,
"narrate": _cmd_narrate,
"install-voice": _cmd_install_voice,
"health": _cmd_health,
}
def _run(ctx: click.Context, command: str, **fields: object) -> None:
"""Merge global + command flags, then dispatch to the handler.
Parameters
----------
ctx : click.Context
The click context; ``ctx.obj`` holds the group-level global options.
command : str
Sub-command name (``synth``, ``route``, …).
**fields
Command-specific flag values.
Raises
------
SystemExit
Always: the handler's integer exit code is propagated to the shell.
"""
# Globals (from the group) first, then the command's own fields — one flag
# bag drives both the settings merge and the handler, so a handler never
# needs to know which option sat where on the command line.
merged = {**(ctx.obj or {}), **fields}
args = SimpleNamespace(command=command, **merged)
settings: Settings = _settings_from_args(args)
raise SystemExit(_HANDLERS[command](args, settings))
# The global options live on the GROUP, not on each command, so they precede
# the sub-command: `speaker-helper --engine kokoro voices`, never the reverse.
# `-h` is declared next to `--help` because the short spelling is the first
# thing a user tries, and `-V` next to `--version` because `-v` is taken by
# verbosity everywhere in this suite. The version is passed explicitly: reading
# it from the installed distribution metadata reports whatever was last
# pip-installed, which an editable checkout then misreports.
@click.group(context_settings={"help_option_names": ["-h", "--help"]})
@click.version_option(__version__, "-V", "--version", package_name="speaker-helper")
@click.option("--config", type=click.Path(path_type=Path), default=None, help="settings.yaml path.")
@click.option(
"--backend",
default=None,
help=(
"TTS backend: auto (default: chatterbox offline, kokoro streaming), "
"kokoro, chatterbox, kyutai, audio8, qwen3tts, openvoice, elevenlabs (cloud, paid) or mock."
),
)
@click.option("--voice-sample", default=None, help="Reference recording to clone.")
@click.option("--engine", default=None, help="Engine/model id (e.g. kokoro).")
@click.option("--voice", default=None, help="Preset voice id (default: auto).")
@click.option("--language", default=None, help="Target language (e.g. fr).")
@click.option(
"--clone", is_flag=True, default=False, help="Use a cloned voice (default: ref-fr-female)."
)
@click.option("--clone-name", default=None, help="Name for the cloned voice profile.")
@click.option("--clone-audio", default=None, help="Reference audio file to clone from.")
@click.option("--clone-text", default=None, help="Transcript of --clone-audio (auto if omitted).")
@click.pass_context
def cli(ctx: click.Context, **globals_: object) -> None:
"""Text-to-speech (offline + streaming) over a local TTS engine.
The options above are global: they apply to every sub-command and have to
precede it, as in: speaker-helper --backend mock synth "hi"
"""
# Configure the ecosystem logging surface once, at the entry point, so
# INFO-level progress is visible rather than swallowed.
osh.init_logging()
# Stash the global options for the sub-command handlers to merge in.
ctx.obj = dict(globals_)
@cli.command()
@click.argument("text", required=False, default=None)
@click.option(
"-o",
"--out",
"out",
type=click.Path(path_type=Path),
default=Path("out.wav"),
help="Output path; the extension picks the container (.wav, .mp3, .m4a).",
)
@click.option("--stream", is_flag=True, default=False, help="Streaming mode: report TTFA/cadence.")
@click.option(
"--bitrate",
default=DEFAULT_SPEECH_BITRATE,
show_default=True,
help="Bitrate when --out names a lossy container (.mp3, .m4a). Ignored for .wav.",
)
@click.pass_context
def synth(ctx: click.Context, text: str | None, out: Path, stream: bool, bitrate: str) -> None:
"""Synthesise TEXT (or stdin) to an audio file."""
# text=None tells the handler to read the utterance from stdin;
# --stream selects the low-TTFA streaming path over whole-text synthesis.
_run(ctx, "synth", text=text, out=out, stream=stream, bitrate=bitrate)
@cli.command()
@click.pass_context
def clone(ctx: click.Context) -> None:
"""Register a cloned voice from reference audio and print its id."""
# The clone reference comes from the global --clone/--clone-audio/--clone-name
# options (merged from ctx.obj), so this command carries no options of its own.
_run(ctx, "clone")
@cli.command()
@click.option(
"--condition",
type=click.Choice(["online_realtime", "offline"]),
required=True,
help="online_realtime (speed=RTF) or offline (quality only).",
)
@click.option("--rtf-ceiling", "rtf_ceiling", type=float, default=0.8, help="Online: max mean RTF.")
@click.option("--rtf-budget", "rtf_budget", type=float, default=None, help="Offline: RTF cap.")
@click.option(
"--quality-floor", "quality_floor", type=float, default=None, help="Reject quality below this."
)
@click.option(
"--json",
"json_out",
type=click.Path(path_type=Path),
default=None,
help="Write decision JSON here.",
)
@click.pass_context
def route(
ctx: click.Context,
condition: str,
rtf_ceiling: float,
rtf_budget: float | None,
quality_floor: float | None,
json_out: Path | None,
) -> None:
"""Choose the best engine + mode for a condition (online real-time / offline)."""
# _cmd_route reads args.language directly; the global --language may be None,
# so default it to fr here to match the router's own default.
language = (ctx.obj or {}).get("language") or "fr"
_run(
ctx,
"route",
condition=condition,
language=language,
rtf_ceiling=rtf_ceiling,
rtf_budget=rtf_budget,
quality_floor=quality_floor,
json_out=json_out,
)
@cli.command(name="narrate")
@click.argument("segments", type=click.Path(exists=True, path_type=Path))
@click.option(
"-o",
"--out",
type=click.Path(path_type=Path),
default=Path("narration.wav"),
help="Output audio; the cues are written beside it as .vtt.",
)
@click.option(
"--read-math",
metavar="LANG",
default=None,
help="Speak the notation as words in LANG, leaving the cues as the page reads.",
)
@click.option(
"--bitrate",
default=DEFAULT_SPEECH_BITRATE,
show_default=True,
help="Bitrate when --out names a lossy container (.mp3, .m4a). Ignored for .wav.",
)
@click.pass_context
def narrate(
ctx: click.Context, segments: Path, out: Path, read_math: str | None, bitrate: str
) -> None:
"""Read a document aloud, and write the timed track that follows it.
SEGMENTS is a JSON list of blocks, each with `text` and optionally `say`,
`pause_before_ms`, `pause_after_ms`, `pace` and `emotion`. A list of plain
strings works too.
"""
_run(ctx, "narrate", segments=segments, out=out, read_math=read_math, bitrate=bitrate)
@cli.command(name="install-voice")
@click.option("--engine", default="kokoro", help="Which engine to prepare.")
@click.option("--force", is_flag=True, default=False, help="Re-download even if present.")
@click.pass_context
def install_voice(ctx: click.Context, engine: str, force: bool) -> None:
"""Download the weights an engine needs, before anything depends on them."""
_run(ctx, "install-voice", engine=engine, force=force)
@cli.command(name="health")
@click.pass_context
def health(ctx: click.Context) -> None:
"""Report whether the configured backend can run; exit non-zero if not."""
_run(ctx, "health")
@cli.command(name="voices")
@click.pass_context
def voices_cmd(ctx: click.Context) -> None:
"""List preset voices for an engine (uses the global --engine)."""
# Named voices_cmd (not voices) to avoid shadowing; registered as "voices".
# The engine to list comes from the global --engine, which precedes the
# sub-command: `speaker-helper --engine kokoro voices`.
_run(ctx, "voices")
@cli.command(name="eval")
@click.option("--dataset", type=click.Path(path_type=Path), default=None, help="JSONL dataset.")
@click.option(
"--thresholds", type=click.Path(path_type=Path), default=None, help="Thresholds YAML."
)
@click.option(
"--json",
"json_out",
type=click.Path(path_type=Path),
default=None,
help="Write JSON report here.",
)
@click.option("--languages", default=None, help="Comma-separated languages (e.g. fr,en,es).")
@click.option(
"--transcribe", is_flag=True, default=False, help="Round-trip WER/chrF via vocal-helper."
)
@click.pass_context
def eval_cmd(
ctx: click.Context,
dataset: Path | None,
thresholds: Path | None,
json_out: Path | None,
languages: str | None,
transcribe: bool,
) -> None:
"""Evaluate the engine against a dataset and gate on thresholds."""
# The handler returns a non-zero exit code when the bar is missed, which
# _run propagates as SystemExit — so `eval` gates CI. --languages runs the
# per-language matrix; --transcribe adds the WER/chrF round-trip.
_run(
ctx,
"eval",
dataset=dataset,
thresholds=thresholds,
json_out=json_out,
languages=languages,
transcribe=transcribe,
)
@cli.command(name="speak-from")
@click.option(
"--source",
type=click.Choice(["youtube", "podcast", "mic"]),
required=True,
help="Audio source.",
)
@click.option("--url", default=None, help="YouTube video URL or podcast feed URL.")
@click.option("--seconds", type=float, default=5.0, help="Microphone capture duration.")
@click.option(
"-o",
"--out",
"out",
type=click.Path(path_type=Path),
default=Path("out.wav"),
help="Output path; the extension picks the container (.wav, .mp3, .m4a).",
)
@click.option(
"--bitrate",
default=DEFAULT_SPEECH_BITRATE,
show_default=True,
help="Bitrate when --out names a lossy container (.mp3, .m4a). Ignored for .wav.",
)
@click.pass_context
def speak_from(
ctx: click.Context, source: str, url: str | None, seconds: float, out: Path, bitrate: str
) -> None:
"""Re-voice audio from a source (youtube / podcast / microphone)."""
# --url is required for youtube/podcast (the handler validates it); the mic
# source uses --seconds instead. The source is transcribed then re-spoken.
_run(ctx, "speak-from", source=source, url=url, seconds=seconds, out=out, bitrate=bitrate)
@cli.command()
@click.option("--bind-host", "bind_host", default="127.0.0.1", help="API server bind host.")
@click.option("--bind-port", "bind_port", type=int, default=8080, help="API server bind port.")
@click.pass_context
def serve(ctx: click.Context, bind_host: str, bind_port: int) -> None:
"""Run the REST API server.
The bind address is spelled --bind-host / --bind-port. The longer spelling
is deliberate: this program used to carry a global --host / --port aimed at
a REMOTE engine, and two pairs one word apart, on the same line, pointing
at different machines, is how a server ends up calling itself for /health.
"""
_run(ctx, "serve", bind_host=bind_host, bind_port=bind_port)
[docs]
def main() -> None:
"""Console-script entry point: run the click command group."""
cli()
if __name__ == "__main__": # pragma: no cover
main()