Document lost connections, cancellation and seeks of episodes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-19 21:47:41 +02:00
1 parent 2989747162
commit 42f22f0fea
3 files changed
+32 -7

No files matched your search

+18 -3
View File
@@ -368,12 +368,27 @@ The TUI owns what the contract leaves to clients:
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.
cannot seek does not start at a saved position it cannot reach, and seeks
in it (or in an episode still connecting) are refused. The stream is
cancelled by the same generation: a superseded start stops connecting or
reading up to its resume offset, and a read blocked on a stalled server
inside the audio callback returns within 100 ms, so it cannot hold the
audio thread past the next stop or start. The player does not report the
end of a superseded source. Pause and resume pressed while a source is
prepared update the intent it starts with.
- **End of a stream.** The reader records whether the decoder stopped on a
read error (lost connection, expired URL, cancellation) and whether the
server announced the file size. Only an end that the server described, or
one within the completion window, completes the episode and moves the
queue on; otherwise the last seen position is saved and playback stops on
the episode (`playback::played_to_the_end`).
- **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
"start over"), checkpoints every 20 s and on pause, explicit seeks (saved
once the audio thread reports that the seek worked,
`PlayerEvent::Seeked`), completion (`reaches_completion` or the real end
of the stream) and an end with the last
seen position on stop, track change, handoff and exit. When the store
reports a newer generation (another device started over, for example), the
playback stops checkpointing until the user's next explicit action.
+5 -1
View File
@@ -36,7 +36,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
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.
stale audio URL triggers one feed check for the episode's new address. A
lost connection stops playback at the saved position (the episode is not
completed and the queue does not move on); a superseded or stalled stream
is cancelled at the next start or stop; pause pressed while an episode
connects is kept; seeks that do not move the audio are not saved.
- Podcast key bindings in the `podcasts` context: `o`, `/`, `Shift+R`,
`Ctrl+R`, `Shift+S`, `f`, `m`, `Shift+U`, `b`.
- An optional top-level `version` in `keymap.toml`; the current format is
+9 -3
View File
@@ -220,11 +220,17 @@ Episodes play in the same queue as music:
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.
instead of starting from the wrong place; "start over" still works, and
seeking in such an episode is refused with a message. If the episode's
address no longer works, the feed is checked once for a new one.
- If the connection is lost during an episode (no data for 30 seconds, or
the address stops working), playback stops there: the position is saved,
the episode is not marked played and the queue does not move on; play
continues from that position. A pause pressed while an episode is still
connecting is kept when the audio arrives.
- 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
30 seconds (or 5 %) or when its stream reaches its end; 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.