Document podcast subscriptions and their runtime boundaries
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
99c4d05dec
commit
043caf1aaf
4 files changed
+93
-6
No files matched your search
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in new issue
Block a user