Drop ID3 CHAP frames, having measured the real library

Peter asked how expensive it would be to check before dropping them. Checking
turned out to be cheaper than arguing about it, so here is the answer from his
own 61 subscriptions rather than from general knowledge.

Every feed's newest episode was fetched far enough to read its entire ID3 tag
-- the declared size from the header, not a guessed window, which matters
because several are multi-megabyte (Cruising the Waves carries 10MB of cover
art) and a first pass with a 400KB window left thirteen of them inconclusive.
ID3v2.2's 3-byte frame headers needed handling separately from v2.3/2.4's
4-byte ones, which is what made Dan Carlin's feeds look truncated at first.

Not one of the 61 carries a CHAP frame. The frames present are all artwork and
metadata: APIC, TALB, TIT2 and friends. Exactly one show publishes chapters at
all -- Wards Way Podcast -- and it does so as Podcasting 2.0 JSON, which has
been supported since the skip work landed.

So CHAP is dropped rather than deferred. The two survey scripts are kept under
tools/ so this can be rerun in a minute if a new subscription ever suggests
otherwise, rather than re-derived.

Two things fell out of the survey worth writing down. A feed can carry two
chapters elements per item -- the podcastindex one with a url and a podlove one
without; Buzzsprout emits both. The parser takes the first non-null url so it
is unaffected, but a last-wins read would silently lose chapters. And the one
show with chapters marks none of them toc:false, so ad-chapter skipping -- on
by default as of this morning -- currently has nothing to act on anywhere in
the library. It is correct and idle, waiting for a publisher who marks breaks.

Documentation and tooling only; no behaviour change.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018AwnALZL6bD4VBtATDVv3B

1 files changed, 17 insertions, 2 deletions

diff --git a/CLAUDE.md b/CLAUDE.md
index 0316ec3..ed4373d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -129,11 +129,26 @@ downloaded at once, Facebook videos are supported, the library ranks shows by th
 
 **Tier 3 skip detection — audio fingerprinting of theme music — is still not built.** Peter
 deferred it; the design plan puts it in Phase 3 and wants a desktop prototype against real
-episodes before any Android code. ID3 `CHAP` frames are also not read: that means parsing ID3
-out of a possibly-partial MP3, and the JSON path covers the shows that mark chapters at all.
+episodes before any Android code.
+
+**ID3 `CHAP` frames are dropped, not deferred** — decided 2026-09-26 by measuring Peter's actual
+61 subscriptions rather than guessing. Every feed's newest episode was fetched far enough to read
+its whole ID3 tag (declared size, not a guessed window — several are multi-megabyte, Cruising the
+Waves is 10MB of cover art). **Not one carries a CHAP frame.** The frames present are all artwork
+and metadata: APIC, TALB, TIT2 and friends. Exactly one show, Wards Way Podcast, publishes
+chapters at all, and it does so as Podcasting 2.0 JSON, which is already supported. The survey
+scripts are worth rerunning rather than re-deriving if this ever comes back up.
+
+**Ad-chapter skipping has nothing to act on in Peter's library yet.** That same survey: the one
+show with chapters has six navigable chapters and *zero* marked `toc: false`. The feature is on
+by default and correct; it is simply waiting for a publisher who marks breaks.
 
 **Known gaps in what is built** (deliberate, not forgotten):
 
+- **A feed can carry two `<...:chapters>` elements per item** — the podcastindex one with a
+  `url`, and a podlove one with none. Buzzsprout emits both. The parser takes the first non-null
+  url, so order does not matter; a naive last-wins read gets null and silently loses chapters.
+
 - **Ad-chapter skipping trusts `toc: false` and nothing else.** No title matching: a show
   discussing its own sponsorship deal has a chapter called "Sponsors" that is the actual
   programme. It shipped off by default out of caution and Peter asked for it on after living