Voice-to-text dictation app with local (Nvidia Parakeet/Whisper) and cloud models (BYOK). Privacy-first and available cross-platform.
JavaScript aianthropiccross-platformgeminigroqlinuxmacosnvidiaopen-sourceopenaiparakeetspeech-to-texttranscribewhisperwindows
const test = require("node:test");
const assert = require("node:assert/strict");
const React = require("react");
const { createRoot } = require("react-dom/client");
const {
createRendererServer,
installBrowserGlobals,
installHookDom,
} = require("../lib/rendererTestHarness");
const FAKE_AUDIO_MANAGER_SOURCE = `
export default class FakeAudioManager {
constructor() {
this.voiceAgentRequested = false;
this.translationRequested = false;
this.sttConfig = {};
globalThis.__forceStopAudioManager = this;
}
getState() {
return {};
}
setCallbacks(callbacks) {
this.callbacks = callbacks;
}
setVoiceAgentRequested() {}
setAssistantSelectionContext() {}
setTranslationRequested() {}
startRecording() {
globalThis.__forceStopStarts += 1;
return Promise.resolve(true);
}
complete(result) {
return this.callbacks.onTranscriptionComplete(result);
}
async safePaste(text, options) {
globalThis.__forceStopPastes.push({ text, options });
return globalThis.__forceStopPasteOutcome;
}
markCleanupNoticeShown(failure) {
globalThis.__forceStopShownNotices.push(failure);
}
saveTranscription() {
return Promise.resolve(true);
}
shouldUseStreaming() {
return false;
}
getRecordingAudioLevel() {
return 0;
}
isSttConfigStale() {
return false;
}
cleanup() {}
}
`;
const SETTINGS_STORE_SOURCE = `
export const getSettings = () => globalThis.__forceStopSettings;
`;
const POLICY_STORE_SOURCE = `
export const usePolicyStore = {
// An unknown status fails closed at the policy gate, which would make the
// second dictation bail before it reaches AudioManager at all.
getState: () => ({ status: "unmanaged" }),
subscribe: () => () => {},
};
`;
const LOGGER_SOURCE = `
const noop = () => {};
export default {
trace: noop, debug: noop, info: noop, warn: noop, error: noop, fatal: noop,
logReasoning: noop,
};
`;
const TRANSLATION_SOURCE = `
const translate = (key) => key;
export const useTranslation = () => ({ t: translate });
`;
const NOOP = () => {};
async function mountHarness(
t,
{
settings,
writeClipboard,
pasteOutcome = { pasted: true },
replaceOutcome = { success: true },
} = {}
) {
let root = null;
t.after(async () => {
if (root) await React.act(async () => root.unmount());
});
const clipboardWrites = [];
const replacements = [];
const lifecycle = [];
const toasts = [];
const dismissals = [];
let previewHides = 0;
let forceStopListener = null;
const noopDispose = () => () => {};
installBrowserGlobals(t, {
window: {
electronAPI: {
onToggleDictation: noopDispose,
onToggleVoiceAgent: noopDispose,
onToggleTranslation: noopDispose,
onStartDictation: noopDispose,
onPrepareDictation: noopDispose,
onCancelDictationPreparation: noopDispose,
onStopDictation: noopDispose,
onDictationForceStopped: (callback) => {
forceStopListener = callback;
return () => {};
},
dictationLifecycleStateChanged: (state) => lifecycle.push(state),
completeDictationPreview: NOOP,
hideDictationPreview: () => {
previewHides += 1;
},
setScreenContextEnabled: NOOP,
async writeClipboard(text) {
clipboardWrites.push(text);
return writeClipboard ? writeClipboard(text) : { success: true };
},
async replaceSelectedText(sessionId, text, options) {
replacements.push({ sessionId, text, options });
return replaceOutcome;
},
},
},
});
const container = installHookDom(t);
globalThis.__forceStopSettings = {
autoPasteEnabled: true,
keepTranscriptionInClipboard: false,
showTranscriptionPreview: false,
snippets: [],
useLocalWhisper: false,
pauseMediaOnDictation: false,
voiceAgentScreenContext: false,
...settings,
};
globalThis.__forceStopPastes = [];
globalThis.__forceStopPasteOutcome = pasteOutcome;
globalThis.__forceStopStarts = 0;
globalThis.__forceStopShownNotices = [];
const vite = await createRendererServer(t, {
cachePrefix: "openwhispr-audio-recording-force-stop-",
noExternal: ["react-i18next"],
mockModules: {
"/helpers/audioManager": FAKE_AUDIO_MANAGER_SOURCE,
"/stores/settingsStore": SETTINGS_STORE_SOURCE,
"/stores/policyStore": POLICY_STORE_SOURCE,
"/utils/logger": LOGGER_SOURCE,
"react-i18next": TRANSLATION_SOURCE,
},
});
const { useAudioRecording } = await vite.ssrLoadModule("/hooks/useAudioRecording.js");
const { useCleanupFailureStore } = await vite.ssrLoadModule("/stores/cleanupFailureStore.ts");
useCleanupFailureStore.setState({ pending: 0, lastFailure: null });
const api = {};
// Stable like the app's ToastProvider callback: a new identity per render
// would re-run the hook's mount effect on every state change.
const pushToast = (entry) => toasts.push(entry);
const dismissDictationError = () => dismissals.push(toasts.length);
function Harness() {
Object.assign(api, useAudioRecording(pushToast, { onDemoEvent: NOOP, dismissDictationError }));
return null;
}
root = createRoot(container);
await React.act(async () => {
root.render(React.createElement(Harness));
});
return {
api,
clipboardWrites,
lifecycle,
pastes: globalThis.__forceStopPastes,
replacements,
toasts,
dismissals,
previewHides: () => previewHides,
recordingStarts: () => globalThis.__forceStopStarts,
cleanupReports: () => useCleanupFailureStore.getState().pending,
shownNotices: () => globalThis.__forceStopShownNotices,
setRecording: async (isRecording) => {
await React.act(async () =>
globalThis.__forceStopAudioManager.callbacks.onStateChange({
isRecording,
isProcessing: false,
isStreaming: false,
})
);
},
forceStop: async (reason) => {
assert.ok(forceStopListener, "the hook must subscribe to dictation-force-stopped");
await React.act(async () => forceStopListener({ reason }));
},
startRecording: async () => {
await React.act(async () => api.startRecording());
},
// `detach` returns while the paste is still in flight, for tests that
// observe the hook mid-paste.
complete: async (result, { detach = false } = {}) => {
await React.act(async () => {
const completion = globalThis.__forceStopAudioManager.complete({
success: true,
text: "held too long",
rawText: "held too long",
clientTranscriptionId: "force-stop",
source: "openai",
...result,
});
if (!detach) await completion;
});
},
flush: async () => {
await React.act(async () => {
await new Promise((resolve) => setTimeout(resolve, 0));
});
},
};
}
const retryAction = (toast) => toast.actions.find((action) => action.label === "common.retry");
const errorToasts = (harness) =>
harness.toasts.filter((entry) => entry.presentation === "dictation-error");
// The whole point of the fix: the trigger keys are still down, so the paste
// shortcut must not be injected, and the transcript must stay recoverable.
for (const reason of ["timeout", "reset"]) {
test(`a push force-stopped by "${reason}" keeps the transcript instead of pasting it`, async (t) => {
const harness = await mountHarness(t);
await harness.forceStop(reason);
await harness.complete();
assert.deepEqual(harness.pastes, [], "nothing may be injected into held keys");
assert.deepEqual(harness.clipboardWrites, ["held too long"]);
const [toast] = errorToasts(harness);
assert.ok(toast, "the transcript is surfaced, not dropped");
assert.equal(toast.description, "hooks.audioRecording.pushForceStopped.description");
// A batch transcription has no streaming text, so the pill's transcript
// argument is the only thing that can produce this action — and it is the
// sole in-app recovery when the clipboard write is the part that failed.
assert.ok(
toast.actions.some(
(action) => action.label === "hooks.audioRecording.errorActions.viewTranscript"
),
"the pill must carry the transcript so it stays recoverable"
);
});
}
// Modifiers still down when the paste was due (#2113): the main process held the
// paste back, so the transcript must be surfaced exactly like a forced stop.
test("a paste held back for still-held modifiers keeps the transcript", async (t) => {
const harness = await mountHarness(t, {
pasteOutcome: { pasted: false, reason: "modifiers-held" },
});
await harness.complete();
assert.equal(harness.pastes.length, 1, "the paste was attempted, then held back");
assert.deepEqual(harness.clipboardWrites, ["held too long"]);
const [toast] = errorToasts(harness);
assert.ok(toast, "the transcript is surfaced, not dropped");
assert.equal(toast.title, "hooks.audioRecording.modifiersHeld.title");
assert.equal(toast.description, "hooks.audioRecording.modifiersHeld.description");
assert.ok(
toast.actions.some(
(action) => action.label === "hooks.audioRecording.errorActions.viewTranscript"
),
"the pill must carry the transcript so it stays recoverable"
);
});
// No Wayland clipboard written on wlroots, Hyprland or niri (#2621): Wayland apps
// can't read the clipboard copy either, so the pill says why and Retry pastes again.
for (const [reason, descriptionKey] of [
["wl-copy-missing", "wlCopyMissing"],
["wl-copy-failed", "wlCopyFailed"],
]) {
test(`a paste held back for ${reason} keeps the transcript and retries the paste`, async (t) => {
const harness = await mountHarness(t, { pasteOutcome: { pasted: false, reason } });
await harness.complete();
const [toast] = errorToasts(harness);
assert.ok(toast, "the transcript is surfaced, not dropped");
assert.equal(toast.title, "hooks.audioRecording.waylandClipboard.title");
assert.equal(toast.description, `hooks.audioRecording.waylandClipboard.${descriptionKey}`);
globalThis.__forceStopPasteOutcome = { pasted: true };
await React.act(async () => retryAction(toast).onClick());
assert.equal(harness.pastes.length, 2);
assert.equal(harness.recordingStarts(), 0);
});
}
// A macOS clipboard-only fallback (accessibility skipped) is also "not pasted",
// but it is expected and carries no reason, so it must stay silent.
test("a clipboard-only fallback without a reason raises no error", async (t) => {
const harness = await mountHarness(t, { pasteOutcome: { pasted: false } });
await harness.complete();
assert.deepEqual(harness.clipboardWrites, []);
assert.deepEqual(errorToasts(harness), []);
});
// A selection edit is blocked by held keys at two points (revalidation and
// the paste itself); both arrive as `modifiers_held`, which must not read as a
// permissions problem, and the edit must be kept like any held-back paste.
test("a selection edit held back for still-held modifiers keeps the edit and says why", async (t) => {
const harness = await mountHarness(t, {
replaceOutcome: { success: false, code: "modifiers_held" },
});
await harness.complete({ selectionEdit: { sessionId: "selection-1" } });
assert.equal(harness.replacements.length, 1);
assert.deepEqual(harness.pastes, [], "the edit is not pasted blindly");
assert.deepEqual(harness.clipboardWrites, ["held too long"]);
const [toast] = errorToasts(harness);
assert.equal(toast.title, "hooks.audioRecording.selectionEditing.notAppliedTitle");
assert.equal(toast.description, "hooks.audioRecording.selectionEditing.modifiersHeld");
});
test("a held-back selection edit whose clipboard write fails is not described as a success", async (t) => {
const harness = await mountHarness(t, {
writeClipboard: () => ({ success: false }),
replaceOutcome: { success: false, code: "modifiers_held" },
});
await harness.complete({ selectionEdit: { sessionId: "selection-1" } });
const [toast] = errorToasts(harness);
assert.equal(
toast.description,
"hooks.audioRecording.selectionEditing.modifiersHeldClipboardFailed"
);
});
// The transcript is already on the clipboard; what the user wants back is the
// paste, not another recording.
test("retrying a held-back paste pastes again instead of recording again", async (t) => {
const harness = await mountHarness(t, {
pasteOutcome: { pasted: false, reason: "modifiers-held" },
});
await harness.complete();
const [toast] = errorToasts(harness);
globalThis.__forceStopPasteOutcome = { pasted: true };
await React.act(async () => retryAction(toast).onClick());
assert.equal(harness.pastes.length, 2);
assert.deepEqual(harness.pastes[1].options, harness.pastes[0].options);
assert.equal(harness.recordingStarts(), 0);
assert.equal(errorToasts(harness).length, 1, "a paste that landed raises no new pill");
});
test("retrying a held-back paste while the keys are still held shows the pill again", async (t) => {
const harness = await mountHarness(t, {
pasteOutcome: { pasted: false, reason: "modifiers-held" },
});
await harness.complete();
const [toast] = errorToasts(harness);
await React.act(async () => retryAction(toast).onClick());
assert.equal(harness.pastes.length, 2);
assert.equal(harness.recordingStarts(), 0);
assert.equal(errorToasts(harness).length, 2);
});
// Force stops come only from macOS and Windows push-to-talk, which have no
// modifier wait: a pasting Retry clicked while the keys are still down would
// inject exactly the chord the pill exists to prevent. Retry records again.
test("retrying a force-stopped push records again instead of pasting", async (t) => {
const harness = await mountHarness(t);
await harness.forceStop("timeout");
await harness.complete();
const [toast] = errorToasts(harness);
await React.act(async () => retryAction(toast).onClick());
assert.deepEqual(harness.pastes, []);
assert.equal(harness.recordingStarts(), 1);
});
function deferredPaste() {
let settle;
const outcome = new Promise((resolve) => {
settle = resolve;
});
return { outcome, settle: (value) => React.act(async () => settle(value)) };
}
// The audio manager settles processing before the paste starts, so the pill
// would sit idle while the modifier wait runs (up to 1.5 s): the hook keeps the
// pill processing until the paste attempt settles. It must not report that to
// main, which drops dictation hotkeys while processing — the user could not
// start the next dictation during every paste.
test("the pill stays processing during a paste without holding back hotkeys", async (t) => {
const paste = deferredPaste();
const harness = await mountHarness(t, { pasteOutcome: paste.outcome });
await harness.complete(undefined, { detach: true });
assert.equal(harness.api.isProcessing, true);
assert.ok(!harness.lifecycle.includes("processing"), "main keeps accepting hotkeys");
await paste.settle({ pasted: true });
await harness.flush();
assert.equal(harness.api.isProcessing, false);
});
// Holding Ctrl and pressing the rest of the chord again starts the next
// dictation while the previous paste is still waiting on that Ctrl. The held-back
// transcript stays on the clipboard, but its pill must not land on top of the new
// recording (which dismisses it at once) or hide that recording's live preview.
test("a paste held back after the next recording started keeps the transcript quietly", async (t) => {
const paste = deferredPaste();
const harness = await mountHarness(t, { pasteOutcome: paste.outcome });
await harness.complete(undefined, { detach: true });
await harness.startRecording();
await harness.setRecording(true);
assert.equal(harness.recordingStarts(), 1);
assert.equal(harness.api.isProcessing, false, "the new recording owns the pill");
const hidesBefore = harness.previewHides();
await paste.settle({ pasted: false, reason: "modifiers-held" });
await harness.flush();
assert.deepEqual(harness.clipboardWrites, ["held too long"]);
assert.deepEqual(errorToasts(harness), []);
assert.equal(harness.previewHides(), hidesBefore, "the live preview is left alone");
assert.equal(harness.lifecycle.at(-1), "recording");
});
test("a paste held back behind the next recording reports no cleanup failure", async (t) => {
const paste = deferredPaste();
const harness = await mountHarness(t, { pasteOutcome: paste.outcome });
localStorage.setItem("onboardingCompleted", "true");
const cleanupFailure = {
message: "AI cleanup is on, but no cleanup model is set up.",
messageKey: "hooks.audioRecording.cleanupUnconfigured",
settingsTarget: "llms",
setupKey: "unconfigured",
};
await harness.complete({ cleanupFailure }, { detach: true });
await harness.startRecording();
await harness.setRecording(true);
await paste.settle({ pasted: false, reason: "modifiers-held" });
await harness.flush();
assert.equal(harness.cleanupReports(), 0, "the new recording owns the window");
assert.deepEqual(harness.shownNotices(), [], "the warning stays unspent");
});
// Retry shows no progress while the paste waits on held keys, so a second click
// is likely; it must not queue a second paste of the same text.
test("a double-clicked Retry pastes once", async (t) => {
const harness = await mountHarness(t, {
pasteOutcome: { pasted: false, reason: "modifiers-held" },
});
await harness.complete();
const [toast] = errorToasts(harness);
const paste = deferredPaste();
globalThis.__forceStopPasteOutcome = paste.outcome;
const retry = retryAction(toast);
const dismissalsBefore = harness.dismissals.length;
await React.act(async () => {
void retry.onClick();
void retry.onClick();
});
await paste.settle({ pasted: true });
await harness.flush();
assert.equal(harness.pastes.length, 2, "the first attempt plus one retry");
assert.equal(
harness.dismissals.length - dismissalsBefore,
1,
"the landed retry closes its pill once"
);
});
test("a Retry that lands after a newer pill leaves that pill alone", async (t) => {
const harness = await mountHarness(t, {
pasteOutcome: { pasted: false, reason: "modifiers-held" },
});
await harness.complete();
const [toast] = errorToasts(harness);
const paste = deferredPaste();
globalThis.__forceStopPasteOutcome = paste.outcome;
await React.act(async () => {
void retryAction(toast).onClick();
});
await harness.forceStop("timeout");
await harness.complete({ text: "newer", rawText: "newer" });
assert.equal(errorToasts(harness).length, 2, "a newer pill is showing");
const dismissalsBefore = harness.dismissals.length;
await paste.settle({ pasted: true });
await harness.flush();
assert.equal(
harness.dismissals.length,
dismissalsBefore,
"the stale Retry must not close the newer pill"
);
});
test("an ordinary dictation still pastes", async (t) => {
const harness = await mountHarness(t);
await harness.complete();
assert.equal(harness.pastes.length, 1);
assert.deepEqual(harness.clipboardWrites, []);
assert.deepEqual(errorToasts(harness), []);
});
// With auto-paste off nothing was going to be injected, so there is no loss to
// report — and overriding keepTranscriptionInClipboard would clobber a clipboard
// the user asked to leave alone.
test("a force stop is inert when auto-paste is disabled", async (t) => {
const harness = await mountHarness(t, { settings: { autoPasteEnabled: false } });
await harness.forceStop("timeout");
await harness.complete();
assert.deepEqual(harness.pastes, []);
assert.deepEqual(harness.clipboardWrites, [], "keepTranscriptionInClipboard is off");
assert.deepEqual(errorToasts(harness), [], "no paste was lost, so no error");
});
// The latch is per-recording. If it survived, every later dictation in the
// session would stop pasting and dump onto the clipboard instead.
test("the latch does not leak into the next dictation", async (t) => {
const harness = await mountHarness(t);
await harness.forceStop("timeout");
await harness.complete();
assert.deepEqual(harness.pastes, [], "the force-stopped one is held back");
await harness.startRecording();
await harness.complete();
assert.equal(harness.pastes.length, 1, "the next dictation pastes normally");
assert.equal(errorToasts(harness).length, 1, "no second error pill");
});
// Only reasons that leave the keys down may suppress a paste. A stop the
// renderer asked for itself must not be swept in.
test("a reason that is not a forced key-down stop does not latch", async (t) => {
const harness = await mountHarness(t);
await harness.forceStop("manual");
await harness.complete();
assert.equal(harness.pastes.length, 1, "a manual stop still pastes");
assert.deepEqual(harness.clipboardWrites, []);
assert.deepEqual(errorToasts(harness), []);
});
// The pill must not promise a clipboard that rejected the write — the transcript
// action on it is the recovery path either way.
for (const [label, writeClipboard] of [
["reports failure", async () => ({ success: false })],
[
"throws",
async () => {
throw new Error("clipboard unavailable");
},
],
]) {
test(`a clipboard write that ${label} is not described as a success`, async (t) => {
const harness = await mountHarness(t, { writeClipboard });
await harness.forceStop("timeout");
await harness.complete();
assert.deepEqual(harness.pastes, [], "still nothing injected into held keys");
const [toast] = errorToasts(harness);
assert.ok(toast, "the transcript is still surfaced");
assert.equal(
toast.description,
"hooks.audioRecording.pushForceStopped.descriptionClipboardFailed"
);
});
test(`a held-back paste whose clipboard write ${label} is not described as a success`, async (t) => {
const harness = await mountHarness(t, {
writeClipboard,
pasteOutcome: { pasted: false, reason: "modifiers-held" },
});
await harness.complete();
const [toast] = errorToasts(harness);
assert.ok(toast, "the transcript is still surfaced");
assert.equal(
toast.description,
"hooks.audioRecording.modifiersHeld.descriptionClipboardFailed"
);
});
}