From 4427d7355a8e16e0d68c8c306b3e95e016d0513d Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sat, 24 Oct 2026 16:22:16 +0200
Subject: [PATCH 1/4] feat(chapters): read embedded ID3 chapters from MP3
 episodes

---
 src/TemplateEngine.ts               |   4 +-
 src/createPodcastNote.test.ts       |   2 +-
 src/createPodcastNote.ts            |   7 +-
 src/main.ts                         |   4 +-
 src/player/mediaSession.test.ts     |  14 +-
 src/player/mediaSession.ts          |  13 +-
 src/types/Episode.ts                |   2 +-
 src/ui/PodcastView/Player.svelte    |  21 ++-
 src/ui/PodcastView/Player.test.ts   |  15 ++-
 src/ui/PodcastView/chapters.test.ts |  34 +++--
 src/ui/PodcastView/chapters.ts      |  16 +--
 src/utility/fetchChapters.test.ts   |  30 ++++-
 src/utility/fetchChapters.ts        |  26 +++-
 src/utility/id3Chapters.test.ts     | 193 ++++++++++++++++++++++++++++
 src/utility/id3Chapters.ts          | 115 +++++++++++++++++
 15 files changed, 432 insertions(+), 64 deletions(-)
 create mode 100644 src/utility/id3Chapters.test.ts
 create mode 100644 src/utility/id3Chapters.ts

diff --git a/src/TemplateEngine.ts b/src/TemplateEngine.ts
index 5d522c86..43e7e5b3 100644
--- a/src/TemplateEngine.ts
+++ b/src/TemplateEngine.ts
@@ -347,8 +347,8 @@ export function NoteTemplateEngine(
 	addTag("url", episodeUrl);
 	addEpisodeDateTags(addTag, episode);
 	addTag("duration", durationTag(episode));
-	// Podcasting 2.0 chapters, fetched before note creation when the template
-	// asks for them. Empty when the feed has no chapters URL or fetching fails.
+	// The chapters, fetched before note creation when the template
+	// asks for them. Empty when the episode has none or fetching fails.
 	addTag("chapters", (prependToLines?: string) =>
 		formatTemplateChapters(chapters, prependToLines),
 	);
diff --git a/src/createPodcastNote.test.ts b/src/createPodcastNote.test.ts
index 5d6bb07c..8b6a4e11 100644
--- a/src/createPodcastNote.test.ts
+++ b/src/createPodcastNote.test.ts
@@ -84,7 +84,7 @@ describe("createPodcastNote chapters template support (#47)", () => {
 
 		await createPodcastNote(episode);
 
-		expect(mockFetchChapters).toHaveBeenCalledWith("https://example.com/chapters.json");
+		expect(mockFetchChapters).toHaveBeenCalledWith(episode);
 		expect(createdFiles[0]).toMatchObject({
 			path: "PodNotes/Chaptered Episode.md",
 			data: "# Chaptered Episode\n\n- 0:00 Intro\n- 1:05 Deep Dive",
diff --git a/src/createPodcastNote.ts b/src/createPodcastNote.ts
index 4a56e862..371a2658 100644
--- a/src/createPodcastNote.ts
+++ b/src/createPodcastNote.ts
@@ -118,11 +118,8 @@ async function getTemplateChapters(
 	template: string,
 	episode: Episode,
 ): Promise<Chapter[] | undefined> {
-	if (!episode.chaptersUrl || !templateHasTag(template, "chapters")) {
-		return undefined;
-	}
-
-	return await fetchChapters(episode.chaptersUrl);
+	if (!templateHasTag(template, "chapters")) return undefined;
+	return (await fetchChapters(episode)) ?? [];
 }
 
 export function getPodcastNote(episode: Episode): TFile | null {
diff --git a/src/main.ts b/src/main.ts
index 30e88773..b8179770 100644
--- a/src/main.ts
+++ b/src/main.ts
@@ -18,6 +18,7 @@ import type { IAPI } from "src/API/IAPI";
 import { VIEW_TYPE } from "src/constants";
 import { PodNotesSettingsTab } from "src/ui/settings/PodNotesSettingsTab";
 import { MainView } from "src/ui/PodcastView";
+import { loadChapters } from "src/ui/PodcastView/chapters";
 import { Navigation } from "src/ui/PodcastView/Navigation";
 import { dismissUndoNotices } from "src/ui/undoNotice";
 import { removePreviousStyles } from "src/ui/removePreviousStyles";
@@ -57,7 +58,6 @@ import { FeedUrlRepository } from "./services/FeedUrlRepository";
 import { privateFeedAddresses, protectPrivateFeeds, resolveFeedUrl } from "./services/privateFeeds";
 import { redactPrivateFeedAddresses } from "./utility/privateFeedUrl";
 import { FeedRepository, loadFeed } from "./services/FeedRepository";
-import { fetchChapters } from "./utility/fetchChapters";
 import { onlineStatus } from "./services/online";
 
 type Closing = "window-unloading" | "obsidian-closing";
@@ -235,7 +235,7 @@ export default class PodNotes extends Plugin implements IPodNotes {
 				captureTimestamp: () => void this.capture.timestamp(),
 				skipBackward: () => this.api.skipBackward(),
 				skipForward: () => this.api.skipForward(),
-				chapters: fetchChapters,
+				chapters: loadChapters,
 			}),
 		);
 		this.isReady = true;
diff --git a/src/player/mediaSession.test.ts b/src/player/mediaSession.test.ts
index 106d8b7f..9bf4aa71 100644
--- a/src/player/mediaSession.test.ts
+++ b/src/player/mediaSession.test.ts
@@ -85,7 +85,7 @@ class FakeMediaSession {
 function setup({
 	mediaSession = new FakeMediaSession() as FakeMediaSession | null,
 	Metadata = FakeMetadata as typeof FakeMetadata | null,
-	chapters = (_url: string): Promise<Chapter[]> => Promise.resolve([]),
+	chapters = (_episode: Episode): Promise<Chapter[]> => Promise.resolve([]),
 } = {}) {
 	const doc = new FakeDocument();
 	const host = {
@@ -445,7 +445,7 @@ describe("headset mapping", () => {
 		});
 
 		test("next and previous chapter seek to the episode's chapter starts", async () => {
-			const chapters = vi.fn(() => Promise.resolve(CHAPTERS));
+			const chapters = vi.fn((_episode: Episode) => Promise.resolve(CHAPTERS));
 			const context = setup({ chapters });
 			context.host.settings.headsetPreviousTrack = "previousChapter";
 			context.host.settings.headsetNextTrack = "nextChapter";
@@ -469,7 +469,9 @@ describe("headset mapping", () => {
 			context.session.act("nexttrack");
 			await flush();
 			expect(context.media().currentTime).toBe(130);
-			expect(chapters.mock.calls).toEqual([[WITH_CHAPTERS.chaptersUrl]]);
+			expect(chapters.mock.calls.map(([episode]) => episode.chaptersUrl)).toEqual([
+				WITH_CHAPTERS.chaptersUrl,
+			]);
 		});
 
 		test("chapters that arrive after the episode changed move nothing", async () => {
@@ -493,7 +495,7 @@ describe("headset mapping", () => {
 			"%s with no chapters is a no-op and retries",
 			async (action) => {
 				const chapters = vi
-					.fn<(url: string) => Promise<Chapter[]>>()
+					.fn<(episode: Episode) => Promise<Chapter[]>>()
 					.mockRejectedValueOnce(new Error("offline"))
 					.mockResolvedValueOnce([])
 					.mockResolvedValue(CHAPTERS);
@@ -511,8 +513,8 @@ describe("headset mapping", () => {
 				playing(context, 30, 3600, B);
 				context.session.act(action);
 				await flush();
-				expect(chapters).toHaveBeenCalledTimes(3);
-				expect(context.media().currentTime).toBe(30);
+				expect(chapters).toHaveBeenCalledTimes(4);
+				expect(chapters).toHaveBeenLastCalledWith(expect.objectContaining({ title: "B" }));
 			},
 		);
 
diff --git a/src/player/mediaSession.ts b/src/player/mediaSession.ts
index 0427c2e6..4409ff9d 100644
--- a/src/player/mediaSession.ts
+++ b/src/player/mediaSession.ts
@@ -4,6 +4,7 @@ import type { Episode } from "src/types/Episode";
 import type { NextTrackAction, PreviousTrackAction } from "src/types/Headset";
 import type { IPodNotesSettings } from "src/types/IPodNotesSettings";
 import { getEpisodeKey } from "src/utility/episodeKey";
+import { chaptersKey } from "src/utility/fetchChapters";
 import {
 	isPlaying,
 	type PlayerController,
@@ -18,7 +19,7 @@ interface MediaSessionHost {
 	captureTimestamp(): void;
 	skipBackward(): void;
 	skipForward(): void;
-	chapters(url: string): Promise<Chapter[]>;
+	chapters(episode: Episode): Promise<Chapter[]>;
 }
 
 const CHAPTER_RESTART_S = 2;
@@ -81,15 +82,15 @@ export function bindMediaSession(
 	const { mediaSession, MediaMetadata } = host;
 	let episodeKey = "";
 	let activation = 0;
-	let chapters: { url: string; loading: Promise<Chapter[]> } | undefined;
+	let chapters: { key: string; loading: Promise<Chapter[]> } | undefined;
 
 	async function seekChapter(direction: 1 | -1): Promise<void> {
 		const { episode } = get(player.state);
-		const url = episode?.chaptersUrl;
-		if (!url) return;
+		if (!episode) return;
 		const requestedActivation = activation;
-		if (chapters?.url !== url) {
-			chapters = { url, loading: host.chapters(url).catch(() => []) };
+		const key = chaptersKey(episode);
+		if (chapters?.key !== key) {
+			chapters = { key, loading: host.chapters(episode).catch(() => []) };
 		}
 		const asked = chapters;
 		const loaded = await asked.loading;
diff --git a/src/types/Episode.ts b/src/types/Episode.ts
index bcc6a1f0..e3e1f7e8 100644
--- a/src/types/Episode.ts
+++ b/src/types/Episode.ts
@@ -22,7 +22,7 @@ export interface Episode {
 	episodeNumber?: number;
 	/** Episode duration in whole seconds, from `<itunes:duration>` where present. */
 	duration?: number;
-	/** URL to the podcast:chapters JSON file */
+	/** URL to the podcast:chapters JSON file. Without one, chapters come from the media's ID3 tag. */
 	chaptersUrl?: string;
 	/** Media element type used to play the enclosure/local file. */
 	mediaType?: EpisodeMediaType;
diff --git a/src/ui/PodcastView/Player.svelte b/src/ui/PodcastView/Player.svelte
index 80c5f78d..343dcb9f 100644
--- a/src/ui/PodcastView/Player.svelte
+++ b/src/ui/PodcastView/Player.svelte
@@ -1,5 +1,5 @@
 <script lang="ts">
-	import { tick } from "svelte";
+	import { tick, untrack } from "svelte";
 	import type { Chapter } from "src/types/Chapter";
 	import type { Episode } from "src/types/Episode";
 	import { icon } from "../obsidian/icon";
@@ -63,16 +63,23 @@
 		return wide ? panels.find((kind) => kind !== "transcript") : undefined;
 	});
 	const chaptersUrl = $derived(episode.chaptersUrl);
+	const streamUrl = $derived(episode.streamUrl);
+	// Chapters without a chapters file come from the media, which a restored player has not loaded.
+	const chaptersReady = $derived(!!chaptersUrl || $playerState.status !== "restored");
 
 	$effect.pre(() => {
-		const url = chaptersUrl;
+		void [chaptersUrl, streamUrl];
 		// A choice of Chapters belongs to the episode it was made on.
-		panel = undefined;
-		const cached = url && cachedChapters(url);
-		chapters = cached || [];
-		if (!url || cached) return;
+		if (untrack(() => panel) === "chapters") panel = undefined;
+	});
+
+	$effect.pre(() => {
+		const source = { chaptersUrl, streamUrl };
+		const cached = cachedChapters(source);
+		chapters = cached ?? [];
+		if (cached || !chaptersReady) return;
 		let latest = true;
-		void loadChapters(url).then((loaded) => latest && (chapters = loaded));
+		void loadChapters(source).then((loaded) => latest && (chapters = loaded));
 		return () => (latest = false);
 	});
 
diff --git a/src/ui/PodcastView/Player.test.ts b/src/ui/PodcastView/Player.test.ts
index 9dd7bd12..61e74e52 100644
--- a/src/ui/PodcastView/Player.test.ts
+++ b/src/ui/PodcastView/Player.test.ts
@@ -23,12 +23,15 @@ import {
 } from "../../../tests/mocks/services";
 import PodcastView from "./PodcastView.svelte";
 
-vi.mock("src/utility/fetchChapters", () => ({
-	fetchChapters: async () =>
-		["Intro", "Memory palaces", "Questions"].map((title, index) => ({
-			title,
-			startTime: index * 600,
-		})),
+vi.mock("src/utility/fetchChapters", async (importOriginal) => ({
+	...(await importOriginal<typeof import("src/utility/fetchChapters")>()),
+	fetchChapters: async ({ chaptersUrl }: Episode) =>
+		chaptersUrl
+			? ["Intro", "Memory palaces", "Questions"].map((title, index) => ({
+					title,
+					startTime: index * 600,
+				}))
+			: [],
 }));
 
 const episode: Episode = {
diff --git a/src/ui/PodcastView/chapters.test.ts b/src/ui/PodcastView/chapters.test.ts
index ab953691..9956a620 100644
--- a/src/ui/PodcastView/chapters.test.ts
+++ b/src/ui/PodcastView/chapters.test.ts
@@ -2,7 +2,10 @@ import { describe, expect, test, vi } from "vitest";
 import { fetchChapters } from "src/utility/fetchChapters";
 import { cachedChapters, chapterAt, loadChapters, segmentsOf } from "./chapters";
 
-vi.mock("src/utility/fetchChapters", () => ({ fetchChapters: vi.fn() }));
+vi.mock("src/utility/fetchChapters", async (importOriginal) => ({
+	...(await importOriginal<typeof import("src/utility/fetchChapters")>()),
+	fetchChapters: vi.fn(),
+}));
 
 const chapters = [0, 60, 120].map((startTime) => ({ startTime, title: `At ${startTime}` }));
 
@@ -37,21 +40,32 @@ describe("chapters", () => {
 	});
 
 	test("a load that failed, as offline, fetches again the next time", async () => {
-		const url = "https://pod.test/chapters.json";
-		vi.mocked(fetchChapters).mockResolvedValueOnce([]).mockResolvedValueOnce(chapters);
+		const episode = { chaptersUrl: "https://pod.test/chapters.json", streamUrl: "" };
+		vi.mocked(fetchChapters).mockResolvedValueOnce(undefined).mockResolvedValueOnce(chapters);
 
-		expect(await loadChapters(url)).toEqual([]);
-		expect(cachedChapters(url)).toBeUndefined();
-		expect(await loadChapters(url)).toEqual(chapters);
+		expect(await loadChapters(episode)).toEqual([]);
+		expect(cachedChapters(episode)).toBeUndefined();
+		expect(await loadChapters(episode)).toEqual(chapters);
 
 		expect(fetchChapters).toHaveBeenCalledTimes(2);
-		expect(cachedChapters(url)).toEqual(chapters);
-		expect(cachedChapters("https://pod.test/other.json")).toBeUndefined();
+		expect(cachedChapters(episode)).toEqual(chapters);
+		expect(
+			cachedChapters({ ...episode, chaptersUrl: "https://pod.test/other.json" }),
+		).toBeUndefined();
+	});
+
+	test("media found to have no chapters is not asked again", async () => {
+		const episode = { streamUrl: "https://pod.test/plain.mp3" };
+		vi.mocked(fetchChapters).mockClear().mockResolvedValueOnce([]);
+
+		expect(await loadChapters(episode)).toEqual([]);
+		expect(cachedChapters(episode)).toEqual([]);
+		expect(fetchChapters).toHaveBeenCalledOnce();
 	});
 
 	test("each episode keeps the chapters it loaded, whichever load finishes first", async () => {
-		const earlier = "https://pod.test/earlier.json";
-		const latest = "https://pod.test/latest.json";
+		const earlier = { chaptersUrl: "https://pod.test/earlier.json", streamUrl: "" };
+		const latest = { streamUrl: "https://pod.test/latest.mp3" };
 		let finishEarlier: (loaded: typeof chapters) => void = () => {};
 		vi.mocked(fetchChapters)
 			.mockReturnValueOnce(new Promise((resolve) => (finishEarlier = resolve)))
diff --git a/src/ui/PodcastView/chapters.ts b/src/ui/PodcastView/chapters.ts
index 66a6e433..02bdb142 100644
--- a/src/ui/PodcastView/chapters.ts
+++ b/src/ui/PodcastView/chapters.ts
@@ -1,5 +1,5 @@
 import type { Chapter } from "src/types/Chapter";
-import { fetchChapters } from "src/utility/fetchChapters";
+import { chaptersKey, fetchChapters, type ChaptersSource } from "src/utility/fetchChapters";
 
 /** The chapter under way at `time`: the last to start at or before it. -1 before the first. */
 export function chapterAt(chapters: readonly Chapter[], time: number): number {
@@ -22,13 +22,13 @@ export function segmentsOf(chapters: readonly Chapter[], duration: number): [num
 
 const loaded = new Map<string, Chapter[]>();
 
-export function cachedChapters(url: string): Chapter[] | undefined {
-	return loaded.get(url);
+export function cachedChapters(episode: ChaptersSource): Chapter[] | undefined {
+	return loaded.get(chaptersKey(episode));
 }
 
-/** The chapters at `url`. A failed load, as offline, is not kept, so the next one fetches again. */
-export async function loadChapters(url: string): Promise<Chapter[]> {
-	const chapters = await fetchChapters(url);
-	if (chapters.length > 0) loaded.set(url, chapters);
-	return chapters;
+/** The episode's chapters. A failed load, as offline, is not kept, so the next one fetches again. */
+export async function loadChapters(episode: ChaptersSource): Promise<Chapter[]> {
+	const chapters = await fetchChapters(episode);
+	if (chapters) loaded.set(chaptersKey(episode), chapters);
+	return chapters ?? [];
 }
diff --git a/src/utility/fetchChapters.test.ts b/src/utility/fetchChapters.test.ts
index bee04e70..ded940ee 100644
--- a/src/utility/fetchChapters.test.ts
+++ b/src/utility/fetchChapters.test.ts
@@ -2,14 +2,22 @@ import { beforeEach, describe, expect, it, vi } from "vitest";
 import { fetchChapters } from "./fetchChapters";
 
 const mockFetchTextWithTimeout = vi.hoisted(() => vi.fn());
+const mockFetchId3Chapters = vi.hoisted(() => vi.fn());
 
 vi.mock("./networkRequest", () => ({
 	fetchTextWithTimeout: mockFetchTextWithTimeout,
 }));
+vi.mock("./id3Chapters", () => ({ fetchId3Chapters: mockFetchId3Chapters }));
+
+const json = (chaptersUrl: string) => ({
+	chaptersUrl,
+	streamUrl: "https://example.com/episode.mp3",
+});
 
 describe("fetchChapters", () => {
 	beforeEach(() => {
 		mockFetchTextWithTimeout.mockReset();
+		mockFetchId3Chapters.mockReset();
 	});
 
 	it("normalizes malformed chapter entries instead of returning raw JSON", async () => {
@@ -27,7 +35,7 @@ describe("fetchChapters", () => {
 			}),
 		);
 
-		await expect(fetchChapters("https://example.com/chapters.json")).resolves.toEqual([
+		await expect(fetchChapters(json("https://example.com/chapters.json"))).resolves.toEqual([
 			{ startTime: 0, title: "Intro" },
 			{ startTime: 35, title: "" },
 			{ startTime: 65, title: "Deep Dive" },
@@ -44,13 +52,29 @@ describe("fetchChapters", () => {
 			new Error("Network request target is not allowed."),
 		);
 
-		await expect(fetchChapters("file:///tmp/chapters.json")).resolves.toEqual([]);
+		await expect(fetchChapters(json("file:///tmp/chapters.json"))).resolves.toBeUndefined();
 		expect(mockFetchTextWithTimeout).toHaveBeenCalledOnce();
 	});
 
 	it("ignores oversized chapter payloads", async () => {
 		mockFetchTextWithTimeout.mockResolvedValue(" ".repeat(1_000_001));
 
-		await expect(fetchChapters("https://example.com/chapters.json")).resolves.toEqual([]);
+		await expect(fetchChapters(json("https://example.com/chapters.json"))).resolves.toEqual([]);
+	});
+
+	it("reads the media's ID3 chapters when the feed names no chapters file", async () => {
+		const id3 = [{ startTime: 0, title: "Intro" }];
+		mockFetchId3Chapters.mockResolvedValue(id3);
+
+		await expect(
+			fetchChapters({ streamUrl: "https://example.com/episode.mp3" }),
+		).resolves.toEqual(id3);
+		await expect(
+			fetchChapters({ streamUrl: "app://local/vault/Episode.mp3" }),
+		).resolves.toEqual([]);
+		expect(mockFetchId3Chapters).toHaveBeenCalledExactlyOnceWith(
+			"https://example.com/episode.mp3",
+		);
+		expect(mockFetchTextWithTimeout).not.toHaveBeenCalled();
 	});
 });
diff --git a/src/utility/fetchChapters.ts b/src/utility/fetchChapters.ts
index bc194ca6..be087f64 100644
--- a/src/utility/fetchChapters.ts
+++ b/src/utility/fetchChapters.ts
@@ -1,4 +1,7 @@
 import type { Chapter, ChaptersData } from "src/types/Chapter";
+import type { Episode } from "src/types/Episode";
+import { isFetchableUrl } from "./assertFetchableUrl";
+import { fetchId3Chapters } from "./id3Chapters";
 import { fetchTextWithTimeout } from "./networkRequest";
 import { normalizeChapters } from "./normalizeChapters";
 
@@ -6,15 +9,24 @@ const MAX_CHAPTERS_RESPONSE_CHARS = 1_000_000;
 const MAX_CHAPTERS_RESPONSE_BYTES = MAX_CHAPTERS_RESPONSE_CHARS * 4;
 const CHAPTERS_REQUEST_TIMEOUT_MS = 10_000;
 
+export type ChaptersSource = Pick<Episode, "chaptersUrl" | "streamUrl">;
+
+/** Where the chapters come from: the chapters file, else the media they are read from. */
+export function chaptersKey(episode: ChaptersSource): string {
+	return episode.chaptersUrl || episode.streamUrl;
+}
+
 /**
- * Fetches and parses podcast chapters from a chapters URL.
- * Returns an empty array if the URL is invalid or the request fails.
+ * An episode's chapters: its Podcasting 2.0 chapters file, else the ID3 chapters of its
+ * media. Undefined when a request failed, as offline, so a later call tries again.
  */
-export async function fetchChapters(chaptersUrl: string): Promise<Chapter[]> {
-	if (!chaptersUrl) {
-		return [];
-	}
+export async function fetchChapters(episode: ChaptersSource): Promise<Chapter[] | undefined> {
+	if (episode.chaptersUrl) return fetchJsonChapters(episode.chaptersUrl);
+	if (!isFetchableUrl(episode.streamUrl)) return [];
+	return fetchId3Chapters(episode.streamUrl);
+}
 
+async function fetchJsonChapters(chaptersUrl: string): Promise<Chapter[] | undefined> {
 	try {
 		const responseText = await fetchTextWithTimeout(chaptersUrl, {
 			timeoutMs: CHAPTERS_REQUEST_TIMEOUT_MS,
@@ -34,6 +46,6 @@ export async function fetchChapters(chaptersUrl: string): Promise<Chapter[]> {
 		return normalizeChapters(data.chapters);
 	} catch {
 		console.warn("Failed to fetch chapters.");
-		return [];
+		return undefined;
 	}
 }
diff --git a/src/utility/id3Chapters.test.ts b/src/utility/id3Chapters.test.ts
new file mode 100644
index 00000000..4d7d30f0
--- /dev/null
+++ b/src/utility/id3Chapters.test.ts
@@ -0,0 +1,193 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { fetchId3Chapters, parseId3Chapters } from "./id3Chapters";
+import { NetworkError, TimeoutError } from "./networkRequest";
+
+const mockRequest = vi.hoisted(() => vi.fn());
+
+vi.mock("./networkRequest", async (importOriginal) => ({
+	...(await importOriginal<typeof import("./networkRequest")>()),
+	requestWithTimeout: mockRequest,
+}));
+
+type Version = 3 | 4;
+
+const latin1 = (text: string) => [0, ...Buffer.from(`${text}\0`, "latin1")];
+const utf16le = (text: string) => [1, 0xff, 0xfe, ...Buffer.from(`${text}\0`, "utf16le")];
+const utf16be = (text: string) => [1, 0xfe, 0xff, ...Buffer.from(`${text}\0`, "utf16le").swap16()];
+const utf8 = (text: string) => [3, ...Buffer.from(text, "utf8")];
+
+function size(value: number, version: Version): number[] {
+	return version === 4
+		? [21, 14, 7, 0].map((shift) => (value >> shift) & 0x7f)
+		: [24, 16, 8, 0].map((shift) => (value >>> shift) & 0xff);
+}
+
+function frame(id: string, body: number[], version: Version, formatFlags = 0): number[] {
+	return [...Buffer.from(id, "latin1"), ...size(body.length, version), 0, formatFlags, ...body];
+}
+
+function chap(id: string, startMs: number, subframes: number[], version: Version = 3): number[] {
+	const times = [startMs, startMs + 1000, 0xffffffff, 0xffffffff].flatMap((value) =>
+		size(value, 3),
+	);
+	return frame("CHAP", [...Buffer.from(`${id}\0`, "latin1"), ...times, ...subframes], version);
+}
+
+function tag(frames: number[], { version = 3 as Version, flags = 0, padding = 32 } = {}) {
+	const body = [...frames, ...Array.from({ length: padding }, () => 0)];
+	return Uint8Array.from([
+		...Buffer.from("ID3"),
+		version,
+		0,
+		flags,
+		...size(body.length, 4),
+		...body,
+	]);
+}
+
+describe("parseId3Chapters", () => {
+	it("reads each CHAP's start and title in start order, past the CTOC and chapter art", () => {
+		const v = 3;
+		const chapters = parseId3Chapters(
+			tag([
+				...frame("TIT2", latin1("Efer 756"), v),
+				...frame("CTOC", [...Buffer.from("TOC\0"), 3, 2, ...Buffer.from("b\0a\0")], v),
+				...chap("b", 838_381, [
+					...frame("TIT2", latin1("Betty León [Voces de Ciencia]"), v),
+					...frame(
+						"APIC",
+						Array.from({ length: 500 }, () => 0xff),
+						v,
+					),
+				]),
+				...chap("a", 152_006, [
+					...frame(
+						"APIC",
+						Array.from({ length: 500 }, () => 0xff),
+						v,
+					),
+					...frame("TIT2", latin1("Coidar a pel en verán"), v),
+				]),
+			]),
+		);
+
+		expect(chapters).toEqual([
+			{ startTime: 152.006, title: "Coidar a pel en verán" },
+			{ startTime: 838.381, title: "Betty León [Voces de Ciencia]" },
+		]);
+	});
+
+	it("decodes UTF-16 with either byte order, and v2.4 UTF-8 with synchsafe sizes", () => {
+		expect(
+			parseId3Chapters(
+				tag([
+					...chap("chp0", 0, frame("TIT2", utf16le("🍕 Pizza"), 3)),
+					...chap("chp1", 60_000, frame("TIT2", utf16be("Follow-up"), 3)),
+				]),
+			),
+		).toEqual([
+			{ startTime: 0, title: "🍕 Pizza" },
+			{ startTime: 60, title: "Follow-up" },
+		]);
+
+		const long = "Ünïcode ".repeat(20).trim();
+		expect(
+			parseId3Chapters(
+				tag(chap("c", 5_000, frame("TIT2", utf8(long), 4), 4), { version: 4 }),
+			),
+		).toEqual([{ startTime: 5, title: long }]);
+	});
+
+	it("keeps an untitled chapter and leaves transformed frames unread", () => {
+		const v = 3;
+		expect(
+			parseId3Chapters(
+				tag([
+					...chap("a", 0, []),
+					...chap("b", 30_000, frame("TIT2", latin1("Compressed"), v, 0x80)),
+					...frame("CHAP", [...Buffer.from("c\0"), 0, 0], v, 0x40),
+				]),
+			),
+		).toEqual([
+			{ startTime: 0, title: "" },
+			{ startTime: 30, title: "" },
+		]);
+	});
+
+	it("skips an extended header", () => {
+		const extended = [0, 0, 0, 6, 0, 0, 0, 0, 0, 0];
+		const chapter = chap("a", 1_000, frame("TIT2", latin1("After"), 3));
+
+		expect(parseId3Chapters(tag([...extended, ...chapter], { flags: 0x40 }))).toEqual([
+			{ startTime: 1, title: "After" },
+		]);
+	});
+
+	it("reads nothing from an unsynchronised, truncated, or missing tag", () => {
+		const chapter = chap("a", 0, frame("TIT2", latin1("Intro"), 3));
+
+		expect(parseId3Chapters(tag(chapter, { flags: 0x80 }))).toEqual([]);
+		expect(parseId3Chapters(tag(chapter).subarray(0, 30))).toEqual([]);
+		expect(parseId3Chapters(Uint8Array.from(Buffer.from("RIFF....WAVEfmt ")))).toEqual([]);
+	});
+});
+
+describe("fetchId3Chapters", () => {
+	const url = "https://pod.test/episode.mp3";
+	const ranged = (bytes: Uint8Array) => ({
+		status: 206,
+		headers: {},
+		arrayBuffer: bytes.slice().buffer,
+	});
+
+	beforeEach(() => mockRequest.mockReset());
+
+	it("reads a small tag with one Range request", async () => {
+		const small = tag(chap("a", 0, frame("TIT2", latin1("Intro"), 3)));
+		mockRequest.mockResolvedValueOnce(ranged(small));
+
+		await expect(fetchId3Chapters(url)).resolves.toEqual([{ startTime: 0, title: "Intro" }]);
+		expect(mockRequest).toHaveBeenCalledExactlyOnceWith(url, {
+			headers: { Range: "bytes=0-65535" },
+			timeoutMs: 30_000,
+			maxResponseBytes: 65_536,
+			acceptedStatuses: [206],
+		});
+	});
+
+	it("asks for the rest of a larger tag and nothing past it", async () => {
+		const art = frame(
+			"APIC",
+			Array.from({ length: 100_000 }, () => 0xff),
+			3,
+		);
+		const large = tag([...art, ...chap("a", 90_000, frame("TIT2", latin1("Late"), 3))]);
+		mockRequest
+			.mockResolvedValueOnce(ranged(large.subarray(0, 65_536)))
+			.mockResolvedValueOnce(ranged(large.subarray(65_536)));
+
+		await expect(fetchId3Chapters(url)).resolves.toEqual([{ startTime: 90, title: "Late" }]);
+		expect(mockRequest.mock.calls[1][1]).toMatchObject({
+			headers: { Range: `bytes=65536-${large.length - 1}` },
+			maxResponseBytes: large.length - 65_536,
+		});
+	});
+
+	it("does not fetch a tag over 16 MB", async () => {
+		const header = Uint8Array.from([...Buffer.from("ID3"), 4, 0, 0, 0x08, 0, 0, 0]);
+		const first = new Uint8Array(65_536);
+		first.set(header);
+		mockRequest.mockResolvedValueOnce(ranged(first));
+
+		await expect(fetchId3Chapters(url)).resolves.toEqual([]);
+		expect(mockRequest).toHaveBeenCalledOnce();
+	});
+
+	it("tries again after a network failure, but not after a server that ignores Range", async () => {
+		mockRequest.mockRejectedValueOnce(new TimeoutError());
+		await expect(fetchId3Chapters(url)).resolves.toBeUndefined();
+
+		mockRequest.mockRejectedValueOnce(new NetworkError("unexpected-status", 200));
+		await expect(fetchId3Chapters(url)).resolves.toEqual([]);
+	});
+});
diff --git a/src/utility/id3Chapters.ts b/src/utility/id3Chapters.ts
new file mode 100644
index 00000000..4cb3154c
--- /dev/null
+++ b/src/utility/id3Chapters.ts
@@ -0,0 +1,115 @@
+import type { Chapter } from "src/types/Chapter";
+import { NetworkError, requestWithTimeout } from "./networkRequest";
+import { normalizeChapters } from "./normalizeChapters";
+
+const HEADER_BYTES = 10;
+const FIRST_REQUEST_BYTES = 64 * 1024;
+/** Chapter and cover art can make a tag several megabytes. A larger tag is not read. */
+const MAX_TAG_BYTES = 16 * 1024 * 1024;
+const REQUEST_TIMEOUT_MS = 30_000;
+const RETRYABLE: ReadonlySet<string> = new Set(["timeout", "transport-failure", "aborted"]);
+const TEXT_ENCODINGS = ["iso-8859-1", "utf-16le", "utf-16be", "utf-8"];
+
+/**
+ * The ID3 chapters at the start of the media at `url`, read with Range requests for the
+ * tag alone. Undefined when the network failed, so a later call tries again.
+ */
+export async function fetchId3Chapters(url: string): Promise<Chapter[] | undefined> {
+	try {
+		const first = await fetchBytes(url, 0, FIRST_REQUEST_BYTES);
+		const size = id3TagSize(first);
+		if (!size || size > MAX_TAG_BYTES) return [];
+		if (first.length >= size || first.length < FIRST_REQUEST_BYTES) {
+			return parseId3Chapters(first);
+		}
+		const tag = new Uint8Array(size);
+		tag.set(first);
+		tag.set(await fetchBytes(url, first.length, size), first.length);
+		return parseId3Chapters(tag);
+	} catch (error) {
+		// A server that ignores Range answers with the whole file, and asking again would too.
+		return error instanceof NetworkError && RETRYABLE.has(error.code) ? undefined : [];
+	}
+}
+
+async function fetchBytes(url: string, start: number, end: number): Promise<Uint8Array> {
+	const response = await requestWithTimeout(url, {
+		headers: { Range: `bytes=${start}-${end - 1}` },
+		timeoutMs: REQUEST_TIMEOUT_MS,
+		maxResponseBytes: end - start,
+		acceptedStatuses: [206],
+	});
+	return new Uint8Array(response.arrayBuffer);
+}
+
+/** The bytes of an ID3v2.3 or v2.4 tag from its header on, or undefined when `bytes` starts with none. */
+export function id3TagSize(bytes: Uint8Array): number | undefined {
+	if (bytes.length < HEADER_BYTES) return undefined;
+	const magic = String.fromCharCode(bytes[0], bytes[1], bytes[2]);
+	if (magic !== "ID3" || (bytes[3] !== 3 && bytes[3] !== 4)) return undefined;
+	const size = synchsafe(bytes, 6);
+	return size === undefined ? undefined : HEADER_BYTES + size;
+}
+
+/** The CHAP frames of an ID3v2.3 or v2.4 tag, `tag` holding it from its header on. */
+export function parseId3Chapters(tag: Uint8Array): Chapter[] {
+	const size = id3TagSize(tag);
+	if (!size || tag.length < size) return [];
+	const version = tag[3];
+	const flags = tag[5];
+	// Podcast tags are not unsynchronised, and undoing it would rewrite every frame.
+	if (flags & 0x80) return [];
+	let start = HEADER_BYTES;
+	if (flags & 0x40) {
+		const extended = version === 4 ? synchsafe(tag, start) : uint32(tag, start) + 4;
+		if (extended === undefined) return [];
+		start += extended;
+	}
+
+	const chapters: Chapter[] = [];
+	for (const chap of framesOf(tag.subarray(start, size), version)) {
+		if (chap.id !== "CHAP") continue;
+		const idEnd = chap.body.indexOf(0);
+		if (idEnd < 0 || chap.body.length < idEnd + 17) continue;
+		const sub = framesOf(chap.body.subarray(idEnd + 17), version);
+		const title = sub.find(({ id }) => id === "TIT2");
+		chapters.push({
+			startTime: uint32(chap.body, idEnd + 1) / 1000,
+			title: title ? decodeText(title.body) : "",
+		});
+	}
+	return normalizeChapters(chapters);
+}
+
+function framesOf(bytes: Uint8Array, version: number): { id: string; body: Uint8Array }[] {
+	const frames = [];
+	let at = 0;
+	while (at + HEADER_BYTES <= bytes.length && bytes[at] !== 0) {
+		const id = String.fromCharCode(...bytes.subarray(at, at + 4));
+		const size = version === 4 ? synchsafe(bytes, at + 4) : uint32(bytes, at + 4);
+		const end = at + HEADER_BYTES + (size ?? Infinity);
+		if (end > bytes.length) break;
+		// Compressed, encrypted or otherwise transformed frames are left unread.
+		if (bytes[at + 9] === 0) frames.push({ id, body: bytes.subarray(at + HEADER_BYTES, end) });
+		at = end;
+	}
+	return frames;
+}
+
+function decodeText(body: Uint8Array): string {
+	const text = body.subarray(1);
+	const bigEndian = body[0] === 1 && text[0] === 0xfe && text[1] === 0xff;
+	const label = bigEndian ? "utf-16be" : TEXT_ENCODINGS[body[0]];
+	if (!label) return "";
+	return new TextDecoder(label).decode(text).split("\0")[0];
+}
+
+function uint32(bytes: Uint8Array, at: number): number {
+	return ((bytes[at] << 24) | (bytes[at + 1] << 16) | (bytes[at + 2] << 8) | bytes[at + 3]) >>> 0;
+}
+
+function synchsafe(bytes: Uint8Array, at: number): number | undefined {
+	const parts = bytes.subarray(at, at + 4);
+	if (parts.length < 4 || parts.some((part) => part > 0x7f)) return undefined;
+	return (parts[0] << 21) | (parts[1] << 14) | (parts[2] << 7) | parts[3];
+}

From c9246209f89feb96bcd58a81b2c777151b2faf1e Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sat, 24 Oct 2026 16:29:18 +0200
Subject: [PATCH 2/4] test(e2e): play an MP3 with ID3 chapters

---
 tests/e2e/journey-player.test.ts | 56 ++++++++++++++++++++++++++++++++
 tests/e2e/journey/fixtures.ts    | 37 ++++++++++++++++++---
 2 files changed, 89 insertions(+), 4 deletions(-)

diff --git a/tests/e2e/journey-player.test.ts b/tests/e2e/journey-player.test.ts
index 1b9889bc..66be53d5 100644
--- a/tests/e2e/journey-player.test.ts
+++ b/tests/e2e/journey-player.test.ts
@@ -242,6 +242,62 @@ describe("player journeys", () => {
 		);
 	});
 
+	test("an MP3's ID3 chapters load once it plays, and a chapter seeks", async () => {
+		const context = getContext();
+		const { obsidian } = context;
+		const chaptered: FixtureEpisode = {
+			title: "Chaptered MP3",
+			seconds: 60,
+			guid: "chaptered",
+			chapters: [
+				{ startTime: 0, title: "Cold open" },
+				{ startTime: 20, title: "Ünïcode 🍕" },
+				{ startTime: 40, title: "Outro" },
+			],
+		};
+		const feed: FixtureFeed = {
+			title: "Journey ID3",
+			slug: "id3",
+			artwork: true,
+			episodes: [chaptered],
+		};
+		const server = await startFixtureServer([feed]);
+		onTestFinished(() => server.stop());
+		await seedLibrary(context, server, {
+			subscriptions: [feed],
+			current: storedEpisode(server, feed, chaptered),
+		});
+		await showPodNotes(obsidian);
+		if (!(await isShown(obsidian, ui.fullPlayer))) await click(obsidian, ui.openPlayer);
+		await waitUntilShown(obsidian, ui.fullPlayer);
+		const media = new URL(server.mediaUrl(feed, chaptered)).pathname;
+
+		expect(
+			await holdsFor(obsidian, () => isShown(obsidian, ui.playerPanel("Chapters")), false),
+			"no Chapters before it plays",
+		).toBe(false);
+		expect(server.requests(), "a restored player loads no media").not.toContain(media);
+
+		await click(obsidian, ui.playbackToggle);
+		await click(obsidian, ui.playerPanel("Chapters"));
+		const rows = () =>
+			obsidian.dev.evalJson<string[]>(
+				`[...document.querySelectorAll(${jsLiteral(`${PLAYER_VIEW} .pn-player ol.pn-panel-scroll button.pn-row`)})].map((row) => row.textContent.replace(/\\s+/g, " ").trim())`,
+			);
+		const expected = ["0:00 Cold open", "0:20 Ünïcode 🍕", "0:40 Outro"];
+		expect(await eventually(obsidian, rows, expected)).toEqual(expected);
+
+		await click(obsidian, {
+			name: "the Outro chapter",
+			elements: `[...document.querySelectorAll(${jsLiteral(`${PLAYER_VIEW} .pn-player ol.pn-panel-scroll button.pn-row`)})].filter((row) => row.textContent.includes("Outro"))`,
+		});
+		await waitForPlayback(
+			obsidian,
+			(playback) => playback.playing && playback.seconds >= 40,
+			"playing from the Outro chapter",
+		);
+	});
+
 	test("Up next reorders the queue in place, writing data.json once per completed move", async () => {
 		const { obsidian } = getContext();
 		await openPlayer([ONE, TWO, THREE, FOUR]);
diff --git a/tests/e2e/journey/fixtures.ts b/tests/e2e/journey/fixtures.ts
index 0173106a..588f20dd 100644
--- a/tests/e2e/journey/fixtures.ts
+++ b/tests/e2e/journey/fixtures.ts
@@ -20,6 +20,8 @@ export type FixtureEpisode = Readonly<{
 	description?: string;
 	guid?: string;
 	transcripts?: readonly FixtureTranscript[];
+	/** Serves the episode as an MP3 whose ID3 tag carries these chapters. */
+	chapters?: readonly Readonly<{ title: string; startTime: number }>[];
 }>;
 
 export type FixtureFeed = Readonly<{
@@ -105,7 +107,7 @@ export async function startFixtureServer(feeds: readonly FixtureFeed[]): Promise
 		`http://${feed.host ?? FIXTURE_HOST}:${port}${feedPath(feed)}`;
 	const artworkUrl = (feed: FixtureFeed) => `${origin}/${feed.slug}/artwork.svg`;
 	const mediaPath = (feed: FixtureFeed, episode: FixtureEpisode) =>
-		`/${feed.slug}/${feed.episodes.indexOf(episode) + 1}.wav`;
+		`/${feed.slug}/${feed.episodes.indexOf(episode) + 1}.${episode.chapters ? "mp3" : "wav"}`;
 	const audio = (feed: FixtureFeed, episode: FixtureEpisode) => {
 		const route = routes.get(mediaPath(feed, episode));
 		if (!route) throw new Error(`${feed.title} / ${episode.title} has no audio.`);
@@ -124,6 +126,7 @@ export async function startFixtureServer(feeds: readonly FixtureFeed[]): Promise
 							? null
 							: {
 									url: `${origin}${mediaPath(feed, episode)}`,
+									type: episode.chapters ? "audio/mpeg" : "audio/wav",
 									bytes: audio(feed, episode).length,
 								},
 					(transcript) =>
@@ -136,7 +139,10 @@ export async function startFixtureServer(feeds: readonly FixtureFeed[]): Promise
 
 	for (const feed of feeds) {
 		feed.episodes.forEach((episode, index) => {
-			if (episode.seconds !== null) {
+			if (episode.chapters && episode.seconds !== null) {
+				const body = chapteredMp3(episode.seconds, episode.chapters);
+				routes.set(mediaPath(feed, episode), { type: "audio/mpeg", body });
+			} else if (episode.seconds !== null) {
 				const body = wav(episode.seconds, 300 + 40 * index + 7 * feed.slug.length);
 				routes.set(mediaPath(feed, episode), { type: "audio/wav", body });
 			}
@@ -250,6 +256,29 @@ export function wav(seconds: number, frequency = 440): Buffer {
 	return buffer;
 }
 
+/** Silent MPEG-1 Layer III frames, 36 ms each, behind an ID3v2.3 tag of CHAP frames. */
+function chapteredMp3(seconds: number, chapters: NonNullable<FixtureEpisode["chapters"]>): Buffer {
+	const frame = (id: string, body: Buffer) => {
+		const header = Buffer.alloc(10);
+		header.write(id, 0, "latin1");
+		header.writeUInt32BE(body.length, 4);
+		return Buffer.concat([header, body]);
+	};
+	const frames = chapters.map(({ title, startTime }, index) => {
+		const times = Buffer.alloc(16, 0xff);
+		times.writeUInt32BE(startTime * 1000, 0);
+		times.writeUInt32BE((chapters[index + 1]?.startTime ?? seconds) * 1000, 4);
+		const tit2 = frame("TIT2", Buffer.concat([Buffer.from([3]), Buffer.from(title, "utf8")]));
+		return frame("CHAP", Buffer.concat([Buffer.from(`ch${index}\0`, "latin1"), times, tit2]));
+	});
+	const body = Buffer.concat(frames);
+	const size = [21, 14, 7, 0].map((shift) => (body.length >> shift) & 0x7f);
+	const tag = Buffer.concat([Buffer.from([0x49, 0x44, 0x33, 3, 0, 0, ...size]), body]);
+	const audio = Buffer.alloc(Math.ceil(seconds / 0.036) * 144);
+	for (let at = 0; at < audio.length; at += 144) audio.set([0xff, 0xfb, 0x18, 0xc0], at);
+	return Buffer.concat([tag, audio]);
+}
+
 function serveRange(
 	request: http.IncomingMessage,
 	response: http.ServerResponse,
@@ -282,7 +311,7 @@ function serveRange(
 function rss(
 	feed: FixtureFeed,
 	artworkUrl: string | null,
-	enclosure: (episode: FixtureEpisode) => { url: string; bytes: number } | null,
+	enclosure: (episode: FixtureEpisode) => { url: string; type: string; bytes: number } | null,
 	transcriptUrl: (transcript: FixtureTranscript) => string,
 ): string {
 	const items = feed.episodes.map((episode) => {
@@ -296,7 +325,7 @@ function rss(
 				? `\t\t\t<description>${escapeXml(episode.description)}</description>`
 				: "",
 			media
-				? `\t\t\t<enclosure url="${escapeXml(media.url)}" type="audio/wav" length="${media.bytes}"/>`
+				? `\t\t\t<enclosure url="${escapeXml(media.url)}" type="${media.type}" length="${media.bytes}"/>`
 				: "",
 			...(episode.transcripts ?? []).map(
 				(transcript) =>

From d0d440451892dbc00941daad72a368545990332a Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sat, 24 Oct 2026 16:41:55 +0200
Subject: [PATCH 3/4] fix(chapters): retry transient ID3 failures and reuse
 cached chapters

---
 src/ui/PodcastView/chapters.test.ts | 1 +
 src/ui/PodcastView/chapters.ts      | 2 ++
 src/utility/id3Chapters.test.ts     | 2 ++
 src/utility/id3Chapters.ts          | 6 +++++-
 4 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/ui/PodcastView/chapters.test.ts b/src/ui/PodcastView/chapters.test.ts
index 9956a620..295f21bf 100644
--- a/src/ui/PodcastView/chapters.test.ts
+++ b/src/ui/PodcastView/chapters.test.ts
@@ -58,6 +58,7 @@ describe("chapters", () => {
 		const episode = { streamUrl: "https://pod.test/plain.mp3" };
 		vi.mocked(fetchChapters).mockClear().mockResolvedValueOnce([]);
 
+		expect(await loadChapters(episode)).toEqual([]);
 		expect(await loadChapters(episode)).toEqual([]);
 		expect(cachedChapters(episode)).toEqual([]);
 		expect(fetchChapters).toHaveBeenCalledOnce();
diff --git a/src/ui/PodcastView/chapters.ts b/src/ui/PodcastView/chapters.ts
index 02bdb142..1ccca58c 100644
--- a/src/ui/PodcastView/chapters.ts
+++ b/src/ui/PodcastView/chapters.ts
@@ -28,6 +28,8 @@ export function cachedChapters(episode: ChaptersSource): Chapter[] | undefined {
 
 /** The episode's chapters. A failed load, as offline, is not kept, so the next one fetches again. */
 export async function loadChapters(episode: ChaptersSource): Promise<Chapter[]> {
+	const cached = cachedChapters(episode);
+	if (cached) return cached;
 	const chapters = await fetchChapters(episode);
 	if (chapters) loaded.set(chaptersKey(episode), chapters);
 	return chapters ?? [];
diff --git a/src/utility/id3Chapters.test.ts b/src/utility/id3Chapters.test.ts
index 4d7d30f0..5fc44676 100644
--- a/src/utility/id3Chapters.test.ts
+++ b/src/utility/id3Chapters.test.ts
@@ -186,6 +186,8 @@ describe("fetchId3Chapters", () => {
 	it("tries again after a network failure, but not after a server that ignores Range", async () => {
 		mockRequest.mockRejectedValueOnce(new TimeoutError());
 		await expect(fetchId3Chapters(url)).resolves.toBeUndefined();
+		mockRequest.mockRejectedValueOnce(new NetworkError("unexpected-status", 503));
+		await expect(fetchId3Chapters(url)).resolves.toBeUndefined();
 
 		mockRequest.mockRejectedValueOnce(new NetworkError("unexpected-status", 200));
 		await expect(fetchId3Chapters(url)).resolves.toEqual([]);
diff --git a/src/utility/id3Chapters.ts b/src/utility/id3Chapters.ts
index 4cb3154c..a86a1298 100644
--- a/src/utility/id3Chapters.ts
+++ b/src/utility/id3Chapters.ts
@@ -8,6 +8,7 @@ const FIRST_REQUEST_BYTES = 64 * 1024;
 const MAX_TAG_BYTES = 16 * 1024 * 1024;
 const REQUEST_TIMEOUT_MS = 30_000;
 const RETRYABLE: ReadonlySet<string> = new Set(["timeout", "transport-failure", "aborted"]);
+const RETRYABLE_STATUSES: ReadonlySet<number> = new Set([408, 429, 500, 502, 503, 504]);
 const TEXT_ENCODINGS = ["iso-8859-1", "utf-16le", "utf-16be", "utf-8"];
 
 /**
@@ -28,7 +29,10 @@ export async function fetchId3Chapters(url: string): Promise<Chapter[] | undefin
 		return parseId3Chapters(tag);
 	} catch (error) {
 		// A server that ignores Range answers with the whole file, and asking again would too.
-		return error instanceof NetworkError && RETRYABLE.has(error.code) ? undefined : [];
+		const retryable =
+			error instanceof NetworkError &&
+			(RETRYABLE.has(error.code) || RETRYABLE_STATUSES.has(error.status ?? 0));
+		return retryable ? undefined : [];
 	}
 }
 

From dab3871268f2274c9a4ce28c40f555f0857c923a Mon Sep 17 00:00:00 2001
From: Christian Bager Bach Houmann <christian@bagerbach.com>
Date: Sat, 24 Oct 2026 16:47:57 +0200
Subject: [PATCH 4/4] docs(chapters): say ID3 chapters come from streamed media

---
 src/types/Episode.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/types/Episode.ts b/src/types/Episode.ts
index e3e1f7e8..7a071bdb 100644
--- a/src/types/Episode.ts
+++ b/src/types/Episode.ts
@@ -22,7 +22,7 @@ export interface Episode {
 	episodeNumber?: number;
 	/** Episode duration in whole seconds, from `<itunes:duration>` where present. */
 	duration?: number;
-	/** URL to the podcast:chapters JSON file. Without one, chapters come from the media's ID3 tag. */
+	/** URL to the podcast:chapters JSON file. Without one, a streamed episode's chapters come from its ID3 tag. */
 	chaptersUrl?: string;
 	/** Media element type used to play the enclosure/local file. */
 	mediaType?: EpisodeMediaType;