Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.
TypeScript cross-platformelectronffmpegopen-sourceproduct-demorustscreen-capturescreen-recorderscreen-recordingscreen-studioscreencastspeech-to-texttypescriptvideo-editingvideo-editorwaylandwgpuwhisper
fix(stt): key unreadable media on an extraction marker, not on wording
Etienne Lescota1a2a760d78e
diff --git a/electron/stt/extractAudio.test.ts b/electron/stt/extractAudio.test.tsindex 24e9694c8..5ed99608c 100644--- a/electron/stt/extractAudio.test.ts+++ b/electron/stt/extractAudio.test.ts@@ -8,10 +8,11 @@ const resolveFfmpegMock = vi.fn<() => string | null>();vi.mock("node:child_process", () => ({ spawn: (...args: unknown[]) => spawnMock(...args) }));vi.mock("../media/audioPeaks", () => ({ resolveFfmpeg: () => resolveFfmpegMock() }));-const { extractMono16kPcm, FfmpegUnavailableError, NoAudioTrackError } = await import(- "./extractAudio"+const { extractMono16kPcm, FfmpegUnavailableError, MediaUnreadableError, NoAudioTrackError } =+ await import("./extractAudio");+const { STT_MEDIA_UNREADABLE, STT_NATIVE_EXTRACTION_UNAVAILABLE } = await import(+ "./transcriptionContract");-const { STT_NATIVE_EXTRACTION_UNAVAILABLE } = await import("./transcriptionContract");/** A stand-in for the ffmpeg child: two pipes and a close event, nothing more. */function fakeChild() {@@ -95,6 +96,35 @@ describe("extractMono16kPcm", () => {await expect(promise).rejects.toBeInstanceOf(NoAudioTrackError);});+ // Issue #968: the renderer explains these as "check folder access" and retries+ // them, so both must carry the marker, which is all that survives the IPC.+ it("reports a read the OS refused as unreadable media, not as no audio", async () => {+ const child = fakeChild();+ spawnMock.mockReturnValue(child);+ const promise = extractMono16kPcm("/Users/me/Downloads/a.mp4");+ child.stderr.end("/Users/me/Downloads/a.mp4: Operation not permitted");+ child.stdout.end();+ child.emit("close", 1);++ await expect(promise).rejects.toBeInstanceOf(MediaUnreadableError);+ await expect(promise).rejects.toThrow(STT_MEDIA_UNREADABLE);+ });++ it("reports an ffmpeg that hangs opening the file as unreadable media", async () => {+ vi.useFakeTimers();+ try {+ const child = fakeChild();+ spawnMock.mockReturnValue(child);+ const promise = extractMono16kPcm("/Users/me/Downloads/a.mp4");+ const settled = expect(promise).rejects.toThrow(STT_MEDIA_UNREADABLE);+ await vi.advanceTimersByTimeAsync(60_000);+ await settled;+ expect(child.kill).toHaveBeenCalled();+ } finally {+ vi.useRealTimers();+ }+ });+it("keeps the samples when ffmpeg exits non-zero AFTER writing audio", async () => {// A truncated file still yields usable audio; throwing it away would lose a// transcript over a trailing byte.diff --git a/electron/stt/extractAudio.ts b/electron/stt/extractAudio.tsindex 08168d21e..bf86f4cb6 100644--- a/electron/stt/extractAudio.ts+++ b/electron/stt/extractAudio.ts@@ -21,7 +21,7 @@import { spawn } from "node:child_process";import { resolveFfmpeg } from "../media/audioPeaks";-import { STT_NATIVE_EXTRACTION_UNAVAILABLE } from "./transcriptionContract";+import { STT_MEDIA_UNREADABLE, STT_NATIVE_EXTRACTION_UNAVAILABLE } from "./transcriptionContract";/** What whisper.cpp wants, and what `decodePeaks` already asks ffmpeg for. */const SAMPLE_RATE = 16_000;@@ -50,6 +50,22 @@ export class NoAudioTrackError extends Error {}}+/**+ * The media file could not be read at all: the OS refused it, or ffmpeg hung+ * opening it. Unlike `NoAudioTrackError` this is NOT permanent: it clears once+ * the user grants access, so it carries `STT_MEDIA_UNREADABLE` for the renderer+ * to explain rather than remember.+ */+export class MediaUnreadableError extends Error {+ constructor(filePath: string, detail: string) {+ super(`${STT_MEDIA_UNREADABLE}: cannot read ${filePath}: ${detail}`);+ this.name = "MediaUnreadableError";+ }+}++/** What ffmpeg's stderr says when the OS refused to open the input. */+const ACCESS_DENIED = /operation not permitted|permission denied/i;+/*** Decode `filePath` to mono 16 kHz float samples.*@@ -106,7 +122,9 @@ export async function extractMono16kPcm(const timer = setTimeout(() => {child.kill("SIGKILL");finish(() =>- reject(new Error(`ffmpeg timed out after ${EXTRACT_TIMEOUT_MS}ms on ${filePath}`)),+ reject(+ new MediaUnreadableError(filePath, `ffmpeg timed out after ${EXTRACT_TIMEOUT_MS}ms`),+ ),);}, EXTRACT_TIMEOUT_MS);@@ -137,7 +155,13 @@ export async function extractMono16kPcm(// caller treats both the same way — this asset will not transcribe — so they// share an error type; `stderr` carries which it was.if (code !== 0 && total === 0) {- finish(() => reject(new NoAudioTrackError(filePath, stderr.trim())));+ // Except a read the OS refused: that also exits non-zero with nothing+ // decoded, but remembering it as "no audio" would never retry the file+ // once access is granted.+ const error = ACCESS_DENIED.test(stderr)+ ? new MediaUnreadableError(filePath, stderr.trim())+ : new NoAudioTrackError(filePath, stderr.trim());+ finish(() => reject(error));return;}const out = new Float32Array(total);diff --git a/electron/stt/transcriptionContract.ts b/electron/stt/transcriptionContract.tsindex 5433698ac..4a2563a78 100644--- a/electron/stt/transcriptionContract.ts+++ b/electron/stt/transcriptionContract.ts@@ -142,6 +142,17 @@ export interface SttTranscribeRequest {*/export const STT_NATIVE_EXTRACTION_UNAVAILABLE = "stt:native-extraction-unavailable";+/**+ * Marker carried in the error message when audio extraction could not read the+ * `sourcePath` itself: the OS refused the read, or ffmpeg hung opening the file+ * (macOS holds the read behind a pending folder-access prompt, issue #968).+ *+ * Only `extractAudio.ts` sets it, so the renderer can tell "this file's folder is+ * not readable" from an engine failure that happens to mention a permission (model+ * loading, the whisper helper). Same IPC reason as above for being a string.+ */+export const STT_MEDIA_UNREADABLE = "stt:media-unreadable";+/** IPC response: main → renderer. */export interface SttTranscribeResponse {segments: SttPhraseSegment[];diff --git a/src/lib/ai-edition/transcription/status.test.ts b/src/lib/ai-edition/transcription/status.test.tsindex 8ff90ded9..c94cdf705 100644--- a/src/lib/ai-edition/transcription/status.test.ts+++ b/src/lib/ai-edition/transcription/status.test.ts@@ -1,4 +1,5 @@import { describe, expect, it } from "vitest";+import { STT_MEDIA_UNREADABLE } from "../../../../electron/stt/transcriptionContract";import type { AxcutDocument, AxcutTranscript } from "../schema";import {type AssetTranscriptionView,@@ -110,33 +111,44 @@ describe("classifyTranscriptionError", () => {// Issue #968: macOS held ffmpeg's read of a file in ~/Downloads behind a// pending TCC prompt until the extraction timeout fired, and the media card// printed the whole IPC rejection.+ // The shape `MediaUnreadableError` takes once `ipcRenderer.invoke` has wrapped it.it("explains an extraction timeout as unreadable media, without the IPC wrapper", () => {const failure = classifyTranscriptionError(new Error(- "Error invoking remote method 'stt:transcribe': Error: ffmpeg timed out after 60000ms on /Users/me/Downloads/clip.mp4",+ `Error invoking remote method 'stt:transcribe': Error: ${STT_MEDIA_UNREADABLE}: cannot read /Users/me/Downloads/clip.mp4: ffmpeg timed out after 60000ms`,),);expect(failure.kind).toBe("error");expect(failure.unreadableMedia).toBe(true);- expect(failure.message).toBe("ffmpeg timed out after 60000ms on /Users/me/Downloads/clip.mp4");+ expect(failure.message).toBe(+ "cannot read /Users/me/Downloads/clip.mp4: ffmpeg timed out after 60000ms",+ );// Transient: once the prompt is answered, the next run must try again.expect(isPermanentFailure(failure.kind)).toBe(false);expect(isSilentFailure(view("a", "failed", failure.kind))).toBe(false);expect(transcriptionFailureHintKey(failure)).toBe("mediaStage.mediaUnreadableHint");});- // A refused read exits ffmpeg non-zero with nothing decoded, which the native- // extractor words as "No decodable audio". It must not be remembered as a- // silent file, or granting access later would never get it transcribed.- it("does not persist a refused read as no-audio", () => {+ // Wording is not evidence: only the extraction step sets the marker, and a+ // permission error out of model loading is an engine failure, which must keep+ // the engine path (raw message, rest of the queue failed with it).+ it("leaves a permission error from model loading on the engine-failure path", () => {const failure = classifyTranscriptionError(new Error(- "Error invoking remote method 'stt:transcribe': Error: No decodable audio in /Users/me/Downloads/clip.mp4: /Users/me/Downloads/clip.mp4: Operation not permitted",+ "Error invoking remote method 'stt:transcribe': Error: EACCES: permission denied, open '/Users/me/Library/Application Support/openscreen/models/ggml-small.bin'",),);expect(failure.kind).toBe("error");- expect(failure.unreadableMedia).toBe(true);- expect(transcriptionFailureHintKey(failure)).toBe("mediaStage.mediaUnreadableHint");+ expect(failure.unreadableMedia).toBeUndefined();+ expect(transcriptionFailureHintKey(failure)).toBeNull();+ });++ it("does not take an ffmpeg timeout without the marker for unreadable media", () => {+ // e.g. the peaks decoder's own timeout, which says the same words.+ const failure = classifyTranscriptionError(+ new Error("ffmpeg timed out after 60000ms on /Users/me/Downloads/clip.mp4"),+ );+ expect(failure.unreadableMedia).toBeUndefined();});it("strips the IPC wrapper from an engine message it has no hint for", () => {diff --git a/src/lib/ai-edition/transcription/status.ts b/src/lib/ai-edition/transcription/status.tsindex 9e4178d83..fe28e88ed 100644--- a/src/lib/ai-edition/transcription/status.ts+++ b/src/lib/ai-edition/transcription/status.ts@@ -6,6 +6,7 @@// plain data — `store/transcriptionStore.ts` owns the queue and the side// effects, this module owns the vocabulary.+import { STT_MEDIA_UNREADABLE } from "../../../../electron/stt/transcriptionContract";import type { AxcutDocument, AxcutTranscript } from "../schema";import { voiceoverPlacements } from "../timeline/aggregated-transcript";@@ -17,9 +18,11 @@ export interface TranscriptionFailure {/** Raw engine/exception message, IPC wrapper stripped. Surfaced as a tooltip. */message: string;/**- * The media file itself could not be read: the OS refused access, or ffmpeg hung- * opening it (macOS parks the read behind a pending "access files in your- * Downloads folder" prompt until the extraction timeout fires, issue #968).+ * Audio extraction could not read the media file itself: the OS refused access,+ * or ffmpeg hung opening it (macOS parks the read behind a pending "access files+ * in your Downloads folder" prompt until the extraction timeout fires, issue+ * #968). Set only from the `STT_MEDIA_UNREADABLE` marker `extractAudio.ts` puts+ * on its rejection, never inferred from wording.* Transient, so `kind` stays `"error"`, but the user can fix it: the UI shows a* hint pointing at file access instead of the raw `message`.*/@@ -138,12 +141,15 @@ export type PersistableFailureKind = Exclude<TranscriptionFailureKind, "error">;*/export function classifyTranscriptionError(error: unknown): TranscriptionFailure {const message = stripIpcErrorWrapper(error instanceof Error ? error.message : String(error));- // Checked before the no-audio verdict: a read the OS refused makes ffmpeg exit- // non-zero with nothing decoded, which `extractAudio.ts` reports as "No- // decodable audio in ...". Persisting that as a permanent no-audio would never- // retry the file once access is granted.- if (/ffmpeg timed out|operation not permitted|permission denied/i.test(message)) {- return { kind: "error", message, unreadableMedia: true };+ // Keyed on the marker only the audio-extraction step sets, not on wording: a+ // "permission denied" out of model loading is an engine failure, and must keep+ // the engine-failure handling (raw message, fail the rest of the queue).+ if (message.includes(STT_MEDIA_UNREADABLE)) {+ return {+ kind: "error",+ message: message.replace(`${STT_MEDIA_UNREADABLE}: `, ""),+ unreadableMedia: true,+ };}if (/no audio track|zero audio frames|no decodable audio/i.test(message)) {return { kind: "no-audio", message };