chore: stage the meeting transcription service for an install homeHEADmain

This is a self-hosted transcription service: whisper.cpp for the words, pyannote for the speaker labels. It has been running on ratio since 2026-09-17, with velox as the offline fallback. A systemd path unit watches a filesystem queue and starts a oneshot worker per job. There is no network listener. ssh is the transport, systemd is the daemon, and the filesystem is the queue.

It lands in working/ rather than its final home because two decisions come first. I haven't picked where the code lives in this repo. The Hugging Face token the diarization model needs on its first download also has to be handled, since anyone can read this repo.

Neither blocks the service, which already runs. Both block the install path this repo owes it.

The accompanying note lists what each machine needs. The torch venv is 1.3 GB and the whisper model is a separate download, so the note describes both rather than carrying them here.

1 files changed, 44 insertions, 0 deletions

diff --git a/working/meeting-transcription-service/2026-09-19-work-handoff.org b/working/meeting-transcription-service/2026-09-19-work-handoff.org
new file mode 100644
index 0000000..d4da1d9
--- /dev/null
+++ b/working/meeting-transcription-service/2026-09-19-work-handoff.org
@@ -0,0 +1,44 @@
+#+TITLE: Handoff from work: the meeting transcription service needs an install home
+#+AUTHOR: Craig Jennings
+
+* What this is
+A self-hosted meeting transcription service (whisper.cpp plus pyannote speaker diarization) that runs on
+ratio, with velox as the offline fallback. It has been running on both machines since 2026-09-17. The code
+arrives as meeting-transcription-service.tar.gz alongside this note. I picked archsetup as its home because
+it is machine setup: a worker, two systemd user units, a Python venv and a model file. The client script and
+its Emacs backend entry are handled separately.
+
+* How it works
+- A job queue under ~/.local/state/meeting-transcribe/ with incoming/, work/, done/ and failed/. A systemd
+  user path unit (meeting-transcribe.path) starts a oneshot worker (meeting-transcribe.service) when a job
+  lands in incoming/.
+- The worker (src/transcribe-worker) converts audio to 16 kHz mono, runs whisper-cli at word level, runs
+  pyannote (speaker-diarization-community-1) through src/diarize.py with the job's speaker count, and
+  merges the two by timestamp with src/merge_transcript.py. One job at a time, behind a lock.
+- A finished job leaves done/<id>.txt. A failed job leaves failed/<id>.log. Nothing half-written reaches done/.
+- No network listener. Tailscale ssh is the transport and the login, systemd is the daemon, the
+  filesystem is the queue.
+
+* What the install has to provide, per machine
+- ~/.local/share/pyannote-diarize/.venv :: Python 3.12, torch (CPU build), pyannote.audio 4.0.7. About
+  1.3 GB. Built with uv.
+- ~/.local/share/whisper-models/ggml-large-v3-turbo-q5_0.bin :: the whisper model; ratio's and velox's
+  copies have the same checksum. whisper-cpp itself must be installed (it was already on velox).
+- The src/ scripts placed where the units expect them, and the two user units enabled.
+- Linger on, so the path unit runs without a login session.
+- One-time, online, by hand: a Hugging Face token and acceptance of the pyannote model terms, so the
+  diarization model can be cached. After that neither machine needs Hugging Face. The token is a
+  credential: it must not be written into this repo, which is publicly cloneable.
+
+* State today
+- Installed by hand on ratio and velox; both verified. No NVIDIA GPU and no ROCm on ratio, so it is CPU only.
+- make check in the bundle runs pytest (129 tests; whisper, pyannote, ssh and scp are faked at the process
+  boundary), pyright and shellcheck. All green on 2026-09-19.
+- Known rough edge: when two local runs overlap, the second finds the lock held, the worker returns
+  silently, and the client says "finished without producing a transcript". Rerunning fixes it, but the
+  message should say the lock was held.
+
+* What I'm asking archsetup for
+Take ownership of the service side: the worker, diarize.py, merge_transcript.py, the two units, and an
+install step that builds the venv, fetches the model and enables the units on both daily drivers. Keep
+anything work-specific out of the repo; the code bundle has none (scanned before sending).