@sfgartland/better-pi-voice 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,67 @@
+# 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.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:
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sfgartland/better-pi-voice",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"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",

package/src/keyterms/index.ts

@@ -26,6 +26,9 @@ export {
 } from "./sanitize.ts";
 export { SEED_KEYTERMS } from "./seed.ts";
 
+/** Seed terms lowercased, so a mined term that collides with one can be spotted. */
+const SEED_LOWER = new Set(SEED_KEYTERMS.map((term) => term.toLowerCase()));
+
 export type CollectOptions = MineInput & {
 	/** Terms the user configured by hand. Highest priority. */
 	userTerms?: readonly string[] | undefined;
@@ -61,7 +64,12 @@ export function collectKeytermSets(options: CollectOptions = {}): KeytermSet {
 	const mined = mineKeyterms(options);
 	const biasOrder = options.useSeed !== false ? [...user, ...SEED_KEYTERMS, ...mined] : [...user, ...mined];
 	const bias = sanitizeKeyterms(biasOrder, { maxTerms: options.maxTerms });
-	const correct = sanitizeKeyterms([...user, ...mined], { maxTerms: options.maxTerms });
+	// A mined term that collides with the seed jargon (a file named `settings.ts`,
+	// say) is still only an ordinary English word. It may bias the recogniser, but
+	// fuzzy repair must not aim at it — the seed is excluded from correction for
+	// exactly that reason. User terms are explicit, so they are left alone.
+	const correctable = mined.filter((term) => !SEED_LOWER.has(term.toLowerCase()));
+	const correct = sanitizeKeyterms([...user, ...correctable], { maxTerms: options.maxTerms });
 	const cap = options.maxTerms ?? DEFAULT_MAX_TERMS;
 	// Something was actually dropped, and the budget is what dropped it.
 	return { bias, correct, truncated: bias.length >= cap && biasOrder.length > bias.length };

package/src/keyterms/mine.ts

@@ -6,7 +6,7 @@
  * what makes recognition of jargon and filenames work.
  */
 
-import { basename } from "node:path";
+import { basename, dirname } from "node:path";
 import { tokenizeLabel } from "./sanitize.ts";
 
 /** Tools whose arguments name a file the user cares about. */
@@ -103,6 +103,44 @@ function stem(path: string): string {
 	return dot > 0 ? base.slice(0, dot) : base;
 }
 
+/**
+ * Stems that name a document rather than a thing.
+ *
+ * A file called `SKILL.md` (or `README.md`, `INDEX.md`, …) is a convention. Its
+ * stem is a generic English word, not vocabulary, and mining it is actively
+ * harmful: the correction pass then rewrites real words one edit away from it
+ * (`still`, `spill`, `skull` and `swill` all became `SKILL`). For these names the
+ * parent directory is the informative one — `…/skills/brainstorming/SKILL.md` is
+ * about brainstorming.
+ */
+const GENERIC_STEMS = new Set([
+	"skill",
+	"readme",
+	"index",
+	"license",
+	"licence",
+	"changelog",
+	"contributing",
+	"copying",
+	"notice",
+	"authors",
+	"todo",
+	"main",
+	"package",
+	"setup",
+]);
+
+/** The terms one file path contributes: usually its stem, else its parent directory. */
+function termsFromPath(path: string): string[] {
+	if (!GENERIC_STEMS.has(stem(path).toLowerCase())) return tokenizeLabel(stem(path));
+
+	const parent = basename(dirname(path));
+	// A generic name with no directory (`SKILL.md`) or at a filesystem root has
+	// nothing informative to offer; mining `.` or `/` would only add noise.
+	if (!parent || parent === "." || parent === "/") return [];
+	return tokenizeLabel(parent);
+}
+
 /**
  * Build the candidate term list. Order matters: callers that truncate will
  * prefer the earlier entries, so the most specific signals come first.
@@ -122,12 +160,12 @@ export function mineKeyterms(input: MineInput): string[] {
 	}
 
 	for (const path of input.filePaths ?? []) {
-		out.push(...tokenizeLabel(stem(path)));
+		out.push(...termsFromPath(path));
 	}
 
 	for (const text of input.texts ?? []) {
 		for (const token of pathLikeTokens(text)) {
-			out.push(...tokenizeLabel(stem(token)));
+			out.push(...termsFromPath(token));
 		}
 	}