Bee Recorder

Local-first meeting recorder for Linux. Captures system audio (Google Meet, Teams, Zoom, Discord, etc.) and your microphone in parallel, then transcribes everything with Whisper and identifies who said what with SpeechBrain — all on your machine. No audio leaves your computer, no API keys, no HuggingFace token.

The product is the transcript itself: a Markdown file you can read and a JSON file you can feed to any LLM later for analysis.

Features

• Fully local — Whisper for transcription, SpeechBrain ECAPA-TDNN for speaker diarization. Nothing uploaded.
• Zero-friction setup — bee setup detects your hardware (RAM, GPU) and picks a Whisper model that will run well, then downloads it (~1.6 GB).
• Channel-aware diarization — microphone audio is diarized into Mic_00, Mic_01, ... (works for in-person meetings where multiple people share one mic), and remote participants from system audio are diarized into Speaker_00, Speaker_01, ...
• Interactive labeling — after processing, Bee shows representative quotes per speaker so you can match Mic_00/Speaker_00 to real names.
• Two outputs per recording — <id>.md (human-readable) and <id>.json (structured for automation/LLM consumption).
• Auto language detection — works out of the box in any language Whisper supports.

Requirements

• Linux with PulseAudio or PipeWire (Ubuntu, Fedora, Debian, Arch, Mint, Pop!_OS, etc.)
• Python 3.10+
• ffmpeg and pulseaudio-utils (for pactl)

# Ubuntu / Debian
sudo apt install ffmpeg pulseaudio-utils python3 python3-venv

# Fedora
sudo dnf install ffmpeg-free pulseaudio-utils python3

# Arch
sudo pacman -S ffmpeg libpulse python

macOS and Windows are not supported today (the audio capture layer relies on PulseAudio/PipeWire).

Install

pipx install bee-recorder
bee setup       # detects hardware, downloads Whisper + SpeechBrain models
bee doctor      # verifies ffmpeg, audio server, models, config

Or with plain pip inside a venv:

python3 -m venv ~/.venvs/bee
~/.venvs/bee/bin/pip install bee-recorder
~/.venvs/bee/bin/bee setup

Choosing how speakers are separated

bee setup asks which diarization backend to use. Both keep your audio on your machine — the difference is only whether a model download needs an account.

Mode	Quality	Account needed
local (default)	Good — SpeechBrain ECAPA-TDNN	No, fully offline
pyannote	Best — pyannote community-1	Yes, a free Hugging Face read token, once

To skip the prompt:

bee setup --diarization local        # nothing ever leaves the machine
bee setup --diarization pyannote     # prompts for the token, then downloads

pyannote needs the optional extra, and you must accept the model terms at https://huggingface.co/pyannote/speaker-diarization-community-1 first:

pipx install --pip-args='--pre' "bee-recorder[pyannote]"

The token only authorizes the one-time model download; the token is stored in the standard Hugging Face location (~/.cache/huggingface/token), and once the model is cached, diarization runs offline. If the extra is missing, the token is rejected, or you skip the prompt, setup falls back to local rather than leaving a config that fails mid-transcription.

From the git checkout, scripts/install.sh takes the same choice as --local / --huggingface (it asks if you pass neither, and defaults to --local under --yes).

Recording a meeting

1. Start the recording before joining

bee start -n weekly-2026-05-08

The name is optional — without -n, Bee uses a timestamp ID. Add --no-mic if you want to capture only the system audio.

2. Join the meeting normally

Bee runs in the background and captures whatever your audio output and microphone produce. It follows device changes during the call — plug in AirPods, switch to a headset mic — and stitches every device onto a single timeline when you stop, so a mid-meeting switch costs you a couple of seconds, not the rest of the call. You don't need to restart anything.

3. Stop and process

bee stop

This stops the capture and runs:

1. Whisper transcription (mic + system audio)
2. SpeechBrain diarization on both audio streams (mic + system)
3. Merging — mic speakers become Mic_XX, remote participants become Speaker_XX

How long it takes depends on the meeting length and your hardware. Measured with the default large-v3-turbo on a 20-thread CPU with int8 and no GPU: ~3.7× real time per channel. Bee transcribes both the mic and the system channel, so a 1-hour meeting takes roughly 30 minutes end to end. With a GPU, much faster.

If you want to stop now and process later:

bee stop --no-process
bee process weekly-2026-05-08    # transcribe + diarize on demand

4. Label the participants

After processing, Bee prints a table of representative quotes per speaker. To re-print it any time:

bee speakers weekly-2026-05-08

Then assign real names:

bee label weekly-2026-05-08 Mic_00="Alice" Speaker_00="Bob (Acme Corp)" Speaker_01="Carol (Acme Corp)"

The label rewrites both the JSON and Markdown transcripts in place.

5. Read or share the transcript

bee show weekly-2026-05-08       # prints metadata + transcript
bee show weekly-2026-05-08 -t    # transcript only
bee list                          # all recordings

Output files

Each recording lives in its own folder under ~/Documents/bee/<YYYY-MM-DD>/<YYYY-MM-DD HH:MM [name]>/:

File	Contents
mic.wav, system.wav	Raw audio captured during the meeting
metadata.json	Recording metadata (id, started_at, display_name, sources, etc.)
transcript.md	Human-readable transcript with timestamps and speaker labels
transcript.json	Structured transcript with metadata header (duration, language, speakers, segments) for automation and LLM consumption
transcript_summary.md	(Optional) summary produced by bee summarize

Everything for a single meeting stays in one folder, so you can re-process or share it as a unit.

Optional: AI summary

Bee does not generate summaries by default — the transcript is the deliverable. If you want a quick summary, the summarize command shells out to the Claude Code CLI (must be installed and authenticated separately):

bee summarize "~/Documents/bee/2026-05-08/2026-05-08 14:30 weekly/transcript.md"

This produces transcript_summary.md next to the transcript.

For richer analyses (action items, sentiment, decisions), feed the JSON transcript into your LLM of choice. The structured format is designed for that.

Command reference

Command	What it does
bee start -n <name>	Start recording
bee start --no-mic	Capture system audio only
bee stop	Stop and process (transcribe + diarize + ask to label)
bee stop --no-process	Just stop the recording
bee stop --no-diarize	Skip diarization (faster, no speaker labels)
bee stop --no-identify	Don't prompt for participant names interactively
bee process <id>	(Re)process a stopped recording
bee speakers <id>	Show preview quotes per detected speaker
bee label <id> SPEAKER_00=Name ...	Rename speakers in a transcript
bee show <id>	Print transcript and metadata
bee list	List all recordings
bee summarize <file>	Generate a Claude summary (requires Claude CLI)
bee watch	Watch the transcripts folder and auto-summarize new files
bee setup	First-time setup: hardware detection + model download
bee setup --diarization local	Setup with fully offline speaker separation (no account)
bee setup --diarization pyannote	Setup with pyannote (prompts for a free Hugging Face token)
bee doctor	Health check (ffmpeg, audio server, models, config)
bee models list	Show available and installed models
bee models download <name>	Download a specific Whisper or diarization model
bee models usage	Show disk usage of downloaded models

Configuration

Bee stores its config at ~/.config/bee/config.toml. Defaults are written by bee setup:

[whisper]
model = "large-v3-turbo"         # live pass, during recording
final_model = "large-v3-turbo"   # final pass, produces the transcript you read
device = "auto"                  # auto, cpu, cuda
language = "auto"                # auto-detect, or "pt", "en", "es", ...
hotwords = ""                    # comma-separated domain vocabulary

[audio]
sample_rate = 16000
channels = 1

[processing]
retranscribe = true     # redo the full audio with final_model on `bee stop`
echo_dedup = true       # drop meeting audio echoed back into the microphone

[diarization]
backend = "ecapa"       # ecapa (fully local), pyannote (best), auto

You can change the model later (bee models download large-v3 and edit the config), or change the language to skip detection. Run bee doctor after editing.

whisper.hotwords biases decoding toward terms Whisper would otherwise mangle — product names, jargon, people's names. The meeting name and any speaker labels you set are added automatically, so this is for vocabulary that recurs across every meeting:

hotwords = "QI Tech, Selic, CNAB, Pix, KYC"

processing.retranscribe controls what the final transcript comes from. With true (default), bee stop re-transcribes the whole audio with final_model — the live transcript is only a preview, produced in 60s chunks with no cross-chunk context. Set it to false to keep the live segments and only transcribe the tail, which is much faster but noticeably less accurate.

processing.echo_dedup removes duplicated speech when the meeting audio plays through loudspeakers instead of headphones: the microphone picks up the remote participants, so every remote utterance gets transcribed twice — once correctly from the system channel and once attributed to you. Bee measures the bleed and drops the echoed copies. Turn it off only if you record two genuinely independent channels.

diarization.backend accepts:

• ecapa — the local SpeechBrain pipeline. No token, no account.
• pyannote — best quality. Errors out if pyannote or its model is unavailable, so problems surface loudly.
• auto — try pyannote, silently fall back to ecapa. This is the default for configs written before the backend was selectable.

Privacy

Everything runs locally. Audio files, transcripts, and models all live on your disk. Network traffic is limited to downloading models when you run bee setup.

With the default local diarization, every model download is anonymous and no token is required. If you opt into pyannote, the one-time download of its gated model authenticates with a free Hugging Face token; the audio itself is still never uploaded.

License

MIT