hearing.cli

Command-line interface for hearing, dispatched with cw.

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 transcribe meeting.wav --engine deepgram   # or openai / mlx / parakeet / whisperx
hearing summarize meeting.wav            # transcribe + AI meeting notes
hearing info                             # check what's installed/available

Functions

info()

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

live([path, engine, model, device, ...])

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

main([argv])

Entry point for the hearing console script.

meetings(store, *[, show])

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

serve(*[, host, port, reload])

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

summarize(path, *[, agent, model, context, ...])

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

transcribe(path, *[, engine, model, ...])

Transcribe an audio file to text or JSON.
hearing.cli.info()[source]

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

Return type:

str

hearing.cli.live(path=None, *, engine='whisper', model=None, device=None, block_ms=200, realtime=False)[source]

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

Parameters:

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

  • engine (str) – STT engine (same choices as transcribe --engine); engines without native streaming are fed VAD-segmented utterances.

  • model (Optional[str]) – STT model override (omit for the engine’s default).

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

  • block_ms (int) – streaming block size in milliseconds.

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

Return type:

None

hearing.cli.main(argv=None)[source]

Entry point for the hearing console script.

cw.run returns the exit code (argh’s parser.dispatch exited by itself), so the SystemExit here is what makes hearing no-such-command exit 2.

Return type:

None

hearing.cli.meetings(store, *, show=None)[source]

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

Parameters:

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

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

Return type:

str

hearing.cli.serve(*, host='127.0.0.1', port=8000, reload=False)[source]

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

Parameters:

  • host (str) – bind address.

  • port (int) – bind port.

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

Return type:

None

hearing.cli.summarize(path, *, agent='auto', model=None, context=None, context_dir=None, retriever='keyword', web_search=False, engine='whisper', transcribe_model=None, split=True)[source]

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

Parameters:

  • path (str) – audio file to transcribe and analyze.

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

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

  • context (Optional[str]) – optional literal context string to connect the agent.

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

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

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

  • engine (str) – STT engine (same choices as transcribe --engine).

  • transcribe_model (Optional[str]) – STT model override (omit for the engine’s default).

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

Return type:

Optional[str]

hearing.cli.transcribe(path, *, engine='whisper', model=None, language=None, split=True, diarize=True, out=None, fmt='text', save=None)[source]

Transcribe an audio file to text or JSON.

Parameters:

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

  • engine (str) – STT engine — “whisper” (local faster-whisper, default), “openai” (cloud), “deepgram” (cloud, Nova-3), “mlx” (Whisper on Apple Silicon), “parakeet” (Parakeet-TDT on Apple Silicon), or “whisperx” (aligned words).

  • model (Optional[str]) – engine model override — a whisper size (tiny/base/small/large-v3/…) for whisper/mlx/whisperx, a model name for cloud engines (e.g. “nova-3”); omit for the engine’s default.

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

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

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

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

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

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

Return type:

Optional[str]