diff --git a/AGENTS.md b/AGENTS.md index 10b161c..89c2eb7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -61,9 +61,13 @@ 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/podcasts/` owns podcast feed HTTP and refresh policy, the episode + stream reader (HTTP Range, bounded buffer) and the ordered progress writer; + podcast identity, merge rules and the SQLite store come from FRID + (`music_dht::podcast`, `furumi_library::podcasts`) and must not be + re-derived here. Queue items are identified by `state::track_key` / + `TrackItem::key`, never by numeric id; music-only code must skip + `TrackItem::is_podcast()` items. - `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 dc176d2..1e03885 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -303,6 +303,34 @@ The TUI owns what the contract leaves to clients: 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. +- **Queue identity.** An episode is a `TrackItem` with an explicit + `podcast` reference (`TrackItem::podcast_episode`); its numeric id is a + shared sentinel and never identifies it. Queue keys check the episode id + first (`ep:…`), then music content ids, federated sources and library rows. + Music-only paths (likes, playlists, history, content-id resolution, + federation download, similarity, share links, metadata edits, release and + artist jumps) check `is_podcast()` and skip episodes. Sync protocol 3 + cannot describe an episode, so peers and Jam guests receive the shared + private placeholder, a queue with episodes is not handed off, and remote + `SetState` commands do not replace it. +- **Playback.** Starting an episode resolves its current audio URL and + resume position from the store, opens `podcasts::stream` (a bounded + Range-request reader on its own thread), decodes and positions it with + coarse seeking, all off the UI and audio threads, then hands the source to + the audio thread with the player's source generation. Any later start or + stop bumps that generation, so a slow stream never replaces what the user + chose since. A stale audio URL (4xx) triggers one feed refresh and a retry + with the address the feed lists for the same episode id. A stream that + cannot seek does not start at a saved position it cannot reach. +- **Progress.** `podcasts::progress` runs one writer thread so every + progress write of this device is ordered. The app tick follows the + position and actual listening time and sends: an explicit start (or + "start over"), checkpoints every 20 s and on pause, explicit seeks, + completion (`reaches_completion` or end of stream) and an end with the last + seen position on stop, track change, handoff and exit. When the store + reports a newer generation, the playback stops checkpointing until the + user's next explicit action. Listening sessions are recorded at pause, + completion and end; the store keeps those that pass the shared threshold. ## Scripted visualizations @@ -469,9 +497,10 @@ 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; +- `podcasts/` owns feed HTTP (conditional requests, redirects, limits), + refresh scheduling policy, the episode stream reader and the progress + writer; the podcast model, identity, merge rules 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 cf13b94..8acdd5c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -20,14 +20,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 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 episodes play from the Podcasts tab and the shared queue (mixed + with music): audio streams from the publisher through a bounded HTTP Range + buffer, Play continues from the saved position, `b` starts over, and the + position is saved every 20 s and on pause, seek, stop, track change and + exit. Completion and listening sessions follow the shared FRID rules. A + stale audio URL triggers one feed check for the episode's new address. - Podcast key bindings in the `podcasts` context: `o`, `/`, `Shift+R`, - `Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`. + `Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`, `b`. - 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. +- Queue items are keyed by their source: podcast episodes by episode id, + library rows as `lib:` instead of `local:`. Likes, playlists, + music history, similarity, share links and metadata edits skip episodes. +- Peers and Jam guests see podcast episodes as "Private item" (sync + protocol 3 cannot describe them); a queue with episodes is not handed to + another device and remote queue changes do not replace it. - 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 428a093..7edcda4 100644 --- a/README.md +++ b/README.md @@ -209,8 +209,31 @@ never imported into the music library or offered to other peers. 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 +Episodes play in the same queue as music: + +- `Enter` on an episode plays it right after the current item and continues + from the saved position; a played episode starts from the beginning. `b` + ("start over") plays it from the beginning even when it is in progress. + `a` / `Shift+A` queue episodes like tracks, and the queue can mix music and + episodes. +- Audio streams from the publisher's server through a bounded buffer (about + 9 MB) and seeks with HTTP range requests. Nothing is downloaded ahead of + time and nothing is kept after playback. If the server cannot seek (no + file length), Furumi says that it cannot continue at the saved position + instead of starting from the wrong place; "start over" still works. If the + episode's address no longer works, the feed is checked once for a new one. +- The position is saved every 20 seconds while playing and on pause, seek, + stop, track change and exit. An episode counts as played within the last + 30 seconds (or 5 %) or when its stream ends; a listen enters the episode's + history when it completed or lasted at least 30 seconds. Seeking back and + "start over" are real changes: an older save never moves the position + forward again. +- Likes, playlists, music history, similarity search and share links are for + music only and skip episodes; `Shift+J` on an episode opens its podcast. + +Episodes play on this device only for now: a queue with episodes cannot be +handed to another device, and other devices or Jam guests see episodes as +"Private item". 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.