echoai-helper 1.2.0__py3-none-any.whl

echoai_helper-1.2.0.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: echoai-helper
+Version: 1.2.0
+Summary: Real-time meeting transcription and interview assistance, on-device
+Author: colakang
+License: MIT
+Project-URL: Homepage, https://github.com/colakang/echoai_helper
+Project-URL: Issues, https://github.com/colakang/echoai_helper/issues
+Keywords: transcription,asr,meeting-notes,diarization,funasr
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sounddevice; sys_platform != "win32"
+Requires-Dist: PyAudioWPatch; sys_platform == "win32"
+Requires-Dist: numpy<2
+Requires-Dist: scipy
+Requires-Dist: torch
+Requires-Dist: torchaudio
+Requires-Dist: funasr
+Requires-Dist: modelscope
+Requires-Dist: huggingface_hub
+Requires-Dist: loguru
+Requires-Dist: onnxruntime
+Requires-Dist: soundfile
+Requires-Dist: openai
+Requires-Dist: customtkinter==5.1.3
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: pytz
+Provides-Extra: litellm
+Requires-Dist: litellm; extra == "litellm"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# 🎙️ EchoAI Helper
+
+[![GitHub Stars](https://img.shields.io/github/stars/colakang/echoai_helper?style=social)](https://github.com/colakang/echoai_helper/stargazers)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.12-blue.svg)](https://python.org)
+[![macOS](https://img.shields.io/badge/macOS-13%2B-lightgrey.svg)](#-install)
+[![Windows](https://img.shields.io/badge/Windows-10%2B-lightgrey.svg)](#windows)
+
+Real-time meeting transcription and interview assistance, running on your own
+machine. It records both sides of a conversation — your microphone and whatever
+the meeting app is playing — transcribes them as they happen, labels who is
+speaking, and exports readable notes.
+
+Speech recognition is local. Audio never leaves the machine unless you ask a
+language model to clean up the finished transcript.
+
+<p>
+<a href="https://www.producthunt.com/posts/echoai-interview-copilot?embed=true&utm_source=badge-featured&utm_medium=badge&utm_souce=badge-echoai&#0045;interview&#0045;copilot" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=601490&theme=light" alt="EchoAI&#0032;Interview&#0032;Copilot&#0032; - Real&#0045;time&#0032;conversation&#0032;with&#0032;LLM&#0032;responses | Product Hunt" style="width: 250px; height: 54px;" width="250" height="54" /></a>
+</p>
+
+<p align="center">
+<img width="800" alt="EchoAI Helper Interface" src="https://github.com/colakang/echoai_helper/raw/main/docs/images/ui.png">
+</p>
+
+---
+
+## ✨ What it does
+
+- **Local speech recognition** — FunASR / SenseVoice, on-device, GPU-accelerated
+  where one is available (Metal on Apple Silicon, CUDA on Windows)
+- **Automatic language detection** — Mandarin, Cantonese, English, Japanese and
+  Korean, switching per utterance, including mid-sentence code-switching
+- **Both sides of the call** — your microphone and the far end, on separate tracks
+- **Speaker labelling** — voices on the far-end track are told apart, with the
+  number of people configurable when you know it
+- **Pause-based segmentation** — sentences are cut where people actually pause,
+  not on a fixed timer, so the model sees whole utterances
+- **Crash-safe recording** — every settled sentence is written to disk as it is
+  produced; a crash costs the last line, not the meeting
+- **LLM cleanup on export** — an optional pass that fixes mis-heard words using
+  the surrounding conversation, through an API key or through a coding-agent CLI
+  on a subscription you already pay for
+- **Markdown and JSON export** — Markdown to read, JSON as a complete record
+- **Live reply suggestions** — for interviews, where a prompt is wanted while the
+  other person is still talking
+
+## 💡 Two modes
+
+| | Meeting notes | Live interview |
+|---|---|---|
+| Text appears | at each pause | as you speak (~0.6s) |
+| Model calls | one per sentence | roughly three times as many |
+| Best for | an accurate record | a prompt you can act on |
+
+Switch in the app; the several settings that differ move together.
+
+## 🎬 Demo
+
+https://github.com/user-attachments/assets/0d627e4a-960b-4628-8bbc-8d892f02cfd1
+
+---
+
+## ⚡ Install
+
+### macOS
+
+```bash
+uv tool install echoai-helper     # uv brings its own Python 3.12
+echoai-helper setup               # audio routing — one password prompt
+echoai-helper install-launcher    # adds an icon to Launchpad
+```
+
+Launch from Launchpad, or run `echoai-helper`.
+
+`setup` installs a virtual audio device and builds the Multi-Output that lets
+you hear a meeting while it is being recorded. macOS asks for a password once,
+because that installs an audio driver — nothing else needs a privilege, and
+Audio MIDI Setup is not involved.
+
+The app takes the audio output while it runs and gives it back silently when it
+quits, including after a crash. `echoai-helper setup --restore` does it by hand;
+`--status` shows what routing is in place.
+
+<details>
+<summary>Prefer Homebrew?</summary>
+
+A formula is in [`packaging/`](packaging/echoai-helper.rb) for a tap. Homebrew
+can declare the virtual audio device as a dependency, which removes the one step
+that needs a password.
+</details>
+
+### Windows
+
+```powershell
+uv tool install echoai-helper
+echoai-helper
+```
+
+No audio setup step: Windows exposes WASAPI loopback directly, so the far end of
+a call is capturable without a virtual device. The macOS-only commands (`setup`,
+`install-launcher`) report that there is nothing to do. See
+[known limitations](#-known-limitations) — this path has not been re-tested since
+the segmentation rework.
+
+### First run
+
+Speech models (~1.5GB) download on first launch. Nothing else is needed.
+
+<details>
+<summary>Why Python 3.12 specifically</summary>
+
+Not caution. The vendored `src/custom_speech_recognition` imports `aifc` and
+`audioop` at module level, and **both were removed from the standard library in
+Python 3.13**. `uv` installs a suitable interpreter itself, and its 3.12 build
+ships tkinter, so there is no separate Tk step.
+</details>
+
+---
+
+## 🎯 Using it
+
+1. Open the app. If audio routing is not in place, it offers to finish it.
+2. Pick a mode, and set the number of people if you know it.
+3. Hold your meeting. Nothing needs touching.
+4. **Export** — one dialog covers format, cleanup, which model to clean with,
+   and merging over-split speakers.
+
+Cleanup runs in the background with a progress bar and an estimate, and can be
+stopped: whatever finished is kept.
+
+### Choosing a cleanup backend
+
+| | Cost | Speed (measured) |
+|---|---|---|
+| **API** (`conf.yaml`) | per token | 5–8s per batch of lines |
+| **Claude CLI** | included in a subscription | 20–50s per batch |
+
+Both are offered at export, and the dialog turns the per-batch figure into an
+estimate for the transcript in hand. The live reply suggestions always use the
+configured API — a CLI takes seconds per answer, which is too late to be useful
+while someone is still talking.
+
+### Past recordings
+
+```bash
+echoai-helper sessions              # list them
+echoai-helper sessions --export 0   # export one again
+echoai-helper sessions --delete 0
+```
+
+Re-exporting is the point: a different format, another pass of cleanup, a
+different number of speakers, without re-recording anything. An unfinished
+session from the last 12 hours is offered on the next launch.
+
+---
+
+## ⚙️ Configuration
+
+Model settings live in `conf.yaml`; everything else is in the app. Installed
+from a wheel the shipped copy sits inside the package, so make yourself an
+editable one:
+
+```bash
+echoai-helper config     # writes conf.yaml where you can reach it, and prints the path
+```
+
+That copy overrides the defaults. You will not usually need it — both values
+below already ship as `auto`.
+
+```yaml
+FunASR:
+  model_name: "iic/SenseVoiceSmall"
+  device: "auto"        # cuda, then mps, then cpu
+  language: "auto"      # zh, en, yue, ja, ko
+
+LLM:
+  provider: "openai"    # openai | litellm | cli
+```
+
+Both `auto` values are load-bearing rather than lazy defaults:
+
+- **`device: "auto"`** — measured on an M4, dual-track real-time factor is 2.04
+  on cpu (falling behind twice over) against 0.35 on Metal. Landing on cpu by
+  accident means transcription that cannot keep up. Naming a device explicitly is
+  also wrong on every machine that does not have it, and this file travels.
+- **`language: "auto"`** — pinning a language does not bias the model, it forces
+  the syllables onto words of that language. A Cantonese call transcribed with
+  `language: "en"` comes back as fluent nonsense.
+
+An OpenAI key goes in `.env` (see `.env.example`), or in a file called `.llm`
+holding nothing else. Both are gitignored.
+
+---
+
+## 🔍 Troubleshooting
+
+```bash
+echoai-helper check-audio           # what is being captured, and from where
+echoai-helper setup --status        # what routing is in place
+```
+
+**Nothing from the far end (macOS).** The meeting app has its own audio settings
+and remembers them. Set its speaker to `EchoAI Meeting`.
+
+**Nothing from the microphone over Bluetooth.** A Bluetooth headset can only send
+its microphone to one device. If it is on a phone call, the Mac gets silence —
+and the stream does not recover on its own; restart the app. A USB microphone
+avoids this entirely.
+
+**More speakers than people.** Voice prints drift with volume and connection
+quality, so one person can end up split across several labels. Set the number of
+people before the meeting, or merge them at export — the export carries the voice
+prints, so this works after the fact.
+
+---
+
+## 🛠️ Development
+
+```bash
+git clone https://github.com/colakang/echoai_helper.git
+cd echoai_helper
+uv venv --python 3.12 .venv
+uv pip install --python .venv/bin/python -r requirements-macos.txt   # or requirements.txt
+.venv/bin/python -m pytest tests/ -q
+```
+
+[`docs/macos-audio-setup.md`](docs/macos-audio-setup.md) covers the audio
+routing, what has been measured, and where the sharp edges are.
+
+---
+
+## 📝 Known limitations
+
+- **A dead microphone stream does not recover.** Seen on a real call: capture
+  stops silently and the app looks like it is still working. Restarting fixes it.
+  This is the most consequential item on the list.
+- **Speaker labelling is tuned against a clean two-party recording** and
+  over-splits on group calls over a lossy connection. Merging at export is the
+  workaround, not the cure.
+- **The Windows capture path is untested** since the segmentation rework. Its
+  detector threshold was lowered to pass silence through, because segmentation
+  now happens on pauses and a recogniser that only reports speech never delivers
+  them — reasoned, not verified. Reports welcome.
+- **macOS audio routing is a shared setting.** Selecting the Multi-Output changes
+  the output for every app, and macOS sometimes moves it back after sleep.
+  Checked at every launch.
+
+## 🤝 Contributing
+
+Pull requests welcome; for anything substantial, open an issue first. See
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+## 🙌 Credits
+
+- [FunASR](https://github.com/modelscope/FunASR) — speech recognition and speaker
+  embeddings
+- [silero-vad](https://github.com/snakers4/silero-vad) — voice activity detection
+- [WhisperLiveKit](https://github.com/QuentinFuxa/WhisperLiveKit) — the
+  LocalAgreement idea behind stable partial transcripts
+- [BlackHole](https://existential.audio/blackhole/) — virtual audio device on macOS
+- [CustomTkinter](https://github.com/TomSchimansky/CustomTkinter) — interface
+- [Ecoute](https://github.com/SevaSk/ecoute) — the original inspiration
+- [@zixing0131](https://github.com/zixing0131) — core audio processing
+
+## 📞 Contact
+
+[echo365.ai](https://www.echo365.ai) · [Issues](https://github.com/colakang/echoai_helper/issues)
+
+## 📄 License
+
+MIT — see [LICENSE](LICENSE).

echoai_helper-1.2.0.dist-info/RECORD

@@ -0,0 +1,67 @@
+echoai_helper-1.2.0.dist-info/licenses/LICENSE,sha256=GENvlKmKL1xWmXu4yDRd4C0gU-lxMCA9Z1L_iNqeMSw,1066
+scripts/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+scripts/calibrate_vad.py,sha256=_erRGc6aqCUSI-_BzdeYIko18svt-E2KxVtF2Q3Fauc,6622
+scripts/check_audio.py,sha256=rwD6U0aNnDIa40_7w83v9PgCzjn7MT2Q613KptbolUY,10858
+scripts/install_launcher.py,sha256=yJaI1ycXjTjhTK6sCS7gDkruia1nKkmCtP89KeClxBQ,1788
+scripts/setup_audio.py,sha256=AKhN56YimIYpXTi5KyqrxSvIkR87Zb_PT_L6_oGcULY,2284
+src/AudioRecorder.py,sha256=3g4NEehNZLCYL2WdP_OUfyhl5KHTB3ibQAVgQez_sy4,2705
+src/AudioTranscriber.py,sha256=dPf6CewhJbZJ8qQwPFhNOLcQQhHMYcKRGejUcmhhNmo,23774
+src/GPTResponder.py,sha256=0VYEw9YU7THfXxSd7zI88zjyiKJjlpEPsVi5TAYel4o,11872
+src/ResponseManager.py,sha256=Db7O261PDbvCmElw_UUC0QWjPMRFBtjzMj2yNOWF3_E,15729
+src/SettingsManager.py,sha256=VEtbIlvDVAFFMF_qZSU89RAMlz4og-WOEVRIKvT82lM,5356
+src/TemplateManager.py,sha256=4cquOIaZvb5WoH8fiwOisYa9U_q7k4LApPg3wHoGMR8,7981
+src/TranscriberModels.py,sha256=qY9D-16BINGM0Ln-O6SInrX4En_KWohJfQ0WjgIZNUA,5873
+src/TranscriptUI.py,sha256=mU7SJw_8upHYoVrp2jvVN4lNrkIaspB_U4PCD_rRUCI,22921
+src/app.py,sha256=Ca9lwjQYFJZ8cUrvHaISFbHke08vYsGGmsyNkdPqrI0,41005
+src/cli.py,sha256=VcRg6jKO6Y3HEFyHwKK_aYD1YM2BUfCDRd5sP4OKKNc,5482
+src/conf.yaml,sha256=iHTFARU1Mk6vxZD7NnGSUD_zAo2bY-I9JGPYYkr4f1Y,5081
+src/config.py,sha256=mxw4v-i7MSwEcqLTL9Qwv78ypVK9nF9LXIXt6H6szV0,10445
+src/export_dialog.py,sha256=AuFqln9iWgGbomXLcvATMiiqzVzBX1RizBpG12U6yBw,14037
+src/export_markdown.py,sha256=-nbylYUu-S3bVLdM8xD1SKkmMVn78IUdpNQfchqkhms,6277
+src/launcher_macos.py,sha256=99gH39JIxup8_t2AYVeCSnKLon5djhKb4e_Avbg4DDA,6020
+src/polish.py,sha256=iuheB_i0MwEjpjz5a_qRQCu1tNllkDwJL4Cdg143-nM,9275
+src/profiles.py,sha256=qSZ32T9Pop3vDHUgTavLimCpyj9uqDWQFIQoeQslw2g,3357
+src/prompts.py,sha256=tVF7zH5PIGfuTzOPllHUC_5NwgJhKiq3ANtdiv_SJkQ,3657
+src/session.py,sha256=kspPbn14Cu3D-ZYR6iVf4-xmKMGFeoodGvVyRtIihlg,10717
+src/asr/asr_factory.py,sha256=zygmh9G_QVOdbBU3owzKTXQgqnkYcUbcVL5wpGKn_ZM,1877
+src/asr/asr_interface.py,sha256=pRv_ZSbv1oYMpnwoH9_6-anl8g0-tQIJ5YPmSEpBIDU,1022
+src/asr/asr_with_vad.py,sha256=5vbnrKpefTtgayhT87vw5oI6bQ93MI8c92CadW9IiZ8,10251
+src/asr/azure_asr.py,sha256=te6CoB9iHwDzLqnPhYOP6xpyL9XZcHhWF5NU7z4hupA,3290
+src/asr/diarization.py,sha256=_VJzWoFm5HdzYSgbrR9r6RhAlDOGSvgcEBMuv0Y-Wgo,9636
+src/asr/faster_whisper_asr.py,sha256=a3myeI6dguNIcCxw-SPrVCp7Jj-NX8jh_lmHR4e7ZcU,1288
+src/asr/fun_asr.py,sha256=kh566fUHC-VtqLOafGHan2072NV_7jHBhklG9yhNJgE,3678
+src/asr/hypothesis.py,sha256=GcNiho_-t5M5UUJXnZoi8yABex0nrePUP_466Y0PR7g,6532
+src/asr/openai_whisper_asr.py,sha256=6sf-xaM38Zpxy4hP1D0JlEQ292zClGfQRgd7ICA2KMY,903
+src/asr/segmenter.py,sha256=4B_yga7a8SNbGxTRdp8JGYY6A8KiT6JZyCvnZ06_qtU,11779
+src/asr/vad.py,sha256=hq6gR0CYTgir8e824hkgI955VOVXVzkSO5hTbwT7p8M,1921
+src/asr/whisper_cpp_asr.py,sha256=CI7pwQ6Pqfb1PLo7WIeT0lt0C1cZSzBIaltT-2DR4fk,1150
+src/asr/models/silero_vad.onnx,sha256=o16_Uv085fFGmyo2FY26dhvEe5c-ozgrMYbKFbH1ryg,1807522
+src/audio/__init__.py,sha256=CWzsEu7UBUhom60q3zY_scFxgXuLXD_BNZmAgwqy9dw,1175
+src/audio/backend.py,sha256=PxApwHfyvxRAJx62VwWi3KN1uFPlpRyYH6EBUa-tn7c,4106
+src/audio/coreaudio.py,sha256=pSG30wWDCqP7UrmyUdFQ3hxxKIrKP1ueJB_aP1tN01k,10951
+src/audio/macos.py,sha256=G8GtUPvTsxtkGgtA4beYHnU_aDbZdZ4gfofLaVeh8UQ,6707
+src/audio/setup_macos.py,sha256=pjwK6dXQ4r-GeDl2xS2PW4bFbQ83ve3nQ4DM2DQpb_E,13993
+src/audio/windows.py,sha256=s4MsX1I8XRkmWT7_NnY2aRB7WofgWlCSyuN9WfzGWPQ,4194
+src/custom_speech_recognition/__init__.py,sha256=k6-RB8BivP6i3FJA0ZTKSzMYKtlI6tRt5wMDHgKAKV4,92343
+src/custom_speech_recognition/__main__.py,sha256=Afbp3l1yq2AW2Bsm7YBz-O0wm6gHNudgPZh69Ijjubc,833
+src/custom_speech_recognition/audio.py,sha256=THoN6uaHcbbwcvhW6vzkBpAZkpP8s-ouClba48KbOkw,14824
+src/custom_speech_recognition/exceptions.py,sha256=LnKmutOVQ6RSMcSO1Ji5Af-UZN-Aqrq4petMgBFXkKs,273
+src/llm/__init__.py,sha256=NxnYypZQbgQGTISvHVPnY6epbiwDoCbwtpKoEjuOtvI,107
+src/llm/cli_provider.py,sha256=3L1tPbtjoyXv4QsgRZVdtRUDE2rI2_P7FQeU_3Jrb6k,7193
+src/llm/litellm_provider.py,sha256=ynhRyyGoJ7YSYnQ6wa3ZmGI1SeV_wN1iRSc58Vlss0c,4815
+src/llm/llm_provider.py,sha256=WtDqYeTymv-qB5M0Ebz7WonQKqrPnA4BfwuhAMtBiPg,1122
+src/llm/openai_provider.py,sha256=9TMKZpK2BDNoJp8GcyXgmgfDEMIe8n7hrp377q4aRQo,2540
+src/llm/provider_factory.py,sha256=n1weyKvWF9JnZ5sHOnh1p-6_aq5cyKtoZpM2bQ_xsQ0,2941
+src/resources/config/settings.json,sha256=QKvOifkogZpb_owPEMAve7r7SLbkXiih89nazuCWauQ,306
+src/resources/prompt/Interview Analysis.md,sha256=stVlPDLrXYPbO9Wg3ex73rnIYQrfSCSLN2uE_zS-oLs,2885
+src/resources/prompt/Meeting Analysis.md,sha256=_YdMLJ_jCclxrDOHHsl5EzYa4XqiK5QBhKMut7SngvQ,7976
+src/resources/prompt/case_detail/inbound_cs.txt,sha256=JJhU8OCCXOTOVAjmJjrU8s5oNb5zsE7AVX6Nebh0he0,1180
+src/resources/prompt/case_detail/none.txt,sha256=AO0frMCzJXR3KHDQWPu-WnUFUYnuKiQKQbHvfPRfgmc,8
+src/resources/prompt/knowledge/none.txt,sha256=6RcVRI85-y-CqHADDxMdwYn67HD6JxyfVme0mDKPdQU,7
+src/resources/prompt/system_role/inbound_cs.py,sha256=5kMRdhhuTDIbJ2awrVhqVHoRzlIHSQMP2u49dOHDQDM,1235
+src/resources/prompt/system_role/phone_interview.py,sha256=vf-OB-NjSRtxYEc_eH08DyBQwtxSEY8Xha-n7FQnWng,1194
+echoai_helper-1.2.0.dist-info/METADATA,sha256=v590S7f0e0wO0VGTRUVy7olaoqsFVVZwtFxzlD8y9q8,11890
+echoai_helper-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+echoai_helper-1.2.0.dist-info/entry_points.txt,sha256=HNWAt73pLEsWFen4F5bVbGyOHOoJJQ-yL_OD0cwCLp8,47
+echoai_helper-1.2.0.dist-info/top_level.txt,sha256=2u1B708VEAisYx1t_BY-Ya_-RVnGzeibiEH429s02AM,12
+echoai_helper-1.2.0.dist-info/RECORD,,

echoai_helper-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

echoai_helper-1.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+echoai-helper = src.cli:main

echoai_helper-1.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Cola Kang
+
+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.

echoai_helper-1.2.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+scripts
+src

scripts/calibrate_vad.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+"""
+scripts/calibrate_vad.py — pick VAD thresholds from a real recording.
+
+min_silence_ms is the dominant accuracy/latency knob in the pipeline: too
+short splits sentences and denies the model the context it needs to
+punctuate; too long merges separate turns and delays the "sentence finished"
+signal that triggers LLM cleanup.
+
+It cannot be set from synthesised speech. `say` produces near-continuous
+audio whose longest pause is ~0.3s, where a real speaker pauses 0.5-2s
+between sentences. Record 30-60s of ordinary talking -- ideally the actual
+meeting or interview setting, with its real background noise -- and run:
+
+    .venv/bin/python scripts/calibrate_vad.py recording.wav
+
+    # also transcribe each segment, to see what the model receives
+    .venv/bin/python scripts/calibrate_vad.py recording.wav --transcribe
+
+Any format ffmpeg reads is fine; it is converted to mono 16kHz internally.
+"""
+
+import argparse
+import os
+import subprocess
+import sys
+import tempfile
+
+import numpy as np
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.asr.segmenter import (  # noqa: E402
+    Event, SegmenterConfig, SpeechSegmenter, SAMPLE_RATE, WINDOW_SAMPLES,
+)
+from src.asr.vad import VAD  # noqa: E402
+
+VAD_MODEL = os.path.join(
+    os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+    "src", "asr", "models", "silero_vad.onnx",
+)
+
+CANDIDATE_SILENCE_MS = [200, 300, 400, 500, 700, 1000, 1500]
+
+
+def load_audio(path: str) -> np.ndarray:
+    """Decode anything ffmpeg understands into mono float32 @16kHz."""
+    import soundfile as sf
+
+    with tempfile.TemporaryDirectory() as tmp:
+        wav = os.path.join(tmp, "audio.wav")
+        subprocess.run(
+            ["ffmpeg", "-y", "-loglevel", "error", "-i", path,
+             "-ar", str(SAMPLE_RATE), "-ac", "1", "-c:a", "pcm_s16le", wav],
+            check=True,
+        )
+        data, rate = sf.read(wav, dtype="float32")
+    assert rate == SAMPLE_RATE
+    return data
+
+
+def probability_profile(audio: np.ndarray) -> np.ndarray:
+    vad = VAD(VAD_MODEL)
+    return np.array([
+        float(vad.process_chunk(audio[i:i + WINDOW_SAMPLES]))
+        for i in range(0, len(audio) - WINDOW_SAMPLES, WINDOW_SAMPLES)
+    ])
+
+
+def describe_pauses(probabilities: np.ndarray, threshold: float) -> None:
+    """Where the natural boundaries actually are in this recording."""
+    below = probabilities < threshold
+    runs, current = [], 0
+    for quiet in below:
+        if quiet:
+            current += 1
+        elif current:
+            runs.append(current * 100)
+            current = 0
+    if current:
+        runs.append(current * 100)
+
+    print(f"  speech probability: median {np.median(probabilities):.2f}  "
+          f"above {threshold}: {(~below).mean() * 100:.0f}% of windows")
+    if not runs:
+        print("  no pauses at all — nothing to segment on")
+        return
+
+    runs.sort()
+    print(f"  {len(runs)} pauses, longest {max(runs)}ms, median {int(np.median(runs))}ms")
+    buckets = [(200, 300), (300, 500), (500, 800), (800, 1500), (1500, 10 ** 9)]
+    for low, high in buckets:
+        count = sum(1 for r in runs if low <= r < high)
+        if count:
+            label = f"{low}-{high}ms" if high < 10 ** 9 else f">{low}ms"
+            print(f"    {label:>12}: {count}")
+
+
+def segment_with(audio: np.ndarray, config: SegmenterConfig):
+    vad = VAD(VAD_MODEL)
+    segmenter = SpeechSegmenter(vad, config)
+    segments = []
+    step = int(0.6 * SAMPLE_RATE)      # the recorder's real chunk size
+    for i in range(0, len(audio), step):
+        for event, segment in segmenter.process(audio[i:i + step]):
+            if event is Event.SPEECH_END:
+                segments.append(segment)
+    tail = segmenter.flush()
+    if tail is not None:
+        segments.append(tail)
+    return segments
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__,
+                                     formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("audio", help="a real recording of ordinary speech")
+    parser.add_argument("--transcribe", action="store_true",
+                        help="transcribe each segment (loads FunASR)")
+    parser.add_argument("--speech-threshold", type=float, default=0.6)
+    parser.add_argument("--silence-threshold", type=float, default=0.35)
+    args = parser.parse_args()
+
+    if not os.path.exists(args.audio):
+        print(f"[FATAL] no such file: {args.audio}")
+        return 1
+
+    audio = load_audio(args.audio)
+    duration = len(audio) / SAMPLE_RATE
+    print("=" * 70)
+    print(f"{os.path.basename(args.audio)} — {duration:.1f}s")
+    print("=" * 70)
+
+    describe_pauses(probability_profile(audio), args.silence_threshold)
+    print()
+
+    print("=" * 70)
+    print("SEGMENTATION vs min_silence_ms")
+    print("=" * 70)
+    print(f"  {'min_silence':>12} {'segments':>9} {'median':>8} {'longest':>8}   capped")
+    results = {}
+    for ms in CANDIDATE_SILENCE_MS:
+        config = SegmenterConfig(
+            speech_threshold=args.speech_threshold,
+            silence_threshold=args.silence_threshold,
+            min_silence_ms=ms,
+        )
+        segments = segment_with(audio, config)
+        results[ms] = segments
+        if not segments:
+            print(f"  {ms:>10}ms {0:>9}")
+            continue
+        durations = [s.duration_s for s in segments]
+        # Segments at the ceiling were cut by the cap, not by a real pause:
+        # a high count means this threshold is not finding boundaries.
+        capped = sum(1 for d in durations if d >= config.max_segment_s - 0.5)
+        print(f"  {ms:>10}ms {len(segments):>9} {np.median(durations):>7.1f}s "
+              f"{max(durations):>7.1f}s   {capped}")
+
+    print()
+    print("  A good setting gives segments of roughly one sentence (2-10s)")
+    print("  with no capped ones. Many capped segments means the threshold is")
+    print("  too long and no natural pause is ever reaching it.")
+
+    if args.transcribe:
+        print()
+        print("=" * 70)
+        print("TRANSCRIPTS")
+        print("=" * 70)
+        from src.TranscriberModels import get_model
+        model = get_model(use_api=False)
+        for ms in (300, 500, 700):
+            segments = results.get(ms, [])
+            print(f"\n--- min_silence={ms}ms, {len(segments)} segments ---")
+            for index, segment in enumerate(segments[:8]):
+                text = model.get_transcription_np(segment.audio).text
+                print(f"  [{index}] {segment.duration_s:4.1f}s  {text!r}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())