Skip to main content
Glama

Omniscribe

BETA (v1.0.0rc1). Experimental. Review the transcript and verify your audio routing before relying on it.

Status: release candidate v1.0.0rc2. Offline tests pass (67). Live capture on real hardware and with Deepgram has not been verified. Not published.

Omniscribe is a macOS command-line tool and local MCP server for live meeting transcription. It captures the remote side of an online meeting (through BlackHole) and your microphone, streams them to Deepgram with your own API key, and writes labelled, channel-tagged transcript files to a folder you choose. It can also help an assistant write a summary, one incremental step at a time.

  • Language: required, with no default. Set language = "id" for Indonesian in config.toml, or pass --language (CLI) / language (MCP) per session. Missing language is refused before consent, capture or upload.

  • Channels: REMOTE (meeting audio) and CAPTAIN (your microphone). Labels identify the channel, not individual speakers.

  • Modes: online (remote + microphone) and in-person (microphone only).

  • Recording: no raw audio is kept by default. Optional local WAV recording (record_wav) is off unless you turn it on.

  • Consent: every start and approve asks for a local, human yes on your Mac, whatever the consent setting says. A legacy consent = "all-meetings" does not skip the prompt. An MCP client cannot give consent.

Requirements

  • macOS, Python 3.11 or newer.

  • SoX with CoreAudio support (brew install sox).

  • BlackHole 16ch, for online mode only.

  • A Deepgram API key, for real transcription.

Related MCP server: openwhispr-transcribe

Install

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

This installs three commands: omniscribe, omniscribe-summary and omniscribe-mcp. Full audio setup is in the macOS setup guide.

Put your key in the environment, never in a file, flag or config:

export DEEPGRAM_API_KEY="YOUR_DEEPGRAM_API_KEY"

Create the private config in the output folder (default ~/.live-meeting-transcribe/):

mkdir -p "$HOME/.live-meeting-transcribe"
cp config.example.toml "$HOME/.live-meeting-transcribe/config.toml"

Quick start

Start a meeting. Omniscribe asks for consent before it connects or captures anything:

omniscribe start --name team-sync

For an in-person meeting, use the microphone only:

omniscribe start --name team-sync --mode in-person

Meeting names may contain letters, digits, _ and - (1 to 80 characters). A dated folder <YYYY-MM-DD>-<name>/ is created. Existing folders are never overwritten, so choose a new name for each meeting.

Prepare, then approve

prepare stages a session without capturing anything. approve then asks for the local yes:

omniscribe prepare --name team-sync --mode online
omniscribe approve

Typing no exits with code 2, removes the staged session, and creates no meeting folder. Closing the input without a yes (for example Ctrl-D) has the same result: exit code 2, the staged session removed, and no meeting folder. A missing or invalid language is also refused with exit code 2, before consent, before capture and before any upload, with a short message that names the setting to change. approve requires the key unless the session was prepared with --mock.

Stop

  • Press Ctrl-C in the capture terminal, or

  • from another terminal, with the same output root: omniscribe stop (add --wait to wait up to 2 seconds for the lock to clear).

Do not force-kill the process. Orderly shutdown finalises the transcript and removes the ACTIVE lock. After a crash, check that the process is gone before removing a stale ACTIVE file by hand.

Status

omniscribe status
omniscribe status --meeting-dir <folder>

This prints JSON: the lifecycle state (ACTIVE, PREPARED, STOPPED or IDLE), the session status and the summary coverage.

What it writes

Output root precedence: --out → OMNISCRIBE_HOME → LMT_HOME → ~/.live-meeting-transcribe. The config is <output_root>/config.toml unless --config is given.

Each meeting folder contains:

File

Contents

live.md

Labelled final lines (REMOTE / CAPTAIN). No interim text.

remote.jsonl (online only), captain.jsonl

Raw final recognition events with meeting offsets.

echo-dropped.txt

Captain lines removed by the echo filter, kept for audit.

status.json

Status snapshot: mode, language, streams, elapsed time, estimated cost.

stream.log

Session log written at shutdown.

full.txt

Final lines merged by start time.

README.md

Per-meeting caveats.

captain.wav, remote.wav

Only when record_wav = true or --record-wav.

live-summary.md, .cursor, .cursor.pending

Summary files, written only by the summary helper.

Summaries

Summary text is written by a person or an assistant, not by the capture tool. The helper omniscribe-summary only tracks which lines are covered:

omniscribe-summary delta <meeting-dir>    # stage the new lines
omniscribe-summary check <meeting-dir>    # validate the draft summary
omniscribe-summary commit <meeting-dir>   # advance the cursor if valid
omniscribe-summary status <meeting-dir>

A summary must start with Updated: HH:MM:SS | lines covered: N and contain the sections ## Summary, ## Actions, ## Decisions and ## Open questions. A failed check leaves the cursor where it was.

MCP server

omniscribe-mcp is a local stdio MCP server (server name omniscribe). It exposes five tools: omniscribe_prepare_session, omniscribe_get_status, omniscribe_stop_session, omniscribe_get_transcript_delta and omniscribe_save_summary. Setup examples are in examples/mcp/ for Claude, Codex and Pi.

The MCP server cannot start capture, cannot give consent, and rejects arguments named consent, approve, auto_approve, yes, api_key or deepgram_api_key. A prepared session still needs omniscribe approve in your terminal. The output root must contain config.toml, with language set there or passed in the tool call, before omniscribe_prepare_session works.

Configuration

Start from config.example.toml. Keys: consent, mode, language, mic, remote, echo, record_wav, exclude_titles, captain_highpass_hz, echo_text_threshold, echo_correlation_threshold. The full table is in the setup guide. Meetings whose exact name is listed in exclude_titles are refused.

Exit codes

Code

Meaning

0

Success.

1

Runtime or argument error, or a stream was DOWN at shutdown.

2

Refused before capture: key missing, excluded title, missing or invalid language, no typed at the consent prompt, or input closed without a yes (in which case a prepared session is also removed).

Privacy

Live sessions send both audio channels to Deepgram. Transcript text and service metadata are written under the output root. Keep that folder private, and get consent from the participants as your policy and local law require. Transcripts are not verbatim or legally verified records.

Limitations

  • Offline tests use local mocks and recorded WAV files. They do not test Deepgram, your devices or Zoom routing.

  • Recognition quality varies with the microphone, accent and room noise. Labels do not identify speakers.

  • The echo filter is heuristic, with provisional thresholds. It may miss speech or remove valid speech.

  • Audio can be lost during a reconnect. The client retries at most three times.

  • Estimated cost is a list-rate calculation, not a bill.

Development

python3 -m unittest discover -s tests -v

The offline suite needs no key and no devices. Run it with DEEPGRAM_API_KEY unset.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers