diff --git a/AGENTS.md b/AGENTS.md index b11237f..10b161c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 48b1cfa..dc176d2 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -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; diff --git a/CHANGELOG.md b/CHANGELOG.md index a8beae7..cf13b94 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. diff --git a/README.md b/README.md index fcc6902..428a093 100644 --- a/README.md +++ b/README.md @@ -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