Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 };