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

+4
View File
@@ -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.
+67 -13
View File
@@ -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
+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://... \