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://... \