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): show a readable message when transcription cannot read the audio
Etienne Lescot6b56f7bf1f54
diff --git a/src/components/ai-edition/v4/MediaStage.tsx b/src/components/ai-edition/v4/MediaStage.tsxindex bb30e2115..7b0558084 100644--- a/src/components/ai-edition/v4/MediaStage.tsx+++ b/src/components/ai-edition/v4/MediaStage.tsx@@ -19,6 +19,7 @@ import {type AssetTranscriptionView,isSilentFailure,transcriptHasSpeech,+ transcriptionFailureHintKey,} from "@/lib/ai-edition/transcription/status";import { formatBytes } from "@/utils/formatBytes";import {@@ -105,6 +106,9 @@ export function MediaStage({: { assetId: "", status: "idle" };const selectedBusy =selectedTranscription.status === "running" || selectedTranscription.status === "queued";+ const failureHintKey = selectedTranscription.failure+ ? transcriptionFailureHintKey(selectedTranscription.failure)+ : null;const handleImport = async () => {if (!projectId) {@@ -380,9 +384,7 @@ export function MediaStage({color: "var(--muted)",}}>- {selectedTranscription.failure.kind === "error"- ? selectedTranscription.failure.message- : t("mediaStage.noAudioTrackHint")}+ {failureHintKey ? t(failureHintKey) : selectedTranscription.failure.message}</p>) : null}diff --git a/src/i18n/locales/ar/editor.json b/src/i18n/locales/ar/editor.jsonindex e93f6914b..0de8bfa88 100644--- a/src/i18n/locales/ar/editor.json+++ b/src/i18n/locales/ar/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "اللغة المكتشفة: {{language}}","noAudioTrack": "لا يوجد مسار صوتي","noAudioTrackHint": "لا يحتوي هذا الملف على مسار صوتي — لا يوجد ما يمكن نسخه.",+ "mediaUnreadableHint": "تعذّرت قراءة صوت هذا الملف. تأكد من أن OpenScreen يمكنه الوصول إلى المجلد الذي يوجد فيه، ثم أعد الإنشاء.","noSpeechDetected": "لم يتم اكتشاف كلام"},"exportDialog": {diff --git a/src/i18n/locales/cs/editor.json b/src/i18n/locales/cs/editor.jsonindex ac242ff8d..78ed90f4f 100644--- a/src/i18n/locales/cs/editor.json+++ b/src/i18n/locales/cs/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Zjištěný jazyk: {{language}}","noAudioTrack": "Žádná zvuková stopa","noAudioTrackHint": "Toto médium nemá zvukovou stopu, takže není co přepisovat.",+ "mediaUnreadableHint": "Zvuk tohoto média se nepodařilo přečíst. Ověřte, že OpenScreen má přístup ke složce, ve které je uloženo, a pak jej vygenerujte znovu.","noSpeechDetected": "Žádná řeč nezjištěna"},"exportDialog": {diff --git a/src/i18n/locales/de/editor.json b/src/i18n/locales/de/editor.jsonindex a292f3270..c5bc7453f 100644--- a/src/i18n/locales/de/editor.json+++ b/src/i18n/locales/de/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Erkannte Sprache: {{language}}","noAudioTrack": "Keine Audiospur","noAudioTrackHint": "Dieses Medium hat keine Audiospur — es gibt nichts zu transkribieren.",+ "mediaUnreadableHint": "Der Ton dieses Mediums konnte nicht gelesen werden. Stelle sicher, dass OpenScreen auf den Ordner zugreifen darf, in dem es liegt, und generiere dann neu.","noSpeechDetected": "Keine Sprache erkannt"},"exportDialog": {diff --git a/src/i18n/locales/en/editor.json b/src/i18n/locales/en/editor.jsonindex 52dbd2d35..8a2073355 100644--- a/src/i18n/locales/en/editor.json+++ b/src/i18n/locales/en/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Detected language: {{language}}","noAudioTrack": "No audio track","noAudioTrackHint": "This media has no audio track — there is nothing to transcribe.",+ "mediaUnreadableHint": "Couldn't read this media's audio. Make sure OpenScreen can access the folder it's in, then regenerate.","noSpeechDetected": "No speech detected"},"exportDialog": {diff --git a/src/i18n/locales/es/editor.json b/src/i18n/locales/es/editor.jsonindex d3e01791c..5640049e7 100644--- a/src/i18n/locales/es/editor.json+++ b/src/i18n/locales/es/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Idioma detectado: {{language}}","noAudioTrack": "Sin pista de audio","noAudioTrackHint": "Este medio no tiene pista de audio: no hay nada que transcribir.",+ "mediaUnreadableHint": "No se pudo leer el audio de este medio. Asegúrate de que OpenScreen puede acceder a la carpeta que lo contiene y vuelve a generar.","noSpeechDetected": "No se detectó voz"},"exportDialog": {diff --git a/src/i18n/locales/fr/editor.json b/src/i18n/locales/fr/editor.jsonindex 60bede225..e7e0c5bf2 100644--- a/src/i18n/locales/fr/editor.json+++ b/src/i18n/locales/fr/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Langue détectée : {{language}}","noAudioTrack": "Aucune piste audio","noAudioTrackHint": "Ce média n'a pas de piste audio — il n'y a rien à transcrire.",+ "mediaUnreadableHint": "Impossible de lire l'audio de ce média. Vérifiez qu'OpenScreen a accès au dossier qui le contient, puis régénérez.","noSpeechDetected": "Aucune parole détectée"},"exportDialog": {diff --git a/src/i18n/locales/it/editor.json b/src/i18n/locales/it/editor.jsonindex bef5e48d6..cc2116ea3 100644--- a/src/i18n/locales/it/editor.json+++ b/src/i18n/locales/it/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Lingua rilevata: {{language}}","noAudioTrack": "Nessuna traccia audio","noAudioTrackHint": "Questo contenuto non ha una traccia audio: non c'è nulla da trascrivere.",+ "mediaUnreadableHint": "Impossibile leggere l'audio di questo contenuto. Verifica che OpenScreen possa accedere alla cartella che lo contiene, poi rigenera.","noSpeechDetected": "Nessun parlato rilevato"},"exportDialog": {diff --git a/src/i18n/locales/ja-JP/editor.json b/src/i18n/locales/ja-JP/editor.jsonindex b8322677a..2313587b6 100644--- a/src/i18n/locales/ja-JP/editor.json+++ b/src/i18n/locales/ja-JP/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "検出された言語: {{language}}","noAudioTrack": "音声トラックがありません","noAudioTrackHint": "このメディアには音声トラックがないため、文字起こしできません。",+ "mediaUnreadableHint": "このメディアの音声を読み取れませんでした。OpenScreen が保存先のフォルダーにアクセスできることを確認してから、再生成してください。","noSpeechDetected": "音声が検出されませんでした"},"exportDialog": {diff --git a/src/i18n/locales/ko-KR/editor.json b/src/i18n/locales/ko-KR/editor.jsonindex 3dfd3a431..b75059aa3 100644--- a/src/i18n/locales/ko-KR/editor.json+++ b/src/i18n/locales/ko-KR/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "감지된 언어: {{language}}","noAudioTrack": "오디오 트랙 없음","noAudioTrackHint": "이 미디어에는 오디오 트랙이 없어 받아쓸 내용이 없습니다.",+ "mediaUnreadableHint": "이 미디어의 오디오를 읽을 수 없습니다. OpenScreen이 파일이 있는 폴더에 접근할 수 있는지 확인한 후 다시 생성하세요.","noSpeechDetected": "음성이 감지되지 않음"},"exportDialog": {diff --git a/src/i18n/locales/pt-BR/editor.json b/src/i18n/locales/pt-BR/editor.jsonindex d4c344ad9..003ea563a 100644--- a/src/i18n/locales/pt-BR/editor.json+++ b/src/i18n/locales/pt-BR/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Idioma detectado: {{language}}","noAudioTrack": "Sem faixa de áudio","noAudioTrackHint": "Esta mídia não tem faixa de áudio — não há nada para transcrever.",+ "mediaUnreadableHint": "Não foi possível ler o áudio desta mídia. Verifique se o OpenScreen tem acesso à pasta onde ela está e gere novamente.","noSpeechDetected": "Nenhuma fala detectada"},"exportDialog": {diff --git a/src/i18n/locales/ru/editor.json b/src/i18n/locales/ru/editor.jsonindex 35f0d0233..096daf5e7 100644--- a/src/i18n/locales/ru/editor.json+++ b/src/i18n/locales/ru/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Обнаруженный язык: {{language}}","noAudioTrack": "Нет аудиодорожки","noAudioTrackHint": "В этом медиафайле нет аудиодорожки — расшифровывать нечего.",+ "mediaUnreadableHint": "Не удалось прочитать звук этого медиафайла. Убедитесь, что у OpenScreen есть доступ к папке, в которой он находится, и создайте расшифровку заново.","noSpeechDetected": "Речь не обнаружена"},"exportDialog": {diff --git a/src/i18n/locales/tr/editor.json b/src/i18n/locales/tr/editor.jsonindex df1eb203f..f4a76714e 100644--- a/src/i18n/locales/tr/editor.json+++ b/src/i18n/locales/tr/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Algılanan dil: {{language}}","noAudioTrack": "Ses parçası yok","noAudioTrackHint": "Bu medyada ses parçası yok — metne dökülecek bir şey bulunmuyor.",+ "mediaUnreadableHint": "Bu medyanın sesi okunamadı. OpenScreen'in bulunduğu klasöre erişebildiğinden emin olun, ardından yeniden oluşturun.","noSpeechDetected": "Konuşma algılanmadı"},"exportDialog": {diff --git a/src/i18n/locales/vi/editor.json b/src/i18n/locales/vi/editor.jsonindex 97e000f27..1ab9da48c 100644--- a/src/i18n/locales/vi/editor.json+++ b/src/i18n/locales/vi/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "Ngôn ngữ phát hiện: {{language}}","noAudioTrack": "Không có bản âm thanh","noAudioTrackHint": "Media này không có bản âm thanh — không có gì để phiên âm.",+ "mediaUnreadableHint": "Không thể đọc âm thanh của media này. Hãy đảm bảo OpenScreen có quyền truy cập thư mục chứa nó, rồi tạo lại.","noSpeechDetected": "Không phát hiện giọng nói"},"exportDialog": {diff --git a/src/i18n/locales/zh-CN/editor.json b/src/i18n/locales/zh-CN/editor.jsonindex e2be1ddc2..98a12b084 100644--- a/src/i18n/locales/zh-CN/editor.json+++ b/src/i18n/locales/zh-CN/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "检测到的语言:{{language}}","noAudioTrack": "无音频轨道","noAudioTrackHint": "此媒体没有音频轨道,没有可转录的内容。",+ "mediaUnreadableHint": "无法读取此媒体的音频。请确认 OpenScreen 可以访问它所在的文件夹,然后重新生成。","noSpeechDetected": "未检测到语音"},"exportDialog": {diff --git a/src/i18n/locales/zh-TW/editor.json b/src/i18n/locales/zh-TW/editor.jsonindex 991a5d04f..8862c279a 100644--- a/src/i18n/locales/zh-TW/editor.json+++ b/src/i18n/locales/zh-TW/editor.json@@ -172,6 +172,7 @@"detectedLanguage": "偵測到的語言:{{language}}","noAudioTrack": "無音訊軌道","noAudioTrackHint": "此媒體沒有音訊軌道,沒有可轉錄的內容。",+ "mediaUnreadableHint": "無法讀取此媒體的音訊。請確認 OpenScreen 可以存取它所在的資料夾,然後重新產生。","noSpeechDetected": "未偵測到語音"},"exportDialog": {diff --git a/src/lib/ai-edition/store/transcriptionStore.ts b/src/lib/ai-edition/store/transcriptionStore.tsindex 0eb950a56..316f30791 100644--- a/src/lib/ai-edition/store/transcriptionStore.ts+++ b/src/lib/ai-edition/store/transcriptionStore.ts@@ -42,6 +42,7 @@ import {type TranscriptionFailure,type TranscriptionPhase,type TranscriptionProgress,+ transcriptionFailureHintKey,transcriptRelevantAssetIds,} from "../transcription/status";import { useProjectStore } from "./projectStore";@@ -451,6 +452,9 @@ async function runJob(assetId: string, job: TranscriptionJob): Promise<void> {}if (!isCurrentRun(assetId, runId)) return; // superseded by a newer requestconst failure = classifyTranscriptionError(error);+ // The UI shows a translated hint or a trimmed message; the full detail+ // (channel, path, ffmpeg stderr) belongs here.+ console.warn(`[transcription] asset ${assetId} failed:`, error);patchJob(assetId, runId, { status: "failed", phase: undefined, progress: undefined, failure });flushSettleWaiters(assetId);await persistPermanentFailure(projectId, assetId, failure);@@ -459,8 +463,13 @@ async function runJob(assetId: string, job: TranscriptionJob): Promise<void> {// queue into the same wall would spend a full retry budget per asset and// stack one identical toast per asset. Fail them with the same verdict// instead — the gate then reads "failed" (not "queued forever"), and one- // manual retry re-runs them all once the engine is back.- if (failure.kind === "error") failRemainingQueue(projectId, failure);+ // manual retry re-runs them all once the engine is back. A file the OS would+ // not let ffmpeg read is the exception: that verdict is about this file's+ // folder, and stamping it on media elsewhere would send the user looking at+ // the wrong permission.+ if (failure.kind === "error" && !failure.unreadableMedia) {+ failRemainingQueue(projectId, failure);+ }// A silent recording is an expected outcome, not an incident: the media card// and every gated button already say so, so the background pass stays quiet.// A run the user asked for by hand still gets an answer — but an@@ -469,7 +478,10 @@ async function runJob(assetId: string, job: TranscriptionJob): Promise<void> {if (isPermanentFailure(failure.kind)) {if (job.manual) toast.info(toastText("mediaStage.noAudioTrackHint"));} else {- toast.error(toastText("mediaStage.transcriptionFailed"), { description: failure.message });+ const hintKey = transcriptionFailureHintKey(failure);+ toast.error(toastText("mediaStage.transcriptionFailed"), {+ description: hintKey ? toastText(hintKey) : failure.message,+ });}} finally {if (activeRun?.controller === controller) activeRun = null;diff --git a/src/lib/ai-edition/transcription/status.test.ts b/src/lib/ai-edition/transcription/status.test.tsindex 442322d8a..8ff90ded9 100644--- a/src/lib/ai-edition/transcription/status.test.ts+++ b/src/lib/ai-edition/transcription/status.test.ts@@ -14,7 +14,9 @@ import {progressFraction,realtimeSpeed,resolveTranscriptGate,+ stripIpcErrorWrapper,transcriptHasSpeech,+ transcriptionFailureHintKey,transcriptRelevantAssetIds,} from "./status";@@ -100,7 +102,80 @@ describe("classifyTranscriptionError", () => {const failure = classifyTranscriptionError(new Error("whisper-server exited"));expect(failure.kind).toBe("error");expect(failure.message).toBe("whisper-server exited");+ expect(failure.unreadableMedia).toBeUndefined();expect(isPermanentFailure(failure.kind)).toBe(false);+ expect(transcriptionFailureHintKey(failure)).toBeNull();+ });++ // 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.+ 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",+ ),+ );+ 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");+ // 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", () => {+ 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",+ ),+ );+ expect(failure.kind).toBe("error");+ expect(failure.unreadableMedia).toBe(true);+ expect(transcriptionFailureHintKey(failure)).toBe("mediaStage.mediaUnreadableHint");+ });++ it("strips the IPC wrapper from an engine message it has no hint for", () => {+ const failure = classifyTranscriptionError(+ new Error("Error invoking remote method 'stt:transcribe': Error: whisper-server exited"),+ );+ expect(failure.kind).toBe("error");+ expect(failure.message).toBe("whisper-server exited");+ expect(transcriptionFailureHintKey(failure)).toBeNull();+ });++ it("gives the media verdicts the no-audio hint", () => {+ expect(transcriptionFailureHintKey({ kind: "no-audio", message: "x" })).toBe(+ "mediaStage.noAudioTrackHint",+ );+ expect(transcriptionFailureHintKey({ kind: "unsupported-audio", message: "x" })).toBe(+ "mediaStage.noAudioTrackHint",+ );+ });+});++describe("stripIpcErrorWrapper", () => {+ it("removes the channel prefix and the rebuilt error name", () => {+ expect(stripIpcErrorWrapper("Error invoking remote method 'stt:transcribe': Error: boom")).toBe(+ "boom",+ );+ expect(+ stripIpcErrorWrapper("Error invoking remote method 'stt:transcribe': TypeError: bad arg"),+ ).toBe("bad arg");+ });++ it("keeps the message when the rejection carries no error name", () => {+ expect(stripIpcErrorWrapper("Error invoking remote method 'x:y': plain reason")).toBe(+ "plain reason",+ );+ });++ it("leaves a message that never crossed IPC untouched", () => {+ expect(stripIpcErrorWrapper("Error: not from IPC")).toBe("Error: not from IPC");});});diff --git a/src/lib/ai-edition/transcription/status.ts b/src/lib/ai-edition/transcription/status.tsindex 825d4e771..9e4178d83 100644--- a/src/lib/ai-edition/transcription/status.ts+++ b/src/lib/ai-edition/transcription/status.ts@@ -14,8 +14,16 @@ export type TranscriptionFailureKind = "no-audio" | "unsupported-audio" | "errorexport interface TranscriptionFailure {kind: TranscriptionFailureKind;- /** Raw engine/exception message — surfaced as a tooltip / toast description. */+ /** 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).+ * 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`.+ */+ unreadableMedia?: boolean;}/** Which part of the pipeline a running job is in (mirrors `TranscribeAssetOptions.onStatus`). */@@ -129,7 +137,14 @@ export type PersistableFailureKind = Exclude<TranscriptionFailureKind, "error">;* open, and pops a toast carrying raw ffmpeg stderr (issue #628).*/export function classifyTranscriptionError(error: unknown): TranscriptionFailure {- const message = error instanceof Error ? error.message : String(error);+ 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 };+ }if (/no audio track|zero audio frames|no decodable audio/i.test(message)) {return { kind: "no-audio", message };}@@ -139,6 +154,24 @@ export function classifyTranscriptionError(error: unknown): TranscriptionFailurereturn { kind: "error", message };}+/**+ * `ipcRenderer.invoke` rejects with `Error invoking remote method '<channel>':+ * <Name>: <message>`. Only `<message>` means anything to the user.+ */+export function stripIpcErrorWrapper(message: string): string {+ return message.replace(/^Error invoking remote method '[^']*': (?:[A-Za-z]*Error: )?/, "");+}++/**+ * The `editor` i18n key of the sentence that explains this failure to the user,+ * or null when the engine message is the best explanation there is.+ */+export function transcriptionFailureHintKey(failure: TranscriptionFailure): string | null {+ if (failure.kind !== "error") return "mediaStage.noAudioTrackHint";+ if (failure.unreadableMedia) return "mediaStage.mediaUnreadableHint";+ return null;+}+/*** True when this asset's job ended on a verdict about the MEDIA rather than on* something that went wrong: no audio track, or an audio codec nothing here can