hearing.cli

Command-line interface for hearing, dispatched with argh.

Surfaces the Python facades (transcribe, summarize) as subcommands — it does not reimplement them (the facades are the SSOT; see the python-dispatching and hearing-architecture skills). Installed as the hearing console script:

hearing transcribe meeting.wav
hearing transcribe meeting.wav --model small --out notes.json
hearing summarize meeting.wav            # transcribe + AI meeting notes
hearing info                             # check what's installed/available

hearing.cli.info() → str

Report which optional components are installed and what’s missing.

hearing.cli.live(path: str | None = None, *, model: str = 'base', device: str | None = None, block_ms: int = 200, realtime: bool = False) → None

Run the LIVE streaming pipeline, printing segments as utterances finalize.

Parameters:

• path – stream this audio FILE through the live loop (great for a demo / no hardware). Omit to capture from an audio DEVICE instead.

• model – whisper model size for the streaming STT.

• device – audio device index/name for live capture (an Aggregate Device with mic + BlackHole; see the hearing-audio-capture skill).

• block_ms – streaming block size in milliseconds.

• realtime – when streaming a file, pace it in real time (else as-fast-as).

hearing.cli.main(argv=None) → None

Entry point for the hearing console script.

hearing.cli.meetings(store: str, *, show: str | None = None) → str

List transcripts saved in a store (or print one with –show ID).

Parameters:

• store – the store/folder a transcript was saved to (transcribe –save).

• show – a meeting id to print (formatted transcript) instead of listing.

hearing.cli.serve(*, host: str = '127.0.0.1', port: int = 8000, reload: bool = False) → None

Serve the HTTP API (FastAPI) the frontend talks to.

Parameters:

• host – bind address.

• port – bind port.

• reload – auto-reload on code changes (dev).

hearing.cli.summarize(path: str, *, agent: str = 'auto', model: str | None = None, context: str | None = None, context_dir: str | None = None, retriever: str = 'keyword', web_search: bool = False, transcribe_model: str = 'base', split: bool = True) → str | None

Transcribe a meeting and produce AI notes (summary, actions, questions).

Parameters:

• path – audio file to transcribe and analyze.

• agent – “auto” (Claude if available, else offline extractive), “claude”, or “extractive” (deterministic, no API key needed).

• model – Claude model id (only used by the claude/auto agent).

• context – optional literal context string to connect the agent.

• context_dir – a folder/file of .txt/.md context docs (prior takeaways, project notes); the agent does RAG over it (context-connected).

• retriever – “keyword” (TF-IDF, offline) or “embedding” (OpenAI semantic; needs hearing[openai] + OPENAI_API_KEY). Only used with context_dir.

• web_search – also bring in Wikipedia fact context (key-free) for the agent.

• transcribe_model – whisper model size used for transcription.

• split – split mic/system channels (me vs them).

hearing.cli.transcribe(path: str, *, engine: str = 'whisper', model: str = 'base', language: str | None = None, split: bool = True, diarize: bool = True, out: str | None = None, fmt: str = 'text', save: str | None = None) → str | None

Transcribe an audio file to text or JSON.

Parameters:

• path – audio file (wav/flac/aiff/…; convert mp3/m4a with ffmpeg first).

• engine – STT engine — “whisper” (local faster-whisper) or “openai” (cloud).

• model – whisper model size (tiny/base/small/medium/large-v3/…); local only.

• language – force a language code (e.g. “en”); omit to auto-detect.

• split – split mic/system channels for multi-channel files (me vs them).

• diarize – apply the channel-trick “me vs them” labelling.

• out – write to this path (.json -> JSON, else formatted text); else stdout.

• fmt – stdout/text format — “text” or “json”.

• save – persist the transcript to this store/folder (keyed by the file stem), so post-meeting agents can load the full transcript later.