Initial commit: MeetRec — record & transcribe meetings with Whisper

- meetrec.py: CLI recorder with live rolling transcript (faster-whisper) - meetrec_gui.py: PySide6 GUI reusing the CLI's recording/transcription logic, with model/device/compute selection and live transcript - install.sh: local install into ~/.local (venv, deps, launchers, desktop entry), with --model/--no-model/--uninstall - bin/meetrec, bin/meetrec-cli: launchers - share/applications/meetrec.desktop: XDG desktop entry - README.md, requirements.txt, .gitignore
2026-09-07 09:38:32 +02:00
commit 18ce1c134c
9 changed files with 1143 additions and 0 deletions
@@ -0,0 +1,119 @@
+# MeetRec
+
+Record an in-person meeting and transcribe it with [Whisper](https://github.com/SYSTRAN/faster-whisper).
+
+Meetrec captures audio from any PipeWire/ALSA input (microphone, USB conference mic, USB audio interface, or a Pulse/PipeWire sink *monitor*) and produces transcripts in `txt`, `srt`, and `json`. It runs fully locally — no audio ever leaves your machine.
+
+Two interfaces:
+
+- **`meetrec.py`** — CLI: record, optionally show a live rolling transcript, and on `Ctrl+C` run a final higher-quality pass.
+- **`meetrec_gui.py`** — Qt (PySide6) GUI: device/model/language selection, level meter, live transcript, and one-click *Stop & transcribe*.
+
+## Output files
+
+With output stem `-o meeting`:
+
+| File               | Contents                                        |
+| ------------------ | ----------------------------------------------- |
+| `meeting.wav`      | raw recording (16 kHz mono WAV)                 |
+| `meeting.live.srt` | live rolling transcript (only with `--live > 0`) |
+| `meeting.txt`      | final transcript                                |
+| `meeting.srt`      | final transcript with timestamps                |
+| `meeting.json`     | final transcript, structured (language, segments) |
+
+## Requirements
+
+- Linux with an audio backend: **PipeWire** (or PulseAudio/ALSA). On Arch: `sudo pacman -S pipewire pipewire-pulse`
+- **Python 3.10+**
+- Python packages (installed for you by the install script): `numpy`, `sounddevice`, `faster-whisper`, `pyside6` (GUI only)
+- A GPU (CUDA) is optional — transcription falls back to CPU.
+
+## Installation
+
+### Quick install
+
+```sh
+./install.sh
+```
+
+This:
+
+1. copies the app to `~/.local/share/meetrec`,
+2. creates a venv and installs all dependencies,
+3. installs the `meetrec` (GUI) and `meetrec-cli` launchers into `~/.local/bin`,
+4. installs the XDG desktop entry (`~/.local/share/applications/meetrec.desktop`),
+5. pre-downloads the `small` Whisper model (first run is otherwise slow).
+
+Options:
+
+```sh
+./install.sh --model base        # pre-download a different model (tiny/base/small/medium/large-v3)
+./install.sh --no-model          # skip the model pre-download
+./install.sh --uninstall         # remove everything the installer created
+PREFIX=/opt/meetrec ./install.sh # install into a different prefix
+```
+
+### Manual install (venv)
+
+```sh
+sudo pacman -S python pipewire pipewire-pulse
+python3 -m venv .venv && source .venv/bin/activate
+pip install numpy sounddevice faster-whisper pyside6
+```
+
+## Usage
+
+### GUI
+
+```sh
+meetrec            # after ./install.sh
+# or from a checkout:
+python meetrec_gui.py
+```
+
+Pick a microphone (or type a name substring), model, language, and compute device/precision (switching model, device, or precision between recordings reloads the model automatically), press **Record**, watch the live transcript, then press **Stop & transcribe**.
+
+### CLI
+
+```sh
+meetrec-cli --list-sources                                  # find your input devices
+meetrec-cli -s "Conference Mic" --model small --live 8 -o meeting
+meetrec-cli -s monitor --model base --language en           # record system audio
+python meetrec.py --help                                    # all options
+```
+
+Key options:
+
+| Option          | Meaning                                                          |
+| --------------- | ---------------------------------------------------------------- |
+| `-s, --source`  | `default` or a substring of a device name (`--list-sources`)     |
+| `-m, --model`   | `tiny` / `base` / `small` / `medium` / `large-v3` (default `small`) |
+| `-o, --output`  | output file stem (default `meeting`)                             |
+| `--live SEC`    | live-transcription interval in seconds; `0` disables (default 8) |
+| `--language`    | force a language code, e.g. `en`, `de` (default: autodetect)     |
+| `--device`      | `auto` / `cpu` / `cuda` (default `auto`)                         |
+| `--compute-type`| `int8` / `int8_float16` / `float16` / `float32` (default `int8`) |
+
+`Ctrl+C` stops recording and runs the final transcription.
+
+### Tips
+
+- **Record system audio**: sink monitors appear as `<sink name>.monitor`; use `-s monitor` (or a matching substring).
+- **Model size vs. speed/accuracy**: `tiny`/`base` are fast and rough, `small` is a good default, `medium`/`large-v3` are most accurate but much slower on CPU.
+- Models are cached in `~/.cache/huggingface` and shared between the CLI and the GUI.
+
+## Project layout
+
+```
+meetrec.py            CLI: recording + live & final transcription
+meetrec_gui.py        PySide6 GUI (reuses meetrec.py's logic)
+requirements.txt      Python dependencies
+install.sh            install / uninstall into a local prefix
+bin/meetrec           GUI launcher (installed into ~/.local/bin)
+bin/meetrec-cli       CLI launcher (installed into ~/.local/bin)
+share/applications/meetrec.desktop   XDG desktop entry
+```
+
+## Privacy
+
+Everything runs locally. The only network access is the one-time Whisper model download from Hugging Face.