softvoice 0.1.0__py3-none-any.whl

softvoice/__init__.py

@@ -0,0 +1,3 @@
+"""softvoice: on-device voice in and out for Claude Code and Codex."""
+
+__version__ = "0.1.0"

softvoice/__main__.py

@@ -0,0 +1,3 @@
+from softvoice.cli import main
+
+main()

softvoice/autostart.py

@@ -0,0 +1,92 @@
+"""`softvoice autostart`: run the app as a macOS login item.
+
+A LaunchAgent in ~/Library/LaunchAgents starts `softvoice app` when you log in, with no terminal
+involved, and starts it again if it ever crashes (not after you quit it on purpose). Permissions
+are then attributed to the Python running softvoice rather than to a terminal, so macOS asks for
+them once more the first time.
+"""
+
+from __future__ import annotations
+
+import os
+import plistlib
+import re
+import subprocess
+from pathlib import Path
+
+from softvoice.config import HOME_DIR, ensure_home
+from softvoice.install import executable
+
+LABEL = "com.softvoice.app"
+PLIST_PATH = Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+APP_LOG = HOME_DIR / "app.log"
+
+
+def program() -> list[str]:
+    exe = executable()
+    if exe:
+        return [exe]
+    import sys
+
+    return [sys.executable, "-m", "softvoice"]
+
+
+def plist(extra_args: list[str] | tuple[str, ...] = ()) -> dict:
+    return {
+        "Label": LABEL,
+        "ProgramArguments": [*program(), "app", *extra_args],
+        "RunAtLoad": True,
+        "KeepAlive": {"SuccessfulExit": False},  # back after a crash; not after Quit
+        "ProcessType": "Interactive",
+        "LimitLoadToSessionType": "Aqua",
+        "StandardOutPath": str(APP_LOG),
+        "StandardErrorPath": str(APP_LOG),
+        "EnvironmentVariables": {
+            "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin",
+            "PYTHONUNBUFFERED": "1",
+            "SOFTVOICE_LAUNCHD": "1",  # lets the app know a crash-exit brings it back
+        },
+    }
+
+
+def _domain() -> str:
+    return f"gui/{os.getuid()}"
+
+
+def _launchctl(*args: str) -> subprocess.CompletedProcess:
+    return subprocess.run(["launchctl", *args], capture_output=True, text=True)
+
+
+def enable(extra_args: list[str] | tuple[str, ...] = ()) -> Path:
+    """Write the LaunchAgent and load it, which also starts the app now."""
+    ensure_home()
+    PLIST_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with PLIST_PATH.open("wb") as fh:
+        plistlib.dump(plist(extra_args), fh)
+    _launchctl("bootout", f"{_domain()}/{LABEL}")  # a previous version, if any; fine when there is none
+    result = _launchctl("bootstrap", _domain(), str(PLIST_PATH))
+    if result.returncode != 0:
+        raise RuntimeError(f"launchctl bootstrap failed: {result.stderr.strip() or result.stdout.strip()}")
+    return PLIST_PATH
+
+
+def disable() -> bool:
+    """Unload (which stops the app) and remove the LaunchAgent. False when there was none."""
+    existed = PLIST_PATH.exists()
+    _launchctl("bootout", f"{_domain()}/{LABEL}")
+    if existed:
+        PLIST_PATH.unlink()
+    return existed
+
+
+def status() -> dict:
+    """{'installed': bool, 'loaded': bool, 'pid': int | None, 'state': str | None}"""
+    info = {"installed": PLIST_PATH.exists(), "loaded": False, "pid": None, "state": None}
+    result = _launchctl("print", f"{_domain()}/{LABEL}")
+    if result.returncode == 0:
+        info["loaded"] = True
+        pid = re.search(r"^\s*pid = (\d+)", result.stdout, re.M)
+        state = re.search(r"^\s*state = (\w+)", result.stdout, re.M)
+        info["pid"] = int(pid.group(1)) if pid else None
+        info["state"] = state.group(1) if state else None
+    return info

softvoice/clean.py

@@ -0,0 +1,152 @@
+"""Turn an agent's markdown reply into text that sounds natural when read aloud.
+
+Code blocks, tables, URLs and long paths are dropped or shortened: you look at the
+screen for those. Anything that looks like a secret is replaced before it reaches a
+speaker.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_FENCE = re.compile(r"```.*?```|~~~.*?~~~", re.DOTALL)
+_HTML = re.compile(r"<[^>\n]{1,200}>")
+_IMAGE = re.compile(r"!\[([^\]]*)\]\([^)]*\)")
+_LINK = re.compile(r"\[([^\]]+)\]\([^)]*\)")
+_URL = re.compile(r"https?://[^\s)>\]]+")
+_INLINE_CODE = re.compile(r"`([^`\n]*)`")
+_HEADING = re.compile(r"^\s{0,3}#{1,6}\s*(.*?)\s*#*\s*$", re.MULTILINE)
+_BULLET = re.compile(r"^\s*(?:[-*+•]|\d{1,3}[.)])\s+", re.MULTILINE)
+_QUOTE = re.compile(r"^\s*>\s?", re.MULTILINE)
+_RULE = re.compile(r"^\s*([-*_])(?:\s*\1){2,}\s*$", re.MULTILINE)
+_TABLE_ROW = re.compile(r"^\s*\|.*\|\s*$", re.MULTILINE)
+_EMPHASIS = re.compile(r"(\*\*|__|\*|_|~~)(?=\S)(.+?)(?<=\S)\1")
+_CHECKBOX = re.compile(r"\[( |x|X)\]\s*")
+# Something with at least two path separators, or a dotted filename with a line number.
+_PATH = re.compile(r"(?<![\w./-])(?:~|\.{1,2})?[\w.@-]*(?:/[\w.@-]+){2,}(?::\d+(?::\d+)?)?")
+_FILE_LINE = re.compile(r"\b([\w-]+\.[a-z]{1,5}):(\d+)(?::\d+)?\b")
+_MULTISPACE = re.compile(r"[ \t]+")
+_MULTINEWLINE = re.compile(r"\n{2,}")
+_SENTENCE_END = re.compile(r"(?<=[.!?])\s+")
+
+_SECRETS = [
+    re.compile(p)
+    for p in (
+        r"\bsk-(?:ant-)?[A-Za-z0-9_-]{16,}\b",  # OpenAI / Anthropic style keys
+        r"\bgh[pousr]_[A-Za-z0-9]{20,}\b",  # GitHub tokens
+        r"\bAKIA[0-9A-Z]{16}\b",  # AWS access keys
+        r"\bxox[baprs]-[A-Za-z0-9-]{10,}\b",  # Slack tokens
+        r"\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b",  # JWTs
+        r"\b[A-Fa-f0-9]{32,}\b",  # long hex: hashes, API keys
+        r"(?<![\w/+])[A-Za-z0-9+/]{40,}={0,2}(?![\w/+])",  # long base64 blobs
+        r"(?i)\b(?:password|passwd|secret|token|api[_-]?key)\s*[:=]\s*\S+",
+    )
+]
+
+_SYMBOLS = [
+    (re.compile(r"\s*->\s*"), " to "),
+    (re.compile(r"\s*=>\s*"), " gives "),
+    (re.compile(r"\s*&&\s*"), " and "),
+    (re.compile(r"\s*\|\|\s*"), " or "),
+    (re.compile(r"(?<=\w)/(?=\w)"), " or "),  # "input/output" -> "input or output"
+]
+
+
+@dataclass
+class Cleaned:
+    text: str
+    truncated: bool
+    dropped_code_blocks: int
+
+
+def clean(markdown: str, max_chars: int = 700, truncation_suffix: str = "More on screen.") -> Cleaned:
+    """Return speakable text for a markdown reply. Empty text means: nothing worth saying."""
+    text = markdown.replace("\r\n", "\n").replace("\r", "\n")
+
+    dropped = len(_FENCE.findall(text))
+    text = _FENCE.sub("\n", text)
+    # An unterminated fence: drop from the fence to the end.
+    if "```" in text:
+        text = text.split("```", 1)[0]
+        dropped += 1
+
+    text = _TABLE_ROW.sub("", text)
+    text = _HTML.sub("", text)
+    text = _IMAGE.sub(lambda m: m.group(1), text)
+    text = _LINK.sub(lambda m: m.group(1), text)
+    text = _URL.sub("link", text)
+    text = _INLINE_CODE.sub(_inline_code, text)
+    text = _HEADING.sub(lambda m: _sentence(m.group(1)), text)
+    text = _RULE.sub("", text)
+    text = _QUOTE.sub("", text)
+    text = _CHECKBOX.sub("", text)
+    text = _BULLET.sub("", text)
+    for _ in range(2):  # nested emphasis like ***x*** or **_x_**
+        text = _EMPHASIS.sub(lambda m: m.group(2), text)
+    text = _FILE_LINE.sub(lambda m: f"{m.group(1)} line {m.group(2)}", text)
+    text = _PATH.sub(_path_basename, text)
+
+    for pattern in _SECRETS:
+        text = pattern.sub("redacted", text)
+    for pattern, replacement in _SYMBOLS:
+        text = pattern.sub(replacement, text)
+
+    # Every line becomes a sentence so the voice pauses between bullets.
+    lines = [_sentence(line.strip()) for line in text.split("\n")]
+    text = " ".join(line for line in lines if line)
+    text = _MULTISPACE.sub(" ", text).strip()
+    text = re.sub(r"\s+([.,;:!?])", r"\1", text)
+    text = re.sub(r"([.!?])\1+", r"\1", text)
+
+    truncated = False
+    if max_chars and len(text) > max_chars:
+        text = _cut_at_sentence(text, max_chars)
+        truncated = True
+        if truncation_suffix:
+            text = f"{text} {truncation_suffix}"
+
+    # Nothing but code or symbols: say nothing.
+    if not re.search(r"[A-Za-z]{2,}", text):
+        text = ""
+    return Cleaned(text=text, truncated=truncated, dropped_code_blocks=dropped)
+
+
+def _inline_code(match: re.Match) -> str:
+    code = match.group(1).strip()
+    if not code or len(code) > 40:
+        return ""
+    return code
+
+
+def _path_basename(match: re.Match) -> str:
+    path = match.group(0)
+    line = ""
+    if ":" in path:
+        path, _, rest = path.partition(":")
+        line = f" line {rest.split(':')[0]}"
+    name = path.rstrip("/").rsplit("/", 1)[-1]
+    return f"{name}{line}" if name else ""
+
+
+def _sentence(line: str) -> str:
+    line = line.strip()
+    if not line:
+        return ""
+    if line[-1] not in ".!?:;,":
+        line += "."
+    elif line[-1] in ":;,":
+        line = line[:-1] + "."
+    return line
+
+
+def _cut_at_sentence(text: str, max_chars: int) -> str:
+    head = text[:max_chars]
+    parts = _SENTENCE_END.split(head)
+    if len(parts) > 1:
+        kept = " ".join(parts[:-1]).strip()
+        if len(kept) >= max_chars // 3:
+            return kept
+    # No sentence boundary in range: cut at a word.
+    cut = head.rsplit(" ", 1)[0].rstrip(",;:")
+    return cut + "."

softvoice/cli.py

@@ -0,0 +1,391 @@
+"""Command-line entry point. Heavy imports stay inside the commands that need them."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+from softvoice import __version__
+from softvoice.config import CONFIG_PATH, LOG_PATH, Config, write_default_config
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="softvoice", description="On-device voice in and out for Claude Code and Codex.")
+    parser.add_argument("--version", action="version", version=f"softvoice {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p = sub.add_parser("serve", help="run the speaker daemon (normally started for you)")
+    p.add_argument("--foreground", "-f", action="store_true", help="log to the terminal as well")
+
+    p = sub.add_parser("say", help="speak text through the daemon")
+    p.add_argument("text", nargs="*", help="text to speak; reads stdin when omitted")
+    p.add_argument("--raw", action="store_true", help="skip markdown cleaning")
+    p.add_argument("--out", metavar="WAV", help="write a WAV file instead of speaking (loads the model in-process)")
+
+    sub.add_parser("stop", help="stop speaking and clear the queue")
+    sub.add_parser("mute", help="stay silent until unmuted")
+    sub.add_parser("unmute", help="speak again")
+    sub.add_parser("status", help="show daemon state")
+    sub.add_parser("restart", help="stop the daemon; the next hook starts a fresh one")
+    sub.add_parser("quit", help="stop the daemon")
+    p = sub.add_parser("voice", help="switch the voice for this daemon run")
+    p.add_argument("name", help="a predefined voice name or a WAV path to clone")
+    sub.add_parser("voices", help="list predefined voices")
+    p = sub.add_parser("log", help="show the daemon log")
+    p.add_argument("-n", type=int, default=40)
+
+    sub.add_parser("hook", help="agent hook entry: reads the hook JSON on stdin")
+    p = sub.add_parser("notify", help="Codex legacy notify entry: JSON as an argument")
+    p.add_argument("payload")
+
+    sub.add_parser("setup", help="download the models and ask macOS for the permissions, so the first run is instant")
+    p = sub.add_parser("install", help="write hooks into Claude Code and Codex settings")
+    p.add_argument("--claude-only", action="store_true")
+    p.add_argument("--codex-only", action="store_true")
+    sub.add_parser("uninstall", help="remove softvoice hooks")
+    sub.add_parser("config", help="print the config file path and contents")
+
+    p = sub.add_parser("listen", help="push-to-talk: hold the hotkey, speak, release to paste")
+    p.add_argument("--hotkey", help="the talk key: alt_r, fn, f5, or a combination such as alt+space")
+    p.add_argument("--auto-submit", action="store_true", help="press Enter after pasting")
+    p.add_argument("--no-paste", action="store_true", help="print transcripts instead of pasting")
+    p.add_argument("--hands-free", action="store_true", help="after each spoken reply, open the mic and send what you say")
+    p = sub.add_parser("app", help="menu bar app: a mic icon that shows whose turn it is, with Talk, Stop, Mute, Hands-free")
+    p.add_argument("--hotkey", help="the talk key: alt_r, fn, f5, or a combination such as alt+space")
+    p.add_argument("--auto-submit", action="store_true", help="press Enter after push-to-talk pastes")
+    p.add_argument("--no-paste", action="store_true", help="print transcripts instead of pasting")
+    hf = p.add_mutually_exclusive_group()
+    hf.add_argument("--hands-free", dest="hands_free", action="store_true", default=None)
+    hf.add_argument("--no-hands-free", dest="hands_free", action="store_false")
+    p = sub.add_parser("autostart", help="run the app as a login item: starts at login, no terminal, back after a crash")
+    p.add_argument("action", nargs="?", choices=["on", "off", "status"], default="status")
+    p.add_argument("--hands-free", action="store_true", help="start hands-free (or set hands_free = true in the config)")
+    p = sub.add_parser("transcribe", help="transcribe an audio file with Parakeet")
+    p.add_argument("file")
+
+    args = parser.parse_args(argv)
+    return COMMANDS[args.cmd](args)
+
+
+# -- speaking -----------------------------------------------------------------------
+
+def cmd_serve(args) -> int:
+    from softvoice.daemon import serve
+
+    return serve(foreground=args.foreground)
+
+
+def cmd_say(args) -> int:
+    text = " ".join(args.text) if args.text else sys.stdin.read()
+    if not text.strip():
+        print("nothing to say", file=sys.stderr)
+        return 1
+    if args.out:
+        import soundfile as sf
+
+        from softvoice.clean import clean
+        from softvoice.tts import Speaker
+
+        cfg = Config.load()
+        spoken = text if args.raw else clean(text, cfg.max_chars, cfg.truncation_suffix).text
+        speaker = Speaker(cfg)
+        t0 = time.monotonic()
+        audio = speaker.synthesize(spoken)
+        sf.write(args.out, audio, speaker.sample_rate)
+        print(f"wrote {args.out}: {len(audio) / speaker.sample_rate:.1f}s audio in {time.monotonic() - t0:.1f}s")
+        return 0
+    return _send({"cmd": "speak", "text": text, "raw": args.raw, "meta": {"event": "say"}})
+
+
+def cmd_simple(cmd: str, **fields):
+    def run(args) -> int:
+        return _send({"cmd": cmd, **fields}, autostart=cmd not in ("stop", "quit", "mute", "unmute"))
+
+    return run
+
+
+def cmd_status(args) -> int:
+    from softvoice.client import alive, send
+
+    if not alive():
+        print("daemon: not running")
+        return 1
+    print(json.dumps(send({"cmd": "status"}, autostart=False), indent=2))
+    return 0
+
+
+def cmd_restart(args) -> int:
+    from softvoice.client import alive, send
+
+    from softvoice.config import PID_PATH
+
+    old_pid = None
+    try:
+        old_pid = int(PID_PATH.read_text().strip() or 0) or None
+    except (OSError, ValueError):
+        pass
+    if alive():
+        send({"cmd": "quit"}, autostart=False)
+    for _ in range(100):  # wait for the old process itself, not just its socket
+        if not alive() and not (old_pid and _pid_running(old_pid)):
+            break
+        time.sleep(0.1)
+    from softvoice.client import ensure_daemon
+
+    ok = ensure_daemon()
+    print("daemon restarted" if ok else "daemon did not come up; see: softvoice log")
+    return 0 if ok else 1
+
+
+def _pid_running(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+
+
+def cmd_voice(args) -> int:
+    return _send({"cmd": "voice", "voice": args.name})
+
+
+def cmd_voices(args) -> int:
+    from softvoice.tts import PREDEFINED_VOICES
+
+    print("\n".join(PREDEFINED_VOICES))
+    print("\nOr pass a path to a short WAV of a voice to clone. Set `voice` in", CONFIG_PATH)
+    return 0
+
+
+def cmd_log(args) -> int:
+    if not LOG_PATH.exists():
+        print("no log yet")
+        return 0
+    lines = LOG_PATH.read_text(errors="replace").splitlines()
+    print("\n".join(lines[-args.n:]))
+    return 0
+
+
+def _send(req: dict, autostart: bool = True) -> int:
+    from softvoice.client import DaemonUnavailable, send
+
+    try:
+        resp = send(req, autostart=autostart)
+    except DaemonUnavailable as exc:
+        print(exc, file=sys.stderr)
+        return 1
+    if not resp.get("ok"):
+        print(resp.get("error", "failed"), file=sys.stderr)
+        return 1
+    extras = {k: v for k, v in resp.items() if k != "ok"}
+    if extras:
+        print(json.dumps(extras))
+    return 0
+
+
+# -- hooks --------------------------------------------------------------------------
+
+def _hook_payload(raw: str) -> int:
+    """Shared by `hook` (stdin) and `notify` (argv). Never fails loudly: agents must not notice us."""
+    if os.environ.get("SOFTVOICE_DISABLED"):
+        return 0
+    try:
+        payload = json.loads(raw) if raw.strip() else {}
+        cfg = Config.load()
+        from softvoice.client import send
+        from softvoice.hooks import interpret
+
+        action = interpret(payload, cfg.speak_notifications, cfg.interrupt_on_prompt,
+                           whole_turn=cfg.speak_whole_turn, interim_min_chars=cfg.interim_min_chars)
+        if action.kind == "speak":
+            send({"cmd": "speak", "text": action.text, "meta": action.meta})
+        elif action.kind == "stop":
+            send({"cmd": "stop", "reason": "prompt"}, autostart=False)
+    except Exception as exc:  # log and stay silent: stdout must stay clean for Codex
+        try:
+            from softvoice.config import HOME_DIR, ensure_home
+
+            ensure_home()
+            with open(HOME_DIR / "hook.log", "a") as fh:
+                fh.write(f"{time.strftime('%F %T')} {type(exc).__name__}: {exc}\n")
+        except OSError:
+            pass
+    return 0
+
+
+def cmd_hook(args) -> int:
+    return _hook_payload(sys.stdin.read())
+
+
+def cmd_notify(args) -> int:
+    return _hook_payload(args.payload)
+
+
+def cmd_setup(args) -> int:
+    """Everything that would otherwise happen, slowly, the first time you use it."""
+    from huggingface_hub import hf_hub_download
+
+    from softvoice import permissions
+
+    cfg = Config.load()
+    print(f"config: {write_default_config()}")
+
+    t0 = time.monotonic()
+    print(f"Pocket TTS ({cfg.language}, voice {cfg.voice}): about 230 MB the first time", flush=True)
+    from softvoice.tts import Speaker
+
+    Speaker(cfg)
+    print(f"  ready in {time.monotonic() - t0:.0f}s")
+
+    t0 = time.monotonic()
+    print(f"Parakeet ({cfg.stt_model}): 2.5 GB the first time", flush=True)
+    for name in ("config.json", "model.safetensors"):  # the same two files parakeet-mlx loads
+        hf_hub_download(cfg.stt_model, name)
+    print(f"  ready in {time.monotonic() - t0:.0f}s")
+
+    print("Permissions (granted to the app this terminal belongs to):")
+    try:
+        import sounddevice as sd
+
+        with sd.InputStream(channels=1, samplerate=16000):  # makes macOS ask for the microphone now
+            time.sleep(0.3)
+        print("Microphone: opened")
+    except Exception as exc:
+        print(f"Microphone: could not open ({exc})")
+    permissions.check_and_request(need_paste=True, need_hotkey=True)
+    print("Next: `softvoice install` adds the hooks, then `softvoice app --hands-free` starts the pill.")
+    return 0
+
+
+def cmd_install(args) -> int:
+    from softvoice import install as inst
+
+    write_default_config()
+    command = inst.hook_command()
+    print(f"hook command: {command}")
+    if not args.codex_only:
+        path, backup = inst.install_claude(command)
+        print(f"Claude Code: hooks written to {path}" + (f" (backup {backup.name})" if backup else ""))
+        print("  Restart Claude Code sessions to pick them up.")
+    if not args.claude_only:
+        result = inst.install_codex(command)
+        if result:
+            path, backup = result
+            print(f"Codex: hooks written to {path}" + (f" (backup {backup.name})" if backup else ""))
+            print("  Run /hooks inside Codex once to trust them.")
+        else:
+            print("Codex: ~/.codex not found, skipped. When you install Codex, run `softvoice install --codex-only`.")
+    print(f"config: {CONFIG_PATH}")
+    return 0
+
+
+def cmd_uninstall(args) -> int:
+    from softvoice import install as inst
+
+    for label, fn in (("Claude Code", inst.uninstall_claude), ("Codex", inst.uninstall_codex)):
+        path = fn()
+        print(f"{label}: {'removed from ' + str(path) if path else 'nothing to remove'}")
+    return 0
+
+
+def cmd_config(args) -> int:
+    path = write_default_config()
+    print(path)
+    print(path.read_text())
+    return 0
+
+
+# -- listening ----------------------------------------------------------------------
+
+def cmd_listen(args) -> int:
+    from softvoice.ptt import listen
+
+    cfg = Config.load()
+    return listen(cfg, hotkey=args.hotkey or cfg.hotkey, auto_submit=args.auto_submit or cfg.auto_submit,
+                  paste=not args.no_paste, hands_free=args.hands_free or cfg.hands_free)
+
+
+def cmd_app(args) -> int:
+    from softvoice.menubar import run_app
+
+    cfg = Config.load()
+    hands_free = cfg.hands_free if args.hands_free is None else args.hands_free
+    return run_app(cfg, hotkey=args.hotkey or cfg.hotkey, auto_submit=args.auto_submit or cfg.auto_submit,
+                   paste=not args.no_paste, hands_free=hands_free)
+
+
+def cmd_autostart(args) -> int:
+    from softvoice import autostart, instance
+
+    if args.action == "on":
+        other = instance.running_pid()
+        if other:
+            print(f"stopping the running copy (pid {other}) so the login item starts it fresh ...", flush=True)
+            if not instance.quit(other):
+                print("it did not stop; quit it yourself and run this again")
+                return 1
+        path = autostart.enable(["--hands-free"] if args.hands_free else [])
+        time.sleep(1.5)
+        st = autostart.status()
+        print(f"login item: {path}")
+        running = f" and is running now (pid {st['pid']})" if st.get("pid") else ""
+        print(f"softvoice app starts at every login{running}. Output: {autostart.APP_LOG}")
+        print("If macOS asks for the microphone, Accessibility or Input Monitoring again, that is because the app")
+        print("now runs under Python instead of your terminal. Grant them once and they stick.")
+        return 0
+    if args.action == "off":
+        if autostart.disable():
+            print("login item removed and the app stopped. `softvoice app` starts it by hand.")
+        else:
+            print("no login item was installed.")
+        return 0
+    st = autostart.status()
+    if not st["installed"]:
+        print("not installed. `softvoice autostart on` makes the app start at login.")
+    else:
+        where = f"running (pid {st['pid']})" if st.get("pid") else ("loaded, not running" if st["loaded"] else "installed, not loaded")
+        print(f"login item {autostart.PLIST_PATH}: {where}")
+    return 0
+
+
+def cmd_transcribe(args) -> int:
+    from softvoice.stt import Transcriber
+
+    cfg = Config.load()
+    t = Transcriber(cfg.stt_model)
+    t0 = time.monotonic()
+    text = t.transcribe_file(Path(args.file))
+    print(text)
+    print(f"[{time.monotonic() - t0:.2f}s]", file=sys.stderr)
+    return 0
+
+
+COMMANDS = {
+    "serve": cmd_serve,
+    "say": cmd_say,
+    "stop": cmd_simple("stop", reason="cli"),
+    "mute": cmd_simple("mute"),
+    "unmute": cmd_simple("unmute"),
+    "status": cmd_status,
+    "restart": cmd_restart,
+    "quit": cmd_simple("quit"),
+    "voice": cmd_voice,
+    "voices": cmd_voices,
+    "log": cmd_log,
+    "hook": cmd_hook,
+    "notify": cmd_notify,
+    "setup": cmd_setup,
+    "install": cmd_install,
+    "uninstall": cmd_uninstall,
+    "config": cmd_config,
+    "listen": cmd_listen,
+    "app": cmd_app,
+    "autostart": cmd_autostart,
+    "transcribe": cmd_transcribe,
+}