SETUP.md

docs/SETUP.md

1. # Setup
3. Written for a Mac (Apple Silicon or Intel). Linux works the same apart from
4. the Keychain and launchd steps.
6. ## 1. Install
8. ```bash
9. git clone https://github.com/mattrguerra/transcription-pipeline.git ~/transcription-pipeline
10. cd ~/transcription-pipeline
11. python3.12 -m venv .venv # brew install python@3.12 if you don't have it
12. .venv/bin/pip install -e ".[test]"
13. ```
15. Use Python 3.10 to 3.13; 3.12 is the safest. WhisperX does not support 3.14
16. yet, and a newer Homebrew `python3` may be 3.14, so name the version.
18. This pulls in WhisperX, faster-whisper, pyannote.audio and PyTorch (a few GB).
19. No system ffmpeg is needed: the `imageio-ffmpeg` package ships its own binary,
20. and a Homebrew `ffmpeg` is used instead when there is one.
22. The first transcription downloads the models into `~/.cache/huggingface`:
23. faster-whisper large-v3-turbo (about 1.6 GB), the wav2vec2 alignment model for
24. the language, and the diarization model. Alignment also fetches NLTK's
25. `punkt_tab` sentence data once. After that everything runs offline, except
26. the DeepInfra engine if you choose it.
28. ## 2. Speaker separation: a Hugging Face token
30. pyannote's models are free but gated behind their terms.
32. 1. Make a Hugging Face account and a **read** token (Settings, Access Tokens).
33. 2. While signed in, open
34. [pyannote/speaker-diarization-community-1](https://huggingface.co/pyannote/speaker-diarization-community-1)
35. and accept the terms. (If you set `TP_DIARIZE_MODEL=pyannote/speaker-diarization-3.1`,
36. accept that model's terms and those of
37. [pyannote/segmentation-3.0](https://huggingface.co/pyannote/segmentation-3.0) instead.)
38. 3. Put the token in the Keychain:
40. ```bash
41. security add-generic-password -a "$USER" -s transcription-pipeline.huggingface -w
42. ```
44. `-w` with no value prompts for it, so the token never lands in shell history.
45. The pipeline reads `HF_TOKEN` from the environment first, then the Keychain.
46. Nothing is ever read from a file in the repo.
48. Without a token, run with `--no-diarize`: you get the transcript without
49. speaker labels.
51. ## 3. Optional: DeepInfra
53. Local transcription is the default and nothing leaves the machine. DeepInfra's
54. hosted Whisper large-v3-turbo is **recommended when quality matters most**: in
55. use it has transcribed noticeably better than faster-whisper running locally
56. with int8. The trade is that the audio is uploaded for that
57. one step (as 16 kHz FLAC). Alignment and speaker separation still run locally.
59. ```bash
60. security add-generic-password -a "$USER" -s transcription-pipeline.deepinfra -w
61. transcribe call.m4a --engine deepinfra
62. ```
64. or set `TP_ENGINE=deepinfra` for the watch folder. Errors come back in plain
65. words: a rejected or rotated key (401/403), rate limited or out of credit
66. (429), file too large (413).
68. ## 4. Check it works
70. ```bash
71. .venv/bin/pytest -q # unit tier, no models
72. TP_INTEGRATION=1 .venv/bin/pytest -q tests/integration # real models on real speech
73. ```
75. The integration tier transcribes `tests/fixtures/two-speakers.flac` (two
76. LibriSpeech readers, four turns). With the Hugging Face token in the
77. Keychain it also runs real pyannote diarization and checks that it finds both
78. voices and switches at the right words.
80. ## 5. The watch folder
82. ```bash
83. mkdir -p ~/Transcription/inbox
84. ```
86. 1. Edit `scheduling/run-inbox.sh`: `TP_ROOT`, `TP_VAULT_INBOX` (or delete that
87. line), `TP_ENGINE`.
88. 2. Copy `scheduling/com.example.transcription-pipeline.plist` to
89. `~/Library/LaunchAgents/`, replace `YOU` with your user name, and load it:
91. ```bash
92. launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.transcription-pipeline.plist
93. ```
95. Now anything dropped in `~/Transcription/inbox` is transcribed. The layout:
97. | Folder | What goes there |
98. |---|---|
99. | `inbox/` | Drop recordings here: any audio or video ffmpeg reads. |
100. | `transcripts/` | `.txt`, `.md`, `.json` (plus `.srt` / `.vtt` if you add them to `TP_FORMATS`). |
101. | `done/` | The recording, once transcribed. |
102. | `failed/` | The recording plus `<name>.error.txt` saying why. Move it back to `inbox/` to retry. |
104. The vault inbox gets a copy of the `.md` transcript, with frontmatter
105. (`type: transcript`, `recorded`, `duration`, `speakers`, `engine`, `source`),
106. so it flows into the rest of the vault like any other note.
108. To stop it: `launchctl bootout gui/$(id -u)/com.example.transcription-pipeline`.
109. The log is `~/Transcription/pipeline.log`.
111. ## Apple Silicon notes
113. - faster-whisper runs on the **CPU with int8**. CTranslate2 has no Metal
114. backend, so there is no GPU path for this step on a Mac.
115. - pyannote runs on the CPU. It supports MPS, but WhisperX's CPU path is the
116. one tested here.
117. - Keep the inbox outside iCloud Drive. With "Optimize Mac Storage" on, a
118. synced file can be a placeholder rather than the audio itself.