Implement Podcast 2.0 chapters (external JSON) #31

New issue

Closed

opened 2026-08-19 20:37:59 +00:00 by agent-pi · 2 comments

agent-pi commented

2026-08-19 20:37:59 +00:00

Collaborator

concept.md lists the Podcast 2.0 namespace (xmlns:podcast) as optional. Nothing currently emits Podcast 2.0 elements, and no specific elements (transcript, chapters, funding, …) have been specified.

Open decision: implement the namespace, or remove the mention from concept.md.

`concept.md` lists the Podcast 2.0 namespace (`xmlns:podcast`) as optional. Nothing currently emits Podcast 2.0 elements, and no specific elements (transcript, chapters, funding, …) have been specified. Open decision: implement the namespace, or remove the mention from `concept.md`.

agent-pi commented

2026-08-19 20:38:19 +00:00

Author

Collaborator

Plan of attack (blocked on owner decision):

If "remove": strike the optional Podcast 2.0 mention from concept.md.
If "implement": specify which Podcast 2.0 elements to emit, then add them in src/sub2pod/feed.py with tests.

Plan of attack (blocked on owner decision): - If "remove": strike the optional Podcast 2.0 mention from `concept.md`. - If "implement": specify which Podcast 2.0 elements to emit, then add them in `src/sub2pod/feed.py` with tests.

agent-pi changed title from ~~Decide: implement or drop the Podcast 2.0 namespace~~ to Implement Podcast 2.0 chapters (external JSON)

2026-08-20 08:32:56 +00:00

agent-pi commented

2026-08-20 08:32:58 +00:00

Author

Collaborator

Decision made: implement the Podcast 2.0 chapters extension (external JSON), not the whole namespace.

Findings (from the ytdl-sub investigation):

ytdl-sub writes a per-episode .info.json (via output_options.info_json_name) whose chapters array (start_time/end_time/title, seconds) is populated from YouTube chapter markers. Confirmed working on the live Links with Friends data.
AntennaPod reads the external JSON form (<podcast:chapters url type="application/json+chapters">), not inline <podcast:chapter> — verified in AntennaPod source (PodcastIndex.java only reads the url attribute; PodcastIndexChapterParser.java parses {"chapters":[{"startTime":…,"title":…}]}).

Plan:

New src/sub2pod/chapters.py — Chapter dataclass (start_time, title), parse_chapters() (info.json → list), chapters_to_json() (Podcast Index JSON {"version":"1.2.0","chapters":[…]}).
discovery.py — add chapters to Episode, discover the .info.json sidecar.
feed.py — declare xmlns:podcast, emit <podcast:chapters> in the item, write chapters.json in write_feed.
TDD tests across parse/serialise/discovery/feed.
Update concept.md to scope the namespace mention to the chapters extension.

Decision made: implement the Podcast 2.0 **chapters** extension (external JSON), not the whole namespace. Findings (from the ytdl-sub investigation): - ytdl-sub writes a per-episode `.info.json` (via `output_options.info_json_name`) whose `chapters` array (`start_time`/`end_time`/`title`, seconds) is populated from YouTube chapter markers. Confirmed working on the live `Links with Friends` data. - AntennaPod reads the external JSON form (`<podcast:chapters url type="application/json+chapters">`), **not** inline `<podcast:chapter>` — verified in AntennaPod source (`PodcastIndex.java` only reads the `url` attribute; `PodcastIndexChapterParser.java` parses `{"chapters":[{"startTime":…,"title":…}]}`). Plan: 1. New `src/sub2pod/chapters.py` — `Chapter` dataclass (`start_time`, `title`), `parse_chapters()` (info.json → list), `chapters_to_json()` (Podcast Index JSON `{"version":"1.2.0","chapters":[…]}`). 2. `discovery.py` — add `chapters` to `Episode`, discover the `.info.json` sidecar. 3. `feed.py` — declare `xmlns:podcast`, emit `<podcast:chapters>` in the item, write `chapters.json` in `write_feed`. 4. TDD tests across parse/serialise/discovery/feed. 5. Update `concept.md` to scope the namespace mention to the chapters extension.

agent-pi referenced this issue from a pull request that will close it,

2026-08-20 08:37:47 +00:00

Emit Podcast 2.0 chapters from ytdl-sub info.json #38

agent-pi closed this issue

2026-08-20 10:10:11 +00:00