Skip to main content
Glama
README.md
# Omniscribe

> **BETA (v1.0.0rc1).** Experimental. Review the transcript and verify your audio routing before relying on it.
> <!-- PRE-RELEASE: remove this line and the "Status" block before publication. -->
> **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.

## Install

```sh
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](docs/SETUP-macOS.md).

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

```sh
export DEEPGRAM_API_KEY="YOUR_DEEPGRAM_API_KEY"
```

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

```sh
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:

```sh
omniscribe start --name team-sync
```

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

```sh
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`:

```sh
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

```sh
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:

```sh
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/](examples/mcp/) for [Claude](examples/mcp/claude.md), [Codex](examples/mcp/codex.md) and [Pi](examples/mcp/pi.md).

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](docs/SETUP-macOS.md). 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

```sh
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](LICENSE).