From ff10f4354da09419a2a1aa1df3e099d81564e32c Mon Sep 17 00:00:00 2001 From: Sanapach Date: Thu, 19 Nov 2026 21:14:54 +0200 Subject: [PATCH] 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 --- README.md | 4 +++ docs/administration.md | 80 +++++++++++++++++++++++++++++++++++------- docs/development.md | 41 ++++++++++++++++++---- 3 files changed, 105 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index d5ecd5d..ccbdbc8 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,10 @@ the Furumi federated network. without creating an account. - **Welcome your people.** Use password login or SSO. Instance admins can approve new users without needing access to the identity provider. +- **Follow podcasts.** Subscribe to RSS feeds, browse seasons and episodes, and + pick up where you stopped, also on your other Furumi players. Episodes stream + from the publisher and are never imported into the library; subscriptions + and listening progress stay private to your own devices. - **Discover more.** Find similar tracks and connect Last.fm for scrobbling. - **Connect your players.** Pair trusted Furumi devices to synchronize playlists, likes, playback state, and playback controls. diff --git a/docs/administration.md b/docs/administration.md index 8f013ce..1efd7ff 100644 --- a/docs/administration.md +++ b/docs/administration.md @@ -71,13 +71,48 @@ Trusted-device pairing is separate from public catalog discovery. It connects a user's own Furumi players so likes, playlists, playback state, and control can move between approved devices. -Queues synchronized from other Furumi players can contain podcast episodes. The -web player keeps them in the queue, in order and with their position, and shows -them as **Podcast · not playable in the web player yet**; local playback skips -them. A device that does not support podcasts yet (device-sync protocol below -4, for example an older terminal player) cannot receive such a queue: selecting -it as the playback device shows that it needs an update, and the episodes stay -in the queue. Jam guests see podcast episodes of the host only as private items. +Queues synchronized from other Furumi players can contain podcast episodes; +the web player plays them (see [Podcasts](#podcasts)) and keeps them in order +with their position. A device that does not support podcasts yet (device-sync +protocol below 4, for example an older terminal player) cannot receive such a +queue: selecting it as the playback device shows that it needs an update, and +the episodes stay in the queue. Jam guests see podcast episodes of the host +only as private items they cannot play, add, remove or clear. + +## Podcasts + +**Podcasts** in the player sidebar lists your subscriptions with the number +of unplayed episodes and the result of the last feed check. Paste an RSS or +Atom feed URL to subscribe: the server loads the feed first and shows why when +it cannot (not a feed, not reachable, or an address that is not public). A +podcast page shows the description, the seasons (episodes without a season +form their own group), a search over episode titles and descriptions, filters +for unplayed, started and played episodes, and the recent listening history. + +- **Play / Resume** continues an episode where you stopped, on whichever of + your Furumi players last saved it. **Start over** plays it from the + beginning; **Mark played** and **Mark unplayed** change its status without + playing (marking does not count as a listen). An episode counts as listened + when playback reaches its end, or its last 30 seconds or last 5 %, whichever + is shorter. +- The web player saves the position about every 20 seconds and when you + pause, seek, switch items, close the page or hand playback to another + device, without interrupting the audio. +- Handing playback to another device keeps the episode, its position and + whether it was paused. A later save of an older listening session never + moves the position back after you seek or start over elsewhere. +- **Unsubscribe** stops checking the feed and keeps your progress and history; + subscribing again continues where you stopped. **Refresh** checks the feed + now (at most every 30 seconds). + +Privacy: a new subscription is private. Subscriptions, progress and listening +history are synchronized only between your own paired Furumi players (trusted +devices), never published to the federation, and Jam guests cannot see your +episodes. Publishing a podcast for discovery is not available in the web +player yet. Episodes are not stored on the server or shared with peers: the +browser streams the audio and loads the artwork directly from the publisher, +so the publisher sees your browser's address. With the audio proxy (below) +the publisher sees the server instead. ### Podcast feeds and audio @@ -94,15 +129,34 @@ through DNS or through a redirect, are refused. System proxy settings are not used for these requests. Episode audio is streamed by the browser directly from the publisher. Some -publishers cannot be played that way (no CORS, or plain HTTP while this -server uses HTTPS). For them, enable **Settings → Podcasts → Podcast audio -proxy** (`FURU_PODCAST_AUDIO_PROXY_ENABLED=true`): the server then fetches -the audio of an episode from the publisher when a signed-in user's player -requests it and passes it through without storing it. This uses the server's bandwidth. Only -audio responses are passed through, up to 1 GiB and 4 hours per request. +publishers cannot be played that way (plain HTTP while this server uses +HTTPS, or a server the browser refuses). For them, enable **Settings → +Podcasts → Podcast audio proxy** (`FURU_PODCAST_AUDIO_PROXY_ENABLED=true`): +the player then switches to the proxy when the direct URL fails or is plain +HTTP on an HTTPS page, and the server fetches the audio from the publisher +and passes it through without storing it. This uses the server's bandwidth. + +Security model of the proxy: + +- It takes an episode id, never a URL. The URL comes from the signed-in + account's own podcast catalog: its feeds, and episode references that its + own trusted devices sent (for example the current item of a handoff). Any + signed-in user can therefore make the server fetch audio URLs of feeds they + subscribe to, as with feed refreshes. +- The same public-address checks as for feeds apply to every connection and + redirect; only audio content types are passed through (no HTML, no video), + with a single byte range, up to 1 GiB and 4 hours per request, and no + cookies or credentials are sent. +- Responses are not cached or stored, and are marked `no-store`, `nosniff` + and sandboxed. + +Leave it off unless your users need it. ### Upgrading from 0.13 +Release 0.14 adds the podcast UI and playback described above; no setting is +needed besides the optional proxy. + Podcast state synchronized from other Furumi players is kept in per-account podcast tables (`furumusic__podcast*`). The upgrade imports what 0.13 kept in `furumusic__fed_podcast_relay`; that table is no longer used and can be diff --git a/docs/development.md b/docs/development.md index 27688cc..253eb8e 100644 --- a/docs/development.md +++ b/docs/development.md @@ -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 = :`) 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://... \