dsh-live-voice 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-live-voice",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "type": "module",
   "scripts": {
     "typecheck": "tsc --noEmit",
@@ -13,17 +13,24 @@
     "setup:hooks": "git config core.hooksPath .githooks",
     "prepack": "npm run build"
   },
-  "description": "Local-first voice conversations for DSH, with local speech recognition and synthesis and optional external providers.",
+  "description": "Local-first hands-free AI voice assistant plugin for DeepSeek Harness (DSH), with speech-to-text, text-to-speech, voice commands, and local speech engines.",
   "keywords": [
     "dsh",
     "dsh-plugin",
     "deepseek-harness",
     "local-first",
     "local-voice",
+    "hands-free",
+    "hands-free-ai",
+    "hands-free-assistant",
+    "voice-control",
+    "voice-commands",
     "voice-assistant",
     "voice-conversation",
+    "conversational-ai",
     "continuous-conversation",
     "voice-dictation",
+    "spoken-prompts",
     "speech-to-text",
     "text-to-speech",
     "speech-recognition",
@@ -68,16 +75,16 @@
     "url": "git+https://github.com/victorwads/dsh-live-voice.git"
   },
   "devDependencies": {
-    "@types/node": "^26.5.1",
-    "@types/react": "^19.3.0",
-    "@types/react-dom": "^19.3.0",
-    "esbuild": "^0.28.2",
-    "jsdom": "^30.0.1",
-    "playwright-core": "^1.63.0",
-    "prettier": "3.9.6",
-    "react": "^19.3.0",
-    "react-dom": "^19.3.0",
-    "typescript": "^7.0.2"
+    "@types/node": "26.6.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "esbuild": "0.28.2",
+    "jsdom": "30.1.0",
+    "playwright-core": "1.63.0",
+    "prettier": "3.9.8",
+    "react": "19.3.0",
+    "react-dom": "19.3.0",
+    "typescript": "7.0.2"
   },
   "main": "./lib/server.js",
   "exports": {

package/src/client/components.ts

@@ -216,25 +216,26 @@ export function createComponents(React) {
     const remaining = state.autoSendAt
       ? Math.max(1, Math.ceil((state.autoSendAt - now) / 1000))
       : null;
-    const status = state.answeringQuestion && state.recognizing
-      ? 'Recognizing answer…'
-      : state.answeringQuestion && state.listening
-        ? 'Listening for your answer…'
-        : remaining
-          ? `Sending in ${remaining}…`
-          : state.starting
-        ? 'Starting microphone…'
-        : state.paused
-          ? 'Speech paused'
-          : state.speaking
-            ? 'Speaking'
-            : state.recognizing
-              ? 'Recognizing speech…'
-              : state.listening
-                ? 'Listening — waiting for speech'
-                : state.conversation
-                  ? 'Conversation idle'
-                  : 'Voice ready';
+    const status =
+      state.answeringQuestion && state.recognizing
+        ? 'Recognizing answer…'
+        : state.answeringQuestion && state.listening
+          ? 'Listening for your answer…'
+          : remaining
+            ? `Sending in ${remaining}…`
+            : state.starting
+              ? 'Starting microphone…'
+              : state.paused
+                ? 'Speech paused'
+                : state.speaking
+                  ? 'Speaking'
+                  : state.recognizing
+                    ? 'Recognizing speech…'
+                    : state.listening
+                      ? 'Listening — waiting for speech'
+                      : state.conversation
+                        ? 'Conversation idle'
+                        : 'Voice ready';
     return h(
       'div',
       {
@@ -884,6 +885,28 @@ export function createComponents(React) {
                     null,
                     'Controls how long a pause must last before captured speech is sent for recognition.',
                   ),
+                  h(
+                    'label',
+                    { className: 'dlv-setting-field' },
+                    'Maximum continuous speech (seconds)',
+                    h('input', {
+                      type: 'number',
+                      min: 10,
+                      max: 300,
+                      step: 1,
+                      value: settings.recognitionMaxUtteranceSeconds ?? 60,
+                      onChange: (event) => {
+                        const value = Number(event.target.value);
+                        if (Number.isInteger(value) && value >= 10 && value <= 300)
+                          invoke('updateSettings', { recognitionMaxUtteranceSeconds: value });
+                      },
+                    }),
+                    h(
+                      'small',
+                      null,
+                      'If speech never pauses, start a new transcription chunk after this duration. Default: 60 seconds.',
+                    ),
+                  ),
                   h(
                     'div',
                     {
@@ -959,6 +982,22 @@ export function createComponents(React) {
             ? 'Sending or steering a new user message stops current or paused assistant speech.'
             : 'Sending another message does not stop the assistant audio you are already hearing.',
         ),
+        h(
+          'label',
+          { key: 'hold-to-talk', className: 'dlv-check' },
+          h('input', {
+            type: 'checkbox',
+            checked: settings.holdToTalkEnabled !== false,
+            onChange: (event) =>
+              invoke('updateSettings', { holdToTalkEnabled: event.target.checked }),
+          }),
+          ' Hold Control to talk',
+        ),
+        h(
+          'p',
+          { key: 'hold-to-talk-description', className: 'dlv-setting-description' },
+          'While a composer is open, hold Control anywhere on the page to capture speech. Release it to flush queued transcription, wait the configured send delay, queue the message, and close voice capture. Press Escape while holding to cancel.',
+        ),
         field('Listening mode', 'mode', [
           { value: 'speaker', label: 'Speakers — gated listening' },
           { value: 'headphones', label: 'Headphones — open microphone' },

package/src/client/index.ts

@@ -13,7 +13,12 @@ import { QwenHttpRecognitionEngine } from '../engines/recognition/qwen-http.ts';
 import { QwenHttpSpeakingEngine } from '../engines/speaking/qwen-http.ts';
 import { createComponents } from './components.ts';
 import { styles } from './styles.ts';
-import { assistantMessages, addressedTurn, latestUserSequence, pendingQuestionSpeech } from './chat.ts';
+import {
+  assistantMessages,
+  addressedTurn,
+  latestUserSequence,
+  pendingQuestionSpeech,
+} from './chat.ts';
 
 export const inject = ['slots', 'connection', 'uiConversation', 'uiSession'];
 export function apply(ctx) {
@@ -27,16 +32,27 @@ export function apply(ctx) {
   // composer should inherit the user's explicit choice to remain in voice mode.
   let voiceModeActive = false;
   const ownership = new VoiceOwnership();
+  const recognitionSettingKeys = new Set([
+    'recognitionEngine',
+    'recognitionProcessLocally',
+    'recognitionAutoInstall',
+    'voiceDetectionPreset',
+    'recognitionMaxUtteranceSeconds',
+  ]);
+  const changesRecognition = (next) =>
+    Object.keys(next).some((key) => recognitionSettingKeys.has(key));
   const recognitionFor = (settings, meter) =>
     settings.recognitionEngine === 'qwen-http'
       ? new QwenHttpRecognitionEngine({
           meter,
           voiceDetectionPreset: settings.voiceDetectionPreset,
+          maxUtteranceSeconds: settings.recognitionMaxUtteranceSeconds,
         })
       : settings.recognitionEngine === 'whisper-http'
         ? new WhisperHttpRecognitionEngine({
             meter,
             voiceDetectionPreset: settings.voiceDetectionPreset,
+            maxUtteranceSeconds: settings.recognitionMaxUtteranceSeconds,
           })
         : new BrowserRecognitionEngine({
             processLocally: settings.recognitionProcessLocally,
@@ -116,7 +132,8 @@ export function apply(ctx) {
             if (capture.index < capture.interaction.questions.length) {
               capture.answering = false;
               const text = pendingQuestionSpeech(capture.interaction, capture.index);
-              if (text) run(entry.controller, entry.controller.speak(text, capture.interaction.key));
+              if (text)
+                run(entry.controller, entry.controller.speak(text, capture.interaction.key));
             } else {
               entry.questionCapture = null;
               entry.controller.patch({ answeringQuestion: false });
@@ -172,9 +189,11 @@ export function apply(ctx) {
       refresh();
       for (const listener of entry.chatListeners) listener();
     });
+    // DSH 0.1.6 may omit this legacy store. Keep the remaining voice controls
+    // available while structured-question integration is unavailable.
     const pendingInteractions = ctx.uiSession.pendingInteractions;
     const refreshPendingQuestion = (baseline = false) => {
-      if (disposed || entry.closed) return;
+      if (disposed || entry.closed || !pendingInteractions) return;
       const interaction = pendingInteractions.getSnapshot().get(sessionId);
       const key = interaction?.kind === 'question' ? interaction.key : null;
       if (!key || (entry.questionCapture && entry.questionCapture.interaction.key !== key)) {
@@ -194,21 +213,27 @@ export function apply(ctx) {
         run(controller, controller.speak(text, key));
       }
     };
-    refreshPendingQuestion(true);
-    entry.unsubscribePendingQuestion = pendingInteractions.subscribe(refreshPendingQuestion);
+    if (pendingInteractions) {
+      refreshPendingQuestion(true);
+      entry.unsubscribePendingQuestion = pendingInteractions.subscribe(refreshPendingQuestion);
+    }
     const update = controller.updateSettings.bind(controller);
-    controller.updateSettings = (next) => {
-      if (disposed || entry.closed) return;
+    entry.applySettings = (next) => {
       update(next);
       engineBrowser.lang = controller.getSnapshot().settings.lang;
       engineQwen.lang = controller.getSnapshot().settings.lang;
+      run(controller, controller.refreshCapabilities());
+    };
+    controller.updateSettings = (next) => {
+      if (disposed || entry.closed) return;
+      entry.applySettings(next);
+      const settings = controller.getSnapshot().settings;
       try {
-        localStorage.setItem(
-          'dsh-live-voice.settings',
-          JSON.stringify(controller.getSnapshot().settings),
-        );
+        localStorage.setItem('dsh-live-voice.settings', JSON.stringify(settings));
       } catch {}
-      run(controller, controller.refreshCapabilities());
+      for (const other of controllers.values()) {
+        if (other !== entry && !other.closed) other.applySettings(settings);
+      }
     };
     // Cancel only this entry's queued acquisition. Global cancellation here would
     // invalidate a newer session while its predecessor is being unmounted.
@@ -220,7 +245,7 @@ export function apply(ctx) {
         return original(...args);
       };
     }
-    for (const method of ['startDictation', 'startConversation', 'speak']) {
+    for (const method of ['startDictation', 'startHoldToTalk', 'startConversation', 'speak']) {
       const original = controller[method].bind(controller);
       controller[method] = (...args) => {
         if (disposed || entry.closed || !entry.refs) return Promise.resolve();
@@ -343,13 +368,11 @@ export function apply(ctx) {
       let settingsRevision = 0;
       c.updateSettings = async (next) => {
         const revision = ++settingsRevision;
-        const previousEngine = c.getSnapshot().settings.recognitionEngine;
         update(next);
         browser.lang = c.getSnapshot().settings.lang;
         qwen.lang = c.getSnapshot().settings.lang;
         const settings = c.getSnapshot().settings;
-        if (previousEngine !== settings.recognitionEngine)
-          c.replaceRecognition(recognitionFor(settings, c.meter));
+        if (changesRecognition(next)) c.replaceRecognition(recognitionFor(settings, c.meter));
         localStorage.setItem('dsh-live-voice.settings', JSON.stringify(settings));
         run(c, c.refreshCapabilities());
         const active = [...controllers.values()];
@@ -360,11 +383,9 @@ export function apply(ctx) {
         if (revision !== settingsRevision || disposed || c.disposed) return;
         for (const entry of controllers.values()) {
           if (entry.closed) continue;
-          if (
-            entry.controller.getSnapshot().settings.recognitionEngine !== settings.recognitionEngine
-          )
+          if (changesRecognition(next))
             entry.controller.replaceRecognition(recognitionFor(settings, entry.controller.meter));
-          entry.controller.updateSettings(settings);
+          entry.applySettings(settings);
           run(entry.controller, entry.controller.refreshCapabilities());
         }
       };
@@ -480,28 +501,49 @@ export function apply(ctx) {
       for (const entry of controllers.values())
         run(entry.controller, entry.controller.endConversation());
     };
-    const onKey = (event) => {
-      if (
-        disposed ||
-        event.defaultPrevented ||
-        !event.ctrlKey ||
-        !event.shiftKey ||
-        event.code !== 'Space' ||
-        event.repeat
-      )
-        return;
+    let holdToTalk = null;
+    const candidate = () => {
       const candidates = [...controllers.values()].filter(
         (entry) => entry.buttons > 0 && entry.composers.size > 0,
       );
-      if (candidates.length !== 1) return;
-      event.preventDefault();
-      const c = candidates[0].controller;
-      run(
-        c,
-        c.getSnapshot().listening || c.getSnapshot().starting
-          ? c.stopListening()
-          : c.startDictation(),
-      );
+      return candidates.length === 1 ? candidates[0] : null;
+    };
+    const releaseHoldToTalk = () => {
+      const entry = holdToTalk;
+      holdToTalk = null;
+      if (!entry || entry.closed) return;
+      run(entry.controller, entry.controller.releaseHoldToTalk());
+    };
+    const onKeyDown = (event) => {
+      if (disposed || event.defaultPrevented || event.repeat) return;
+      if (event.key === 'Escape' && holdToTalk) {
+        const entry = holdToTalk;
+        holdToTalk = null;
+        event.preventDefault();
+        run(entry.controller, entry.controller.cancelDictation());
+        return;
+      }
+      if (event.ctrlKey && event.shiftKey && event.code === 'Space') {
+        const entry = candidate();
+        if (!entry) return;
+        event.preventDefault();
+        const c = entry.controller;
+        run(
+          c,
+          c.getSnapshot().listening || c.getSnapshot().starting
+            ? c.stopListening()
+            : c.startDictation(),
+        );
+        return;
+      }
+      if (event.key !== 'Control' || event.altKey || event.metaKey || event.shiftKey) return;
+      const entry = candidate();
+      if (!entry || !entry.controller.getSnapshot().settings.holdToTalkEnabled) return;
+      holdToTalk = entry;
+      run(entry.controller, entry.controller.startHoldToTalk());
+    };
+    const onKeyUp = (event) => {
+      if (event.key === 'Control') releaseHoldToTalk();
     };
     const refreshCapabilities = () => {
       for (const entry of controllers.values())
@@ -514,7 +556,9 @@ export function apply(ctx) {
     window.speechSynthesis?.addEventListener?.('voiceschanged', refreshCapabilities);
     navigator.mediaDevices?.addEventListener?.('devicechange', refreshCapabilities);
     document.addEventListener('visibilitychange', visibilityChanged);
-    document.addEventListener('keydown', onKey);
+    document.addEventListener('keydown', onKeyDown);
+    document.addEventListener('keyup', onKeyUp);
+    window.addEventListener('blur', releaseHoldToTalk);
     window.addEventListener('pagehide', stop);
     return () => {
       disposed = true;
@@ -522,7 +566,9 @@ export function apply(ctx) {
       window.speechSynthesis?.removeEventListener?.('voiceschanged', refreshCapabilities);
       navigator.mediaDevices?.removeEventListener?.('devicechange', refreshCapabilities);
       document.removeEventListener('visibilitychange', visibilityChanged);
-      document.removeEventListener('keydown', onKey);
+      document.removeEventListener('keydown', onKeyDown);
+      document.removeEventListener('keyup', onKeyUp);
+      window.removeEventListener('blur', releaseHoldToTalk);
       window.removeEventListener('pagehide', stop);
       for (const entry of controllers.values()) retire(entry);
     };

package/src/core/coordinator.ts

@@ -46,7 +46,8 @@ export class VoiceCoordinator {
       conversation: false,
       listening: false,
       recognizing: false,
-      muted: false,
+      pendingTranscriptions: 0,
+      muted: normalizeSettings(settings).microphoneEnabled === false,
       speaking: false,
       paused: false,
       starting: false,
@@ -60,6 +61,7 @@ export class VoiceCoordinator {
     };
     this.autoSendTimer = null;
     this.autoSendDraft = null;
+    this.holdToTalkRelease = false;
     this.interruptionTimer = null;
     this.interruptionTranscriptConfirmed = false;
     this.interruptionPausedSpeech = false;
@@ -116,7 +118,12 @@ export class VoiceCoordinator {
       autoInstallLocalPack: settings.recognitionAutoInstall,
       voiceDetectionPreset: settings.voiceDetectionPreset,
     });
-    this.patch({ settings, error: null });
+    this.patch({
+      settings,
+      muted: settings.microphoneEnabled === false,
+      recognizing: settings.microphoneEnabled === false ? false : this.snapshot.recognizing,
+      error: null,
+    });
     if (settings.sendingMode === 'manual') this.cancelAutoSend();
     if (Object.hasOwn(next, 'announceAssistantMessages') && !settings.announceAssistantMessages) {
       this.queue = [];
@@ -181,20 +188,42 @@ export class VoiceCoordinator {
   startDictation() {
     return this.startListening(false);
   }
+  startHoldToTalk() {
+    this.holdToTalkRelease = false;
+    return this.startListening(false);
+  }
+  async releaseHoldToTalk() {
+    if (this.disposed || (!this.snapshot.listening && !this.snapshot.starting)) return;
+    this.holdToTalkRelease = true;
+    if (this.snapshot.starting) return;
+    await this.recognition.finish?.();
+    if (this.snapshot.pendingTranscriptions === 0) this._finishHoldToTalk();
+  }
+  _finishHoldToTalk() {
+    if (!this.holdToTalkRelease) return;
+    this.holdToTalkRelease = false;
+    const draft = this.composer.getDraft();
+    if (!draft.trim()) {
+      void this.stopListening();
+      return;
+    }
+    this.scheduleAutoSend(draft, { force: true, stopAfter: true });
+  }
   startConversation() {
     return this.startListening(true);
   }
   muteListening() {
-    if (!this.snapshot.settings.voiceCommandsEnabled) return this.stopListening();
     this.cancelAutoSend();
     this.composer.setDraft(this.transcript.update(this.composer.getDraft(), '', true));
     this.transcript.reset();
-    this.patch({ muted: true, recognizing: false });
+    this.updateSettings({ microphoneEnabled: false });
+    if (!this.snapshot.settings.voiceCommandsEnabled) return this.stopListening();
   }
   resumeListeningInput() {
+    this.transcript.reset();
+    this.updateSettings({ microphoneEnabled: true });
     if (this.snapshot.listening || this.snapshot.starting) {
-      this.transcript.reset();
-      this.patch({ muted: false, recognizing: false });
+      this.patch({ recognizing: false });
       return;
     }
     return this.startListening(this.snapshot.conversation);
@@ -263,6 +292,14 @@ export class VoiceCoordinator {
           onResult: (result) => {
             if (valid()) this.onResult(result);
           },
+          onProcessingChange: ({ pending = 0 } = {}) => {
+            if (!valid()) return;
+            const count = Number.isSafeInteger(pending) && pending >= 0 ? pending : 0;
+            this.patch({ pendingTranscriptions: count });
+            if (count > 0) this.cancelAutoSend();
+            else if (this.holdToTalkRelease) this._finishHoldToTalk();
+            else this.maybeScheduleAutoSend();
+          },
           onActivity: (active) => {
             if (!valid()) return;
             if (active) {
@@ -288,6 +325,7 @@ export class VoiceCoordinator {
           return;
         }
         this.patch({ listening: true, starting: false });
+        if (this.holdToTalkRelease) void this.releaseHoldToTalk();
         this._drain();
       } catch (error) {
         try {
@@ -372,8 +410,10 @@ export class VoiceCoordinator {
     }
     // Pending structured questions own recognition while waiting for a hands-free
     // answer. Keep their interim and final text out of the normal chat composer.
-    if (typeof this.composer.handleQuestionResult === 'function' &&
-        this.composer.handleQuestionResult({ final, interim })) {
+    if (
+      typeof this.composer.handleQuestionResult === 'function' &&
+      this.composer.handleQuestionResult({ final, interim })
+    ) {
       this.cancelAutoSend();
       this.transcript.reset();
       this.patch({ recognizing: !!interim });
@@ -435,7 +475,7 @@ export class VoiceCoordinator {
       }
       const next = this.transcript.update(this.composer.getDraft(), final, true);
       this.composer.setDraft(next);
-      if (this.snapshot.settings.sendingMode !== 'manual') this.scheduleAutoSend(next);
+      this.maybeScheduleAutoSend(next);
     }
     if (interim) {
       this.cancelAutoSend();
@@ -447,7 +487,16 @@ export class VoiceCoordinator {
     this.patch({ recognizing: !!interim });
     this._drain();
   }
-  scheduleAutoSend(draft) {
+  maybeScheduleAutoSend(draft = this.composer.getDraft()) {
+    if (
+      this.snapshot.settings.sendingMode === 'manual' ||
+      this.snapshot.recognizing ||
+      this.snapshot.pendingTranscriptions > 0
+    )
+      return;
+    this.scheduleAutoSend(draft);
+  }
+  scheduleAutoSend(draft, { force = false, stopAfter = false } = {}) {
     this.cancelAutoSend();
     if (!draft.trim() || typeof this.composer.submit !== 'function') return;
     const delay = this.snapshot.settings.autoSendDelaySeconds * 1000;
@@ -460,16 +509,19 @@ export class VoiceCoordinator {
       this.patch({ autoSendAt: null });
       if (
         !this.disposed &&
-        this.snapshot.settings.sendingMode !== 'manual' &&
+        (force || this.snapshot.settings.sendingMode !== 'manual') &&
         expected === this.composer.getDraft()
       ) {
         try {
-          this.composer.submit(this.snapshot.settings.sendingMode === 'steer' ? 'steer' : 'queue');
+          this.composer.submit(
+            this.snapshot.settings.sendingMode === 'steer' && !force ? 'steer' : 'queue',
+          );
           // Web Speech keeps a cumulative native result list for the lifetime of
           // one recognition instance. Start a fresh instance at the turn boundary
           // so the sent utterance cannot prefix the next one.
           this.transcript.reset();
           this.recognition.reset?.();
+          if (stopAfter) void this.stopListening();
         } catch (error) {
           this.patch({ error: message(error) });
         }
@@ -486,10 +538,11 @@ export class VoiceCoordinator {
     if (this.autoSendDraft !== null && draft !== this.autoSendDraft) this.cancelAutoSend();
   }
   stopListening() {
+    this.holdToTalkRelease = false;
     this.cancelAutoSend();
     ++this.epoch;
     this.inputController?.abort();
-    this.patch({ listening: false, recognizing: false, starting: false });
+    this.patch({ listening: false, recognizing: false, pendingTranscriptions: 0, starting: false });
     return this._input(async () => {
       try {
         await this._releaseInput();

package/src/core/settings.ts

@@ -36,6 +36,9 @@ export const defaultSettings = Object.freeze({
   recognitionProcessLocally: true,
   recognitionAutoInstall: true,
   voiceDetectionPreset: 'natural',
+  recognitionMaxUtteranceSeconds: 60,
+  microphoneEnabled: true,
+  holdToTalkEnabled: true,
   announceAssistantMessages: true,
   interruptSpeechOnUserMessage: false,
   sendingMode: 'manual',
@@ -93,6 +96,20 @@ export function normalizeSettings(value) {
     voiceDetectionPreset: Object.hasOwn(voiceDetectionPresets, source.voiceDetectionPreset)
       ? source.voiceDetectionPreset
       : defaultSettings.voiceDetectionPreset,
+    recognitionMaxUtteranceSeconds:
+      Number.isInteger(source.recognitionMaxUtteranceSeconds) &&
+      source.recognitionMaxUtteranceSeconds >= 10 &&
+      source.recognitionMaxUtteranceSeconds <= 300
+        ? source.recognitionMaxUtteranceSeconds
+        : defaultSettings.recognitionMaxUtteranceSeconds,
+    microphoneEnabled:
+      typeof source.microphoneEnabled === 'boolean'
+        ? source.microphoneEnabled
+        : defaultSettings.microphoneEnabled,
+    holdToTalkEnabled:
+      typeof source.holdToTalkEnabled === 'boolean'
+        ? source.holdToTalkEnabled
+        : defaultSettings.holdToTalkEnabled,
     announceAssistantMessages:
       typeof source.announceAssistantMessages === 'boolean'
         ? source.announceAssistantMessages

package/src/engines/recognition/browser.ts

@@ -141,6 +141,9 @@ export class BrowserRecognitionEngine {
       timer: null,
       recognition: null,
       speaking: false,
+      finishing: false,
+      finishPromise: null,
+      resolveFinish: null,
     };
     this.session = session;
     const cancelled = new Promise((resolve, reject) => {
@@ -244,6 +247,12 @@ export class BrowserRecognitionEngine {
       session.recognition = null;
       this._activity(session, false);
       if (this.session !== session) return;
+      if (session.finishing) {
+        this.session = null;
+        session.signal?.removeEventListener('abort', session.cancel);
+        session.resolveFinish?.();
+        return;
+      }
       if (session.restarts >= this.maxRestarts) {
         this._fail(
           session,
@@ -273,6 +282,34 @@ export class BrowserRecognitionEngine {
     recognition.start();
   }
 
+  finish() {
+    const session = this.session;
+    if (!session) return Promise.resolve();
+    if (session.finishPromise) return session.finishPromise;
+    session.finishing = true;
+    session.finishPromise = new Promise((resolve) => {
+      session.resolveFinish = resolve;
+    });
+    if (session.timer !== null) {
+      (this.globals.clearTimeout ?? globalThis.clearTimeout)(session.timer);
+      session.timer = null;
+      this.session = null;
+      session.resolveFinish();
+      return session.finishPromise;
+    }
+    try {
+      session.recognition?.stop();
+      if (!session.recognition) {
+        this.session = null;
+        session.resolveFinish();
+      }
+    } catch {
+      this.session = null;
+      session.resolveFinish();
+    }
+    return session.finishPromise;
+  }
+
   reset() {
     const session = this.session;
     const recognition = session?.recognition;
@@ -310,5 +347,6 @@ export class BrowserRecognitionEngine {
       /* Browser already ended capture. */
     }
     this._activity(session, false);
+    session.resolveFinish?.();
   }
 }