pi-push-to-talk 0.1.0 → 0.2.0

package/README.md

@@ -25,7 +25,7 @@ Remove any other voice extension first. Several of them also bind space or repla
 | Pause 2.5 s while holding | The open phrase is committed and dictation continues |
 | Tap space | An ordinary space, as usual |
 
-While you speak, the open phrase is drawn dim; committed text is normal.
+While you speak, the open phrase is drawn dim; committed text is normal. The footer alternates a red `●` with `○` every 600 ms: `● listening` while the microphone is live, or `● loading model` until Whisper is ready.
 
 ## First run
 
@@ -50,7 +50,6 @@ Extraction uses the system `tar` with bzip2 support, which is present on macOS,
 
 - Undo history records each preview rewrite; `Ctrl+Z` after a dictation steps back through them. The editor API offers no way to write without an undo entry.
 - English only.
-- A true sentence end followed by a pause longer than 2.5 s loses its full stop, because a mid-session commit drops Whisper's trailing period.
 - Brackets are stripped from transcripts, since Whisper emits them as sound captions. Dictating code with brackets is not supported.
 - The cursor is restored with simulated left-arrow presses, capped at 4,000 characters. Inserting near the start of a very long prompt can leave the cursor short of the dictation point.
 - Nested editors (dialogs) do not accept dictation, only normal typing.
@@ -61,7 +60,7 @@ Both are off unless the environment variable is set; both write only to `/tmp`.
 
 | Variable | File | Content |
 |---|---|---|
-| `PI_DICTATION_DEBUG=1` | `/tmp/pi-dictation.log` | Space events, phrase decodes, recognizer errors |
+| `PI_DICTATION_DEBUG=1` | `/tmp/pi-dictation.log` | Space events, phrase decodes, cancels, and session commits |
 | `PI_DICTATION_PROBE=1` | `/tmp/pi-dictation-probe.log` | Every terminal key sequence, for diagnosing key encoding. Dictation is disabled in this mode. |
 
 ## Uninstall

package/index.ts

@@ -7,6 +7,7 @@ import { Stt } from "./src/stt.ts";
 type Ui = {
 	notify: (message: string, level: "info" | "warning" | "error") => void;
 	setStatus: (key: string, text: string | undefined) => void;
+	theme: { fg: (color: "error", text: string) => string };
 	onTerminalInput: (handler: (data: string) => { consume?: boolean } | undefined) => () => void;
 };
 
@@ -18,15 +19,17 @@ export default function dictationExtension(pi: ExtensionAPI): void {
 
 	const getStt = (): Promise<Stt> => {
 		if (!sttPromise) {
-			sttPromise = Stt.create(undefined, (message) => ui?.setStatus("dictation", message)).then(
+			// Model progress has its own key: the listening indicator blinks on the
+			// dictation key and must not overwrite a first-run download.
+			sttPromise = Stt.create(undefined, (message) => ui?.setStatus("dictation-model", message)).then(
 				(stt) => {
-					ui?.setStatus("dictation", undefined);
+					ui?.setStatus("dictation-model", undefined);
 					return stt;
 				},
 				(error: unknown) => {
 					// Do not cache a failure: the next hold retries.
 					sttPromise = undefined;
-					ui?.setStatus("dictation", undefined);
+					ui?.setStatus("dictation-model", undefined);
 					throw error;
 				},
 			);
@@ -39,6 +42,10 @@ export default function dictationExtension(pi: ExtensionAPI): void {
 		getStt,
 		notify: (message, level) => ui?.notify(message, level),
 		status: (text) => ui?.setStatus("dictation", text),
+		indicator: (state, filled) => {
+			const circle = filled ? (ui?.theme.fg("error", "●") ?? "●") : "○";
+			return `${circle} ${state === "loading" ? "loading model" : "listening"}`;
+		},
 	});
 
 	pi.on("session_start", (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-push-to-talk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "Hold space to dictate into pi's prompt, transcribed locally with Whisper.",
   "keywords": [
@@ -14,6 +14,14 @@
   ],
   "license": "MIT",
   "author": "sqwxl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sqwxl/pi-push-to-talk.git"
+  },
+  "homepage": "https://github.com/sqwxl/pi-push-to-talk#readme",
+  "bugs": {
+    "url": "https://github.com/sqwxl/pi-push-to-talk/issues"
+  },
   "engines": {
     "node": ">=20"
   },

package/src/config.ts

@@ -33,8 +33,8 @@ export const MIN_PHRASE_RMS = 0.005;
 /** SPACE held this long starts dictating. */
 export const HOLD_MS = 350;
 
-/** A space this soon after typing stays a space (pi-voicekit's value). */
-export const TYPING_COOLDOWN_MS = 400;
+/** The listening indicator alternates filled and empty at this interval. */
+export const LISTENING_BLINK_MS = 600;
 
 export const MODEL_DIR = path.join(os.homedir(), ".pi", "models", "whisper-base");
 

package/src/editor.ts

@@ -14,8 +14,6 @@ const MAX_CURSOR_REWIND = 4000;
 export class DictationEditor extends CustomEditor {
 	/** Characters before the cursor that are not committed yet. */
 	private partialLength = 0;
-	/** Last buffer state written, so identical rewrites are skipped. */
-	private lastWrite = "";
 
 	override render(width: number): string[] {
 		const lines = super.render(width);
@@ -33,9 +31,12 @@ export class DictationEditor extends CustomEditor {
 
 	/** Replace the buffer, keep the cursor at `cursorOffset`, dim `partialLength` before it. */
 	writeAtCursor(text: string, cursorOffset: number, partialLength: number): void {
-		const state = `${cursorOffset}:${partialLength}:${text}`;
-		if (state === this.lastWrite) return;
-		this.lastWrite = state;
+		// Compare against the live editor, not a remembered state: the buffer can
+		// change outside this extension (submit, undo, history). A stale cache
+		// would skip an identical write and the transcript would never appear.
+		if (this.getText() === text && this.insertionOffset() === cursorOffset && this.partialLength === partialLength) {
+			return;
+		}
 
 		this.setText(text);
 		let rewind = Math.min(MAX_CURSOR_REWIND, Math.max(0, text.length - cursorOffset));

package/src/hold.ts

@@ -7,7 +7,7 @@
  * space the editor just typed is taken back and dictation starts.
  */
 import { isKeyRelease, isKeyRepeat, matchesKey } from "@earendil-works/pi-tui";
-import { HOLD_MS, TYPING_COOLDOWN_MS } from "./config.ts";
+import { HOLD_MS } from "./config.ts";
 import { trace } from "./debug.ts";
 import type { DictationEditor } from "./editor.ts";
 import { createRegion } from "./region.ts";
@@ -19,8 +19,10 @@ export type HoldDeps = {
 	getStt: () => Promise<Stt>;
 	notify: (message: string, level: "info" | "warning" | "error") => void;
 	status: (text: string | undefined) => void;
+	/** Indicator text for a blink phase, already coloured. */
+	indicator: (state: "loading" | "listening", filled: boolean) => string;
 	/** Test seam; production uses DictationSession. */
-	createSession?: (stt: Stt, ui: SessionUi) => DictationSession;
+	createSession?: (stt: Stt | Promise<Stt>, ui: SessionUi) => DictationSession;
 };
 
 /** A hold with no release event for this long is treated as stale. */
@@ -32,8 +34,10 @@ export class SpaceHold {
 	private holdTimer: ReturnType<typeof setTimeout> | undefined;
 	private holding = false;
 	private holdingSince = 0;
-	private lastTypingAt = 0;
 	private starting = false;
+	private beginQueued = false;
+	/** Bumped by each new press and by cancel; an older begin must not claim it. */
+	private holdId = 0;
 	/** Resolves when the previous session finished its final decode. */
 	private stopping: Promise<unknown> = Promise.resolve();
 
@@ -54,16 +58,15 @@ export class SpaceHold {
 		}
 
 		if (matchesKey(data, "space")) return this.handleSpace(isKeyRelease(data), isKeyRepeat(data));
-
-		if (!isKeyRelease(data) && !isKeyRepeat(data) && data.length === 1 && data.charCodeAt(0) >= 32) {
-			this.lastTypingAt = Date.now();
-		}
 		return false;
 	}
 
 	/** Abandon any open session without committing, e.g. when the prompt is submitted. */
 	cancel(): void {
+		trace("cancel");
 		this.holding = false;
+		this.holdId++;
+		this.beginQueued = false;
 		this.clearHoldTimer();
 		this.session?.cancel();
 		this.session = undefined;
@@ -82,6 +85,9 @@ export class SpaceHold {
 		if (released) {
 			this.holding = false;
 			this.clearHoldTimer();
+			// A session that failed by itself is already stopping; keep that
+			// shutdown visible to the next begin before the key is pressed again.
+			this.finish();
 			return false; // the space the editor typed stays
 		}
 
@@ -96,13 +102,14 @@ export class SpaceHold {
 		}
 
 		if (repeated) return false;
-		if (Date.now() - this.lastTypingAt < TYPING_COOLDOWN_MS) return false;
 
 		this.holding = true;
 		this.holdingSince = Date.now();
+		this.holdId++;
+		const id = this.holdId;
 		this.holdTimer = setTimeout(() => {
 			this.holdTimer = undefined;
-			void this.begin();
+			this.requestBegin(id);
 		}, HOLD_MS);
 		return false;
 	}
@@ -110,12 +117,27 @@ export class SpaceHold {
 	private finish(): void {
 		this.holding = false;
 		this.clearHoldTimer();
-		if (this.session) this.stopping = this.session.stop();
-		void this.stopping;
+		if (!this.session) return;
+		this.stopping = this.session.stop().catch((error: unknown) => {
+			this.deps.notify(`Dictation: ${String(error)}`, "error");
+		});
 	}
 
-	private async begin(): Promise<void> {
-		if (this.starting) return;
+	/** Start against the given press; queue it when an older begin is still unwinding. */
+	private requestBegin(id: number): void {
+		if (id !== this.holdId) return;
+		if (this.starting) {
+			this.beginQueued = true;
+			return;
+		}
+		void this.begin(id);
+	}
+
+	private async begin(id: number): Promise<void> {
+		if (this.starting) {
+			this.beginQueued = true;
+			return;
+		}
 		this.starting = true;
 		try {
 			const editor = this.deps.getEditor();
@@ -127,22 +149,21 @@ export class SpaceHold {
 			// A previous stop may still be decoding its tail; its write would land
 			// on top of the text this session is about to produce.
 			await this.stopping;
+			// A newer press now owns the buffer and will start its own session.
+			if (id !== this.holdId) return;
 
 			// Released before capture began: the tap must not vanish.
 			if (!this.holding) {
+				trace("begin: released while the previous stop finished, space restored");
 				editor.typeSpace();
 				return;
 			}
 
-			const stt = await this.deps.getStt();
-			if (!this.holding) {
-				editor.typeSpace();
-				return;
-			}
-
+			const stt = this.deps.getStt();
 			const ui: SessionUi = {
 				write: (text, cursorOffset, partialLength) => editor.writeAtCursor(text, cursorOffset, partialLength),
 				status: (text) => this.deps.status(text),
+				indicator: (state, filled) => this.deps.indicator(state, filled),
 				notify: (message, level) => this.deps.notify(message, level),
 			};
 			const create = this.deps.createSession ?? ((engine, sessionUi) => new DictationSession(engine, sessionUi));
@@ -150,6 +171,9 @@ export class SpaceHold {
 			this.session = session;
 			await session.start(createRegion(editor.getText(), editor.insertionOffset()));
 
+			// Cancelled while the device was opening: leave the buffer alone.
+			if (id !== this.holdId) return;
+
 			// Released while the capture device was opening: close it, and give the
 			// space back if nothing was transcribed.
 			if (!this.holding) {
@@ -162,6 +186,10 @@ export class SpaceHold {
 			if (!this.session?.isActive()) this.deps.getEditor()?.typeSpace();
 		} finally {
 			this.starting = false;
+			if (this.beginQueued) {
+				this.beginQueued = false;
+				if (this.holding && !this.session?.isActive()) this.requestBegin(this.holdId);
+			}
 		}
 	}
 

package/src/session.ts

@@ -5,7 +5,7 @@
  * is ever rewritten, so the rest of the buffer stays the user's.
  */
 import { openMicrophone, type Microphone } from "./capture.ts";
-import { MIN_PHRASE_MS, MIN_PHRASE_RMS, PARTIAL_INTERVAL_MS, msToSamples } from "./config.ts";
+import { LISTENING_BLINK_MS, MIN_PHRASE_MS, MIN_PHRASE_RMS, PARTIAL_INTERVAL_MS, msToSamples } from "./config.ts";
 import { trace } from "./debug.ts";
 import { commitPartial, joinText, regionCursorOffset, renderRegion, withPartial, type Region } from "./region.ts";
 import { Segmenter, rmsOf } from "./segmenter.ts";
@@ -16,31 +16,45 @@ export type SessionUi = {
 	/** Replace the editor text, place the cursor at `cursorOffset`, dim `partialLength` before it. */
 	write(text: string, cursorOffset: number, partialLength: number): void;
 	status(text: string | undefined): void;
+	/** Indicator text for a blink phase, already coloured. */
+	indicator(state: "loading" | "listening", filled: boolean): string;
 	notify(message: string, level: "info" | "warning" | "error"): void;
 };
 
 const MIN_PHRASE_SAMPLES = msToSamples(MIN_PHRASE_MS);
 
-/** Whisper ends a decode with a full stop; mid-session that is not the sentence end. */
-const TRAILING_PERIOD = /\.\s*$/;
-
 export class DictationSession {
-	private readonly stt: Stt;
+	private readonly stt: Promise<Stt>;
 	private readonly ui: SessionUi;
 	private readonly openMic: typeof openMicrophone;
 	private region: Region | undefined;
 	private mic: Microphone | undefined;
 	private segmenter = new Segmenter();
 	private timer: ReturnType<typeof setInterval> | undefined;
+	private listeningTimer: ReturnType<typeof setInterval> | undefined;
+	private listeningFilled = true;
+	/** The recognizer is still loading until this flips; the indicator says so. */
+	private modelReady = false;
 	private pending = 0;
+	private inFlight = new Set<Promise<void>>();
+	private stopPromise: Promise<boolean> | undefined;
 	private stopped = true;
 	/** Characters committed during this session, to tell a real result from silence. */
 	private committedChars = 0;
 
-	constructor(stt: Stt, ui: SessionUi, openMic: typeof openMicrophone = openMicrophone) {
-		this.stt = stt;
+	constructor(stt: Stt | Promise<Stt>, ui: SessionUi, openMic: typeof openMicrophone = openMicrophone) {
+		this.stt = Promise.resolve(stt);
 		this.ui = ui;
 		this.openMic = openMic;
+
+		void this.stt.then(
+			() => {
+				this.modelReady = true;
+				if (!this.stopped) this.writeListening();
+			},
+			// The first decode or stop reports a load failure; keep it handled.
+			() => {},
+		);
 	}
 
 	async start(region: Region): Promise<void> {
@@ -49,7 +63,7 @@ export class DictationSession {
 		this.region = region;
 		this.segmenter = new Segmenter();
 		this.committedChars = 0;
-		this.ui.status("MIC listening");
+		this.startListening();
 
 		try {
 			this.mic = await this.openMic(
@@ -58,7 +72,7 @@ export class DictationSession {
 			);
 		} catch (error) {
 			this.stopped = true;
-			this.ui.status(undefined);
+			this.stopListening();
 			this.ui.notify(`Dictation: microphone unavailable (${String(error)})`, "error");
 			return;
 		}
@@ -70,7 +84,7 @@ export class DictationSession {
 			return;
 		}
 
-		this.timer = setInterval(() => void this.preview(), PARTIAL_INTERVAL_MS);
+		this.timer = setInterval(() => this.track(this.preview()), PARTIAL_INTERVAL_MS);
 	}
 
 	isActive(): boolean {
@@ -78,7 +92,14 @@ export class DictationSession {
 	}
 
 	/** Decode what is still open, commit it, and close the session. Returns whether anything was transcribed. */
-	async stop(): Promise<boolean> {
+	stop(): Promise<boolean> {
+		// Callers can race (a failure and a release); they must share one shutdown
+		// so the final write cannot land in a newer session's buffer.
+		this.stopPromise ??= this.finish();
+		return this.stopPromise;
+	}
+
+	private async finish(): Promise<boolean> {
 		if (this.stopped) return false;
 		this.stopped = true;
 		this.clearTimer();
@@ -88,17 +109,28 @@ export class DictationSession {
 		const tail = this.segmenter.open();
 		this.segmenter.reset();
 		if (tail.length >= MIN_PHRASE_SAMPLES && rmsOf(tail) >= MIN_PHRASE_RMS) {
-			await this.decodePhrase(tail, true);
+			await this.decodePhrase(tail);
+		}
+
+		// A phrase that closed just before the release may still be decoding. Its
+		// samples left the segmenter, so dropping the result loses that speech.
+		while (this.inFlight.size > 0) {
+			await Promise.allSettled([...this.inFlight]);
 		}
 
-		// A preview of audio that was never committed must not stay in the buffer.
+		// If the tail was too short to decode, or its decode returned nothing, the
+		// preview is the only transcript of that audio. Commit it, do not wipe it.
 		if (this.region && this.region.partial.length > 0) {
-			this.region = { ...this.region, partial: "" };
-			this.write();
+			this.commitText(this.region.partial);
+			if (this.region.partial.length > 0) {
+				this.region = { ...this.region, partial: "" };
+				this.write();
+			}
 		}
 
 		const committed = this.committedChars > 0;
-		this.ui.status(undefined);
+		trace(`stop committed=${String(committed)} chars=${this.committedChars}`);
+		this.stopListening();
 		this.region = undefined;
 		return committed;
 	}
@@ -116,7 +148,7 @@ export class DictationSession {
 			const cleaned = joinText(this.region.before, this.region.after);
 			this.ui.write(cleaned, this.region.before.length, 0);
 		}
-		this.ui.status(undefined);
+		this.stopListening();
 		this.region = undefined;
 	}
 
@@ -125,18 +157,18 @@ export class DictationSession {
 		const closed = this.segmenter.add(samples);
 		if (!closed) return;
 		if (rmsOf(closed.samples) < MIN_PHRASE_RMS) return;
-		// A phrase closing while the session is open is not the end of the thought:
-		// its trailing full stop is Whisper's, not the speaker's.
-		void this.decodePhrase(closed.samples, false);
+		this.track(this.decodePhrase(closed.samples));
 	}
 
-	private async decodePhrase(samples: Float32Array, final: boolean): Promise<void> {
+	private async decodePhrase(samples: Float32Array): Promise<void> {
 		this.pending++;
 		try {
-			const raw = await this.stt.recognize(samples);
-			trace(`phrase ${samples.length} samples final=${String(final)} -> ${JSON.stringify(raw)}`);
-			const text = cleanTranscript(raw);
-			this.commitText(final ? text : text.replace(TRAILING_PERIOD, ""));
+			const stt = await this.stt;
+			const raw = await stt.recognize(samples);
+			trace(`phrase ${samples.length} samples -> ${JSON.stringify(raw)}`);
+			// Keep the model's punctuation: a pause usually is a real boundary, and
+			// removing a mark here also turned "..." into "..".
+			this.commitText(cleanTranscript(raw));
 		} catch (error) {
 			this.fail(error instanceof Error ? error : new Error(String(error)));
 		} finally {
@@ -152,7 +184,8 @@ export class DictationSession {
 
 		this.pending++;
 		try {
-			const text = cleanTranscript(await this.stt.recognize(open));
+			const stt = await this.stt;
+			const text = cleanTranscript(await stt.recognize(open));
 			if (this.stopped || !this.region) return;
 			this.region = withPartial(this.region, text);
 			this.write();
@@ -176,9 +209,45 @@ export class DictationSession {
 		this.ui.write(renderRegion(this.region), regionCursorOffset(this.region), this.region.partial.length);
 	}
 
+	/** Alternate a filled red circle with an empty one while the session is live. */
+	private startListening(): void {
+		this.stopListening();
+		this.listeningFilled = true;
+		this.writeListening();
+		this.listeningTimer = setInterval(() => {
+			this.listeningFilled = !this.listeningFilled;
+			this.writeListening();
+		}, LISTENING_BLINK_MS);
+	}
+
+	private writeListening(): void {
+		this.ui.status(this.ui.indicator(this.modelReady ? "listening" : "loading", this.listeningFilled));
+	}
+
+	private stopListening(): void {
+		if (this.listeningTimer) {
+			clearInterval(this.listeningTimer);
+			this.listeningTimer = undefined;
+		}
+		this.ui.status(undefined);
+	}
+
+	/** Keep the speech already captured; a failed stream must not eat the transcript. */
 	private fail(error: Error): void {
 		this.ui.notify(`Dictation: ${error.message}`, "error");
-		this.cancel();
+		void this.stop().catch((stopError: unknown) => {
+			trace(`stop after failure failed: ${String(stopError)}`);
+		});
+	}
+
+	/** Keep the decode visible to `stop` so it can wait for the commit. */
+	private track(work: Promise<void>): void {
+		const settled = work.then(
+			() => {},
+			() => {},
+		);
+		this.inFlight.add(settled);
+		void settled.finally(() => this.inFlight.delete(settled));
 	}
 
 	private clearTimer(): void {