openspeechapi 0.1.0__py3-none-any.whl

openspeech/demo.py

@@ -0,0 +1,675 @@
+"""OpenSpeech interactive demo CLI."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import io
+import os
+import shlex
+import struct
+import sys
+import time
+import wave
+from pathlib import Path
+from typing import Any
+
+# ANSI color codes — no extra deps needed
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_GREEN = "\033[32m"
+_CYAN = "\033[36m"
+_YELLOW = "\033[33m"
+_RED = "\033[31m"
+_DIM = "\033[2m"
+
+
+def _c(text: str, *codes: str) -> str:
+    """Apply ANSI color codes if stdout is a TTY."""
+    if not sys.stdout.isatty():
+        return text
+    return "".join(codes) + text + _RESET
+
+
+def _load_dotenv() -> None:
+    """Try to load .env file."""
+    try:
+        from dotenv import load_dotenv  # type: ignore[import]
+
+        load_dotenv()
+    except ImportError:
+        pass
+
+
+def _build_registry() -> Any:
+    """Build provider registry with available providers."""
+    from openspeech.core.registry import ProviderRegistry
+    from openspeech.providers.stt.faster_whisper import FasterWhisperSTT
+    from openspeech.providers.stt.openai import OpenAISTT
+    from openspeech.providers.tts.openai import OpenAITTS
+
+    registry = ProviderRegistry()
+    registry.register("openai", OpenAISTT)
+    registry.register("faster-whisper", FasterWhisperSTT)
+    registry.register("openai-tts", OpenAITTS)
+    return registry
+
+
+def _write_audio_file(path: str, audio: Any) -> None:
+    """Write AudioData to a file. Wraps raw PCM in WAV headers if needed."""
+    from openspeech.core.enums import AudioFormat
+
+    p = Path(path)
+    ext = p.suffix.lower()
+
+    # If output is .wav and data is raw PCM (no WAV header), wrap it
+    is_raw_pcm = audio.format in (AudioFormat.PCM_16K, AudioFormat.PCM_44K) or (
+        len(audio.data) > 4 and audio.data[:4] != b"RIFF"
+    )
+
+    if ext == ".wav" and is_raw_pcm:
+        buf = io.BytesIO()
+        with wave.open(buf, "wb") as wf:
+            wf.setnchannels(audio.channels)
+            wf.setsampwidth(2)  # 16-bit
+            wf.setframerate(audio.sample_rate)
+            wf.writeframes(audio.data)
+        p.write_bytes(buf.getvalue())
+    else:
+        p.write_bytes(audio.data)
+
+
+def _read_audio(path: str) -> Any:
+    """Read an audio file into AudioData."""
+    from openspeech.core.enums import AudioFormat
+    from openspeech.core.models import AudioData
+
+    p = Path(path)
+    if not p.exists():
+        print(_c(f"Error: File not found: {path}", _RED), file=sys.stderr)
+        sys.exit(1)
+
+    data = p.read_bytes()
+    ext = p.suffix.lower()
+    fmt_map = {
+        ".wav": AudioFormat.WAV,
+        ".mp3": AudioFormat.MP3,
+        ".ogg": AudioFormat.OGG,
+        ".flac": AudioFormat.FLAC,
+        ".opus": AudioFormat.OPUS,
+    }
+    fmt = fmt_map.get(ext, AudioFormat.WAV)
+    return AudioData(data=data, sample_rate=16000, channels=1, format=fmt)
+
+
+def _check_openai_key() -> str:
+    """Return OPENAI_API_KEY or print error and exit."""
+    key = os.environ.get("OPENAI_API_KEY", "")
+    if not key:
+        print(
+            _c("Error: OPENAI_API_KEY environment variable is not set.", _RED),
+            file=sys.stderr,
+        )
+        print(
+            "  Set it with: export OPENAI_API_KEY=sk-...",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return key
+
+
+def _print_stt_result(result: Any, elapsed: float, show_words: bool = False) -> None:
+    """Pretty-print a Transcription result."""
+    print()
+    print(_c("STT Result", _BOLD + _CYAN))
+    print(_c("─" * 50, _DIM))
+    print(f"  {_c('Text:', _BOLD)}       {result.text}")
+    lang = result.language or "N/A"
+    print(f"  {_c('Language:', _BOLD)}   {lang}")
+    conf = f"{result.confidence:.3f}" if result.confidence is not None else "N/A"
+    print(f"  {_c('Confidence:', _BOLD)} {conf}")
+    print(f"  {_c('Elapsed:', _BOLD)}    {elapsed:.2f}s")
+
+    if show_words and result.words:
+        print()
+        print(_c("  Word timestamps:", _BOLD))
+        for w in result.words:
+            word_conf = f"{w.confidence:.2f}" if w.confidence is not None else "N/A"
+            print(
+                f"    [{w.start_ms:>6}ms - {w.end_ms:>6}ms]  "
+                f"{w.text:<20}  conf={word_conf}"
+            )
+    print()
+
+
+def _print_tts_result(out_path: str, audio: Any, elapsed: float) -> None:
+    """Pretty-print a TTS synthesis result."""
+    file_size = len(audio.data)
+    print()
+    print(_c("TTS Result", _BOLD + _CYAN))
+    print(_c("─" * 50, _DIM))
+    print(f"  {_c('Output:', _BOLD)}      {out_path}")
+    print(f"  {_c('File size:', _BOLD)}   {file_size:,} bytes")
+    print(f"  {_c('Sample rate:', _BOLD)} {audio.sample_rate} Hz")
+    print(f"  {_c('Elapsed:', _BOLD)}     {elapsed:.2f}s")
+    print()
+
+
+async def _make_stt_provider(provider_name: str, args: Any) -> Any:
+    """Instantiate and start an STT provider."""
+    registry = _build_registry()
+    cls = registry.get(provider_name)
+
+    settings: Any = None
+    if provider_name == "faster-whisper":
+        from openspeech.providers.stt.faster_whisper import FasterWhisperSTTSettings
+
+        model_size = getattr(args, "model_size", None) or "base"
+        device = getattr(args, "device", None) or "auto"
+        settings = FasterWhisperSTTSettings(model_size=model_size, device=device)
+    elif provider_name in ("openai", "openai-stt"):
+        from openspeech.providers.stt.openai import OpenAISTTSettings
+
+        api_key = _check_openai_key()
+        settings = OpenAISTTSettings(api_key=api_key)
+
+    provider = cls(settings)
+    await provider.start()
+    return provider
+
+
+async def _make_tts_provider(provider_name: str, args: Any) -> Any:
+    """Instantiate and start a TTS provider."""
+    registry = _build_registry()
+    cls = registry.get(provider_name)
+
+    settings: Any = None
+    if provider_name == "openai-tts":
+        from openspeech.providers.tts.openai import OpenAITTSSettings
+
+        api_key = _check_openai_key()
+        voice = getattr(args, "voice", None) or "alloy"
+        model = getattr(args, "model", None) or "tts-1"
+        settings = OpenAITTSSettings(api_key=api_key, voice=voice, model=model)
+
+    provider = cls(settings)
+    await provider.start()
+    return provider
+
+
+async def _cmd_stt(args: Any) -> None:
+    """Run STT transcription."""
+    provider_name = getattr(args, "provider", None) or "faster-whisper"
+    audio = _read_audio(args.input)
+
+    print(_c(f"Transcribing with provider: {provider_name} ...", _DIM))
+    provider = await _make_stt_provider(provider_name, args)
+    try:
+        t0 = time.perf_counter()
+        result = await provider.transcribe(audio)
+        elapsed = time.perf_counter() - t0
+    finally:
+        await provider.stop()
+
+    show_words = getattr(args, "words", False)
+    _print_stt_result(result, elapsed, show_words=show_words)
+
+
+async def _cmd_tts(args: Any) -> None:
+    """Run TTS synthesis."""
+    provider_name = getattr(args, "provider", None) or "openai-tts"
+    out_path = getattr(args, "output", None) or "output.wav"
+    text = args.text
+
+    print(_c(f"Synthesizing with provider: {provider_name} ...", _DIM))
+    provider = await _make_tts_provider(provider_name, args)
+    try:
+        t0 = time.perf_counter()
+        audio = await provider.synthesize(text)
+        elapsed = time.perf_counter() - t0
+    finally:
+        await provider.stop()
+
+    _write_audio_file(out_path, audio)
+    _print_tts_result(out_path, audio, elapsed)
+    if getattr(args, "play", False):
+        from openspeech.utils.audio_playback import play_audio
+
+        play_audio(
+            audio,
+            device=getattr(args, "play_device", None),
+            volume=float(getattr(args, "play_volume", 1.0)),
+            blocking=not getattr(args, "play_non_blocking", False),
+            backend=getattr(args, "play_backend", "auto"),
+        )
+
+
+async def _cmd_roundtrip(args: Any) -> None:
+    """Run TTS -> STT roundtrip."""
+    tts_provider_name = getattr(args, "tts", None) or "openai-tts"
+    stt_provider_name = getattr(args, "stt", None) or "faster-whisper"
+    text = args.text
+
+    print()
+    print(_c("Roundtrip Test", _BOLD + _CYAN))
+    print(_c("─" * 50, _DIM))
+    print(f"  {_c('Original text:', _BOLD)} {text}")
+    print(f"  {_c('TTS provider:', _BOLD)}  {tts_provider_name}")
+    print(f"  {_c('STT provider:', _BOLD)}  {stt_provider_name}")
+    print()
+
+    # Step 1: TTS
+    print(_c(f"Step 1: Synthesizing with {tts_provider_name} ...", _DIM))
+    tts_provider = await _make_tts_provider(tts_provider_name, args)
+    try:
+        t0 = time.perf_counter()
+        audio = await tts_provider.synthesize(text)
+        tts_elapsed = time.perf_counter() - t0
+    finally:
+        await tts_provider.stop()
+
+    if getattr(args, "play", False):
+        from openspeech.utils.audio_playback import play_audio
+
+        play_audio(
+            audio,
+            device=getattr(args, "play_device", None),
+            volume=float(getattr(args, "play_volume", 1.0)),
+            blocking=not getattr(args, "play_non_blocking", False),
+            backend=getattr(args, "play_backend", "auto"),
+        )
+
+    print(
+        f"  {_c('Audio:', _BOLD)} {len(audio.data):,} bytes "
+        f"@ {audio.sample_rate} Hz  ({tts_elapsed:.2f}s)"
+    )
+
+    # Step 2: STT
+    print(_c(f"Step 2: Transcribing with {stt_provider_name} ...", _DIM))
+    stt_provider = await _make_stt_provider(stt_provider_name, args)
+    try:
+        t0 = time.perf_counter()
+        result = await stt_provider.transcribe(audio)
+        stt_elapsed = time.perf_counter() - t0
+    finally:
+        await stt_provider.stop()
+
+    print(f"  {_c('Transcribed:', _BOLD)} {result.text}")
+    conf = f"{result.confidence:.3f}" if result.confidence is not None else "N/A"
+    print(f"  {_c('Confidence:', _BOLD)}  {conf}  ({stt_elapsed:.2f}s)")
+    print()
+
+    # Summary
+    total = tts_elapsed + stt_elapsed
+    print(_c("Summary", _BOLD))
+    print(f"  Original:    {text}")
+    print(f"  Transcribed: {result.text}")
+    print(f"  Total time:  {total:.2f}s")
+    print()
+
+
+async def _cmd_compare(args: Any) -> None:
+    """Run multi-provider STT comparison."""
+    providers_str: str = getattr(args, "provider", None) or "faster-whisper"
+    provider_names = [p.strip() for p in providers_str.split(",")]
+    audio = _read_audio(args.input)
+
+    print(_c(f"Comparing {len(provider_names)} STT provider(s) ...", _DIM))
+
+    async def _run_one(name: str) -> tuple[str, Any, float]:
+        try:
+            provider = await _make_stt_provider(name, args)
+            t0 = time.perf_counter()
+            try:
+                result = await provider.transcribe(audio)
+            finally:
+                await provider.stop()
+            elapsed = time.perf_counter() - t0
+            return (name, result, elapsed)
+        except Exception as exc:  # noqa: BLE001
+            return (name, exc, 0.0)
+
+    results = await asyncio.gather(*[_run_one(n) for n in provider_names])
+
+    # Print comparison table
+    col_prov = 18
+    col_text = 35
+    col_conf = 12
+    col_time = 8
+
+    header = (
+        f"{'Provider':<{col_prov}}"
+        f"{'Text':<{col_text}}"
+        f"{'Confidence':<{col_conf}}"
+        f"{'Time':>{col_time}}"
+    )
+    sep = "─" * (col_prov + col_text + col_conf + col_time)
+
+    print()
+    print(_c(header, _BOLD))
+    print(_c(sep, _DIM))
+    for name, result, elapsed in results:
+        if isinstance(result, Exception):
+            text_cell = _c(f"ERROR: {result}", _RED)
+            conf_cell = "N/A"
+            time_cell = "N/A"
+        else:
+            raw_text = result.text or ""
+            text_cell = raw_text[:col_text - 2] + ".." if len(raw_text) > col_text - 1 else raw_text
+            conf_val = result.confidence
+            conf_cell = f"{conf_val:.3f}" if conf_val is not None else "N/A"
+            time_cell = f"{elapsed:.2f}s"
+        print(
+            f"{name:<{col_prov}}"
+            f"{text_cell:<{col_text}}"
+            f"{conf_cell:<{col_conf}}"
+            f"{time_cell:>{col_time}}"
+        )
+    print()
+
+
+def _parse_repl_line(line: str) -> list[str]:
+    """Parse a REPL input line using shell-like splitting."""
+    try:
+        return shlex.split(line.strip())
+    except ValueError:
+        # Fallback for unbalanced quotes
+        return line.strip().split()
+
+
+def _print_repl_help() -> None:
+    print()
+    print(_c("Available REPL commands:", _BOLD + _CYAN))
+    print("  stt <audio_file> [-p <provider>]          Transcribe audio file")
+    print("  tts <text> [-o <output.wav>] [-p <prov>] [--play]  Synthesize speech")
+    print("  roundtrip <text> [--tts <prov>] [--stt <prov>]  Roundtrip test")
+    print("  compare <audio_file> [-p p1,p2]           Compare providers")
+    print("  providers                                  List available providers")
+    print("  help                                       Show this help")
+    print("  quit / exit / q                            Exit")
+    print()
+
+
+def _print_providers() -> None:
+    print()
+    print(_c("Available providers:", _BOLD + _CYAN))
+    print(
+        f"  {'Name':<20}{'Type':<8}{'Mode':<14}{'Requirements'}"
+    )
+    print(_c("  " + "─" * 56, _DIM))
+    rows = [
+        ("faster-whisper", "STT", "subprocess", "pip install faster-whisper"),
+        ("openai",         "STT", "in_process", "OPENAI_API_KEY"),
+        ("openai-tts",     "TTS", "in_process", "OPENAI_API_KEY"),
+    ]
+    for name, ptype, mode, req in rows:
+        print(f"  {name:<20}{ptype:<8}{mode:<14}{req}")
+    print()
+
+
+async def _repl_dispatch(tokens: list[str]) -> None:
+    """Dispatch a single REPL command."""
+    if not tokens:
+        return
+
+    cmd = tokens[0].lower()
+
+    if cmd in ("quit", "exit", "q"):
+        print(_c("Goodbye!", _GREEN))
+        sys.exit(0)
+
+    elif cmd == "help":
+        _print_repl_help()
+
+    elif cmd == "providers":
+        _print_providers()
+
+    elif cmd == "stt":
+        if len(tokens) < 2:
+            print(_c("Usage: stt <audio_file> [-p <provider>]", _YELLOW))
+            return
+        parser = argparse.ArgumentParser(prog="stt", add_help=False)
+        parser.add_argument("input")
+        parser.add_argument("-p", "--provider", default="faster-whisper")
+        parser.add_argument("--model-size", default="base")
+        parser.add_argument("--device", default="auto")
+        parser.add_argument("--words", action="store_true")
+        try:
+            parsed = parser.parse_args(tokens[1:])
+        except SystemExit:
+            return
+        await _cmd_stt(parsed)
+
+    elif cmd == "tts":
+        if len(tokens) < 2:
+            print(_c("Usage: tts <text> [-o output.wav] [-p <provider>]", _YELLOW))
+            return
+        parser = argparse.ArgumentParser(prog="tts", add_help=False)
+        parser.add_argument("text")
+        parser.add_argument("-o", "--output", default="output.wav")
+        parser.add_argument("-p", "--provider", default="openai-tts")
+        parser.add_argument("--voice", default="alloy")
+        parser.add_argument("--model", default="tts-1")
+        parser.add_argument("--play", action="store_true")
+        parser.add_argument("--play-device", default=None)
+        parser.add_argument("--play-volume", type=float, default=1.0)
+        parser.add_argument("--play-backend", default="auto")
+        parser.add_argument("--play-non-blocking", action="store_true")
+        try:
+            parsed = parser.parse_args(tokens[1:])
+        except SystemExit:
+            return
+        await _cmd_tts(parsed)
+
+    elif cmd == "roundtrip":
+        if len(tokens) < 2:
+            print(_c("Usage: roundtrip <text> [--tts <provider>] [--stt <provider>]", _YELLOW))
+            return
+        parser = argparse.ArgumentParser(prog="roundtrip", add_help=False)
+        parser.add_argument("text")
+        parser.add_argument("--tts", default="openai-tts")
+        parser.add_argument("--stt", default="faster-whisper")
+        parser.add_argument("--voice", default="alloy")
+        parser.add_argument("--model-size", default="base")
+        parser.add_argument("--device", default="auto")
+        parser.add_argument("--play", action="store_true")
+        parser.add_argument("--play-device", default=None)
+        parser.add_argument("--play-volume", type=float, default=1.0)
+        parser.add_argument("--play-backend", default="auto")
+        parser.add_argument("--play-non-blocking", action="store_true")
+        try:
+            parsed = parser.parse_args(tokens[1:])
+        except SystemExit:
+            return
+        await _cmd_roundtrip(parsed)
+
+    elif cmd == "compare":
+        if len(tokens) < 2:
+            print(_c("Usage: compare <audio_file> [-p provider1,provider2]", _YELLOW))
+            return
+        parser = argparse.ArgumentParser(prog="compare", add_help=False)
+        parser.add_argument("input")
+        parser.add_argument("-p", "--provider", default="faster-whisper")
+        parser.add_argument("--model-size", default="base")
+        parser.add_argument("--device", default="auto")
+        try:
+            parsed = parser.parse_args(tokens[1:])
+        except SystemExit:
+            return
+        await _cmd_compare(parsed)
+
+    else:
+        print(_c(f"Unknown command: {cmd}. Type 'help' for available commands.", _YELLOW))
+
+
+async def _repl_loop() -> None:
+    """Interactive REPL loop."""
+    print()
+    print(_c("OpenSpeech Interactive Demo", _BOLD + _GREEN))
+    print(_c("═" * 40, _DIM))
+    _print_repl_help()
+    print(_c("Type 'help' for commands, 'quit' to exit.", _DIM))
+    print()
+
+    while True:
+        try:
+            line = input(_c("> ", _BOLD + _GREEN))
+        except (EOFError, KeyboardInterrupt):
+            print()
+            print(_c("Goodbye!", _GREEN))
+            break
+
+        tokens = _parse_repl_line(line)
+        if not tokens:
+            continue
+
+        try:
+            await _repl_dispatch(tokens)
+        except KeyboardInterrupt:
+            print(_c("\nInterrupted.", _YELLOW))
+        except Exception as exc:  # noqa: BLE001
+            print(_c(f"Error: {exc}", _RED))
+
+
+def _cmd_repl(_args: Any) -> None:
+    """Entry point for REPL subcommand."""
+    asyncio.run(_repl_loop())
+
+
+def main() -> None:
+    _load_dotenv()
+
+    parser = argparse.ArgumentParser(
+        prog="openspeech-demo",
+        description="OpenSpeech interactive demo — STT, TTS, roundtrip, and compare.",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="<command>")
+    subparsers.required = True
+
+    # ── stt ──────────────────────────────────────────────────────────────────
+    stt_p = subparsers.add_parser("stt", help="Transcribe audio file to text")
+    stt_p.add_argument("-i", "--input", required=True, metavar="FILE", help="Input audio file")
+    stt_p.add_argument(
+        "-p", "--provider", default="faster-whisper",
+        metavar="PROVIDER", help="STT provider (default: faster-whisper)"
+    )
+    stt_p.add_argument(
+        "--model-size", default="base",
+        metavar="SIZE", help="Model size for faster-whisper (default: base)"
+    )
+    stt_p.add_argument(
+        "--device", default="auto",
+        metavar="DEVICE", help="Device for faster-whisper (default: auto)"
+    )
+    stt_p.add_argument(
+        "--words", action="store_true",
+        help="Show word-level timestamps"
+    )
+    stt_p.set_defaults(func=lambda a: asyncio.run(_cmd_stt(a)))
+
+    # ── tts ──────────────────────────────────────────────────────────────────
+    tts_p = subparsers.add_parser("tts", help="Synthesize text to audio file")
+    tts_p.add_argument("-t", "--text", required=True, metavar="TEXT", help="Input text")
+    tts_p.add_argument(
+        "-o", "--output", default="output.wav",
+        metavar="FILE", help="Output audio file (default: output.wav)"
+    )
+    tts_p.add_argument(
+        "-p", "--provider", default="openai-tts",
+        metavar="PROVIDER", help="TTS provider (default: openai-tts)"
+    )
+    tts_p.add_argument(
+        "--voice", default="alloy",
+        metavar="VOICE", help="Voice for openai-tts (default: alloy)"
+    )
+    tts_p.add_argument(
+        "--model", default="tts-1",
+        metavar="MODEL", help="Model for openai-tts (default: tts-1)"
+    )
+    tts_p.add_argument("--play", action="store_true", help="Play audio after synthesis")
+    tts_p.add_argument("--play-device", default=None, metavar="DEVICE", help="Playback device")
+    tts_p.add_argument(
+        "--play-volume", type=float, default=1.0, metavar="VOLUME", help="Playback volume"
+    )
+    tts_p.add_argument(
+        "--play-backend",
+        default="auto",
+        choices=["auto", "sounddevice", "external"],
+        metavar="BACKEND",
+        help="Playback backend",
+    )
+    tts_p.add_argument(
+        "--play-non-blocking",
+        action="store_true",
+        help="Do not block while playing audio",
+    )
+    tts_p.set_defaults(func=lambda a: asyncio.run(_cmd_tts(a)))
+
+    # ── roundtrip ─────────────────────────────────────────────────────────────
+    rt_p = subparsers.add_parser("roundtrip", help="TTS -> STT roundtrip test")
+    rt_p.add_argument("-t", "--text", required=True, metavar="TEXT", help="Input text")
+    rt_p.add_argument(
+        "--tts", default="openai-tts",
+        metavar="PROVIDER", help="TTS provider (default: openai-tts)"
+    )
+    rt_p.add_argument(
+        "--stt", default="faster-whisper",
+        metavar="PROVIDER", help="STT provider (default: faster-whisper)"
+    )
+    rt_p.add_argument(
+        "--voice", default="alloy",
+        metavar="VOICE", help="Voice for openai-tts (default: alloy)"
+    )
+    rt_p.add_argument(
+        "--model-size", default="base",
+        metavar="SIZE", help="Model size for faster-whisper (default: base)"
+    )
+    rt_p.add_argument(
+        "--device", default="auto",
+        metavar="DEVICE", help="Device for faster-whisper (default: auto)"
+    )
+    rt_p.add_argument("--play", action="store_true", help="Play synthesized audio before STT")
+    rt_p.add_argument("--play-device", default=None, metavar="DEVICE", help="Playback device")
+    rt_p.add_argument(
+        "--play-volume", type=float, default=1.0, metavar="VOLUME", help="Playback volume"
+    )
+    rt_p.add_argument(
+        "--play-backend",
+        default="auto",
+        choices=["auto", "sounddevice", "external"],
+        metavar="BACKEND",
+        help="Playback backend",
+    )
+    rt_p.add_argument(
+        "--play-non-blocking",
+        action="store_true",
+        help="Do not block while playing audio",
+    )
+    rt_p.set_defaults(func=lambda a: asyncio.run(_cmd_roundtrip(a)))
+
+    # ── compare ───────────────────────────────────────────────────────────────
+    cmp_p = subparsers.add_parser("compare", help="Compare multiple STT providers")
+    cmp_p.add_argument("-i", "--input", required=True, metavar="FILE", help="Input audio file")
+    cmp_p.add_argument(
+        "-p", "--provider", default="faster-whisper",
+        metavar="PROVIDERS", help="Comma-separated provider list (default: faster-whisper)"
+    )
+    cmp_p.add_argument(
+        "--model-size", default="base",
+        metavar="SIZE", help="Model size for faster-whisper (default: base)"
+    )
+    cmp_p.add_argument(
+        "--device", default="auto",
+        metavar="DEVICE", help="Device for faster-whisper (default: auto)"
+    )
+    cmp_p.set_defaults(func=lambda a: asyncio.run(_cmd_compare(a)))
+
+    # ── repl ──────────────────────────────────────────────────────────────────
+    repl_p = subparsers.add_parser("repl", help="Interactive REPL mode")
+    repl_p.set_defaults(func=_cmd_repl)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()