fix(transcription): always transcribe the currently playing episode (#182)

* fix(transcription): always transcribe the currently playing episode

Transcription resolved its audio through downloadEpisode(), which derived an
on-disk path from the user's download-path template and reused any file already
at that path without confirming it belonged to the episode. When the template
was not per-episode unique (the default empty path -> ".mp3", or any path
lacking {{title}}), different episodes mapped to the same file, so the
transcriber read a different episode's audio and saved it under the current
episode's note.

Replace that path-keyed reuse with getEpisodeAudioBuffer(episode), which always
yields the episode's own audio: a resolved local file, an already-downloaded
copy confirmed by the downloaded-episodes registry (keyed by the episode, not a
collidable path), or an in-memory fetch of the episode's stream URL. Nothing is
written to the vault during transcription, so the audio can no longer collide
with another episode. A non-audio response (e.g. an expired private feed) now
fails clearly instead of producing a placeholder-only transcript.

Note: transcription no longer writes audio to the vault or marks an episode as
downloaded; it reuses an already-downloaded copy when one exists.

* fix(transcription): require stream-URL match before reusing a downloaded copy

The downloaded-episodes registry is keyed by podcastName+title, which two
distinct episodes can share (re-releases, placeholder titles). Reusing a
registry-confirmed file on title alone could still transcribe the wrong
episode's audio, so also require the stored stream URL to match; otherwise fetch
the episode's own audio fresh. Addresses Codex review feedback on #182.

* refactor(transcription): match audio source by origin+path; flag unused downloadEpisode

- Reuse a registry-confirmed download when the stream URL's origin+path match,
  so a rotated signed-CDN query token no longer forces a full re-download of an
  already-cached episode (still safe: a different episode has a different path).
- Add a warning banner to the now-unused downloadEpisode noting it carries the
  #107 collision behavior and must not be used for transcription.

Addresses adversarial review feedback on #182.

Author: chhoumann

docs/docs/transcripts.md

@@ -18,7 +18,7 @@ To create a transcript:
 
 1. Start playing the podcast episode you want to transcribe.
 2. Use the "Transcribe current episode" command in Obsidian.
-3. PodNotes will download the episode (if it hasn't been downloaded already), split it into chunks, and send these chunks to OpenAI for transcription.
+3. PodNotes will fetch the audio for the episode you are playing (reusing an already-downloaded copy when one exists), split it into chunks, and send these chunks to OpenAI for transcription. The transcription always uses the currently playing episode's own audio, regardless of your download path settings.
 4. Once the transcription is complete, a new file will be created at the specified location with the transcribed content.
 
 ## Transcript Template

src/TemplateEngine.ts

@@ -242,7 +242,7 @@ export function TranscriptTemplateEngine(
 	return replacer(template);
 }
 
-function replaceIllegalFileNameCharactersInString(string: string) {
+export function replaceIllegalFileNameCharactersInString(string: string) {
 	return (
 		string
 			// Strip characters that are illegal in file names on major platforms,

src/downloadEpisode.test.ts

@@ -4,9 +4,11 @@ import { requestUrl, TFile } from "obsidian";
 import {
 	detectAudioFileExtension,
 	downloadEpisode,
+	getEpisodeAudioBuffer,
 } from "./downloadEpisode";
 import { downloadedEpisodes } from "./store";
 import type { Episode } from "./types/Episode";
+import type { LocalEpisode } from "./types/LocalEpisode";
 
 vi.mock("obsidian", async (importOriginal) => {
 	const actual = await importOriginal<typeof import("obsidian")>();
@@ -127,3 +129,220 @@ describe("downloadEpisode (API path)", () => {
 		expect(createBinary).not.toHaveBeenCalled();
 	});
 });
+
+describe("getEpisodeAudioBuffer (issue #107)", () => {
+	const files = new Map<string, ArrayBuffer>();
+
+	function makeTFile(path: string): TFile {
+		const file = new TFile();
+		const dot = path.lastIndexOf(".");
+		const slash = path.lastIndexOf("/");
+		(file as { path: string }).path = path;
+		(file as { extension: string }).extension =
+			dot > slash ? path.slice(dot + 1) : "";
+		(file as { basename: string }).basename = path.slice(
+			slash + 1,
+			dot > slash ? dot : undefined,
+		);
+		return file;
+	}
+
+	function seedFile(path: string, text: string): void {
+		files.set(path, new TextEncoder().encode(text).buffer);
+	}
+
+	function decode(buffer: ArrayBuffer): string {
+		return new TextDecoder().decode(new Uint8Array(buffer));
+	}
+
+	function episode(overrides: Partial<Episode>): Episode {
+		return {
+			title: "Title",
+			streamUrl: "https://example.com/audio.mp3",
+			url: "https://example.com/audio",
+			description: "",
+			content: "",
+			podcastName: "Pod",
+			feedUrl: "https://example.com/feed.xml",
+			episodeDate: undefined,
+			...overrides,
+		} as unknown as Episode;
+	}
+
+	beforeEach(() => {
+		files.clear();
+		(globalThis as { app?: unknown }).app = {
+			vault: {
+				getAbstractFileByPath: (path: string) =>
+					files.has(path) ? makeTFile(path) : null,
+				readBinary: async (file: TFile) => files.get(file.path),
+			},
+		};
+		requestUrlMock.mockImplementation((req: unknown) => {
+			const url = typeof req === "string" ? req : (req as { url: string }).url;
+			const text = url.includes("spanish") ? "SPANISH-AUDIO" : "ENGLISH-AUDIO";
+			return Promise.resolve({
+				status: 200,
+				headers: { "content-type": "audio/mpeg" },
+				arrayBuffer: new TextEncoder().encode(text).buffer,
+			}) as unknown as ReturnType<typeof requestUrl>;
+		});
+	});
+
+	it("fetches each episode's own audio from its stream URL — never another episode's", async () => {
+		const spanish = episode({
+			title: "Hola soy Sere",
+			streamUrl: "https://example.com/spanish.mp3",
+			podcastName: "Otro Podcast",
+		});
+		const english = episode({
+			title: "107. How could a PBS of the Internet...",
+			streamUrl: "https://example.com/english.mp3",
+			podcastName: "Reimagining the Internet",
+		});
+
+		const a = await getEpisodeAudioBuffer(spanish);
+		const b = await getEpisodeAudioBuffer(english);
+
+		// Each episode gets ITS OWN bytes — the wrong-episode collision is gone.
+		expect(decode(a.buffer)).toBe("SPANISH-AUDIO");
+		expect(decode(b.buffer)).toBe("ENGLISH-AUDIO");
+		expect(a.extension).toBe("mp3");
+		expect(b.extension).toBe("mp3");
+		expect(requestUrlMock).toHaveBeenCalledWith(
+			expect.objectContaining({ url: "https://example.com/spanish.mp3" }),
+		);
+		expect(requestUrlMock).toHaveBeenCalledWith(
+			expect.objectContaining({ url: "https://example.com/english.mp3" }),
+		);
+	});
+
+	it("reuses a registry-confirmed downloaded copy without re-fetching", async () => {
+		const ep = episode({
+			title: "Cached Episode",
+			streamUrl: "https://example.com/english.mp3",
+		});
+		seedFile("Podcasts/cached.mp3", "CACHED-CORRECT-AUDIO");
+		downloadedEpisodes.addEpisode(ep, "Podcasts/cached.mp3", 20);
+
+		const result = await getEpisodeAudioBuffer(ep);
+
+		expect(decode(result.buffer)).toBe("CACHED-CORRECT-AUDIO");
+		expect(result.extension).toBe("mp3");
+		expect(result.basename).toBe("cached");
+		expect(requestUrlMock).not.toHaveBeenCalled();
+	});
+
+	it("reuses the cached file when only the signed-CDN query token changed", async () => {
+		// Same audio file, rotated token: origin+path match, so the cache should
+		// still be used rather than re-downloading the (large) episode.
+		const downloaded = episode({
+			title: "Token Episode",
+			streamUrl: "https://cdn.example.com/ep.mp3?token=OLD&exp=1",
+		});
+		seedFile("Podcasts/token.mp3", "CACHED-CORRECT-AUDIO");
+		downloadedEpisodes.addEpisode(downloaded, "Podcasts/token.mp3", 20);
+
+		const current = episode({
+			title: "Token Episode",
+			streamUrl: "https://cdn.example.com/ep.mp3?token=NEW&exp=2",
+		});
+		const result = await getEpisodeAudioBuffer(current);
+
+		expect(decode(result.buffer)).toBe("CACHED-CORRECT-AUDIO");
+		expect(requestUrlMock).not.toHaveBeenCalled();
+	});
+
+	it("does not reuse a same-title sibling's download; fetches this episode's own audio", async () => {
+		// Same podcast + same title, different episode (different stream URL). The
+		// registry is keyed by podcastName+title, so getEpisode() returns the
+		// sibling's entry — reusing its file would transcribe the wrong audio.
+		const downloaded = episode({
+			title: "Episode",
+			streamUrl: "https://example.com/spanish.mp3",
+		});
+		seedFile("Podcasts/sibling.mp3", "SPANISH-AUDIO");
+		downloadedEpisodes.addEpisode(downloaded, "Podcasts/sibling.mp3", 13);
+
+		const current = episode({
+			title: "Episode",
+			streamUrl: "https://example.com/english.mp3",
+		});
+		const result = await getEpisodeAudioBuffer(current);
+
+		expect(decode(result.buffer)).toBe("ENGLISH-AUDIO");
+		expect(requestUrlMock).toHaveBeenCalledWith(
+			expect.objectContaining({ url: "https://example.com/english.mp3" }),
+		);
+	});
+
+	it("ignores a stale registry entry whose file no longer exists and fetches fresh", async () => {
+		const ep = episode({
+			title: "Stale Episode",
+			streamUrl: "https://example.com/english.mp3",
+		});
+		// Registry points at a file that is not in the vault.
+		downloadedEpisodes.addEpisode(ep, "Podcasts/missing.mp3", 20);
+
+		const result = await getEpisodeAudioBuffer(ep);
+
+		expect(decode(result.buffer)).toBe("ENGLISH-AUDIO");
+		expect(requestUrlMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("ignores a wrong-episode file at a colliding path and fetches the right audio", async () => {
+		// Direct reproduction of issue #107: a different episode's audio already
+		// lives at the old collidable download-path location, and this episode has
+		// no registry entry. The old code returned the colliding file's bytes; the
+		// new code must fetch this episode's own audio instead.
+		seedFile("Downloads.mp3", "WRONG-EPISODE-AUDIO");
+		const ep = episode({
+			title: "Right Episode",
+			streamUrl: "https://example.com/english.mp3",
+		});
+
+		const result = await getEpisodeAudioBuffer(ep);
+
+		expect(decode(result.buffer)).toBe("ENGLISH-AUDIO");
+		expect(decode(result.buffer)).not.toBe("WRONG-EPISODE-AUDIO");
+		expect(requestUrlMock).toHaveBeenCalledTimes(1);
+	});
+
+	it("throws a clear error when the stream returns non-audio content", async () => {
+		requestUrlMock.mockImplementation(
+			() =>
+				Promise.resolve({
+					status: 200,
+					headers: { "content-type": "text/html" },
+					arrayBuffer: new TextEncoder().encode("<html>login required</html>")
+						.buffer,
+				}) as unknown as ReturnType<typeof requestUrl>,
+		);
+		const ep = episode({
+			title: "Private Episode",
+			streamUrl: "https://example.com/private-feed-token",
+		});
+
+		await expect(getEpisodeAudioBuffer(ep)).rejects.toThrow(/not audio/i);
+	});
+
+	it("reads local-file episodes from disk by their resolved path", async () => {
+		const local = episode({
+			title: "Local Recording",
+			podcastName: "local file",
+			description: "",
+			content: "",
+			streamUrl: "",
+			url: "Local/recording.m4a",
+			filePath: "Local/recording.m4a",
+		} as Partial<LocalEpisode>) as LocalEpisode;
+		seedFile("Local/recording.m4a", "LOCAL-AUDIO");
+
+		const result = await getEpisodeAudioBuffer(local);
+
+		expect(decode(result.buffer)).toBe("LOCAL-AUDIO");
+		expect(result.extension).toBe("m4a");
+		expect(result.basename).toBe("recording");
+		expect(requestUrlMock).not.toHaveBeenCalled();
+	});
+});

src/downloadEpisode.ts

@@ -1,6 +1,9 @@
 import { Notice, TFile, requestUrl } from "obsidian";
 import { downloadedEpisodes } from "./store";
-import { DownloadPathTemplateEngine } from "./TemplateEngine";
+import {
+	DownloadPathTemplateEngine,
+	replaceIllegalFileNameCharactersInString,
+} from "./TemplateEngine";
 import type { Episode } from "./types/Episode";
 import type { LocalEpisode } from "./types/LocalEpisode";
 import { encodeUrlForRequest } from "./utility/encodeUrlForRequest";
@@ -265,6 +268,14 @@ function inferFileExtensionFromDownload(
 	return getExtensionFromContentType(contentType);
 }
 
+/**
+ * UNUSED IN PRODUCTION — kept only for the #178 tests. Do NOT use this for
+ * transcription: it derives the on-disk path from the download-path template and
+ * reuses any file already there without confirming episode identity, which is
+ * the exact collision behind issue #107. Use {@link getEpisodeAudioBuffer} (for
+ * transcription) or {@link downloadEpisodeWithNotice} (for the Download command)
+ * instead. Candidate for removal in a follow-up.
+ */
 export async function downloadEpisode(
 	episode: Episode,
 	downloadPathTemplate: string,
@@ -334,6 +345,115 @@ async function getFileExtension(url: string): Promise<string> {
 	return "mp3";
 }
 
+/**
+ * Resolves the audio bytes for an episode for transcription.
+ *
+ * The returned bytes always belong to the given episode, regardless of the
+ * user's download-path template. This is the fix for issue #107: transcription
+ * previously went through downloadEpisode(), which derived an on-disk path from
+ * the download-path template and reused whatever file already lived there, so
+ * episodes that mapped to the same (non-unique) path — e.g. the default empty
+ * path, or any path without `{{title}}` — were transcribed using a different
+ * episode's audio.
+ *
+ * Resolution order:
+ * 1. Local files already resolve to a unique, episode-specific path on disk.
+ * 2. An already-downloaded copy is reused only when the downloaded-episodes
+ *    registry (keyed by the episode, not a collidable path) confirms the file
+ *    belongs to THIS episode — preserving the cache without the collision risk.
+ * 3. Otherwise the episode's own stream URL is fetched into memory. Nothing is
+ *    written to the vault, so the audio can never collide with another episode.
+ */
+export async function getEpisodeAudioBuffer(
+	episode: Episode,
+): Promise<{ buffer: ArrayBuffer; extension: string; basename: string }> {
+	if (isLocalFile(episode)) {
+		const localFilePath = resolveLocalEpisodeFilePath(episode);
+		if (!localFilePath) {
+			throw new Error(
+				`Unable to locate the local audio file for "${episode.title}". Try playing the file again.`,
+			);
+		}
+
+		return readVaultAudio(localFilePath);
+	}
+
+	// Reuse a previously downloaded file only when the registry entry is the SAME
+	// episode. The registry is keyed by podcastName+title, which two distinct
+	// episodes can share (re-releases, placeholder titles), so also require the
+	// stream source to match before trusting the cached bytes. Comparison is by
+	// origin+path so a rotated signed-CDN query token (?token=...) still hits the
+	// cache; a genuinely different episode has a different path and falls through
+	// to a fresh fetch — correct, just not cached.
+	const registered = downloadedEpisodes.getEpisode(episode);
+	if (
+		registered?.filePath &&
+		isSameAudioSource(registered.streamUrl, episode.streamUrl)
+	) {
+		const existingFile = app.vault.getAbstractFileByPath(registered.filePath);
+		if (existingFile instanceof TFile) {
+			return readVaultAudio(registered.filePath);
+		}
+	}
+
+	try {
+		const { data, contentType } = await downloadFile(episode.streamUrl);
+		const inferredExtension = inferFileExtensionFromDownload(
+			episode,
+			data,
+			contentType,
+		);
+		const normalizedType = contentType.toLowerCase();
+		const typeAppearsAudio =
+			normalizedType === "" || normalizedType.includes("audio");
+		if (!typeAppearsAudio && !inferredExtension) {
+			throw new Error(
+				`The downloaded file is not audio (received "${contentType}"). The episode may be unavailable or require re-authentication.`,
+			);
+		}
+
+		return {
+			buffer: data,
+			extension: inferredExtension ?? "mp3",
+			basename:
+				replaceIllegalFileNameCharactersInString(episode.title) || "episode",
+		};
+	} catch (error: unknown) {
+		throw new Error(
+			`Failed to fetch ${episode.title}: ${getErrorMessage(error)}`,
+		);
+	}
+}
+
+/**
+ * Whether two stream URLs point at the same audio file. Compares origin+path so
+ * rotating query strings (signed-CDN tokens, cache-busters) don't count as a
+ * different source. Falls back to exact equality for non-absolute/odd URLs.
+ */
+function isSameAudioSource(a: string, b: string): boolean {
+	if (a === b) return true;
+	if (!a || !b) return false;
+	try {
+		const ua = new URL(a);
+		const ub = new URL(b);
+		return ua.origin === ub.origin && ua.pathname === ub.pathname;
+	} catch {
+		return false;
+	}
+}
+
+async function readVaultAudio(
+	filePath: string,
+): Promise<{ buffer: ArrayBuffer; extension: string; basename: string }> {
+	const file = app.vault.getAbstractFileByPath(filePath);
+	if (!(file instanceof TFile)) {
+		throw new Error(`Unable to read the audio file at "${filePath}".`);
+	}
+
+	const buffer = await app.vault.readBinary(file);
+	return { buffer, extension: file.extension, basename: file.basename };
+}
+
 interface AudioSignature {
 	signature: number[];
 	mask?: number[];