Document episode playback, queue identity and progress saving

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 20:28:36 +02:00
1 parent 9321e82335
commit 54db2978e0
4 files changed
+77 -9

No files matched your search

+7 -3
View File
@@ -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
+32 -3
View File
@@ -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;
+13 -1
View File
@@ -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:<id>` instead of `local:<id>`. 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.
+25 -2
View File
@@ -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.