mattrguerra.comHouston area
Matt Guerra
  1. 01AI & Automation
  2. 02Photography
  3. 03Design
  4. 04About
  5. 05Notes
  6. 06Contact
Back to the systems

mattrguerra/transcription-pipelinemainPrivate on GitHub, published here in full

README.md

Markdown4.9 KB122 lines

README.md

  1. # transcription-pipeline
  3. [![tests](https://github.com/mattrguerra/transcription-pipeline/actions/workflows/tests.yml/badge.svg)](https://github.com/mattrguerra/transcription-pipeline/actions/workflows/tests.yml)
  5. Drop a recording in a folder; get back a transcript that says who said what,
  6. stamped to the word, filed where the rest of your notes live.
  8. ```
  9. inbox/ --launchd WatchPaths--> transcribe inbox
  10. 1. take files whose size has stopped changing; one run at a time (lock file)
  11. 2. ffmpeg any audio or video -> 16 kHz mono WAV
  12. 3. transcribe local: faster-whisper large-v3-turbo, int8 (default)
  13. deepinfra: hosted Whisper large-v3-turbo (optional)
  14. 4. align wav2vec2 forced alignment -> a start and end time for every word
  15. 5. diarize pyannote -> who spoke when; each word gets a speaker
  16. 6. shape sentences (split at punctuation and at every change of speaker),
  17. speakers renumbered "Speaker 1, 2, ..." by first appearance
  18. 7. write transcripts/<name>.txt .md .json (+ .srt .vtt); the .md also to a vault
  19. 8. file recording -> done/, or failed/ with <name>.error.txt
  20. ```
  22. Steps 3 to 5 are [WhisperX](https://github.com/m-bain/whisperX). The rest is
  23. this package: the watch folder, the sentence and speaker shaping, the writers,
  24. and the plumbing that makes it safe to leave running.
  26. ## What a transcript looks like
  28. From the integration test, which runs on two LibriSpeech readers taking turns
  29. (`tests/fixtures/two-speakers.flac`):
  31. ```
  32. [00:00:00] Speaker 1: for a full hour he had paced up and down waiting but he could wait no longer
  33. [00:00:06] Speaker 2: harangue the tiresome product of a tireless tongue
  34. [00:00:13] Speaker 1: pride after satisfaction uplifted him like long slow waves
  35. [00:00:19] Speaker 2: anger pain painful to hear
  36. ```
  38. The model returned that clip as one unpunctuated segment. It still comes out
  39. as four turns, because sentences are also split wherever the speaker changes.
  41. The `.md` is a vault note: this frontmatter, then one paragraph per speaker turn.
  42. The `.json` keeps every segment, every timed word and the run's metadata.
  44. ```markdown
  45. ---
  46. type: transcript
  47. title: "two-speakers"
  48. recorded: 2026-09-28
  49. transcribed: 2026-09-28T06:15:09
  50. duration: "0:00:24"
  51. engine: local
  52. language: en
  53. source: "two-speakers.flac"
  54. speakers:
  55. - "Speaker 1"
  56. - "Speaker 2"
  57. tags:
  58. - transcript
  59. ---
  60. ```
  62. ## Use it
  64. ```bash
  65. transcribe call.m4a # local, with speakers; outputs beside the file
  66. transcribe *.mp3 --out ~/transcripts --formats txt,srt
  67. transcribe interview.mov --speakers 2 # you know how many voices there are
  68. transcribe memo.m4a --no-diarize # just the words
  69. transcribe call.m4a --engine deepinfra # hosted Whisper; uploads the audio
  70. transcribe inbox --root ~/Transcription # what launchd runs
  71. ```
  73. ## Install
  75. ```bash
  76. python3.12 -m venv .venv && .venv/bin/pip install -e ".[test]"
  77. ```
  79. Python 3.10 to 3.13 (WhisperX does not support 3.14 yet). Tokens, the gated
  80. diarization model and the launchd job: [docs/SETUP.md](docs/SETUP.md).
  82. ## Tests
  84. ```bash
  85. pytest -q # unit tier: no network, no models (CI)
  86. TP_INTEGRATION=1 pytest -q tests/integration # real models; add HF_TOKEN for pyannote
  87. ```
  89. The integration tier checks every reference word, monotonic word times and the four
  90. turn boundaries on four utterances from LibriSpeech test-clean (Panayotov, Chen,
  91. Povey and Khudanpur, 2015), used under CC BY 4.0.
  93. ## Choices worth knowing
  95. - **Local by default.** DeepInfra's hosted Whisper has transcribed noticeably better
  96. than local int8 faster-whisper; use it when quality matters and uploading is fine.
  97. - **Timed to the word.** A sentence starts at its first aligned word; where nothing
  98. aligns, the time is interpolated and the JSON marks it `"timed": false`.
  99. - **Sentence rules pinned by a golden file.** `sentences.py` ports a JavaScript splitter;
  100. `tests/fixtures/sentences-golden.json` holds that splitter's output.
  101. - **Speakers.** Sentences split at every change of speaker; a one-word run is diarization
  102. noise; labels are renumbered by first appearance.
  103. - **Safe to leave running.** Settle window, one run at a time with stale-lock takeover,
  104. `failed/` with the reason, never an overwrite; tokens from the env or the Keychain.
  106. ## Layout
  108. | Path | What it is |
  109. |---|---|
  110. | `transcription_pipeline/` | The package: `cli`, `pipeline`, `inbox`, `audio`, `engines/`, `align`, `diarize`, `sentences`, `shape`, `render`, `filing`, `secrets`, `steps`. |
  111. | `tests/` | Unit tier (runs in CI) and `tests/integration` (real models on real speech). |
  112. | `scheduling/` | The launchd plist and the script it runs. |
  113. | `docs/SETUP.md` | Install, tokens, the watch folder. |
  115. ## Where it came from
  117. It grew out of a small DeepInfra transcriber with a one-page UI. The pipeline kept its
  118. sentence rules, `[HH:MM:SS]` lines and never-overwrite filing, and added the rest.
  120. ## License
  122. MIT.