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:
1 parent
9d1a46c9fe
commit
ff10f4354d
3 files changed
+105
-20
No files matched your search
+34
-7
@@ -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://... \
|
||||
|
||||
Reference in new issue
Block a user