A channel holds a buffer behind its live edge, its filler matches the stream, and the e2e runs in 30 s #54

Merged
cmoriarty merged 3 commits from feature/steady-live-edge into develop 2026-10-29 22:37:01 -04:00
Owner

Closes #53 and #50 once seen in Emby. Also #44's e2e speed-up.

#53: a buffer behind the live edge

  • The buffer. The channel holds its newest two ready segments (CHANNEL_BUFFER_SEGMENTS, 0 = off) and lists the oldest whenever the listed video would have played out, whether or not the source delivered since. A buffer over its depth (a burst, a cold start's backlog) releases at once. A separate 1 s clock task does the releasing, so a pull stuck on a slow fetch can't stop the playlist.
  • Replayed against the Packers arrivals of 2026-10-29 (Emby's fetch times, 21:15–21:18), for a player joining 3 segments from the edge:
    • without the buffer, the player's video in hand hit 0 s at the 19 s gap, the freeze;
    • with two segments, it never dropped below 12 s.
  • The cost: about 12 s more delay.
  • Late segments count. Segments released more than half their duration late count against the upstream. Three of the last five make it degrading, shown as Running late, so a better standby takes over by the usual swap rule.

#50: filler in time, matching the stream

  • Filler in time. When the buffer is empty and the next release is half a target duration overdue, filler goes in whether or not recovery has started. While the stream still plays, the card is headed "Waiting for the stream". Before this, filler waited for FAILED (2× target duration), after the player had already run dry.
  • A matching card. The card is encoded with the stream's H.264 profile, level, reordering depth, reference frames and aspect ratio. These are probed after each landing and recorded with each verification, and saved in the readiness snapshot.
    • x264's features are chosen to land on the same profile: CABAC for Main, the 8×8 transform for High, B-frames with or without a pyramid for a reordering depth of 1 or 2.
    • Checked by ffprobe in test_fillercard.py for Main 3.1, High 4.0 and Constrained Baseline.

Admin card

  • "Buffer 12 s" sits beside the health; it turns amber once the buffer has run dry.
  • Running late shows with an "N of 5 late" chip.

#44: the e2e in about 30 s instead of about 2 min

Measured in the image, --network none, on an arm64 build: 128 s → 29 s.

  • The fake feed and source servers' listen backlog was 5. A page load opens dozens of feed reads at once, and the overflow was answered only on TCP's retries 1–15 s later. That made 10–12 s page loads, and very likely run 277's flake (a retry past the app's 10 s feed timeout drops a sport from the list).
  • The real-page attempt is skipped without a route to the internet, so it doesn't run in CI.
  • The channel leg runs alongside part (b), with its own app and fake source.
  • The fake live stream advances by the clock, not once per fetch.
  • Fixed sleeps became waits for the condition.

Checks

  • openspec validate steady-live-edge --strict passes.
  • make test passes: 769 tests. The lane runs with the buffer off, as it does with the audio step; the buffer's own tests switch it on.
  • The frontend tests pass: 180.
  • make e2e passes locally in 45 s with the buffer on. The channel leg rode through a 12 s cut on filler and resumed.

Known limits (in the proposal):

  • A segment still being fetched holds the listing behind it, so a download slower than the buffer still reaches the player as a gap.
  • A swap onto another site's stream still changes the H.264 settings at that splice.

🤖 Generated with Claude Code

Closes #53 and #50 once seen in Emby. Also #44's e2e speed-up. ## #53: a buffer behind the live edge - **The buffer.** The channel holds its newest two ready segments (`CHANNEL_BUFFER_SEGMENTS`, 0 = off) and lists the oldest whenever the listed video would have played out, whether or not the source delivered since. A buffer over its depth (a burst, a cold start's backlog) releases at once. A separate 1 s clock task does the releasing, so a pull stuck on a slow fetch can't stop the playlist. - **Replayed against the Packers arrivals of 2026-10-29** (Emby's fetch times, 21:15–21:18), for a player joining 3 segments from the edge: - without the buffer, the player's video in hand hit **0 s at the 19 s gap**, the freeze; - with two segments, it never dropped below **12 s**. - **The cost:** about 12 s more delay. - **Late segments count.** Segments released more than half their duration late count against the upstream. Three of the last five make it degrading, shown as **Running late**, so a better standby takes over by the usual swap rule. ## #50: filler in time, matching the stream - **Filler in time.** When the buffer is empty and the next release is half a target duration overdue, filler goes in whether or not recovery has started. While the stream still plays, the card is headed **"Waiting for the stream"**. Before this, filler waited for FAILED (2× target duration), after the player had already run dry. - **A matching card.** The card is encoded with the stream's H.264 profile, level, reordering depth, reference frames and aspect ratio. These are probed after each landing and recorded with each verification, and saved in the readiness snapshot. - x264's features are chosen to land on the same profile: CABAC for Main, the 8×8 transform for High, B-frames with or without a pyramid for a reordering depth of 1 or 2. - Checked by ffprobe in `test_fillercard.py` for Main 3.1, High 4.0 and Constrained Baseline. ## Admin card - **"Buffer 12 s"** sits beside the health; it turns amber once the buffer has run dry. - **Running late** shows with an "N of 5 late" chip. ## #44: the e2e in about 30 s instead of about 2 min Measured in the image, `--network none`, on an arm64 build: 128 s → 29 s. - **The fake feed and source servers' listen backlog was 5.** A page load opens dozens of feed reads at once, and the overflow was answered only on TCP's retries 1–15 s later. That made 10–12 s page loads, and very likely run 277's flake (a retry past the app's 10 s feed timeout drops a sport from the list). - **The real-page attempt is skipped without a route to the internet**, so it doesn't run in CI. - **The channel leg runs alongside part (b)**, with its own app and fake source. - **The fake live stream advances by the clock**, not once per fetch. - **Fixed sleeps became waits for the condition.** ## Checks - `openspec validate steady-live-edge --strict` passes. - `make test` passes: 769 tests. The lane runs with the buffer off, as it does with the audio step; the buffer's own tests switch it on. - The frontend tests pass: 180. - `make e2e` passes locally in 45 s with the buffer on. The channel leg rode through a 12 s cut on filler and resumed. **Known limits** (in the proposal): - A segment still being fetched holds the listing behind it, so a download slower than the buffer still reaches the player as a gap. - A swap onto another site's stream still changes the H.264 settings at that splice. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
#53: the playlist keeps the newest ready segments (CHANNEL_BUFFER_SEGMENTS,
two by default) and lists the oldest whenever the listed video would have
played out, whether or not the source delivered since; a buffer over its
depth releases at once. A source that sends late and then two at once
reaches the player as a steady edge: replaying the Packers arrivals of
2026-10-29, a player that ran dry at the 19 s gap keeps 12 s ahead.

#50: when the buffer is empty and the next release is half a target
duration overdue, filler goes in whether or not recovery has started,
headed "Waiting for the stream" while the stream still plays. The card is
encoded with the stream's H.264 profile, level, reordering depth,
reference frames and aspect ratio, probed after each landing and recorded
with a link's verification, so a VAAPI-to-QSV transcode can cross it.

Segments released late count against the upstream (three of five:
Running late), and the Admin card shows the buffer.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Issue #44. Measured with docker run --network none on a native build:
128 s before, 29 s after. Locally with a network: 93 s before, 44 s after.

- The fake feed and fake source listen with a backlog of 128. The default
  backlog of 5 overflowed on every page load, and Linux answered the
  dropped connections only on TCP's retries: each page took 10-12 s to
  show its list in the image. A read left for the 15 s retry outlasts the
  app's 10 s feed timeout, which is the likeliest cause of run 277's
  "'Hawks vs. Magic' is not shown on the page".
- The checks also ask /api/games again until every expected game is
  listed, before part (a) and before each leg that opens the page, and the
  page check waits for the matchups. A whole list costs no extra time.
- The real-page try runs only where the host has a route off itself. A
  UDP connect sends nothing, and it fails at once under --network none.
- The channel leg runs in a thread beside parts (a) and (b), with its own
  app and its own fake source, so its cut reaches no other leg's stream.
- The fake live playlist moves one segment a second by the clock. It used
  to move one segment per fetch, so every channel the app kept polling
  sped it up, and the eighth row took 7 s to play instead of 1.
- The recording leg waits for 80 KB to be written, not a fixed 5 s. The
  page and file polls are tighter. The tuner ffmpeg is killed once the
  checks are done, where SIGTERM took 2-3 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The steady-live-edge checks pass: strict validation, make test, the frontend tests and the e2e
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 2m0s
01e727befe
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cmoriarty merged commit 3dbd4c870d into develop 2026-10-29 22:37:01 -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!54
No description provided.