Document podcast subscriptions and their runtime boundaries

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 19:58:37 +02:00
1 parent 99c4d05dec
commit 043caf1aaf
4 files changed
+93 -6

No files matched your search

+3
View File
@@ -61,6 +61,9 @@ update it only when dependencies change.
- `src/player/` owns rodio playback and audio analysis.
- `src/federation/` owns DHT discovery, peer catalogs, audio exchange, and
federation caches.
- `src/podcasts/` owns podcast feed HTTP and refresh policy; podcast identity,
merge rules and the SQLite store come from FRID (`music_dht::podcast`,
`furumi_library::podcasts`) and must not be re-derived here.
- `src/devices.rs` owns trusted-device replication, membership, and playback
coordination.
- `src/ui/` renders `AppState`; rendering code must not start background work
+39 -1
View File
@@ -271,6 +271,39 @@ order and have their tab indices remapped. A `version` key that TOML attached
to a binding (written after a `[[keymaps]]` header) is rejected, so a versioned
file is never silently mistaken for a legacy one.
## Podcasts
Podcasts are a separate content type, not library tracks. The shared contract
lives in FRID: `music_dht::podcast` defines podcast and episode identity, feed
URL canonicalization, the RSS/Atom parser and the merge rules, and
`furumi_library::podcasts::PodcastStore` persists the catalog, the personal
registers (subscription, share, progress) and listening sessions in
`podcasts.sqlite3`. The TUI does not re-derive ids or merge rules.
The TUI owns what the contract leaves to clients:
- **Fetching.** Feeds are fetched with conditional requests (ETag,
Last-Modified), bounded size and time, and redirects followed by hand so the
store learns whether every hop was permanent; only then does the new URL
become a feed alias and the fetch URL. Validators are dropped after a
permanent redirect because they belong to the old address.
- **Scheduling.** The store keeps each feed's local fetch state (validators,
last error, consecutive failures, next check). A timer asks it which
subscriptions are due; feeds are checked at most a few at a time, a success
waits an hour, and failures back off exponentially (honouring
`Retry-After`). Errors never clear the stored catalog.
- **Runtime boundary.** Every store call, fetch and parse runs on the blocking
pool or as a task and reports back through `AppEvent`s; `update::podcasts`
holds the pure state transitions. Store open failures (newer schema,
foreign file) disable only the Podcasts tab and leave the file untouched.
- **Sync log.** Local actions (subscribe, unsubscribe, mark played) draw their
operation stamps from the device-sync log through
`DeviceSync::run_podcast_action`, and the operations are appended with
exactly those stamps, so the store's registers and the log agree. The lock
order is podcast store, then sync log. Podcast operations are protocol v4
payloads; until this client speaks sync v4 they stay in the log and are not
sent to peers.
## Scripted visualizations
Visualizations are an extension boundary rather than hard-coded rendering
@@ -398,6 +431,7 @@ Furumi stores different kinds of state according to their lifetime:
| State | Storage | Role |
| --- | --- | --- |
| Library, playlists, likes, history | SQLite | Durable local source of truth |
| Podcast subscriptions, episodes, progress | SQLite (`podcasts.sqlite3`, FRID store) | Durable personal state and a refreshable episode catalog |
| Device operation log and replicas | SQLite | Offline synchronization |
| Versioned track embeddings | SQLite | Durable, locally rebuildable similarity data |
| Federation catalog cache | SQLite/cache | Faster network browsing |
@@ -405,7 +439,8 @@ Furumi stores different kinds of state according to their lifetime:
| Settings, keymap, identity | Platform config/data dirs | Node configuration |
| Queue and playback snapshots | Application/device sync state | Continuity and handoff |
Caches are replaceable. The local library and device operation log are durable.
Caches are replaceable. The local library, the podcast store's personal state
and the device operation log are durable.
This distinction lets maintenance and recovery code discard derived network
data without risking the user's collection.
@@ -434,6 +469,9 @@ The source tree follows the architectural responsibilities:
- `similarity.rs` owns model acquisition, preprocessing, background indexing,
and the replaceable exact in-memory index;
- `federation/` owns DHT-facing search, peer catalogs, and audio exchange;
- `podcasts/` owns feed HTTP (conditional requests, redirects, limits) and
refresh scheduling policy; the podcast model, identity and SQLite store
come from FRID;
- `devices.rs` owns trusted-device replication and playback coordination;
- `app/` owns state transitions and runtime orchestration;
- `ui/` renders the TUI;
+14 -2
View File
@@ -9,13 +9,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Added
- A Podcasts tab on `4`. It is a placeholder in this build and states that
podcasts are not available yet.
- A Podcasts tab on `4`: subscribe to RSS/Atom feeds by URL, browse
podcast → seasons → episodes with saved position, played state, duration and
date, search episodes, filter by listening state, change the order, mark
episodes played or unplayed, check one or all feeds, and unsubscribe (progress
and history are kept). Feeds are checked in the background with conditional
requests and back-off; permanent redirects become feed aliases.
- Podcast data uses the shared FRID store (`furumi_library::podcasts`) in
`podcasts.sqlite3`; a database of the earlier podcast test build is migrated
in place, and a newer or foreign file is refused without changes.
- Podcast subscription and progress changes are recorded in the trusted-device
sync log with their own stamps. They are not sent to other devices yet.
- Podcast key bindings in the `podcasts` context: `o`, `/`, `Shift+R`,
`Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`.
- An optional top-level `version` in `keymap.toml`; the current format is
`version = 2`, and a `podcasts` binding context.
### Changed
- `music-dht` 0.6.0 and `furumi-library` 0.3.0.
- Tab order is now `1` Library, `2` Playlists, `3` Queue, `4` Podcasts,
`5` Settings, `6` Logs, for the tab bar, Tab/Shift+Tab, and the default
number keys.
+37 -3
View File
@@ -163,9 +163,9 @@ Shift+Tab cycle through them:
| `5` | Settings |
| `6` | Logs |
The Podcasts tab is a placeholder in this build; podcast support is not
available yet. On narrow terminals the tab bar shortens titles and then shows
only the numbers, keeping the active tab's full name. Press `?` for the full list of bindings and commands.
On narrow terminals the tab bar shortens titles and then shows only the
numbers, keeping the active tab's full name. Press `?` for the full list of
bindings and commands.
Bindings can be overridden in `keymap.toml` in the platform config directory
(`~/.config/furumi/keymap.toml` on Linux,
@@ -181,6 +181,40 @@ keep opening the same tabs, shows a short notice at startup, and never
rewrites the file. Add `version = 2` once the indices match the new order to
take them literally and silence the notice.
### Podcasts
The Podcasts tab (`4`) follows RSS and Atom podcast feeds. Furumi stores only
the feed's episode information; audio stays on the publisher's server and is
never imported into the music library or offered to other peers.
- **Add podcast** (`o`, or the first row) takes a feed URL; `feed://`,
`podcast://` and URLs without a scheme are accepted. Nothing is stored unless
the URL serves a feed. New subscriptions are private.
- The list shows each podcast's unplayed and total episode counts and its
check status; `!` marks a podcast whose last check failed, with the error in
the side panel (or below the list on narrow terminals).
- `Enter` opens a podcast. Podcasts with seasons show their seasons first
(plus "All episodes" and "Without a season"); `Esc` goes back.
- Episodes show the date, season/episode number, duration and listening
state: `●` not started, `◐` in progress with the saved position, `✓` played.
`/` searches titles and descriptions, `f` cycles all / unplayed / in
progress / played, `Shift+S` changes the order, `m` marks the selected
episode played or unplayed.
- `Shift+R` checks the selected podcast for new episodes, `Ctrl+R` checks all
of them. Feeds are also checked in the background about once an hour with
conditional requests; a failing feed is retried with growing pauses and its
known episodes stay available. A permanent redirect moves the subscription
to the new address.
- `Shift+U` (or `Shift+D`) unsubscribes after a confirmation. Listening
progress and history are kept, so subscribing again continues where you
left off.
Playing episodes from the Podcasts tab is not available in this build yet.
Podcast data lives in `podcasts.sqlite3` in the platform data directory (the
same file the earlier podcast test build used; it is upgraded in place). If
that file was written by a newer Furumi or is not a podcast database, the tab
explains why it is unavailable and the file is left unchanged.
### Now playing in tmux
While Furumi is running, a second invocation can print a cheap, single-line