Document podcasts in the web player

README and the administration guide describe the Podcasts section,
resume and completion, handoffs, unsubscribing, what stays private and
what the publisher sees, and the security model of the optional audio
proxy. The development guide lists the endpoints, how the player
writes progress and the node tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 15:12:38 +02:00
1 parent 9d1a46c9fe
commit ff10f4354d
3 files changed
+105 -20

No files matched your search

+34 -7
View File
@@ -52,11 +52,13 @@ copies) and announces protocol version 4. Each account is one virtual device:
typed value is used only while the legacy columns it recorded
(`queue_json`, `current_track_id`, `queue_position`) match the row. Jam
placeholders are never stored in a user's own queue.
- a browser that selects a podcast episode it cannot play does not know the
episode's position. It reports `position_unknown`, and the server sends the
resume position of the episode's progress register instead of 0. Jam
participant commands carry `jam_participant`; the host browser checks them
against its own queue.
- a browser that selects an item it cannot play (a Jam placeholder), or an
episode whose resume position the server has not sent yet, reports
`position_unknown`, and the server sends the resume position of the
episode's progress register instead of 0. Outgoing playback states raise
each episode's `progress_generation` to the register generation, so the
device that takes over writes above it. Jam participant commands carry
`jam_participant`; the host browser checks them against its own queue.
Rolling back to 0.12 needs the podcast operations removed from the operation
log first; see "Rolling back to 0.12" in `administration.md`.
@@ -82,7 +84,7 @@ reference store in `furumi-library`; every table has a `user_id` key.
`music_dht::podcast`. Each write transaction holds a per-account advisory
lock.
- Local actions (`subscribe`, `unsubscribe`, `set_shared`, `start_session`,
`checkpoint`, `seek`, `complete_session`, `restart`, `mark_played`,
`checkpoint`, `seek`, `complete_if_current`, `restart`, `mark_played`,
`mark_unplayed`, `record_listen_session`) append their operation to the
account's sync log with the next stamp (`devices::append_local_op`: `seq`,
`hlc_ms`, `op_id = <device>:<seq>`) and apply exactly that operation in
@@ -137,6 +139,31 @@ The runtime around the store lives next to it in `src/podcasts/`:
`podcast_audio_proxy_enabled` is set; by default the browser streams from
the publisher URL.
### Podcast UI and playback
`api.rs` holds what the endpoints do, independent of HTTP (`http.rs` only
authenticates and maps statuses), so the Postgres tests drive it directly:
| Endpoint (`/api/podcasts`) | Does |
| --- | --- |
| `GET /feeds[?all=1]`, `POST /feeds {url}` | list; subscribe after fetching the feed (`runner::subscribe_url`) |
| `GET /feeds/{id}`, `GET /feeds/{id}/episodes?season=&played=&q=&sort=&limit=&offset=` | podcast, seasons, history; episode pages with the browser queue item |
| `POST /feeds/{id}/subscribe`, `/unsubscribe`, `POST /{id}/refresh` | subscription and manual refresh |
| `POST /episodes/{id}/restart`, `/played`, `/unplayed` | explicit progress actions |
| `POST /episodes/{id}/playback` | source, resume position; with `start` a new session (explicit, above `carried_generation`); records an unknown handed-off reference first |
| `POST /episodes/{id}/progress` | `checkpoint`/`pause`/`stop`/`handoff` at the session generation, `seek` explicit, completion once (`ended` or `reaches_completion`), listening session record |
In the browser (`templates/player/scripts.html`), `_playEpisodeLocal` asks
for the playback, loads the publisher URL (or the proxy: mixed content, or a
failed direct load) and seeks before playing; when the source cannot seek to
the saved position it shows that instead of playing from elsewhere. Writes of
one session run in order (`_reportEpisode`), read the session generation at
send time, stop after `superseded`, and carry the position of their own
episode. A browser that stops being the active device ends its session
without a report; a handoff from it reports first. Jam guests never play or
save episodes (they only ever see placeholders). The `podcasts` store backs
the Podcasts views in `shell.html`.
Tests never reach the internet: `test_server.rs` serves on 127.0.0.1 and
provides a scripted resolver. Loopback is reachable only through
`AddressPolicy::test_allow_loopback`, which exists only under `#[cfg(test)]`.
@@ -147,7 +174,7 @@ contract (`PODCASTS.md`) and `PLAYBACK_PROTOCOL.md` in the Frid repository.
```bash
cargo test devices:: queue_items podcasts:: queue_persistence
node --test tests/player_queue_sources.test.cjs
node --test tests/player_queue_sources.test.cjs tests/player_podcasts.test.cjs
# Disposable PostgreSQL; the tests run the production migrations on it, and
# the migration test creates and drops a database next to it:
FURU_DEVICE_SYNC_TEST_DATABASE_URL=postgresql://... \