[chhoumann]

Summary

Fixes #512. MP3 episodes that embed ID3 CHAP chapters now show them in the player, the progress bar, headset chapter skips, and the {{chapters}} note tag, the same way Podcasting 2.0 chapter files already work. A chapter file in the feed still wins.

• A small parser reads ID3v2.3 and v2.4 CHAP frames: start time and TIT2 title, in any of the four ID3 text encodings. No new dependency.
• PodNotes reads only the tag. It asks for the first 64 KB with a Range request through requestUrl, then for the rest of the tag when it is larger. It skips tags over 16 MB.
• A restored player loads no media after a restart, so it also reads no tag until you press play.
• The session keeps a definitive result, including "no chapters", so a chapterless MP3 is read once. A network failure, timeout, 408, 429, or 5xx is retried later.
• The player clears a Chapters choice when the episode changes, as before. A Transcript or Up next choice now stays, which was already true for every episode without a chapter file.

Scope

• Streamed episodes only. Local vault files have no chapters this way.
• Titles and start times only. Chapter images, links, and CTOC nesting are ignored, as the panel shows neither.
• Docs change at release, per docs/STYLE.md. player.md and templates.md say chapters come from the feed.

Tradeoffs

requestUrl cannot stream or cancel. A server that ignores Range sends the whole file once, and PodNotes then keeps "no chapters" for the session. Every host I probed honors Range through its redirects (Spreaker, Podtrac, Libsyn, Megaphone, Simplecast, atp.fm), and the audio element downloads the file anyway as it plays. A renderer fetch could abort early, but most podcast hosts send no CORS headers.

Verification

• Desktop, Obsidian 1.14.4 on Linux, isolated instance. Added https://www.spreaker.com/show/2892576/episodes/feed in the view and played Efer 756 from the issue: 4 chapters, two Range requests, seeking from the panel, and the {{chapters}} note. Added https://atp.fm/rss and played 714: 13 chapters with UTF-16 and emoji titles in the 820 px layout. After a plugin reload the restored player made no request until Play, and an open Up next stayed open when the chapters arrived.
• Android, Obsidian 1.14.4 on an Android 14 emulator: native requestUrl sent the Range requests, the 4 Efervesciencia chapters loaded, and a tap seeked to 37:05.
• New e2e journey an MP3's ID3 chapters load once it plays, and a chapter seeks. The fixture server now serves a silent MP3 with a real ID3 tag. The test fails with the ID3 path disabled. Full npm run test:e2e: 243 of 244 passed. The other one, settings export/import in marketplace-review-runtime.test.ts, passed on two reruns.
• npm run lint, format:check, typecheck, build, test (2,793 tests), test:tooling, docs:build, and size (102,325 of 103,000 gzip bytes) pass.

Spreaker 756, compact	Seeked to a chapter	ATP 714, wide

Restored, before Play	Android

Release impact

None. No settings, storage, API, or URI change. fetchChapters is internal.

---

Note

Medium Risk
Adds Range-based network reads and binary ID3 parsing on the playback path; behavior is bounded but touches core player, media session, and note creation.

Overview
Adds ID3 CHAP chapter support for streamed MP3s when the feed has no Podcasting 2.0 chapters file. A feed chapters URL still wins; otherwise PodNotes reads chapter markers from the media via HTTP Range requests (first 64 KB, then the rest of the tag, capped at 16 MB).

Chapter loading is unified on an episode (chaptersUrl + streamUrl) through fetchChapters, loadChapters, and chaptersKey caching. Failed fetches stay uncached for retry; confirmed empty chapter lists are cached so chapterless files are not re-read. The player defers ID3 loads until playback starts on a restored session (no media fetch until Play). Headset chapter skip, {{chapters}} notes, and the Chapters panel use the same path.

The player only clears an open Chapters panel when the episode changes; Transcript/Up next selections can persist when chapters arrive later.

^{Reviewed by Cursor Bugbot for commit dab3871. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Show ID3 chapters embedded in MP3 episodes

• Episodes without a Podcasting 2.0 chapters file now fall back to ID3 chapters parsed from the episode's MP3 stream via bounded Range requests in id3Chapters.ts. Supports ID3v2.3/v2.4 tags up to 16 MiB with Latin-1, UTF-16, and UTF-8 titles.
• fetchChapters now takes an Episode-derived ChaptersSource and a new chaptersKey utility prefers chaptersUrl over streamUrl in fetchChapters.ts. Local media returns no chapters without a network request.
• Chapter loading gains a cache keyed by the full chapter source in chapters.ts; cached empty results are reused while undefined failures are retried later.
• The player loads media chapters only after the restored player reaches media readiness, and preserves non-Chapters panel selections across chapter-source changes in Player.svelte. Media-session chapter seeking passes the current Episode to the loader in mediaSession.ts.
• Behavioral Change: fetchJsonChapters now returns undefined for failed requests instead of an empty array, and the host chapter-loader contract in MediaSessionHost changed from URL to Episode.

📊 Macroscope summarized 0659355. 9 files reviewed, 1 issue evaluated, 0 issues filtered, 1 comment posted

🗂️ Filtered Issues

[cloudflare-workers-and-pages]

Deploying podnotes with    Cloudflare Pages

Latest commit:	0659355
Status:	✅  Deploy successful!
Preview URL:	https://1e86fd77.podnotes.pages.dev
Branch Preview URL:	https://feat-mp3-chapters.podnotes.pages.dev

View logs