fix(transcription): resolve three deepsec transcription-pipeline bugs (#224)

* fix(transcription): don't save failed chunks as a completed transcript

A chunk that exhausted its retries wrote an "[Error transcribing chunk N]"
placeholder and was counted as completed, and buildTranscriptBody only
rejected a fully-empty body. A transcript made of error placeholders was
therefore saved as "completed", and the existence check then blocked any
retry, leaving the user with a corrupt transcript and no easy way to re-run.

transcribeChunks now reports how many chunks failed. buildTranscriptBody
strips the error placeholders to decide whether any real speech was
transcribed: if nothing real remains (every chunk failed, or the only
successes were empty) it throws, so no file is written and the episode stays
retryable - mirroring the diarization provider's all-chunks-failed contract.
When some chunks fail but real speech remains, the transcript is kept and a
warning notice reports the partial failure instead of a clean success.

Fixes deepsec finding other-silent-failure.

* fix(transcription): decode container/lossless audio to WAV before splitting

createChunkFiles only routed m4a over the decode+WAV path; every other
format over the 20 MB request limit fell through to raw byte-splitting. MP3
frames are self-synchronizing so that is fine, but container/header-dependent
formats (ogg, webm, flac, wav, m4a) carry codec setup only at the stream
start, so non-first byte slices are undecodable and the API rejects or
garbles them.

Restrict raw byte-splitting to MP3; route every other format through the
existing decode+WAV re-encode path. When WAV conversion yields nothing (no
Web Audio decoder, or an undecodable codec) throw a clear error rather than
byte-splitting a container into corrupt chunks, keeping the run retryable.

Fixes deepsec finding other-logic-bug (audioChunker).

* fix(diarization): insert speaker labels verbatim in formatSpeakerLabel

formatSpeakerLabel passed the speaker label as the replacement string to
String.replace, which interprets special patterns ($$, $&, $`, $', $n). A
label containing one of those would be rewritten with matched/surrounding
text instead of inserted literally. Use a replacer function so the label is
inserted verbatim.

Fixes deepsec finding other-logic-bug (diarization segments).

Author: chhoumann

src/services/TranscriptionService.test.ts

@@ -193,7 +193,20 @@ describe("TranscriptionService", () => {
 	});
 
 	describe("buildTranscriptBody (TR-01)", () => {
-		const buildBody = (plugin: PodNotes) => {
+		const buildBody = (
+			plugin: PodNotes,
+			audio: {
+				buffer: ArrayBuffer;
+				mimeType: string;
+				extension: string;
+				basename: string;
+			} = {
+				buffer: new ArrayBuffer(1024),
+				mimeType: "audio/mpeg",
+				extension: "mp3",
+				basename: "episode",
+			},
+		) => {
 			const service = new TranscriptionService(plugin);
 			return (
 				service as unknown as {
@@ -205,17 +218,9 @@ describe("TranscriptionService", () => {
 							basename: string;
 						},
 						update: (message: string) => void,
-					) => Promise<string>;
+					) => Promise<{ body: string; warning?: string }>;
 				}
-			).buildTranscriptBody(
-				{
-					buffer: new ArrayBuffer(1024),
-					mimeType: "audio/mpeg",
-					extension: "mp3",
-					basename: "episode",
-				},
-				() => {},
-			);
+			).buildTranscriptBody(audio, () => {});
 		};
 
 		test("throws when the trimmed Whisper body is empty", async () => {
@@ -231,9 +236,133 @@ describe("TranscriptionService", () => {
 				text: "One. Two.",
 			});
 
-			await expect(buildBody(createMockPlugin())).resolves.toBe(
-				"One.\n\nTwo.",
+			await expect(buildBody(createMockPlugin())).resolves.toEqual({
+				body: "One.\n\nTwo.",
+				warning: undefined,
+			});
+		});
+	});
+
+	describe("failed chunks are not saved as a completed transcript (other-silent-failure)", () => {
+		const buildBodyDirect = (
+			plugin: PodNotes,
+			audio: {
+				buffer: ArrayBuffer;
+				mimeType: string;
+				extension: string;
+				basename: string;
+			},
+		) => {
+			const service = new TranscriptionService(plugin);
+			return (
+				service as unknown as {
+					buildTranscriptBody: (
+						a: typeof audio,
+						update: (message: string) => void,
+					) => Promise<{ body: string; warning?: string }>;
+				}
+			).buildTranscriptBody(audio, () => {});
+		};
+
+		const mp3Audio = (byteLength: number) => ({
+			buffer: new ArrayBuffer(byteLength),
+			mimeType: "audio/mp3",
+			extension: "mp3",
+			basename: "episode",
+		});
+
+		test("throws (no file) when the single chunk fails every retry", async () => {
+			transcriptionsCreateMock.mockRejectedValue(new Error("boom"));
+			vi.useFakeTimers();
+			try {
+				const promise = buildBodyDirect(createMockPlugin(), mp3Audio(1024));
+				const assertion = expect(promise).rejects.toThrow(
+					"Transcription failed: all 1 audio chunk(s) failed or returned no text.",
+				);
+				await vi.runAllTimersAsync();
+				await assertion;
+			} finally {
+				vi.useRealTimers();
+			}
+		});
+
+		test("throws when failed chunks plus empty successes leave no real text", async () => {
+			// >20 MB mp3 → two chunks. chunk 0 fails every retry; chunk 1 "succeeds"
+			// but returns empty text. The body is then only an error marker, which
+			// must NOT be saved as a completed transcript.
+			transcriptionsCreateMock.mockImplementation(
+				async ({ file }: { file: File }) => {
+					if (file.name.includes("part0")) {
+						throw new Error("boom");
+					}
+					return { text: "   " };
+				},
 			);
+
+			vi.useFakeTimers();
+			try {
+				const promise = buildBodyDirect(
+					createMockPlugin(),
+					mp3Audio(20 * 1024 * 1024 + 1024),
+				);
+				const assertion = expect(promise).rejects.toThrow(
+					"Transcription failed: all 2 audio chunk(s) failed or returned no text.",
+				);
+				await vi.runAllTimersAsync();
+				await assertion;
+			} finally {
+				vi.useRealTimers();
+			}
+		});
+
+		test("does not write a file when transcription fails completely", async () => {
+			transcriptionsCreateMock.mockRejectedValue(new Error("boom"));
+			const plugin = createMockPlugin();
+			const service = new TranscriptionService(plugin);
+
+			vi.useFakeTimers();
+			try {
+				const promise = (
+					service as unknown as {
+						transcribeEpisode: (episode: Episode) => Promise<void>;
+					}
+				).transcribeEpisode(mockEpisode);
+				// One chunk, MAX_RETRIES=3 → backoff 1000ms + 2000ms before it gives up.
+				await vi.advanceTimersByTimeAsync(3500);
+				await promise;
+			} finally {
+				vi.useRealTimers();
+			}
+
+			expect(plugin.app.vault.create).not.toHaveBeenCalled();
+		});
+
+		test("keeps an otherwise-good transcript but warns when only some chunks fail", async () => {
+			// A >20 MB mp3 byte-splits into two chunks; fail the second one.
+			transcriptionsCreateMock.mockImplementation(
+				async ({ file }: { file: File }) => {
+					if (file.name.includes("part1")) {
+						throw new Error("boom");
+					}
+					return { text: "Good chunk." };
+				},
+			);
+
+			vi.useFakeTimers();
+			try {
+				const promise = buildBodyDirect(
+					createMockPlugin(),
+					mp3Audio(20 * 1024 * 1024 + 1024),
+				);
+				await vi.runAllTimersAsync();
+				const result = await promise;
+
+				expect(result.body).toContain("Good chunk.");
+				expect(result.body).toContain("[Error transcribing chunk 1]");
+				expect(result.warning).toContain("1 of 2 chunk(s) failed");
+			} finally {
+				vi.useRealTimers();
+			}
 		});
 	});
 });

src/services/TranscriptionService.ts

@@ -57,6 +57,14 @@ function formatTime(ms: number): string {
 	return `${hours.toString().padStart(2, "0")}:${(minutes % 60).toString().padStart(2, "0")}:${(seconds % 60).toString().padStart(2, "0")}`;
 }
 
+// A chunk that exhausts its retries leaves this placeholder in its transcript
+// slot; the pattern matches it so buildTranscriptBody can tell real speech apart
+// from a body made only of error markers. Keep the builder and matcher in sync.
+function chunkErrorPlaceholder(index: number): string {
+	return `[Error transcribing chunk ${index}]`;
+}
+const CHUNK_ERROR_PLACEHOLDER_PATTERN = /\[Error transcribing chunk \d+\]/g;
+
 export class TranscriptionService {
 	private plugin: PodNotes;
 	private client: OpenAI | null = null;
@@ -168,7 +176,7 @@ export class TranscriptionService {
 			} = await getEpisodeAudioBuffer(episode);
 			const mimeType = getMimeType(fileExtension);
 
-			const transcriptBody = await this.buildTranscriptBody(
+			const { body: transcriptBody, warning } = await this.buildTranscriptBody(
 				{
 					buffer: fileBuffer,
 					mimeType,
@@ -182,7 +190,7 @@ export class TranscriptionService {
 			await this.saveTranscription(episode, transcriptBody);
 
 			notice.stop();
-			notice.update("Transcription completed and saved.");
+			notice.update(warning ?? "Transcription completed and saved.");
 		} catch (error) {
 			console.error("Transcription error:", error);
 			const message = error instanceof Error ? error.message : String(error);
@@ -201,11 +209,20 @@ export class TranscriptionService {
 	 * separated into paragraphs, so it is rendered as-is. Either path yielding no
 	 * speech is treated as a failure rather than writing an empty transcript (empty
 	 * Whisper chunks join to whitespace, so the body is trimmed before the check).
+	 *
+	 * A chunk that exhausts its retries leaves an `[Error transcribing chunk N]`
+	 * placeholder in its slot. If stripping those placeholders leaves no real text -
+	 * every chunk failed, or the only successes were empty - we throw, so no file is
+	 * written and the episode stays retryable instead of saving a "transcript" made
+	 * only of error markers that the existence check would then refuse to re-run
+	 * (mirrors the diarization provider's all-chunks-failed contract). When some
+	 * chunks fail but real speech remains we keep the otherwise-good transcript and
+	 * return a `warning` so the run is reported as partial, not a clean success.
 	 */
 	private async buildTranscriptBody(
 		audio: DiarizationAudio,
 		updateNotice: (message: string) => void,
-	): Promise<string> {
+	): Promise<{ body: string; warning?: string }> {
 		const diarization = this.plugin.settings.transcript.diarization;
 
 		if (diarization?.enabled) {
@@ -217,19 +234,41 @@ export class TranscriptionService {
 			if (segments.length === 0) {
 				throw new Error("Diarization returned no speech segments.");
 			}
-			return renderDiarizedTranscript(segments, diarization.speakerTemplate);
+			return {
+				body: renderDiarizedTranscript(segments, diarization.speakerTemplate),
+			};
 		}
 
 		updateNotice("Creating audio chunks...");
 		const files = await createChunkFiles(audio);
 		updateNotice("Starting transcription...");
-		const transcription = await this.transcribeChunks(files, updateNotice);
-		// Empty chunks join to " " (not ""), so trim before deciding it is empty.
-		const body = transcription.trim().replace(/\.\s+/g, ".\n\n");
-		if (body.length === 0) {
-			throw new Error("Transcription returned no text.");
+		const { text, failedChunks } = await this.transcribeChunks(
+			files,
+			updateNotice,
+		);
+
+		// Strip the error placeholders (and trim) to see whether ANY real speech was
+		// transcribed. Nothing real means every chunk failed or the only successes
+		// were empty - either way there is no usable transcript, so throw instead of
+		// saving a body of pure error markers (empty chunks join to " ", not "").
+		const realText = text.replace(CHUNK_ERROR_PLACEHOLDER_PATTERN, " ").trim();
+		if (realText.length === 0) {
+			throw new Error(
+				failedChunks > 0
+					? `Transcription failed: all ${files.length} audio chunk(s) failed or returned no text.`
+					: "Transcription returned no text.",
+			);
 		}
-		return body;
+
+		// Reflow the full body (placeholders kept inline so the user can see which
+		// chunks failed) after sentence periods for readability.
+		const body = text.trim().replace(/\.\s+/g, ".\n\n");
+
+		const warning =
+			failedChunks > 0
+				? `Transcription saved, but ${failedChunks} of ${files.length} chunk(s) failed - look for [Error transcribing chunk N] markers and re-run after deleting the note to retry.`
+				: undefined;
+		return { body, warning };
 	}
 
 	/** Route the episode audio to the configured diarization provider (#168). */
@@ -269,10 +308,11 @@ export class TranscriptionService {
 	private async transcribeChunks(
 		files: File[],
 		updateNotice: (message: string) => void,
-	): Promise<string> {
+	): Promise<{ text: string; failedChunks: number }> {
 		const client = await this.getClient();
 		const transcriptions: string[] = new Array(files.length);
 		let completedChunks = 0;
+		let failedChunks = 0;
 		let nextIndex = 0;
 
 		const updateProgress = () => {
@@ -308,7 +348,8 @@ export class TranscriptionService {
 								`Failed to transcribe chunk ${index} after ${this.MAX_RETRIES} attempts:`,
 								error,
 							);
-							transcriptions[index] = `[Error transcribing chunk ${index}]`;
+							transcriptions[index] = chunkErrorPlaceholder(index);
+							failedChunks++;
 							completedChunks++;
 							updateProgress();
 						} else {
@@ -329,7 +370,7 @@ export class TranscriptionService {
 
 		await Promise.all(workers);
 
-		return transcriptions.join(" ");
+		return { text: transcriptions.join(" "), failedChunks };
 	}
 
 	/**