Steady streaming: keep pace, judge by the viewer, one video shape, and who's watching #60

Merged
cmoriarty merged 6 commits from feature/steady-streaming into develop 2026-10-31 00:38:59 -04:00
Owner

The Steady streaming batch (milestone 31): four OpenSpec changes from the night Wizards vs. Hornets froze 18 times in five minutes while the card said Healthy.

#56 keep-pace: a channel keeps pace with a source that limits each connection

  • Parallel downloads: up to three segments at once (CHANNEL_FETCH_CONCURRENCY). The clock, audio and listing still follow playlist order.
  • Polls on a schedule: every half target duration from the last poll's start, never waiting for downloads, and again at once after a burst.
  • A bounded backlog: a refresh appends at most eight segments that haven't landed.
  • A jump to the edge: when the next segment has left the source's window, the channel lands three from the edge and counts the skip. A recovery's own landing isn't counted.
  • The pace on the status view: how far behind the source the channel is, and its downloads in flight.
  • Virtual-time replay: the 2026-10-30 source keeps pace with three slots and falls behind with one.

#57 viewer-side-health: the channel judges its stream by what the viewer gets

  • The watch runs on the buffer's clock: it classifies every second and acts (recovery, or a swap in its own task), never waiting on a download.
  • Filler ahead of a late segment: filler goes in ahead of a segment still on its way, once the release is a target duration overdue.
  • What the viewer gets is counted: stalls the viewer sees (dry spells), the game served per second over the last minute, and the lag behind the source.
    • Stalling: two stalls in two minutes, or under 0.9× real time.
    • Falling behind: three segments behind the source, or a skip.
    • Slow downloads stay on the strip but no longer degrade on their own.
  • The card: never says Nothing to do while the channel stalls. It shows the served rate and the pace, and its trouble line counts stalls and skipped game.

#58 whos-watching: every viewer on the card

  • Sessions: each Emby and Jellyfin session on the channel, read from the servers' /Sessions while a channel plays and matched by tvg-chno. Each shows the user, device, local or remote, and play method, with a full transcode flagged.
  • Readers: readers that no session accounts for are counted by connection.

#39 steady-shape: one video shape for a channel's life

  • The channel's shape: the first stream's probed shape. Each landing's first segment is probed before it is listed.
  • Re-encode on mismatch: a stream of another shape is re-encoded to the channel's shape (x264 veryfast with the card's settings, timestamps kept, audio passed on). A matching stream is copied, and a failed re-encode is served as it came and counted.
  • Filler is drawn in the channel's shape.
  • No wait before a resize: a standby of another size swaps at once when matching is available (CHANNEL_VIDEO_MATCH, on by default).
  • The card says "matched to W×H".

Checks

  • openspec validate --strict passes for keep-pace, viewer-side-health, steady-shape and whos-watching.
  • make test: 808 passed, 1 skipped, in about 15 s.
  • Frontend: 186 passed. The build is clean.
  • make e2e passed. The channel leg rides through a 12 s cut, and Emby-style ffmpeg keeps writing.
  • One real ffmpeg re-encode in the lane, test_videonorm.py, probes at the target shape.

Closes #56, #57, #58, #39 once validated live.

🤖 Generated with Claude Code

The Steady streaming batch (milestone 31): four OpenSpec changes from the night Wizards vs. Hornets froze 18 times in five minutes while the card said Healthy. ## #56 keep-pace: a channel keeps pace with a source that limits each connection - **Parallel downloads:** up to three segments at once (`CHANNEL_FETCH_CONCURRENCY`). The clock, audio and listing still follow playlist order. - **Polls on a schedule:** every half target duration from the last poll's start, never waiting for downloads, and again at once after a burst. - **A bounded backlog:** a refresh appends at most eight segments that haven't landed. - **A jump to the edge:** when the next segment has left the source's window, the channel lands three from the edge and counts the skip. A recovery's own landing isn't counted. - **The pace on the status view:** how far behind the source the channel is, and its downloads in flight. - **Virtual-time replay:** the 2026-10-30 source keeps pace with three slots and falls behind with one. ## #57 viewer-side-health: the channel judges its stream by what the viewer gets - **The watch runs on the buffer's clock:** it classifies every second and acts (recovery, or a swap in its own task), never waiting on a download. - **Filler ahead of a late segment:** filler goes in ahead of a segment still on its way, once the release is a target duration overdue. - **What the viewer gets is counted:** stalls the viewer sees (dry spells), the game served per second over the last minute, and the lag behind the source. - **Stalling:** two stalls in two minutes, or under 0.9× real time. - **Falling behind:** three segments behind the source, or a skip. - Slow downloads stay on the strip but no longer degrade on their own. - **The card:** never says Nothing to do while the channel stalls. It shows the served rate and the pace, and its trouble line counts stalls and skipped game. ## #58 whos-watching: every viewer on the card - **Sessions:** each Emby and Jellyfin session on the channel, read from the servers' `/Sessions` while a channel plays and matched by `tvg-chno`. Each shows the user, device, local or remote, and play method, with a full transcode flagged. - **Readers:** readers that no session accounts for are counted by connection. ## #39 steady-shape: one video shape for a channel's life - **The channel's shape:** the first stream's probed shape. Each landing's first segment is probed before it is listed. - **Re-encode on mismatch:** a stream of another shape is re-encoded to the channel's shape (x264 veryfast with the card's settings, timestamps kept, audio passed on). A matching stream is copied, and a failed re-encode is served as it came and counted. - **Filler** is drawn in the channel's shape. - **No wait before a resize:** a standby of another size swaps at once when matching is available (`CHANNEL_VIDEO_MATCH`, on by default). - **The card** says "matched to W×H". ## Checks - `openspec validate --strict` passes for keep-pace, viewer-side-health, steady-shape and whos-watching. - `make test`: 808 passed, 1 skipped, in about 15 s. - Frontend: 186 passed. The build is clean. - `make e2e` passed. The channel leg rides through a 12 s cut, and Emby-style ffmpeg keeps writing. - One real ffmpeg re-encode in the lane, `test_videonorm.py`, probes at the target shape. Closes #56, #57, #58, #39 once validated live. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
#56: the one-at-a-time puller served Wizards vs. Hornets at 0.64x real
time from a CDN that limits each connection. Downloads now run up to
CHANNEL_FETCH_CONCURRENCY (3) at once, polls start every half target
duration from the last poll's start without waiting for them, a refresh
appends at most eight segments not yet landed, and a next segment gone
from the source's window lands three from the edge with the skip
counted. The status view carries the pace. A virtual-time replay of the
source keeps pace with three slots and falls behind with one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
While a channel plays, the media servers' sessions are read every 10 s with the guide refresh's servers and keys, and kept per channel number with the user, device, local or remote and play method. A channel counts its readers by connection, so two sessions through one address and agent show as two viewers, and readers no session accounts for are listed by their client. The card shows the count with the list behind it and flags a full transcode in amber (#58).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#57: the Hornets froze 18 times in five minutes while the card said
Healthy and counted 0 stalls. With the buffer on, its one-second clock
now classifies and acts (recovery, or a swap in its own task), never
waiting on a download. Filler goes in ahead of a segment still on its
way once the release is a target duration overdue. The channel counts
the stalls its viewer sees (dry spells), the game served per second over
the last minute, and how far behind its source it is; two stalls in two
minutes or under 0.9x real time make it Stalling, three segments behind
or a skip make it Falling behind. Slow downloads stay on the strip but no
longer degrade by themselves. The card never says Nothing to do while
the channel stalls, and shows the served rate and the pace.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
#39: a degrading swap from 1152x648 at 59.94 fps to 1280x720 at 30 fps
ended Emby's VAAPI-to-QSV transcode on Wizards vs. Hornets. The channel's
first stream's shape (size, rate, H.264 profile, level, reordering
depth, refs, aspect ratio) is now its shape for life. After each landing
the new stream's first segment is probed before it is listed, and a
stream of another shape is re-encoded to the channel's with x264
veryfast (videonorm.py), timestamps kept and audio passed on; a matching
stream is copied, a failed re-encode is served as it came and counted.
The filler is drawn in the channel's shape, a standby of another size
swaps at once when matching is available (CHANNEL_VIDEO_MATCH, on by
default), and the card says "matched to W×H".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A recovery across an outage is not counted as skipped game
All checks were successful
ci / Unit tests, type check, bundle (pull_request) Successful in 47s
ci / One container, e2e click-to-play inside the image (pull_request) Successful in 1m46s
7829ff2685
A landing's own first pull lands near the source's edge by design; the
outage's stall already counts the gap. Counting it as a skip marked the
recovered stream Falling behind for two minutes, and with a ready
standby it would have swapped away right after recovering (seen in the
e2e's channel leg). Only the puller's routine polls count skips now.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cmoriarty merged commit f57fd129d3 into develop 2026-10-31 00:38:59 -04:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
cmoriarty/sports-breaker!60
No description provided.