rek 0.1.1__tar.gz

rek-0.1.1/PKG-INFO

@@ -0,0 +1,241 @@
+Metadata-Version: 2.3
+Name: rek
+Version: 0.1.1
+Summary: Local English transcription and speaker diarization with ONNX Runtime
+Requires-Dist: huggingface-hub>=1.33.0
+Requires-Dist: librosa>=1.0.0
+Requires-Dist: numpy>=2.5.3
+Requires-Dist: onnxruntime>=1.31.1
+Requires-Dist: sherpa-onnx>=2.0.1
+Requires-Dist: sounddevice>=0.5.6
+Requires-Dist: soundfile>=0.14.0
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/gardner/rek
+Project-URL: Issues, https://github.com/gardner/rek/issues
+Description-Content-Type: text/markdown
+
+# rek
+
+[GitHub repository](https://github.com/gardner/rek) · [Issues](https://github.com/gardner/rek/issues)
+
+Record your microphone, then transcribe locally with timestamps and speaker labels.
+Inference uses ONNX Runtime (with [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) for ASR),
+with Core ML acceleration by default on macOS and CPU inference on Linux/Windows.
+There is no MLX, PyTorch, or CUDA dependency.
+
+- [Parakeet TDT 0.6B v2 INT8](https://huggingface.co/csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8)
+  transcribes **English only**.
+- [Nemotron 3 Diarization ONNX](https://huggingface.co/onnx-community/Nemotron-3-Diarization-ONNX)
+  detects up to eight speakers directly, replacing both Pyannote segmentation and
+  TitaNet embeddings/clustering. It runs in 27.2-second chunks with 3.2 seconds of
+  look-ahead and an arrival-order speaker cache carried across the full recording.
+  The NumPy/librosa frontend and cache follow the model's Transformers implementation;
+  PyTorch is not needed. Speaker activity is thresholded at 0.5 on 10 ms frames,
+  including overlapping speakers.
+
+Nemotron uses the FP32 graph and its external weights (about 398 MB), pinned to
+revision `353b6f8ad2cac3580e982d7fbdf0a010786b0406`. Both files are downloaded into
+the same cache directory so ONNX Runtime can resolve the external weights.
+The model is distributed under the [OpenMDW 1.1 license](https://huggingface.co/onnx-community/Nemotron-3-Diarization-ONNX/blob/main/README.md).
+
+
+The dependencies are intended for macOS, Linux, and Windows. This ONNX migration
+has **not been runtime-tested**, including on Linux or Windows.
+
+## Run
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and FFmpeg
+(see below). From this checkout, install the command once:
+
+```sh
+uv tool install .
+```
+
+Then just give it a filename:
+
+```sh
+rek "Voice Memo.m4a"
+```
+
+No model, language, device, speaker-count, or tuning flags are required. The command
+downloads the models if needed, decodes and normalizes the audio, detects speakers,
+transcribes speech, and saves both text and JSON in a new `recordings/<timestamp>/`
+directory under your current working directory. It prints the transcript and output
+location when finished. First use needs internet access for the model downloads.
+If your shell cannot find `rek` after installation, run `uv tool update-shell`
+and reopen your terminal.
+
+You can also run directly from the checkout without installing the command:
+
+```sh
+uv run main.py "Voice Memo.m4a"
+```
+
+The defaults are:
+
+| Setting | Default |
+| --- | --- |
+| Hardware | Core ML on macOS; CPU on Linux/Windows |
+| Speech recognition | English Parakeet v2 INT8, greedy decoding |
+| Speaker detection | Nemotron 3 FP32, up to eight speakers automatically |
+| Diarization windows | Published offline settings: 27.2 s + 3.2 s look-ahead, persistent speaker cache |
+| Speaker activity | Probability above 0.5, at 10 ms resolution |
+| Transcription windows | 30 s with 2 s context on each side |
+| Audio | Automatic mono mixing and resampling to 16 kHz |
+| Output | Timestamped text and JSON; existing output folders are never overwritten |
+
+These use the model's published settings and bounded inference windows; they are
+starting defaults, not benchmark-tuned settings for a particular machine.
+
+Run `rek` without a filename to record your default microphone until **Ctrl+C**.
+Start speaking when you see **“Recording”**. Ctrl+C finishes saving the WAV and starts
+transcription. There is no duration limit or `--seconds` option.
+
+The project uses Python 3.14; uv can install it automatically. Built-in model revisions
+are pinned. Later runs reuse the Hugging Face cache, and audio stays on your computer.
+To relocate the cache, set `HF_HOME`. For offline use, populate the cache first,
+then set `HF_HUB_OFFLINE=1`.
+
+Overrides are optional, mainly for troubleshooting or changing the destination:
+
+```sh
+rek meeting.wav --output-dir recordings/meeting
+rek meeting.wav --device cpu
+rek --help
+```
+
+The older `--input filename` syntax remains supported.
+
+`--asr-model` accepts a compatible sherpa-onnx Parakeet v2 INT8 Hugging Face
+repository or local directory containing `encoder.int8.onnx`, `decoder.int8.onnx`,
+`joiner.int8.onnx`, and `tokens.txt`. MLX repositories are no longer compatible.
+
+M4A (AAC or Apple Lossless), WAV, FLAC, and other formats supported by libsndfile can
+be used as input. M4A decoding uses FFmpeg automatically, without changing the
+original file or creating an intermediate WAV. FFmpeg must be on PATH:
+
+- macOS: `brew install ffmpeg`
+- Debian/Ubuntu: `sudo apt install ffmpeg`
+- Windows: `winget install Gyan.FFmpeg` (reopen your terminal after installation)
+
+Stereo files are mixed to mono and resampled to 16 kHz. Parakeet v2 is English-only;
+`--language en` is optional, and other languages are rejected. Transcription starts
+after recording ends. Long audio is decoded in 30-second windows with two seconds
+of context on either side. Words are retained by their timestamp midpoint within
+each window, with timestamps relative to the full recording. Chunk boundaries
+can still affect recognition.
+
+## Output
+
+Each run creates a new `recordings/<timestamp>/` directory containing:
+
+- `recording.wav`: 16 kHz mono audio (microphone mode only).
+- `transcript.txt`: readable timestamped speaker turns, also printed to the terminal.
+- `transcript.json`: transcript, individual word timestamps, raw speaker turns,
+  model IDs, diarization graph filename, backends, requested device, and the original audio path.
+
+Example format:
+
+```text
+[00:00:00.100 - 00:00:02.300] Speaker 1: Hello, everyone.
+[00:00:02.500 - 00:00:03.800] Speaker 2: Hi there.
+```
+
+Speaker labels are anonymous and apply to one recording; they do not identify
+people by name. Parakeet's timestamped subword pieces are joined into complete
+words, preserving punctuation. Words are assigned to the speaker with the greatest
+total time overlap. Ties, missing word timestamps, and unmatched words are labelled
+`Unknown`. Token end times use TDT durations when available; otherwise they are
+estimated from the next token's start or the end of the chunk.
+Overlapping voices can reduce accuracy: this script does not separate mixed voices.
+When diarization detects no speech, transcription is skipped. Microphone audio is
+written to disk as you record; the completed recording is loaded into memory for
+inference. CPU inference can take longer than the recording.
+
+Existing output directories are refused to prevent overwriting recordings. If model
+loading or inference fails, a completed microphone recording remains available;
+retry it with `--input path/to/recording.wav`. Ctrl+C during recording saves and
+transcribes the captured audio; Ctrl+C during model loading or transcription cancels
+processing and preserves the recording. Stopping before any audio arrives reports
+an empty recording instead of starting inference.
+
+## Devices and troubleshooting
+
+`--device auto` requests the ONNX Runtime Core ML provider on macOS for both
+transcription and diarization, and CPU elsewhere. `--device coreml`, `--device mps`,
+and `--device gpu` explicitly request Core ML on macOS. `--device cpu` forces CPU
+on every platform. CUDA is not configured in this project.
+
+[Core ML](https://onnxruntime.ai/docs/execution-providers/CoreML-ExecutionProvider.html)
+can use Apple hardware acceleration; it is not PyTorch's MPS backend. Core ML chooses
+the compute hardware, and unsupported ONNX operations run on CPU. In particular,
+quantized Parakeet operations may remain on CPU: selecting Core ML does not guarantee
+that the whole model runs on the GPU or that inference is faster. The bundled macOS
+runtime includes Core ML support. Nemotron uses the Python ONNX Runtime package
+and falls back to CPU with a warning if Core ML is unavailable in that runtime.
+Custom sherpa-onnx runtimes without Core ML may also fall back to CPU.
+The JSON `device` field records the requested provider, not measured hardware usage.
+Core ML model compilation can add startup time. Use `--device cpu` if initialization
+fails or acceleration performs poorly. No acceleration benchmarks were run.
+
+If microphone capture fails, check the system's default input device and grant
+microphone access to your terminal/app. macOS and Windows sounddevice wheels include
+PortAudio. Linux may need `libportaudio2` and `libsndfile1` installed using the system
+package manager. If a device does not support 16 kHz mono capture, record a file
+with another recorder and pass it with `--input`.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run python scripts/check_file_length.py
+```
+
+Tests use synthetic audio and mocked recording/inference; they do not access a
+microphone or download model weights. M4A integration tests generate real AAC and
+ALAC files and are skipped when FFmpeg is unavailable. Tests were updated for ONNX
+but deliberately not run during the migration. Ruff enforces annotations and a
+complexity limit of 10, Pyright checks types, and source files are limited to 500 lines.
+
+## Publishing
+
+Version tags publish the `rek` distribution through GitHub Actions OIDC. No PyPI API
+token or password is stored in GitHub. Configure a PyPI Trusted Publisher with:
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `rek` |
+| GitHub owner | `gardner` |
+| GitHub repository | `rek` |
+| Workflow filename | `publish.yml` |
+| GitHub environment | `pypi` |
+
+Create the `pypi` environment in the repository settings. For the first upload,
+register a pending publisher in your PyPI account's Publishing settings. See the
+[PyPI Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+
+To release, update `version` in `pyproject.toml`, run `uv lock`, and commit and push
+the changes. Create and push a matching version tag:
+
+```sh
+git tag -a v0.1.1 -m "Release rek 0.1.1"
+git push origin v0.1.1
+```
+
+This example assumes `version = "0.1.1"` has already been committed.
+The workflow checks that the tag matches the package version, builds a wheel and
+source distribution, and publishes them from a separate job with `id-token: write`.
+Pushing a `v*` tag triggers publishing automatically; no GitHub release is required.
+Ordinary branch pushes do not publish. The tag must point to a commit containing
+this tag-triggered workflow; tags pushed before that change are not retriggered.
+Each new PyPI release needs a new version. The workflow does not run tests.
+
+Once published, users can install and run the command with:
+
+```sh
+uv tool install rek
+rek "Voice Memo.m4a"
+```

rek-0.1.1/README.md

@@ -0,0 +1,225 @@
+# rek
+
+[GitHub repository](https://github.com/gardner/rek) · [Issues](https://github.com/gardner/rek/issues)
+
+Record your microphone, then transcribe locally with timestamps and speaker labels.
+Inference uses ONNX Runtime (with [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx) for ASR),
+with Core ML acceleration by default on macOS and CPU inference on Linux/Windows.
+There is no MLX, PyTorch, or CUDA dependency.
+
+- [Parakeet TDT 0.6B v2 INT8](https://huggingface.co/csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8)
+  transcribes **English only**.
+- [Nemotron 3 Diarization ONNX](https://huggingface.co/onnx-community/Nemotron-3-Diarization-ONNX)
+  detects up to eight speakers directly, replacing both Pyannote segmentation and
+  TitaNet embeddings/clustering. It runs in 27.2-second chunks with 3.2 seconds of
+  look-ahead and an arrival-order speaker cache carried across the full recording.
+  The NumPy/librosa frontend and cache follow the model's Transformers implementation;
+  PyTorch is not needed. Speaker activity is thresholded at 0.5 on 10 ms frames,
+  including overlapping speakers.
+
+Nemotron uses the FP32 graph and its external weights (about 398 MB), pinned to
+revision `353b6f8ad2cac3580e982d7fbdf0a010786b0406`. Both files are downloaded into
+the same cache directory so ONNX Runtime can resolve the external weights.
+The model is distributed under the [OpenMDW 1.1 license](https://huggingface.co/onnx-community/Nemotron-3-Diarization-ONNX/blob/main/README.md).
+
+
+The dependencies are intended for macOS, Linux, and Windows. This ONNX migration
+has **not been runtime-tested**, including on Linux or Windows.
+
+## Run
+
+Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and FFmpeg
+(see below). From this checkout, install the command once:
+
+```sh
+uv tool install .
+```
+
+Then just give it a filename:
+
+```sh
+rek "Voice Memo.m4a"
+```
+
+No model, language, device, speaker-count, or tuning flags are required. The command
+downloads the models if needed, decodes and normalizes the audio, detects speakers,
+transcribes speech, and saves both text and JSON in a new `recordings/<timestamp>/`
+directory under your current working directory. It prints the transcript and output
+location when finished. First use needs internet access for the model downloads.
+If your shell cannot find `rek` after installation, run `uv tool update-shell`
+and reopen your terminal.
+
+You can also run directly from the checkout without installing the command:
+
+```sh
+uv run main.py "Voice Memo.m4a"
+```
+
+The defaults are:
+
+| Setting | Default |
+| --- | --- |
+| Hardware | Core ML on macOS; CPU on Linux/Windows |
+| Speech recognition | English Parakeet v2 INT8, greedy decoding |
+| Speaker detection | Nemotron 3 FP32, up to eight speakers automatically |
+| Diarization windows | Published offline settings: 27.2 s + 3.2 s look-ahead, persistent speaker cache |
+| Speaker activity | Probability above 0.5, at 10 ms resolution |
+| Transcription windows | 30 s with 2 s context on each side |
+| Audio | Automatic mono mixing and resampling to 16 kHz |
+| Output | Timestamped text and JSON; existing output folders are never overwritten |
+
+These use the model's published settings and bounded inference windows; they are
+starting defaults, not benchmark-tuned settings for a particular machine.
+
+Run `rek` without a filename to record your default microphone until **Ctrl+C**.
+Start speaking when you see **“Recording”**. Ctrl+C finishes saving the WAV and starts
+transcription. There is no duration limit or `--seconds` option.
+
+The project uses Python 3.14; uv can install it automatically. Built-in model revisions
+are pinned. Later runs reuse the Hugging Face cache, and audio stays on your computer.
+To relocate the cache, set `HF_HOME`. For offline use, populate the cache first,
+then set `HF_HUB_OFFLINE=1`.
+
+Overrides are optional, mainly for troubleshooting or changing the destination:
+
+```sh
+rek meeting.wav --output-dir recordings/meeting
+rek meeting.wav --device cpu
+rek --help
+```
+
+The older `--input filename` syntax remains supported.
+
+`--asr-model` accepts a compatible sherpa-onnx Parakeet v2 INT8 Hugging Face
+repository or local directory containing `encoder.int8.onnx`, `decoder.int8.onnx`,
+`joiner.int8.onnx`, and `tokens.txt`. MLX repositories are no longer compatible.
+
+M4A (AAC or Apple Lossless), WAV, FLAC, and other formats supported by libsndfile can
+be used as input. M4A decoding uses FFmpeg automatically, without changing the
+original file or creating an intermediate WAV. FFmpeg must be on PATH:
+
+- macOS: `brew install ffmpeg`
+- Debian/Ubuntu: `sudo apt install ffmpeg`
+- Windows: `winget install Gyan.FFmpeg` (reopen your terminal after installation)
+
+Stereo files are mixed to mono and resampled to 16 kHz. Parakeet v2 is English-only;
+`--language en` is optional, and other languages are rejected. Transcription starts
+after recording ends. Long audio is decoded in 30-second windows with two seconds
+of context on either side. Words are retained by their timestamp midpoint within
+each window, with timestamps relative to the full recording. Chunk boundaries
+can still affect recognition.
+
+## Output
+
+Each run creates a new `recordings/<timestamp>/` directory containing:
+
+- `recording.wav`: 16 kHz mono audio (microphone mode only).
+- `transcript.txt`: readable timestamped speaker turns, also printed to the terminal.
+- `transcript.json`: transcript, individual word timestamps, raw speaker turns,
+  model IDs, diarization graph filename, backends, requested device, and the original audio path.
+
+Example format:
+
+```text
+[00:00:00.100 - 00:00:02.300] Speaker 1: Hello, everyone.
+[00:00:02.500 - 00:00:03.800] Speaker 2: Hi there.
+```
+
+Speaker labels are anonymous and apply to one recording; they do not identify
+people by name. Parakeet's timestamped subword pieces are joined into complete
+words, preserving punctuation. Words are assigned to the speaker with the greatest
+total time overlap. Ties, missing word timestamps, and unmatched words are labelled
+`Unknown`. Token end times use TDT durations when available; otherwise they are
+estimated from the next token's start or the end of the chunk.
+Overlapping voices can reduce accuracy: this script does not separate mixed voices.
+When diarization detects no speech, transcription is skipped. Microphone audio is
+written to disk as you record; the completed recording is loaded into memory for
+inference. CPU inference can take longer than the recording.
+
+Existing output directories are refused to prevent overwriting recordings. If model
+loading or inference fails, a completed microphone recording remains available;
+retry it with `--input path/to/recording.wav`. Ctrl+C during recording saves and
+transcribes the captured audio; Ctrl+C during model loading or transcription cancels
+processing and preserves the recording. Stopping before any audio arrives reports
+an empty recording instead of starting inference.
+
+## Devices and troubleshooting
+
+`--device auto` requests the ONNX Runtime Core ML provider on macOS for both
+transcription and diarization, and CPU elsewhere. `--device coreml`, `--device mps`,
+and `--device gpu` explicitly request Core ML on macOS. `--device cpu` forces CPU
+on every platform. CUDA is not configured in this project.
+
+[Core ML](https://onnxruntime.ai/docs/execution-providers/CoreML-ExecutionProvider.html)
+can use Apple hardware acceleration; it is not PyTorch's MPS backend. Core ML chooses
+the compute hardware, and unsupported ONNX operations run on CPU. In particular,
+quantized Parakeet operations may remain on CPU: selecting Core ML does not guarantee
+that the whole model runs on the GPU or that inference is faster. The bundled macOS
+runtime includes Core ML support. Nemotron uses the Python ONNX Runtime package
+and falls back to CPU with a warning if Core ML is unavailable in that runtime.
+Custom sherpa-onnx runtimes without Core ML may also fall back to CPU.
+The JSON `device` field records the requested provider, not measured hardware usage.
+Core ML model compilation can add startup time. Use `--device cpu` if initialization
+fails or acceleration performs poorly. No acceleration benchmarks were run.
+
+If microphone capture fails, check the system's default input device and grant
+microphone access to your terminal/app. macOS and Windows sounddevice wheels include
+PortAudio. Linux may need `libportaudio2` and `libsndfile1` installed using the system
+package manager. If a device does not support 16 kHz mono capture, record a file
+with another recorder and pass it with `--input`.
+
+## Development
+
+```sh
+uv run pytest
+uv run ruff check .
+uv run ruff format --check .
+uv run pyright
+uv run python scripts/check_file_length.py
+```
+
+Tests use synthetic audio and mocked recording/inference; they do not access a
+microphone or download model weights. M4A integration tests generate real AAC and
+ALAC files and are skipped when FFmpeg is unavailable. Tests were updated for ONNX
+but deliberately not run during the migration. Ruff enforces annotations and a
+complexity limit of 10, Pyright checks types, and source files are limited to 500 lines.
+
+## Publishing
+
+Version tags publish the `rek` distribution through GitHub Actions OIDC. No PyPI API
+token or password is stored in GitHub. Configure a PyPI Trusted Publisher with:
+
+| Field | Value |
+| --- | --- |
+| PyPI project | `rek` |
+| GitHub owner | `gardner` |
+| GitHub repository | `rek` |
+| Workflow filename | `publish.yml` |
+| GitHub environment | `pypi` |
+
+Create the `pypi` environment in the repository settings. For the first upload,
+register a pending publisher in your PyPI account's Publishing settings. See the
+[PyPI Trusted Publishing guide](https://docs.pypi.org/trusted-publishers/creating-a-project-through-oidc/).
+
+To release, update `version` in `pyproject.toml`, run `uv lock`, and commit and push
+the changes. Create and push a matching version tag:
+
+```sh
+git tag -a v0.1.1 -m "Release rek 0.1.1"
+git push origin v0.1.1
+```
+
+This example assumes `version = "0.1.1"` has already been committed.
+The workflow checks that the tag matches the package version, builds a wheel and
+source distribution, and publishes them from a separate job with `id-token: write`.
+Pushing a `v*` tag triggers publishing automatically; no GitHub release is required.
+Ordinary branch pushes do not publish. The tag must point to a commit containing
+this tag-triggered workflow; tags pushed before that change are not retriggered.
+Each new PyPI release needs a new version. The workflow does not run tests.
+
+Once published, users can install and run the command with:
+
+```sh
+uv tool install rek
+rek "Voice Memo.m4a"
+```

rek-0.1.1/pyproject.toml

@@ -0,0 +1,66 @@
+[project]
+name = "rek"
+version = "0.1.1"
+description = "Local English transcription and speaker diarization with ONNX Runtime"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "huggingface-hub>=1.33.0",
+    "librosa>=1.0.0",
+    "numpy>=2.5.3",
+    "onnxruntime>=1.31.1",
+    "sherpa-onnx>=2.0.1",
+    "sounddevice>=0.5.6",
+    "soundfile>=0.14.0",
+]
+
+[project.urls]
+Repository = "https://github.com/gardner/rek"
+Issues = "https://github.com/gardner/rek/issues"
+
+[project.scripts]
+rek = "rek:main"
+
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+    "ruff>=0.16.10",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+    "C90",
+    "ANN",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.pyright]
+include = [
+    "main.py",
+    "src",
+    "scripts",
+]
+typeCheckingMode = "basic"
+strict = ["src/rek/transcript.py"]
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rek-0.1.1/pyproject.toml.orig

@@ -0,0 +1,54 @@
+[project]
+name = "rek"
+version = "0.1.1"
+description = "Local English transcription and speaker diarization with ONNX Runtime"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "huggingface-hub>=1.33.0",
+    "librosa>=1.0.0",
+    "numpy>=2.5.3",
+    "onnxruntime>=1.31.1",
+    "sherpa-onnx>=2.0.1",
+    "sounddevice>=0.5.6",
+    "soundfile>=0.14.0",
+]
+
+[project.urls]
+Repository = "https://github.com/gardner/rek"
+Issues = "https://github.com/gardner/rek/issues"
+
+[project.scripts]
+rek = "rek:main"
+
+[build-system]
+requires = ["uv_build>=0.12.22,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pyright>=1.1.414",
+    "pytest>=9.1.1",
+    "ruff>=0.16.10",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py314"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "C90", "ANN"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.pyright]
+include = ["main.py", "src", "scripts"]
+typeCheckingMode = "basic"
+strict = ["src/rek/transcript.py"]
+pythonVersion = "3.14"
+venvPath = "."
+venv = ".venv"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

rek-0.1.1/src/rek/__init__.py

@@ -0,0 +1,5 @@
+def main() -> None:
+    """Run the command-line recorder."""
+    from rek.cli import main as run
+
+    run()

rek-0.1.1/src/rek/audio.py

@@ -0,0 +1,101 @@
+"""Capture or normalize audio to the models' common 16 kHz mono input."""
+
+import subprocess
+import sys
+from pathlib import Path
+
+import numpy as np
+import numpy.typing as npt
+import soundfile as sf
+
+SAMPLE_RATE = 16_000
+type Audio = npt.NDArray[np.float32]
+
+
+def record_audio(path: Path) -> Audio:
+    """Write microphone blocks to disk until Ctrl+C, then return the saved audio."""
+    import sounddevice as sd
+
+    overflowed = False
+    try:
+        with (
+            sf.SoundFile(
+                path, mode="x", samplerate=SAMPLE_RATE, channels=1, subtype="PCM_16"
+            ) as wav,
+            sd.InputStream(samplerate=SAMPLE_RATE, channels=1, dtype="float32") as stream,
+        ):
+            print("Recording. Speak now! Press Ctrl+C to stop and transcribe.", flush=True)
+            try:
+                while True:
+                    samples, dropped = stream.read(SAMPLE_RATE // 10)
+                    overflowed |= dropped
+                    wav.write(samples)
+            except KeyboardInterrupt:
+                pass  # Ctrl+C finishes this recording; model inference continues below.
+    except sd.PortAudioError as error:
+        raise RuntimeError(
+            "Could not record audio. Check your default microphone and microphone permissions."
+        ) from error
+    if overflowed:
+        print("Warning: microphone input overflowed; some audio was lost.", file=sys.stderr)
+    if sf.info(path).frames == 0:
+        raise ValueError("No audio was recorded. Start again and speak before pressing Ctrl+C.")
+    print(f"\nRecording stopped. Audio saved to {path}", flush=True)
+    return load_audio(path)
+
+
+def _load_m4a(path: Path) -> Audio:
+    """Decode AAC or ALAC in memory without creating an intermediate WAV."""
+    try:
+        result = subprocess.run(
+            [
+                "ffmpeg",
+                "-nostdin",
+                "-v",
+                "error",
+                "-i",
+                str(path.resolve()),
+                "-map",
+                "0:a:0",
+                "-f",
+                "f32le",
+                "-acodec",
+                "pcm_f32le",
+                "-ar",
+                str(SAMPLE_RATE),
+                "-ac",
+                "1",
+                "-rematrix_maxval",
+                "1",
+                "pipe:1",
+            ],
+            check=True,
+            capture_output=True,
+        )
+    except FileNotFoundError as error:
+        raise RuntimeError(
+            "M4A input requires FFmpeg on PATH. Install FFmpeg with your system package manager "
+            "(macOS: brew install ffmpeg; Debian/Ubuntu: sudo apt install ffmpeg; "
+            "Windows: winget install Gyan.FFmpeg)."
+        ) from error
+    except subprocess.CalledProcessError as error:
+        detail = error.stderr.decode(errors="replace").strip()
+        raise ValueError(f"Could not decode M4A audio: {detail}") from error
+    if not result.stdout:
+        raise ValueError("The audio file is empty.")
+    return np.frombuffer(result.stdout, dtype="<f4").astype(np.float32)
+
+
+def load_audio(path: Path) -> Audio:
+    """Load M4A or a soundfile-supported file as 16 kHz mono audio."""
+    if path.suffix.lower() == ".m4a":
+        return _load_m4a(path)
+    samples, sample_rate = sf.read(path, dtype="float32", always_2d=True)
+    if samples.size == 0:
+        raise ValueError("The audio file is empty.")
+    audio = np.asarray(samples.mean(axis=1), dtype=np.float32)
+    if sample_rate != SAMPLE_RATE:
+        import librosa
+
+        audio = librosa.resample(audio, orig_sr=sample_rate, target_sr=SAMPLE_RATE)
+    return np.asarray(audio, dtype=np.float32)

rek-0.1.1/src/rek/cli.py

@@ -0,0 +1,122 @@
+"""A small command-line interface around recording and local model inference."""
+
+import argparse
+import json
+import sys
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from pathlib import Path
+from typing import cast
+
+from rek.audio import load_audio, record_audio
+from rek.models import (
+    DEFAULT_ASR_MODEL,
+    DIARIZATION_MODEL,
+    Device,
+    diarize,
+    resolve_device,
+    transcribe,
+)
+from rek.transcript import align_words, render_transcript
+
+
+@dataclass(frozen=True)
+class Options:
+    input: Path | None
+    output_dir: Path | None
+    device: Device
+    asr_model: str
+    language: str | None
+
+
+def parse_args(argv: list[str] | None = None) -> Options:
+    parser = argparse.ArgumentParser(
+        prog="rek",
+        description="Transcribe an audio file with timestamps and speaker labels. "
+        "Without a file, record your microphone until Ctrl+C.",
+        epilog="Example: rek 'Voice Memo.m4a'. Models download automatically on first use. "
+        "Defaults: English, Nemotron speaker detection, Parakeet transcription, "
+        "Core ML on macOS and CPU elsewhere.",
+    )
+    parser.add_argument("file", nargs="?", type=Path, help="Audio file, including M4A.")
+    parser.add_argument("--input", type=Path, help=argparse.SUPPRESS)
+    parser.add_argument(
+        "--output-dir", type=Path, help="New output directory (default: recordings/<time>)."
+    )
+    advanced = parser.add_argument_group("optional overrides (defaults need no flags)")
+    advanced.add_argument(
+        "--device",
+        choices=["auto", "gpu", "cpu", "cuda", "mps", "coreml"],
+        default="auto",
+        help="ONNX provider (auto: Core ML on macOS, CPU elsewhere; mps/gpu alias Core ML).",
+    )
+    advanced.add_argument(
+        "--asr-model",
+        default=DEFAULT_ASR_MODEL,
+        help="Sherpa ONNX Parakeet v2 INT8 repository ID or local model directory.",
+    )
+    advanced.add_argument(
+        "--language",
+        type=str.lower,
+        choices=["en", "english"],
+        default="en",
+        help="Parakeet v2 is English-only (default: en).",
+    )
+    args = parser.parse_args(argv)
+    if args.file is not None and args.input is not None:
+        parser.error("Specify the audio file once: either a filename or --input, not both.")
+    options = Options(
+        args.file if args.file is not None else args.input,
+        args.output_dir,
+        cast(Device, args.device),
+        args.asr_model,
+        args.language,
+    )
+    if options.input is not None and not options.input.is_file():
+        parser.error(f"Audio file does not exist: {options.input}")
+    return options
+
+
+def run(options: Options) -> Path:
+    device = resolve_device(options.device)
+    output_dir = options.output_dir or Path("recordings") / datetime.now().strftime(
+        "%Y%m%d-%H%M%S-%f"
+    )
+    output_dir.mkdir(parents=True, exist_ok=False)
+    audio_path = options.input or output_dir / "recording.wav"
+    audio = load_audio(audio_path) if options.input else record_audio(audio_path)
+    turns = diarize(audio, device)
+    # Skip ASR when diarization detects no speech.
+    words = transcribe(audio, device, options.asr_model, options.language) if turns else []
+    utterances = align_words(words, turns)
+    text = render_transcript(utterances)
+    (output_dir / "transcript.txt").write_text(text, encoding="utf-8")
+    data = {
+        "audio_file": str(audio_path.resolve()),
+        "diarization_model": DIARIZATION_MODEL,
+        "backend": "onnxruntime",
+        "asr_backend": "sherpa-onnx",
+        "diarization_file": "onnx/model.onnx",
+        "device": device,
+        "asr_model": options.asr_model,
+        "speaker_turns": [asdict(turn) for turn in turns],
+        "words": [asdict(word) for word in words],
+        "transcript": [asdict(utterance) for utterance in utterances],
+    }
+    (output_dir / "transcript.json").write_text(
+        json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    print(f"\n{text}\nResults saved to {output_dir.resolve()}")
+    return output_dir
+
+
+def main(argv: list[str] | None = None) -> None:
+    options = parse_args(argv)
+    try:
+        run(options)
+    except KeyboardInterrupt:
+        print("\nCancelled.", file=sys.stderr)
+        raise SystemExit(130) from None
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"Error: {error}", file=sys.stderr)
+        raise SystemExit(1) from None

rek-0.1.1/src/rek/diarization.py

@@ -0,0 +1,101 @@
+"""Nemotron 3 ONNX diarization with cached speaker identity across chunks."""
+
+import sys
+from typing import Literal, cast
+
+import numpy as np
+
+from rek.audio import SAMPLE_RATE, Audio
+from rek.model_files import DIARIZATION_MODEL, model_file
+from rek.speaker_cache import SUBSAMPLING, FloatArray, SpeakerCache
+from rek.transcript import SpeakerTurn
+
+_HOP = 160
+_CHUNK_FRAMES = 340 * SUBSAMPLING
+_LOOKAHEAD_FRAMES = 40 * SUBSAMPLING
+
+
+def mel_features(audio: Audio) -> FloatArray:
+    """Match the export's unnormalized 128-bin log-mel frontend without Torch.
+
+    See transformers' NemotronAsrStreamingFeatureExtractor: symmetric Hann window,
+    constant centering, preemphasis, Slaney filters, and a 2**-24 log guard.
+    """
+    import librosa
+
+    emphasized = audio.copy()
+    emphasized[1:] -= np.float32(0.97) * audio[:-1]
+    spectrum = librosa.stft(
+        emphasized,
+        n_fft=512,
+        hop_length=_HOP,
+        win_length=400,
+        window=np.hanning(400).astype(np.float32),
+        center=True,
+        pad_mode="constant",
+    )
+    filters = librosa.filters.mel(sr=SAMPLE_RATE, n_fft=512, n_mels=128, norm="slaney")
+    power = np.abs(spectrum) ** 2
+    features = np.log(filters @ power + 2**-24).T
+    # The upstream mask counts floor(samples / hop) valid frames.
+    return np.asarray(features[: len(audio) // _HOP], dtype=np.float32)
+
+
+def speaker_turns(logits: FloatArray, duration: float) -> list[SpeakerTurn]:
+    """Threshold logits at zero (sigmoid > 0.5), retaining overlapping speakers."""
+    changes = np.diff(np.pad((logits > 0).astype(np.int8), ((1, 1), (0, 0))), axis=0)
+    turns: list[SpeakerTurn] = []
+    for speaker in range(logits.shape[1]):
+        starts = np.flatnonzero(changes[:, speaker] == 1)
+        ends = np.flatnonzero(changes[:, speaker] == -1)
+        for start, end in zip(starts, ends, strict=True):
+            turns.append(
+                SpeakerTurn(
+                    float(start) * 0.01, min(float(end) * 0.01, duration), f"Speaker {speaker + 1}"
+                )
+            )
+    return sorted(turns, key=lambda turn: (turn.start, turn.speaker))
+
+
+def diarize(audio: Audio, device: Literal["cpu", "coreml"]) -> list[SpeakerTurn]:
+    import onnxruntime as ort
+
+    if len(audio) < _HOP:
+        return []
+    print(f"Identifying speakers with {DIARIZATION_MODEL} using {device}...", flush=True)
+    # The graph references this sibling external-data file by its exact basename.
+    graph = model_file(DIARIZATION_MODEL, "onnx/model.onnx")
+    model_file(DIARIZATION_MODEL, "onnx/model.onnx_data")
+    providers = ["CPUExecutionProvider"]
+    if device == "coreml":
+        if "CoreMLExecutionProvider" in ort.get_available_providers():
+            providers.insert(0, "CoreMLExecutionProvider")
+        else:
+            print("Core ML is unavailable in ONNX Runtime; diarization uses CPU.", file=sys.stderr)
+    options = ort.SessionOptions()
+    options.intra_op_num_threads = 4
+    session = ort.InferenceSession(graph, sess_options=options, providers=providers)
+    features = mel_features(audio)
+    cache = SpeakerCache()
+    outputs: list[FloatArray] = []
+    for start in range(0, len(features), _CHUNK_FRAMES):
+        end = min(start + _CHUNK_FRAMES, len(features))
+        chunk = features[start : end + _LOOKAHEAD_FRAMES]
+        cached = cache.embeds
+        frame_count = (len(chunk) + SUBSAMPLING - 1) // SUBSAMPLING
+        logits, embeds, silence = cast(
+            list[FloatArray],
+            session.run(
+                ["logits", "chunk_embeds", "silence_embeds"],
+                {
+                    "input_features": chunk[None],
+                    "cached_embeds": cached[None],
+                    "attention_mask": np.ones((1, len(cached) + frame_count), dtype=np.int64),
+                },
+            ),
+        )
+        core_frames = (end - start + SUBSAMPLING - 1) // SUBSAMPLING
+        offset = len(cached) * SUBSAMPLING
+        outputs.append(logits[0, offset : offset + end - start])
+        cache.update(embeds[0, :core_frames], logits[0], silence)
+    return speaker_turns(np.concatenate(outputs), len(audio) / SAMPLE_RATE)

rek-0.1.1/src/rek/model_files.py

@@ -0,0 +1,29 @@
+"""Download only required ONNX assets, or use a supplied local model directory."""
+
+from pathlib import Path
+
+DEFAULT_ASR_MODEL = "csukuangfj/sherpa-onnx-nemo-parakeet-tdt-0.6b-v2-int8"
+DIARIZATION_MODEL = "onnx-community/Nemotron-3-Diarization-ONNX"
+
+# Keep the built-in exports reproducible; custom repositories use their default revision.
+_REVISIONS = {
+    DEFAULT_ASR_MODEL: "1ab9323565ddb038682214b292f588070a538ce2",
+    DIARIZATION_MODEL: "353b6f8ad2cac3580e982d7fbdf0a010786b0406",
+}
+
+
+def model_file(model_id: str, filename: str) -> str:
+    """Resolve an asset without downloading unrelated weights or sample recordings."""
+    directory = Path(model_id).expanduser()
+    if directory.is_dir():
+        path = directory / filename
+        if not path.is_file():
+            raise ValueError(f"Model directory is missing {filename}: {directory}")
+        return str(path.resolve())
+
+    from huggingface_hub import hf_hub_download
+
+    try:
+        return hf_hub_download(model_id, filename, revision=_REVISIONS.get(model_id))
+    except Exception as error:
+        raise RuntimeError(f"Could not load {filename} from {model_id}: {error}") from error

rek-0.1.1/src/rek/models.py

@@ -0,0 +1,109 @@
+"""Portable ONNX speaker diarization and English Parakeet v2 transcription."""
+
+import sys
+from typing import Literal, Protocol
+
+from rek.audio import SAMPLE_RATE, Audio
+from rek.diarization import diarize as diarize
+from rek.model_files import (
+    DEFAULT_ASR_MODEL as DEFAULT_ASR_MODEL,
+)
+from rek.model_files import (
+    DIARIZATION_MODEL as DIARIZATION_MODEL,
+)
+from rek.model_files import (
+    model_file,
+)
+from rek.transcript import Word, merge_word_tokens
+
+type Device = Literal["auto", "cpu", "gpu", "cuda", "mps", "coreml"]
+type InferenceDevice = Literal["cpu", "coreml"]
+_CHUNK_SAMPLES = 30 * SAMPLE_RATE
+_CONTEXT_SAMPLES = 2 * SAMPLE_RATE
+
+
+class RecognitionResult(Protocol):
+    text: str
+    tokens: list[str]
+    timestamps: list[float]
+    durations: list[float]
+
+
+def resolve_device(requested: Device) -> InferenceDevice:
+    if requested == "cpu":
+        return "cpu"
+    if requested == "auto":
+        return "coreml" if sys.platform == "darwin" else "cpu"
+    if requested in {"coreml", "mps", "gpu"} and sys.platform == "darwin":
+        return "coreml"
+    raise ValueError(
+        "Core ML acceleration is available on macOS only; CUDA is not configured. "
+        "Use --device cpu or --device auto."
+    )
+
+
+def _result_words(result: RecognitionResult, offset: float, duration: float) -> list[Word]:
+    """Convert SentencePiece tokens and TDT durations into absolute word timestamps."""
+    if not result.tokens or len(result.tokens) != len(result.timestamps):
+        return [Word(None, None, result.text)] if result.text.strip() else []
+    tokens: list[Word] = []
+    for index, (token, start) in enumerate(zip(result.tokens, result.timestamps, strict=True)):
+        if len(result.durations) == len(result.tokens):
+            end = start + result.durations[index]
+        else:
+            # Some exports supply starts only; use the next start as an estimate.
+            end = result.timestamps[index + 1] if index + 1 < len(result.tokens) else duration
+        start = max(0.0, min(start, duration))
+        end = max(start, min(end, duration))
+        tokens.append(Word(offset + start, offset + end, token.replace("▁", " ")))
+    return merge_word_tokens(tokens)
+
+
+def transcribe(
+    audio: Audio,
+    device: InferenceDevice,
+    model_id: str = DEFAULT_ASR_MODEL,
+    language: str | None = "en",
+) -> list[Word]:
+    if language is not None and language.lower() not in {"en", "english"}:
+        raise ValueError("Parakeet v2 supports English only.")
+    import sherpa_onnx
+
+    print(f"Transcribing English with {model_id} using ONNX provider {device}...", flush=True)
+    recognizer = sherpa_onnx.OfflineRecognizer.from_transducer(
+        encoder=model_file(model_id, "encoder.int8.onnx"),
+        decoder=model_file(model_id, "decoder.int8.onnx"),
+        joiner=model_file(model_id, "joiner.int8.onnx"),
+        tokens=model_file(model_id, "tokens.txt"),
+        model_type="nemo_transducer",
+        sample_rate=SAMPLE_RATE,
+        provider=device,
+        num_threads=4,
+        decoding_method="greedy_search",
+    )
+    words: list[Word] = []
+    for core_start in range(0, len(audio), _CHUNK_SAMPLES):
+        core_end = min(core_start + _CHUNK_SAMPLES, len(audio))
+        start = max(0, core_start - _CONTEXT_SAMPLES)
+        end = min(len(audio), core_end + _CONTEXT_SAMPLES)
+        stream = recognizer.create_stream()
+        stream.accept_waveform(SAMPLE_RATE, audio[start:end])
+        recognizer.decode_stream(stream)
+        chunk_words = _result_words(stream.result, start / SAMPLE_RATE, (end - start) / SAMPLE_RATE)
+        if any(word.start is None for word in chunk_words) and (start, end) != (
+            core_start,
+            core_end,
+        ):
+            stream = recognizer.create_stream()
+            stream.accept_waveform(SAMPLE_RATE, audio[core_start:core_end])
+            recognizer.decode_stream(stream)
+            chunk_words = _result_words(
+                stream.result, core_start / SAMPLE_RATE, (core_end - core_start) / SAMPLE_RATE
+            )
+        # Each chunk owns words whose midpoint is inside its non-overlapping core.
+        for word in chunk_words:
+            if word.start is None or word.end is None:
+                words.append(word)
+            elif core_start / SAMPLE_RATE <= (word.start + word.end) / 2 < core_end / SAMPLE_RATE:
+                words.append(word)
+    return words

rek-0.1.1/src/rek/speaker_cache.py

@@ -0,0 +1,86 @@
+# Cache policy adapted from Hugging Face Transformers.
+# Copyright 2026 The HuggingFace Inc. team. Licensed under Apache-2.0.
+# https://www.apache.org/licenses/LICENSE-2.0
+
+"""NumPy arrival-order speaker cache for the pinned Nemotron ONNX export.
+
+Policy follows Hugging Face's Nemotron3DiarizationSpeakerCache:
+https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron3_diarization/modeling_nemotron3_diarization.py
+"""
+
+import math
+
+import numpy as np
+import numpy.typing as npt
+
+type FloatArray = npt.NDArray[np.float32]
+CACHE_LENGTH = 264
+FIFO_LENGTH = 40
+UPDATE_PERIOD = 300
+NUM_SPEAKERS = 8
+SUBSAMPLING = 8
+
+
+class SpeakerCache:
+    """Keep representative speaker frames plus a FIFO across offline chunks."""
+
+    def __init__(self) -> None:
+        self.speakers: FloatArray = np.empty((0, 512), dtype=np.float32)
+        self.probabilities: FloatArray = np.empty((0, NUM_SPEAKERS), dtype=np.float32)
+        self.fifo: FloatArray = np.empty((0, 512), dtype=np.float32)
+        self.compressed = False
+
+    @property
+    def embeds(self) -> FloatArray:
+        return np.concatenate((self.speakers, self.fifo))
+
+    def update(self, chunk: FloatArray, logits: FloatArray, silence: FloatArray) -> None:
+        """Append core frames only; look-ahead frames must not enter the cache."""
+        probabilities = 1 / (1 + np.exp(-np.clip(logits, -80, 80)))
+        pooled = (
+            probabilities.reshape(-1, SUBSAMPLING, NUM_SPEAKERS).mean(axis=1).astype(np.float32)
+        )
+        cached = len(self.speakers)
+        fifo = np.concatenate((self.fifo, chunk))
+        if len(fifo) <= FIFO_LENGTH:
+            self.fifo = fifo
+            return
+        popped = min(len(fifo), max(UPDATE_PERIOD, len(fifo) - FIFO_LENGTH))
+        stored = self.probabilities if self.compressed else pooled[:cached]
+        self.speakers = np.concatenate((self.speakers, fifo[:popped]))
+        self.probabilities = np.concatenate((stored, pooled[cached : cached + popped]))
+        self.fifo = fifo[popped:]
+        if len(self.speakers) > CACHE_LENGTH:
+            self._compress(silence)
+            self.compressed = True
+
+    def _compress(self, silence: FloatArray) -> None:
+        scores = _frame_scores(self.probabilities)
+        scores[CACHE_LENGTH:] += 0.05
+        # Each speaker has a 32-frame budget plus one reserved silence frame.
+        for count, boost in ((24, -2 * math.log(0.5)), (48, -math.log(0.5))):
+            indices = np.argsort(scores, axis=0, kind="stable")[-count:]
+            np.add.at(scores, (indices, np.arange(NUM_SPEAKERS)), boost)
+        scores = np.concatenate((scores, np.full((1, NUM_SPEAKERS), np.inf)))
+        frames = len(scores)
+        flat = scores.T.reshape(-1)
+        selected = np.argsort(flat, kind="stable")[-CACHE_LENGTH:]
+        selected = np.where(np.isneginf(flat[selected]), frames * NUM_SPEAKERS, selected)
+        selected.sort()
+        indices = np.where(selected == frames * NUM_SPEAKERS, frames - 1, selected % frames)
+        self.speakers = np.concatenate((self.speakers, silence.reshape(1, -1)))[indices]
+        self.probabilities = np.concatenate(
+            (self.probabilities, np.zeros((1, NUM_SPEAKERS), dtype=np.float32))
+        )[indices]
+
+
+def _frame_scores(probabilities: FloatArray) -> FloatArray:
+    log_probabilities = np.log(np.maximum(probabilities, 0.25))
+    log_complements = np.log(np.maximum(1 - probabilities, 0.25))
+    scores = log_probabilities - log_complements + log_complements.sum(axis=1, keepdims=True)
+    scores -= math.log(0.5)
+    scores[probabilities <= 0.5] = -np.inf
+    positive = scores > 0
+    enough_positive = positive.sum(axis=0) >= 16
+    scores[(~positive) & enough_positive[None, :]] = -np.inf
+    return scores

rek-0.1.1/src/rek/transcript.py

@@ -0,0 +1,107 @@
+"""Match timestamped words to diarization turns and format a readable transcript."""
+
+from collections import defaultdict
+from collections.abc import Sequence
+from dataclasses import dataclass, replace
+from math import isclose
+
+
+@dataclass(frozen=True)
+class SpeakerTurn:
+    start: float
+    end: float
+    speaker: str
+
+
+@dataclass(frozen=True)
+class Word:
+    start: float | None
+    end: float | None
+    text: str
+
+
+@dataclass(frozen=True)
+class Utterance:
+    start: float | None
+    end: float | None
+    speaker: str
+    text: str
+
+
+def merge_word_tokens(tokens: Sequence[Word]) -> list[Word]:
+    """Join Parakeet subword pieces, preserving punctuation and word boundaries."""
+    words: list[Word] = []
+    new_word = True
+    for token in tokens:
+        if not token.text:
+            continue
+        if not token.text.strip():
+            new_word = True
+            continue
+        if new_word or token.text[0].isspace():
+            words.append(Word(token.start, token.end, " " + token.text.lstrip()))
+        else:
+            previous = words[-1]
+            words[-1] = replace(previous, end=token.end, text=previous.text + token.text)
+        new_word = False
+    return words
+
+
+def _speaker_for(word: Word, turns: Sequence[SpeakerTurn]) -> str:
+    if word.start is None or word.end is None or word.end < word.start:
+        return "Unknown"
+    scores: dict[str, float] = defaultdict(float)
+    for turn in turns:
+        overlap = max(0.0, min(word.end, turn.end) - max(word.start, turn.start))
+        if word.start == word.end and turn.start <= word.start < turn.end:
+            overlap = 1.0
+        if overlap > 0:
+            scores[turn.speaker] += overlap
+    if not scores:
+        return "Unknown"
+    best = max(scores.values())
+    winners = [speaker for speaker, score in scores.items() if isclose(score, best)]
+    return winners[0] if len(winners) == 1 else "Unknown"
+
+
+def align_words(words: Sequence[Word], turns: Sequence[SpeakerTurn]) -> list[Utterance]:
+    """Assign by total temporal overlap; retain ambiguous words as Unknown."""
+    utterances: list[Utterance] = []
+    for word in words:
+        if not word.text.strip():
+            continue
+        speaker = _speaker_for(word, turns)
+        previous = utterances[-1] if utterances else None
+        if (
+            previous is not None
+            and previous.speaker == speaker
+            and previous.end is not None
+            and word.start is not None
+            and word.end is not None
+            # Adjacent Parakeet boundaries may differ by floating-point roundoff.
+            and -1e-6 <= word.start - previous.end <= 1.0
+        ):
+            # Word text retains its leading space and punctuation.
+            utterances[-1] = replace(previous, end=word.end, text=previous.text + word.text)
+        else:
+            utterances.append(Utterance(word.start, word.end, speaker, word.text.strip()))
+    return utterances
+
+
+def _timestamp(seconds: float | None) -> str:
+    if seconds is None:
+        return "??:??:??.???"
+    total_ms = round(seconds * 1000)
+    minutes, ms = divmod(total_ms, 60_000)
+    hours, minutes = divmod(minutes, 60)
+    seconds, ms = divmod(ms, 1000)
+    return f"{hours:02}:{minutes:02}:{seconds:02}.{ms:03}"
+
+
+def render_transcript(utterances: Sequence[Utterance]) -> str:
+    if not utterances:
+        return "No speech detected.\n"
+    return "".join(
+        f"[{_timestamp(line.start)} - {_timestamp(line.end)}] {line.speaker}: {line.text}\n"
+        for line in utterances
+    )