@sfgartland/better-pi-voice 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-18
+
+### Added
+
+- **Non-destructive recording queue.** Starting a recording while earlier ones are still
+  transcribing no longer drops the new utterance: each recording is queued, transcribed
+  exactly once, and its text is inserted in **recording-start order**, even when calls
+  finish out of order. When the queue is full (4 jobs, or 8 MiB of buffered audio) a new
+  capture is refused with a notice instead of silently discarding audio, and the status
+  line reports the queue depth.
+- **Silero VAD** for batch cuts, behind a new `PauseDetector` interface, with the existing
+  RMS level heuristic as the fallback when the VAD model is unavailable.
+- **Eager batch cuts:** beginning a new recording asks the previous batch tail to transcribe
+  immediately instead of waiting for the chunk target.
+- A `pi-package` contract guard (`src/packaging.test.ts`) plus install/discoverability notes,
+  so the manifest cannot silently drop out of the pi package gallery.
+
+### Changed
+
+- **Sequence-aware transcription plumbing.** `EditorSink` rebuilds `prefix + finals in
+  order + live interim`, suppresses interims while jobs are pending, and submits once per
+  drained queue; `submitOnStop` no longer fires once per final.
+- **Resident local model window** raised to 60 s (`idleUnloadMs` 0 -> 60000), so
+  back-to-back recordings stop reloading the model.
+- **Batch chunk length** settled at 15 s (`chunkSeconds` 30 -> 15), matching
+  `DEFAULT_CHUNK_SECONDS`.
+- **Keyterm budget is per backend:** Deepgram 100 (its cap), local correction 60.
+- `dispose()` is now async and drains stored text on shutdown.
+
+### Fixed
+
+- A recording started during transcription was **silently dropped** (the microphone was
+  never opened and the utterance was lost with no notification). This was the bug the
+  queue replaces.
+- Parakeet sessions are refcounted and `model.transcribe` is serialized, so an
+  unload/dispose can never free the model under a queued job.
+- Failed, empty or hung jobs always free their queue slot via a reap timeout, so one bad
+  job cannot deadlock the queue.
+- Stale Parakeet header comments and the README "not implemented yet" line are corrected.
+- The fresh-install test now polls for the setup file instead of racing a fixed delay.
+
+## [0.1.1] - 2026-10-16
+
+### Added
+
+- A `media/demo.mp4` storyboard of the before/after transcription, wired into the
+  package manifest as `pi.video` so the [pi package gallery](https://pi.dev/packages)
+  can preview it.
+
+### Fixed
+
+- **A skill file no longer becomes the keyterm `SKILL`.** Keyterms are mined from the
+  basenames of files the session touches, so reading `…/skills/<name>/SKILL.md` mined
+  the generic document stem `SKILL`. The local backend's correction pass then rewrote
+  ordinary words one edit away from it — `still`, `spill`, `skull` and `swill` all came
+  back as `SKILL`. Generic document names (`SKILL`, `README`, `INDEX`, `LICENSE`,
+  `CHANGELOG`, …) now mine their parent directory instead, which carries the name that
+  actually matters, and a mined term that collides with the seed jargon is no longer
+  eligible for fuzzy repair.
+
+## [0.1.0] - 2026-10-16
+
+First release.
+
+### Added
+
+- Streaming voice input for pi, one shortcut away (`ctrl+alt+z` by default), with
+  hold-to-talk and tap modes and a hard cap so a stuck key cannot leave the microphone
+  open.
+- **Two interchangeable backends**: Deepgram `nova-3` streaming, or local Parakeet via
+  `transcribe-cpp`.
+- **Repository-aware vocabulary biasing.** Keyterms are mined from the project name,
+  the git repository, file paths touched by the session, paths mentioned in messages,
+  a developer-jargon seed list and your own list, then sent to Deepgram as repeated
+  `keyterm` parameters (native biasing) and updatable live with a `Configure` message.
+  The local backend, which cannot be vocabulary-biased (`supports("vocabulary")` is
+  `false` for the Parakeet GGUFs), gets a deterministic correction pass instead:
+  re-joining identifiers the recogniser split, and repairing one misheard token within
+  a small edit distance of a keyterm.
+- **A recovery layer that never loses a sentence**: one early retry before the first
+  transcript, replay of the retained audio when a stream dies unconfirmed, salvage of a
+  partial transcript when the socket dies late, promotion of an unreported interim, and
+  a circuit breaker after repeated fast failures. Audio is buffered in memory only and
+  never written to disk.
+- **Local batch mode with pause-aware chunking**: audio is cut at real (silence-checked)
+  pauses while you speak and transcribed in the background, so only the tail is left at
+  finalize. The pause threshold is derived per recording, and a chunk is only cut where
+  the signal is genuinely quiet, so a chunk never starts mid-word.
+- **Guided setup** (`/voice setup`, or the first shortcut press with no settings):
+  backend, key or model (with checksum-verified, resumable model downloads), run mode,
+  and shortcut, ending in an overview of the result.
+- Commands: `/voice`, `/voice setup`, `/voice backend`, `/voice model`, `/voice key`,
+  `/voice set`, and `/voice-keyterms add|remove|list`.
+- Diagnostics that name the cause rather than the symptom — a failed connection
+  distinguishes a rejected key, an unreachable host, and an HTTP error.
+- A `media/screenshot.png` before/after card, exposed to the gallery as `pi.image`.
+
+[Unreleased]: https://github.com/sfgartland/better-pi-voice/compare/v0.1.1...HEAD
+[0.1.1]: https://github.com/sfgartland/better-pi-voice/releases/tag/v0.1.1
+[0.1.0]: https://github.com/sfgartland/better-pi-voice/releases/tag/v0.1.0

package/README.md

@@ -1,8 +1,10 @@
 # @sfgartland/better-pi-voice
 
+![the same sentence transcribed without keyterms (sub agent, Worktree T's config) and with them (subagent, worktree tsconfig)](https://raw.githubusercontent.com/sfgartland/better-pi-voice/main/media/screenshot.png)
+
 Streaming voice input for pi. Hold a key, talk, and the words land in the editor —
 in the right spelling, including the jargon and filenames generic speech
-recognition gets wrong.
+recognition gets wrong. ([8-second demo](https://github.com/sfgartland/better-pi-voice/raw/main/media/demo.mp4))
 
 Two interchangeable backends behind one pipeline:
 
@@ -85,6 +87,10 @@ pi install /path/to/better-pi-voice        # from a local checkout
 pi install npm:@sfgartland/better-pi-voice      # once published
 ```
 
+The npm package is gallery-discoverable: it carries the `pi-package` keyword and
+declares its extension, so `pi install npm:@sfgartland/better-pi-voice` also works from
+the pi package gallery.
+
 Then add a Deepgram key. The easiest way is `/voice key`:
 
 - `/voice key <path-to-dotenv>` — use a key from an existing dotenv file (it checks one is
@@ -250,8 +256,8 @@ There is **no streaming model lighter than parakeet-0.6b**. The genuinely small
 `medasr` (128 MB), `parakeet-tdt_ctc-110m` (135 MB), `canary-180m-flash` (218 MB),
 `SenseVoiceSmall` (253 MB), `whisper-small` (270 MB) — are all batch-only, so using one
 means giving up live text and transcribing after you release the key. With batch running
-at 3.5× real-time that is a reasonable trade, and the pipeline already retains the whole
-utterance, but it is not implemented yet.
+at 3.5× real-time that is a reasonable trade, and the pipeline retains the whole
+utterance, chunk-transcribes it while you speak, and finishes the tail when you release.
 
 For non-English dictation, `nemotron-3.5-asr-streaming-0.6b` is the only streaming option
 that is not parakeet, at the same size.
@@ -265,7 +271,7 @@ option for the small models, none of which can stream.
 In batch mode the audio is transcribed in pieces while you are still speaking, so only
 the tail is left when you release the key:
 
-- `parakeet.chunkSeconds` (default 30) is a **target, not a limit**, and only its lower
+- `parakeet.chunkSeconds` (default 15) is a **target, not a limit**, and only its lower
   70% matters: the audio is cut at the **first real pause** at or after that point and
   transcribed in the background. A pause arriving later than the target still triggers a
   cut, and unbroken speech simply grows a longer chunk
@@ -293,21 +299,36 @@ returns an **empty transcript** for any clip that begins mid-sentence, so a chun
 merely the *quietest* moment silently discarded everything in it. Requiring real silence
 costs tail latency on unbroken speech instead of costing speech.
 
+### Recording queue
+
+Recordings never block each other. Press the shortcut again while an earlier recording
+is still being transcribed and a new one starts immediately; results are always emitted
+in the order the recordings *started*, even when a later one finishes first.
+
+- one capture at a time; each recording carries a sequence number and its own audio
+- at most **4** recordings may be waiting, and at most **8 MiB** of buffered audio. When
+  either is reached the new press is **refused with a notification** rather than
+  silently dropped
+- a job that never settles is abandoned after `jobReapMs` (default 30 s) so the queue
+  always advances; a recording that produced nothing stores `""` and is skipped, which
+  keeps the order intact
+- the status line shows the depth (`1 recording`, `3 recordings`), so a backlog is
+  visible without opening anything
+- with `submitOnStop`, a drained queue is submitted **once**, not once per recording
+
 ### Keeping the model loaded
 
-The model is **released after every recording by default**, because a warm reload is only
-about 0.4 s and holding ~700 MB between recordings is not a good trade on a laptop. Set
-`parakeet.idleUnloadMs` to keep it resident instead — useful for larger models, where a
-reload costs real time. When residency is on, the model is released by whichever of these
-happens first:
+The model is **held for a minute after the last recording by default**
+(`parakeet.idleUnloadMs` is `60000`). Queued recordings arrive in bursts, and a warm
+reload of a 135 MB–700 MB GGUF is felt between each one, so keeping it resident across a
+burst is the better trade. Residency is released by whichever of these happens first:
 
-- the idle window expires (`parakeet.idleUnloadMs`)
+- the idle window expires (`parakeet.idleUnloadMs`; set it to `0` to release as soon as
+  the queue empties)
 - the machine gets busy — one-minute load average per CPU reaching **0.8**
   (`parakeet.loadShedRatio`), checked once a minute
 
 A new recording cancels a pending release, and session shutdown releases immediately.
-Note that the load-shedding half only matters while residency is on: at the default of 0
-the memory is already back after each recording, so there is nothing to shed.
 
 ## Settings
 
@@ -332,9 +353,9 @@ malformed falls back to a default and warns rather than breaking the microphone.
   "parakeet": {
     "modelPath": null,                // null = read pi-voice's config if present
     "mode": "batch",                  // "batch" (faster, chunked) | "streaming"
-    "chunkSeconds": 30,               // cut at a pause near this length; 0 = only at the end
+    "chunkSeconds": 15,               // cut at a pause near this length; 0 = only at the end
     "silenceLevel": "auto",           // "auto" derives the pause threshold per recording; a number pins it
-    "idleUnloadMs": 0,                // 0 = release after each recording (see above)
+    "idleUnloadMs": 60000,            // hold the model this long after the queue empties; 0 = release at once
     "loadShedRatio": 0.8              // with residency on, release early once load per CPU reaches this
   },
   "keyterms": {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sfgartland/better-pi-voice",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"description": "Streaming voice input for pi: Deepgram (nova-3, repo-aware keyterms) or local Parakeet, with Claude-Code-style recovery so speech is never lost.",
 	"license": "MIT",
 	"author": "Severin Gartland <sfgartland@hotmail.com>",
@@ -10,7 +10,7 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/sfgartland/better-pi-voice"
+		"url": "git+https://github.com/sfgartland/better-pi-voice.git"
 	},
 	"homepage": "https://github.com/sfgartland/better-pi-voice#readme",
 	"bugs": {
@@ -36,6 +36,7 @@
 		"!src/**/*.test.ts",
 		"!src/testing/",
 		"README.md",
+		"CHANGELOG.md",
 		"LICENSE"
 	],
 	"peerDependencies": {
@@ -57,7 +58,8 @@
 		"extensions": [
 			"./index.ts"
 		],
-		"image": "https://raw.githubusercontent.com/sfgartland/better-pi-voice/main/media/screenshot.png"
+		"image": "https://raw.githubusercontent.com/sfgartland/better-pi-voice/main/media/screenshot.png",
+		"video": "https://raw.githubusercontent.com/sfgartland/better-pi-voice/main/media/demo.mp4"
 	},
 	"scripts": {
 		"typecheck": "tsc --noEmit",