Document episode playback, queue identity and progress saving
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
9321e82335
commit
54db2978e0
4 files changed
+77
-9
No files matched your search
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in new issue
Block a user