erm 0.1.0__tar.gz

erm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doug Calobrisi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

erm-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.4
+Name: erm
+Version: 0.1.0
+Summary: Strip disfluencies (um, uh, er, ah, hmm) from spoken audio.
+Author-email: Doug Calobrisi <doug@calobrisi.com>
+License: MIT
+Project-URL: Homepage, https://github.com/dougcalobrisi/erm
+Project-URL: Repository, https://github.com/dougcalobrisi/erm
+Project-URL: Issues, https://github.com/dougcalobrisi/erm/issues
+Keywords: audio,speech,transcription,filler-words,disfluency,whisper,ffmpeg
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Topic :: Multimedia :: Sound/Audio :: Editors
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: faster-whisper>=1.0.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: librosa>=0.10
+Requires-Dist: soundfile>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# erm
+
+Local CLI that strips disfluencies (`um`, `uh`, `er`, `erm`, `ah`, `hmm`, `mhm`,
+`mm`, `uh-huh`, plus any-length elongations like `ummmm` / `uhhhhh`) from
+recordings of English speech.
+
+It uses [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) (running
+the `medium.en` Whisper model by default — override with `--model`) for
+word-level timestamps, three audio-domain detectors that catch fillers Whisper
+hides, and ffmpeg for the cuts. Each splice is snapped to a local energy
+minimum and zero-crossing, optionally crossfaded with a length that scales
+with the cut size, and laid over a constant looped sample of the recording's
+own room tone so the noise floor stays uniform across edits.
+
+## Install
+
+Requires Python 3.11+ and `ffmpeg` / `ffprobe` on `PATH`.
+
+```sh
+python3.13 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Usage
+
+```sh
+# Remove fillers; output and cut-list paths are auto-generated next to the input.
+erm input.wav
+
+# Specify output explicitly.
+erm input.wav -o cleaned.wav
+
+# Inspect what would be cut without rendering.
+erm input.wav --dry-run
+
+# Validate a rendered output against its source.
+erm validate input.wav cleaned.wav --cuts cuts.json
+```
+
+When `-o` / `--json` are omitted, output paths are written next to the input as
+`{stem}-cleaned-{YYYYMMDD-HHMMSS}.wav` and `{stem}-cuts-{YYYYMMDD-HHMMSS}.json`.
+
+## How it works
+
+1. **Transcribe.** `faster-whisper` runs with `word_timestamps=True` and a
+   verbatim-bias `initial_prompt` so it emits filler tokens instead of
+   silently cleaning them up.
+2. **Detect.** Four passes produce candidate cut ranges:
+   - **Word-list match** — words whose normalized text is in `--fillers`,
+     including arbitrary-length elongations (e.g. `ummmm` matches the `um`
+     stem).
+   - **Gap fillers** — voiced regions in inter-word gaps longer than
+     `--gap-min-ms`. Catches fillers Whisper drops entirely.
+   - **Intra-word fillers** — long words whose interior splits across a
+     silence dip into multiple voiced runs. The non-vowel run whose duration
+     best matches the word's expected duration is treated as the real word;
+     siblings become cuts. Catches `"in, uhhhhh"` that Whisper rolls into one
+     `'in'` token.
+   - **Overlong words** — words much longer than `expected_max_word_duration`
+     for their text. The trailing portion is scanned for voiced runs.
+     Optionally pitch-confirmed (`--confirm-pitch`) by checking the cut
+     region looks like a sustained filler vowel (stable spectral centroid,
+     voiced ZCR), so we don't trim slow-but-real speech.
+3. **Refine.** Each cut endpoint snaps to a local RMS-energy minimum within
+   ±`--search-ms`, then to the nearest zero-crossing. Refinement is clamped
+   so it never crosses a neighboring word's timestamp.
+4. **Merge.** Cuts whose surviving fragment would be shorter than
+   `--merge-gap-ms` are collapsed into one — a 40ms surviving fragment
+   between two cuts gets eaten by the surrounding crossfades and would
+   otherwise blurp.
+5. **Render.** ffmpeg `atrim` + `acrossfade` renders the kept segments. Each
+   splice's crossfade length scales with that splice's cut size:
+   `clamp(min, cut_ms * factor, max)`. Crossfades are also clamped so they
+   never reach back across a real word boundary.
+6. **Room tone (optional, on by default).** A quiet region of the *original*
+   recording is sampled and looped under the output at `--room-tone-level-db`.
+   This keeps the noise floor identical everywhere, masking the residual
+   noise-floor mismatch at each splice.
+
+## Denoising
+
+`--denoise` picks how ffmpeg's `afftdn` denoiser is used:
+
+| Mode     | Detection sees | ffmpeg cuts from         | Notes |
+|----------|----------------|--------------------------|-------|
+| `none`   | original       | original                 | No denoising. |
+| `pre`    | denoised       | denoised                 | Cleanest splices, but detection less sensitive (denoising flattens energy/pitch signals). |
+| `post`   | original       | original; output denoised at end | Full detection sensitivity; splice noise-floor mismatch smoothed afterward. |
+| `hybrid` (default) | original | denoised               | Full detection sensitivity *and* clean splices. Recommended. |
+
+Tune with `--denoise-nr` (reduction strength dB) and `--denoise-nf` (noise
+floor dB).
+
+## Flags
+
+### Detection
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--model` | `medium.en` | Any faster-whisper model. `small.en` faster; `large-v3` more accurate. |
+| `--fillers` | `ah,er,erm,hmm,mhm,mm,uh,uh-huh,um` | Comma-separated stems. Elongations matched dynamically. |
+| `--detect-gaps` / `--no-detect-gaps` | on | Run gap + intra-word + overlong detectors. |
+| `--gap-min-ms` | `350` | Minimum inter-word gap to scan for fillers. |
+| `--gap-min-voiced-ms` / `--gap-max-voiced-ms` | `100` / `1500` | Voiced-run length bounds. |
+| `--intraword-min-ms` | `550` | Minimum word length to scan internally. |
+| `--confirm-pitch` / `--no-confirm-pitch` | on | Drop overlong/intra candidates that don't look like sustained filler vowels. |
+
+### Cuts and splices
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--search-ms` | `60` | How far each endpoint may slide to find a local energy minimum. |
+| `--crossfade-ms` | *(unset)* | Force a fixed crossfade length for every splice. When unset, per-splice scaling is used. |
+| `--min-crossfade-ms` / `--max-crossfade-ms` | `50` / `120` | Floor and ceiling for the per-splice crossfade scaling. |
+| `--crossfade-factor` | `0.15` | `cut_ms * factor`, clamped to `[min, max]`. Higher = smoother but blurrier. |
+| `--merge-gap-ms` | `120` | Merge two cuts whose surviving fragment would be shorter than this. |
+
+### Audio cleanup
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--denoise` | `hybrid` | `none` / `pre` / `post` / `hybrid` (see table above). |
+| `--denoise-nr` | `12.0` | `afftdn` noise reduction (dB). |
+| `--denoise-nf` | `-25.0` | `afftdn` noise floor (dB). |
+| `--room-tone` / `--no-room-tone` | on | Loop a quiet sample of the original under the output. |
+| `--room-tone-level-db` | `-12.0` | Attenuation applied to the looped tone. `-12` to `-20` is usually right. |
+| `--room-tone-source` | `auto` | `auto` finds a quiet region; otherwise `START-END` in seconds (e.g. `0.05-1.4`). |
+
+### Output
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `-o`, `--output` | auto-named next to input | Output `.wav` path. |
+| `--json PATH` | auto-named next to input | Cut list JSON. |
+| `--dry-run` | off | Print the cut list and exit; no audio rendered. |
+
+## `validate` subcommand
+
+```sh
+erm validate input.wav cleaned.wav --cuts cuts.json
+```
+
+Runs three deterministic checks:
+
+- **Container sanity** — `ffprobe` reads the output without errors.
+- **Duration math** — `output_duration ≈ input_duration - sum(cut lengths)`,
+  within 50ms.
+- **No-filler invariant** — re-transcribe the output; assert no token in the
+  filler set survives.
+
+Writes a JSON report to `--report PATH` (or auto-named next to the output)
+and exits non-zero if any check fails.
+
+## Tests
+
+```sh
+pytest
+```
+
+The pure helpers (`find_fillers`, `invert_to_keep_ranges`,
+`refine_boundaries`, `merge_close_cuts`, `expected_max_word_duration`,
+`_voiced_runs_in_region`, …) run without faster-whisper or librosa imported.
+Heavy deps are imported lazily inside `transcribe`, `render`,
+`load_audio_mono`, and `is_sustained_vowel`.
+
+## Out of scope
+
+- Removing `like`, `you know`, `I mean` — too risky for meaning.
+- Languages other than English.
+- Real-time / streaming.

erm-0.1.0/README.md

@@ -0,0 +1,171 @@
+# erm
+
+Local CLI that strips disfluencies (`um`, `uh`, `er`, `erm`, `ah`, `hmm`, `mhm`,
+`mm`, `uh-huh`, plus any-length elongations like `ummmm` / `uhhhhh`) from
+recordings of English speech.
+
+It uses [`faster-whisper`](https://github.com/SYSTRAN/faster-whisper) (running
+the `medium.en` Whisper model by default — override with `--model`) for
+word-level timestamps, three audio-domain detectors that catch fillers Whisper
+hides, and ffmpeg for the cuts. Each splice is snapped to a local energy
+minimum and zero-crossing, optionally crossfaded with a length that scales
+with the cut size, and laid over a constant looped sample of the recording's
+own room tone so the noise floor stays uniform across edits.
+
+## Install
+
+Requires Python 3.11+ and `ffmpeg` / `ffprobe` on `PATH`.
+
+```sh
+python3.13 -m venv .venv
+source .venv/bin/activate
+pip install -e '.[dev]'
+```
+
+## Usage
+
+```sh
+# Remove fillers; output and cut-list paths are auto-generated next to the input.
+erm input.wav
+
+# Specify output explicitly.
+erm input.wav -o cleaned.wav
+
+# Inspect what would be cut without rendering.
+erm input.wav --dry-run
+
+# Validate a rendered output against its source.
+erm validate input.wav cleaned.wav --cuts cuts.json
+```
+
+When `-o` / `--json` are omitted, output paths are written next to the input as
+`{stem}-cleaned-{YYYYMMDD-HHMMSS}.wav` and `{stem}-cuts-{YYYYMMDD-HHMMSS}.json`.
+
+## How it works
+
+1. **Transcribe.** `faster-whisper` runs with `word_timestamps=True` and a
+   verbatim-bias `initial_prompt` so it emits filler tokens instead of
+   silently cleaning them up.
+2. **Detect.** Four passes produce candidate cut ranges:
+   - **Word-list match** — words whose normalized text is in `--fillers`,
+     including arbitrary-length elongations (e.g. `ummmm` matches the `um`
+     stem).
+   - **Gap fillers** — voiced regions in inter-word gaps longer than
+     `--gap-min-ms`. Catches fillers Whisper drops entirely.
+   - **Intra-word fillers** — long words whose interior splits across a
+     silence dip into multiple voiced runs. The non-vowel run whose duration
+     best matches the word's expected duration is treated as the real word;
+     siblings become cuts. Catches `"in, uhhhhh"` that Whisper rolls into one
+     `'in'` token.
+   - **Overlong words** — words much longer than `expected_max_word_duration`
+     for their text. The trailing portion is scanned for voiced runs.
+     Optionally pitch-confirmed (`--confirm-pitch`) by checking the cut
+     region looks like a sustained filler vowel (stable spectral centroid,
+     voiced ZCR), so we don't trim slow-but-real speech.
+3. **Refine.** Each cut endpoint snaps to a local RMS-energy minimum within
+   ±`--search-ms`, then to the nearest zero-crossing. Refinement is clamped
+   so it never crosses a neighboring word's timestamp.
+4. **Merge.** Cuts whose surviving fragment would be shorter than
+   `--merge-gap-ms` are collapsed into one — a 40ms surviving fragment
+   between two cuts gets eaten by the surrounding crossfades and would
+   otherwise blurp.
+5. **Render.** ffmpeg `atrim` + `acrossfade` renders the kept segments. Each
+   splice's crossfade length scales with that splice's cut size:
+   `clamp(min, cut_ms * factor, max)`. Crossfades are also clamped so they
+   never reach back across a real word boundary.
+6. **Room tone (optional, on by default).** A quiet region of the *original*
+   recording is sampled and looped under the output at `--room-tone-level-db`.
+   This keeps the noise floor identical everywhere, masking the residual
+   noise-floor mismatch at each splice.
+
+## Denoising
+
+`--denoise` picks how ffmpeg's `afftdn` denoiser is used:
+
+| Mode     | Detection sees | ffmpeg cuts from         | Notes |
+|----------|----------------|--------------------------|-------|
+| `none`   | original       | original                 | No denoising. |
+| `pre`    | denoised       | denoised                 | Cleanest splices, but detection less sensitive (denoising flattens energy/pitch signals). |
+| `post`   | original       | original; output denoised at end | Full detection sensitivity; splice noise-floor mismatch smoothed afterward. |
+| `hybrid` (default) | original | denoised               | Full detection sensitivity *and* clean splices. Recommended. |
+
+Tune with `--denoise-nr` (reduction strength dB) and `--denoise-nf` (noise
+floor dB).
+
+## Flags
+
+### Detection
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--model` | `medium.en` | Any faster-whisper model. `small.en` faster; `large-v3` more accurate. |
+| `--fillers` | `ah,er,erm,hmm,mhm,mm,uh,uh-huh,um` | Comma-separated stems. Elongations matched dynamically. |
+| `--detect-gaps` / `--no-detect-gaps` | on | Run gap + intra-word + overlong detectors. |
+| `--gap-min-ms` | `350` | Minimum inter-word gap to scan for fillers. |
+| `--gap-min-voiced-ms` / `--gap-max-voiced-ms` | `100` / `1500` | Voiced-run length bounds. |
+| `--intraword-min-ms` | `550` | Minimum word length to scan internally. |
+| `--confirm-pitch` / `--no-confirm-pitch` | on | Drop overlong/intra candidates that don't look like sustained filler vowels. |
+
+### Cuts and splices
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--search-ms` | `60` | How far each endpoint may slide to find a local energy minimum. |
+| `--crossfade-ms` | *(unset)* | Force a fixed crossfade length for every splice. When unset, per-splice scaling is used. |
+| `--min-crossfade-ms` / `--max-crossfade-ms` | `50` / `120` | Floor and ceiling for the per-splice crossfade scaling. |
+| `--crossfade-factor` | `0.15` | `cut_ms * factor`, clamped to `[min, max]`. Higher = smoother but blurrier. |
+| `--merge-gap-ms` | `120` | Merge two cuts whose surviving fragment would be shorter than this. |
+
+### Audio cleanup
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `--denoise` | `hybrid` | `none` / `pre` / `post` / `hybrid` (see table above). |
+| `--denoise-nr` | `12.0` | `afftdn` noise reduction (dB). |
+| `--denoise-nf` | `-25.0` | `afftdn` noise floor (dB). |
+| `--room-tone` / `--no-room-tone` | on | Loop a quiet sample of the original under the output. |
+| `--room-tone-level-db` | `-12.0` | Attenuation applied to the looped tone. `-12` to `-20` is usually right. |
+| `--room-tone-source` | `auto` | `auto` finds a quiet region; otherwise `START-END` in seconds (e.g. `0.05-1.4`). |
+
+### Output
+
+| Flag | Default | Notes |
+|------|---------|-------|
+| `-o`, `--output` | auto-named next to input | Output `.wav` path. |
+| `--json PATH` | auto-named next to input | Cut list JSON. |
+| `--dry-run` | off | Print the cut list and exit; no audio rendered. |
+
+## `validate` subcommand
+
+```sh
+erm validate input.wav cleaned.wav --cuts cuts.json
+```
+
+Runs three deterministic checks:
+
+- **Container sanity** — `ffprobe` reads the output without errors.
+- **Duration math** — `output_duration ≈ input_duration - sum(cut lengths)`,
+  within 50ms.
+- **No-filler invariant** — re-transcribe the output; assert no token in the
+  filler set survives.
+
+Writes a JSON report to `--report PATH` (or auto-named next to the output)
+and exits non-zero if any check fails.
+
+## Tests
+
+```sh
+pytest
+```
+
+The pure helpers (`find_fillers`, `invert_to_keep_ranges`,
+`refine_boundaries`, `merge_close_cuts`, `expected_max_word_duration`,
+`_voiced_runs_in_region`, …) run without faster-whisper or librosa imported.
+Heavy deps are imported lazily inside `transcribe`, `render`,
+`load_audio_mono`, and `is_sustained_vowel`.
+
+## Out of scope
+
+- Removing `like`, `you know`, `I mean` — too risky for meaning.
+- Languages other than English.
+- Real-time / streaming.

erm-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "erm"
+version = "0.1.0"
+description = "Strip disfluencies (um, uh, er, ah, hmm) from spoken audio."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Doug Calobrisi", email = "doug@calobrisi.com" }]
+keywords = ["audio", "speech", "transcription", "filler-words", "disfluency", "whisper", "ffmpeg"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: End Users/Desktop",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Topic :: Multimedia :: Sound/Audio :: Editors",
+]
+dependencies = [
+    "faster-whisper>=1.0.3",
+    "numpy>=1.26",
+    "librosa>=0.10",
+    "soundfile>=0.12",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/dougcalobrisi/erm"
+Repository = "https://github.com/dougcalobrisi/erm"
+Issues = "https://github.com/dougcalobrisi/erm/issues"
+
+[project.scripts]
+erm = "erm.cli:main"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+markers = ["slow: tests that need the Whisper model (download required)"]

erm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

erm-0.1.0/src/erm/__init__.py

@@ -0,0 +1,58 @@
+"""erm: strip disfluencies from spoken audio.
+
+The pure-helper modules (`fillers`, `ranges`, `refine`, `envelope`, `models`)
+depend only on numpy + stdlib so the unit tests can run without
+faster-whisper or librosa installed. Heavy deps (`librosa`,
+`faster_whisper`) are imported lazily inside the functions that need them.
+"""
+
+from .acoustic import is_sustained_vowel
+from .asr import VERBATIM_PROMPT, transcribe
+from .audio import find_quiet_region, load_audio_mono
+from .cli import main
+from .detect import (
+    detect_gap_fillers,
+    detect_intraword_fillers,
+    detect_overlong_words,
+    expected_max_word_duration,
+)
+from .ffmpeg_ops import (
+    denoise_to,
+    extract_segment,
+    ffprobe_duration,
+    overlay_room_tone,
+    render,
+)
+from .fillers import DEFAULT_FILLERS, find_fillers, is_filler, normalize_word
+from .models import Cut, Word
+from .ranges import invert_to_keep_ranges, merge_close_cuts
+from .refine import refine_boundaries
+from .validate import validate_output
+
+__all__ = [
+    "Cut",
+    "DEFAULT_FILLERS",
+    "VERBATIM_PROMPT",
+    "Word",
+    "denoise_to",
+    "detect_gap_fillers",
+    "detect_intraword_fillers",
+    "detect_overlong_words",
+    "expected_max_word_duration",
+    "extract_segment",
+    "ffprobe_duration",
+    "find_fillers",
+    "find_quiet_region",
+    "invert_to_keep_ranges",
+    "is_filler",
+    "is_sustained_vowel",
+    "load_audio_mono",
+    "main",
+    "merge_close_cuts",
+    "normalize_word",
+    "overlay_room_tone",
+    "refine_boundaries",
+    "render",
+    "transcribe",
+    "validate_output",
+]

erm-0.1.0/src/erm/__main__.py

@@ -0,0 +1,11 @@
+"""`python -m erm` entrypoint."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())

erm-0.1.0/src/erm/acoustic.py

@@ -0,0 +1,59 @@
+"""Acoustic feature checks (librosa-based, lazy-imported)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+
+def is_sustained_vowel(
+    audio: np.ndarray,
+    sr: int,
+    start_s: float,
+    end_s: float,
+    max_centroid_cv: float = 0.18,
+    min_voiced_frac: float = 0.50,
+) -> bool:
+    """Return True if [start_s, end_s] looks acoustically like a sustained
+    filler vowel ("uhhh", "ahhh", "ummm").
+
+    Filler vowels have two distinguishing features compared to real word
+    content: (a) the spectral energy stays in roughly the same place across
+    the region (low spectral-centroid variation), and (b) most frames are
+    voiced (ZCR in the voiced range, not silence or fricative noise).
+
+    `max_centroid_cv` is the std/mean ratio of the spectral centroid; lower
+    means more stable. `min_voiced_frac` is the fraction of frames whose
+    zero-crossing rate is in the typical voiced-speech range.
+    """
+    import librosa  # heavy; lazy
+
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    s = max(0, int(start_s * sr))
+    e = min(audio.size, int(end_s * sr))
+    seg = audio[s:e]
+    if seg.size < int(0.06 * sr):
+        return False
+
+    n_fft = 1024
+    hop = max(1, int(0.020 * sr))
+    if seg.size < n_fft:
+        seg = np.pad(seg, (0, n_fft - seg.size), mode="constant")
+
+    centroid = librosa.feature.spectral_centroid(
+        y=seg, sr=sr, n_fft=n_fft, hop_length=hop,
+    )[0]
+    if centroid.size < 3:
+        return False
+    mean_c = float(centroid.mean())
+    if mean_c <= 1e-6:
+        return False
+    cv = float(centroid.std() / mean_c)
+
+    zcr = librosa.feature.zero_crossing_rate(
+        y=seg, frame_length=n_fft, hop_length=hop,
+    )[0]
+    voiced = (zcr > 0.02) & (zcr < 0.20)
+    voiced_frac = float(voiced.mean()) if voiced.size else 0.0
+
+    return cv <= max_centroid_cv and voiced_frac >= min_voiced_frac

erm-0.1.0/src/erm/asr.py

@@ -0,0 +1,43 @@
+"""faster-whisper transcription (lazy-imported)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .models import Word
+
+
+VERBATIM_PROMPT = (
+    "Um, uh, er, erm, ah, hmm. Like, you know, I mean, sort of. "
+    "Verbatim transcription including all filler words and disfluencies."
+)
+
+
+def transcribe(
+    path: str | Path,
+    model_name: str = "medium.en",
+    verbatim: bool = True,
+) -> tuple[list[Word], float]:
+    """Transcribe `path` with faster-whisper. Returns (words, duration_seconds).
+
+    `verbatim=True` passes an `initial_prompt` that biases Whisper toward
+    keeping disfluencies, which it normally cleans up silently.
+    """
+    from faster_whisper import WhisperModel  # heavy; lazy
+
+    model = WhisperModel(model_name, device="auto", compute_type="auto")
+    segments, info = model.transcribe(
+        str(path),
+        word_timestamps=True,
+        initial_prompt=VERBATIM_PROMPT if verbatim else None,
+        condition_on_previous_text=False,  # otherwise the prompt gets diluted
+    )
+    words: list[Word] = []
+    for seg in segments:
+        if not seg.words:
+            continue
+        for w in seg.words:
+            if w.start is None or w.end is None:
+                continue
+            words.append(Word(text=w.word.strip(), start=float(w.start), end=float(w.end)))
+    return words, float(info.duration)

erm-0.1.0/src/erm/audio.py

@@ -0,0 +1,59 @@
+"""Audio loading and quiet-region selection."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Sequence
+
+import numpy as np
+
+from .models import Word
+
+
+def load_audio_mono(path: str | Path, target_sr: int = 16_000) -> tuple[np.ndarray, int]:
+    """Load any ffmpeg-readable audio file as mono float32 at `target_sr`."""
+    import librosa  # heavy; lazy
+    y, sr = librosa.load(str(path), sr=target_sr, mono=True)
+    return y.astype(np.float32), int(sr)
+
+
+def find_quiet_region(
+    audio: np.ndarray,
+    sr: int,
+    words: Sequence[Word],
+    min_length_s: float = 0.4,
+    max_length_s: float = 1.5,
+    win_ms: float = 10.0,
+) -> tuple[float, float] | None:
+    """Find a stretch of mostly-silent audio suitable as a room-tone sample.
+
+    We need a region with no speech and only background noise (HVAC, mic
+    hiss, room tone). The gap *before the first transcribed word* is usually
+    the cleanest source — it's pre-roll silence with no speaker activity.
+    Falls back to the gap after the last word if the leading gap is too
+    short.
+    """
+    if audio.ndim > 1:
+        audio = audio.mean(axis=1)
+    audio = np.ascontiguousarray(audio, dtype=np.float32)
+    total = float(audio.size) / sr
+
+    sorted_words = sorted(words, key=lambda w: w.start)
+    candidates: list[tuple[float, float]] = []
+    if sorted_words:
+        candidates.append((0.0, sorted_words[0].start))
+        candidates.append((sorted_words[-1].end, total))
+    else:
+        candidates.append((0.0, total))
+
+    # Trim 50ms off each side to avoid clipping the start of speech
+    # or the tail of the previous word's silence-pad.
+    pad = 0.05
+    for start_s, end_s in candidates:
+        if end_s - start_s < min_length_s + 2 * pad:
+            continue
+        s = start_s + pad
+        e = min(end_s - pad, s + max_length_s)
+        if e - s >= min_length_s:
+            return (s, e)
+    return None