scriba

Free, local, accurate meeting transcription with speaker recognition — for your AI assistant or second brain.
Drop a file path into your AI agent's chat — or run one command in your terminal — and get a clean, speaker-labeled transcript. Works with Claude Code, Codex, Cursor, Aider & others via AGENTS.md, or as a plain CLI with no AI at all. Everything runs on your Mac: no cloud, no uploads, no subscription.

Contents

• Why
• How this compares
• What you'll get
• Install
• Usage
• Limitations
• Advanced — for power users
• License · Acknowledgments

Why

• Your audio never leaves your computer. Nothing is uploaded to any cloud — not Otter, not AssemblyAI, not OpenAI, not us. Transcription and speaker recognition run locally on your Mac (or Linux box).
• Works with anything. Zoom recordings, voice memos, podcast files, phone call exports — .mp4, .mov, .m4a, .mp3, .wav, .webm, you name it. The skill handles the format conversion for you.
• Accurate speaker recognition — and honest about it. "Who said what" runs on pyannote's speaker-diarization-community-1 — one of the most accurate open-source diarization models (its authors report ~10–11% DER on standard benchmarks), picked so it runs on a normal Mac (M3 / 16 GB), not only a top-end M-Max. A heavier model (DiariZen-WavLM) edges it on some English benchmarks but costs a lot more compute; scriba favors the accuracy/footprint balance. Words come from OpenAI Whisper large-v3. Don't take our word for it — measure it on your own audio with scripts/benchmark_der.py.
• You can actually see it working. Live progress in your editor's statusline, in a side terminal, or as a macOS notification when it's done — pick what you like. No more staring at a black screen wondering if it's stuck.
• Just one command. No setup steps to learn. The assistant walks you through anything you don't have yet (HuggingFace account, etc.) in plain language.
• Built to be run automatically. Point a launchd/cron watcher at your Zoom or Meet recordings folder — every call becomes a searchable transcript that flows into your second brain / personal AI knowledge base (Obsidian, Notion, Cognee, mem0, whatever you use). The more conversations you capture and feed your assistant, the sharper its answers about you get. See Karpathy on personal Wikis for the broader idea.

How this compares

"…and how sure it is": every word in the JSON sidecar carries an ASR confidence, a speaker-attribution confidence, and an overlap flag, so your AI knows which lines to trust and which to treat as shaky. And you can put a number on the diarization itself — benchmarks/ ships a pure-Python DER scorer you run on your own labeled audio.

What you'll get

A portable <title>.transcript/ folder next to your input video, holding the Markdown plus its assets, with a 10-second voice clip per speaker embedded right in the file (click ▶ to play in Obsidian / VS Code / GitHub):

# q3-planning-sync

## Speakers — identify who's who

**Speaker 1** (80% of speaking time).
<audio controls src="data/speaker-1.wav"></audio>

Sample utterances:
> [00:00:03] «So the launch is moved to Friday — can we ship the docs by Thursday?»
> [00:00:40] «...»

**Speaker 2** (18% of speaking time).
<audio controls src="data/speaker-2.wav"></audio>
...

The assistant then asks you "who's Speaker 1?" — you answer, and it renames them everywhere in the transcript.

Install

git clone https://github.com/AlexanderAbramovPav/scriba ~/.claude/skills/scriba

That's it. Don't pre-configure anything. The first time you transcribe, the assistant will pause and walk you through a one-time ~30-second step: creating a free HuggingFace account and pasting a token back into the chat. Three clicks in a browser, no terminal commands. You'll never see it again after that.

Why HuggingFace? It's the open-source equivalent of an app store for AI models. The speaker-recognition model is free, but its authors require accepting a usage agreement once — pretty standard for research-grade open source.

Don't use Claude Code? Use it with anything else

The core of scriba is a bash + Python pipeline. The "skill" layer is a thin wrapper that helps an AI agent guide you through setup and speaker naming — and there's a tool-agnostic version of those instructions in AGENTS.md, supported by most modern AI coding tools.

AGENTS.md is becoming a de-facto standard for cross-tool AI agent instructions — same role as SKILL.md but vendor-neutral. The bash CLI works in any environment, with or without an AI driving it.

Usage

Easiest path is Claude Code (other agents & the plain CLI: see Use it with anything else above). Open Claude Code, type:

/scriba /path/to/your-meeting.mp4

Now you can walk away. The assistant runs the transcription in the background. While it's working:

• Live status is visible inline in your chat statusline (something like 🎙 tx 47% · ETA 01:18), updated every few seconds.
• A macOS notification pops up when it's done (Glass sound).
• Or open a side terminal and run the same command with --watch for a full-screen progress view.

_{Live progress streams right into Claude Code's “Shell details” — current stage, % and ETA update as it runs (even while diarization is quiet).}

When it finishes, the assistant opens the result and shows you the speakers it found. For each one you get:

• A short voice clip (~10 seconds, click play in the chat / your editor — <audio> is embedded right in the Markdown).
• Three sample sentences with timestamps.

The assistant asks "who is who?" — you answer (e.g. "Speaker 1 is Alice, Speaker 2 is Bob") — it renames them everywhere in the transcript. Done.

Where files go

Each recording becomes a self-contained, portable folder next to your input file:

your-meeting.transcript/      ← move/zip/sync this whole folder; nothing breaks
├── your-meeting.md           ← the transcript (H1 title + frontmatter)
└── data/
    ├── transcript.json       ← rich machine-readable sidecar (per-word confidence, speakers)
    └── speaker-1.wav …       ← one ≤10 s voice clip per speaker, embedded in the MD

The MD points at data/… with relative paths, so the folder travels as a unit — open your-meeting.md in any Markdown viewer (Obsidian, VS Code, GitHub) and the embedded <audio> players just work.

The folder/file name is meaningful: it's derived from your video's name (kebab-cased). When the source name is generic (zoom_0, GMT20260605-120000, recording, …), the assistant picks a real title for you. The original filename is always preserved in the source: frontmatter field.

Alongside your recordings, a hidden .scriba/ folder holds corpus-wide state your AI uses to navigate everything: index.json (one entry per recording — read once, find any meeting), plus the glossary and persistent voiceprints. Full layout in references/file-layout.md.

Beyond one-off meetings — run it automatically

The slash-command flow is the easy path. If you want every conversation captured automatically, point a small watcher at whatever folder your meeting tool dumps recordings into:

# Watch ~/Documents/Zoom/, transcribe new .m4a or .mp4 files
fswatch -0 ~/Documents/Zoom | while read -d '' f; do
  case "$f" in *.m4a|*.mp4)
    bash ~/.claude/skills/scriba/scripts/transcribe.sh "$f" ;;
  esac
done

Then point your second-brain tool (Obsidian, Cognee, mem0, Notion AI, …) at the *.transcript/*.md files and you have a personal, private, searchable corpus of everything that's been said in your meetings — feeding back into AI assistants the way Karpathy described a personal Wiki. The more conversations the assistant can reach, the more it sounds like you and the better it answers questions about your world.

Limitations

• Two speakers who sound similar (e.g. brothers, or two soft-spoken voices) may be merged into one.
• Heavy background music or three+ people speaking simultaneously degrades speaker boundaries.
• Apple Silicon strongly recommended. Intel Macs work but are ~3× slower; Linux works (no macOS notification, no MLX fast-mode).
• First run downloads ~3 GB of models — plan accordingly on metered connections.
• Languages other than English and Russian are auto-detected and transcribed, but speaker recognition quality hasn't been benchmarked specifically per language.

Advanced — for power users

Everything below is optional. The slash command flow above is what 99% of people need.

Run the bash directly

bash scripts/transcribe.sh <media-file> [--fast] [--speakers N] [--lang XX] [--model M]

Speaker renaming after the fact:

python3 scripts/rename_speakers.py meeting.transcript/meeting.md "Alice,Bob,Carol"
# or explicit mapping:
python3 scripts/rename_speakers.py meeting.transcript/meeting.md --map "Speaker 1=Alice,Speaker 2=Bob"

Monitoring surfaces

Pick the channel that fits your workflow. All read the same source of truth (*.transcript.progress.json next to the input — auto-deleted on successful completion together with *.transcript.log, so you're left with only the human-facing <title>.transcript/ folder. Diagnostic files are kept only when something fails).

Performance — how long will it take?

Rule of thumb: a 1-hour recording takes roughly 1 hour on an M4 Max, ~1.5 h on an M2 Max, ~2 h on an M1. First run is slower (~5 min one-time model download); after that, the skill auto-calibrates to your machine's actual speed and the next ETA is anchored to your measured rate.

The model: wall_clock ≈ audio_sec × factor + warmup, where factor is the wall-clock-per-audio-second ratio for the full pipeline (transcribe + align + diarize). Anchored to one observed M4 Max run = 1.0× (Jun 2026, batch_size=1, int8 compute_type). Other chips scaled from public CPU benchmarks — starting estimates only; the calibration cache at ~/.config/scriba/calibration.json replaces the value with the actual observed rate after the first ≥60 s run.

Intel and unknown CPUs fall back to 2.0×. Linux works (degraded: no macOS notification, no native MLX) — same factor table applies, the cache corrects after the first run.

Have a chip not in this table, or a measurably different rate? See CONTRIBUTING.md — adding a row is a one-line PR.

How it works

1. transcribe.sh extracts the input to 16 kHz mono WAV via ffmpeg.
2. transcribe_whisperx.py calls whisperX with verbose=True, which prints Transcript: [start --> end] text per segment as it's decoded.
3. The wrapper bypasses whisperX's DiarizationPipeline and calls pyannote.audio.Pipeline directly with a custom TextProgressHook so each pyannote sub-step (segmentation, embeddings, clustering, speaker_counting, discrete_diarization) reports its real completed/total counters as plain text.
4. A bash ticker scans the log every 5 s and writes the canonical *.progress.json.
5. All monitoring surfaces read that one JSON.
6. On exit, json_to_md.py turns the JSON into Markdown inside <title>.transcript/, ffmpeg cuts one ≤10 s WAV clip per speaker into its data/ folder for the embedded <audio> players, the JSON sidecar is copied there too, and update_index.py upserts the recording into .scriba/index.json. See references/file-layout.md.

License

MIT — © 2026 Alexander Abramov. Source & issues: https://github.com/AlexanderAbramovPav/scriba

Runtime dependencies (whisperX, pyannote.audio, faster-whisper, CTranslate2, OpenAI Whisper, ffmpeg) are installed locally, not vendored. Their licenses are catalogued in THIRD_PARTY_LICENSES.md.

One model has an attribution clause: the default diarization pipeline pyannote/speaker-diarization-community-1 is CC-BY-4.0. If you redistribute output produced with this skill, include a short attribution:

Speaker diarization powered by pyannote/speaker-diarization-community-1 by Hervé Bredin / pyannoteAI, licensed under CC-BY-4.0.

Acknowledgments

This skill is glue around four excellent OSS projects:

• whisperX — Max Bain et al. — word-level alignment + diarization orchestration on top of faster-whisper.
• pyannote.audio — Hervé Bredin et al. — neural speaker diarization.
• faster-whisper — SYSTRAN — the actual ASR engine, CTranslate2-backed.
• OpenAI Whisper — OpenAI — the acoustic model.

And on uv (Astral) for the bootstrap, and ffmpeg for everything audio-shaped.