Metadata-Version: 2.4
Name: bee-recorder
Version: 0.1.0b10
Summary: Local-first meeting recorder with AI transcription and speaker diarization
Author: Paulo Henrique
License: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Multimedia :: Sound/Audio
Classifier: Topic :: Multimedia :: Sound/Audio :: Capture/Recording
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: faster-whisper>=1.0
Requires-Dist: speechbrain>=1.0
Requires-Dist: silero-vad>=5.1
Requires-Dist: rich>=13.0
Requires-Dist: soundfile>=0.12
Requires-Dist: numpy>=1.24
Requires-Dist: scikit-learn>=1.3
Requires-Dist: torch>=2.0
Requires-Dist: torchaudio>=2.0
Requires-Dist: huggingface-hub>=0.20
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: summary
Requires-Dist: anthropic>=0.20; extra == "summary"
Provides-Extra: pyannote
Requires-Dist: pyannote.audio>=4.0; extra == "pyannote"

# 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`)

```bash
# 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

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

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

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

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

```bash
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 auto-detects new audio sinks during the call (e.g. you plug in AirPods mid-meeting), so you don't need to restart anything.

### 3. Stop and process

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

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

```bash
bee speakers weekly-2026-05-08
```

Then assign real names:

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

```bash
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](https://docs.claude.com/en/docs/claude-code) (must be installed and authenticated separately):

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

```toml
[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:

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