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

+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