Ready means watched: know streams by what they carry, watch them, keep followed games warm #99

Merged
cmoriarty merged 2 commits from feature/ready-means-watched into develop 2026-11-07 23:17:40 -05:00
Owner

OpenSpec change: ready-means-watched. Milestone 36, "Ready means watched": closes the build step of #91, #94, #95, #96 and #97 (each stays open for its live check).

Why

Ole Miss vs. Georgia on 2026-11-07 was Ready all evening and unwatchable: 12 degrading swaps and 3 recoveries in 16 minutes across 10 sites.

  • It was one stream. All 10 sites carried the same stream, so no swap could help, and each cost a splice and usually filler.
  • The stream fell behind in stretches, about 0.8× real time, catching up in bursts a two-segment buffer could not cover.
  • Ready was a 10-second snapshot. Nothing asked whether a link keeps real time over minutes.
  • A copy counted as an alternative, and each swap reset the health verdict, so the channel swapped again a minute later.
  • A tune always started cold, so the app learned how a stream plays only once someone watched.

What changes

  • Stream identity (#91). A verified link records its stream's own clock and the JSON playlist's stream_id. Links are the same stream when their URLs, stream ids or clocks (within 20 s) agree. A game remembers the streams it moved away from for the cooldown, and walks hold them back.
  • The watch (#94, watch.py). The kept links of played, background and followed live games are polled every 1–3 s and sampled every 45 s. Each is graded Unproven for its first 2 minutes, then Steady or Choppy. A game's grade is its best stream's.
  • The best stream (#95). Followed live games keep a second standby. While nobody watches, a Steady standby replaces a Choppy stream, or a Steady one at least 20% shorter.
  • Stay put (#97). A degrading channel swaps only to a different stream graded Steady. A bursty stream gets a deeper buffer, up to 30 s. A Choppy game says so on its card, in the games list and in the guide. The filler card over a late stream names the standby being checked, or why it won't take over.
  • Background channels (#96, background.py). Up to CHANNEL_BACKGROUND_LIMIT (5; 0 is off) followed live Ready games play with nobody watching, so a tune finds them warm. They show plain filler, take each stream's shape, never spend a site read, and the Admin page shows them as Warm.

Load

About 25–50 KB/s per watched link (WATCH_LINKS_LIMIT, 24) and a stream's bitrate per background channel (about 15 Mbit/s at the limit). Both settings are in .env.example.

Tests

make test 984 passed, 1 skipped; npm --prefix frontend test 197 passed; make e2e passed; openspec validate ready-means-watched --strict passes. Not yet seen against a live game.

CI off for now

ci.yml now runs only when started by hand (Actions → ci → Run workflow) until the runners' disks are fixed. Its first run here timed out four TestClient teardowns past 120 s on the slow runner; the rerun passed both jobs. publish-image.yml still builds, checks and pushes the image on every develop push.

🤖 Generated with Claude Code

OpenSpec change: `ready-means-watched`. Milestone 36, "Ready means watched": closes the build step of #91, #94, #95, #96 and #97 (each stays open for its live check). ## Why Ole Miss vs. Georgia on 2026-11-07 was Ready all evening and unwatchable: 12 degrading swaps and 3 recoveries in 16 minutes across 10 sites. - **It was one stream.** All 10 sites carried the same stream, so no swap could help, and each cost a splice and usually filler. - **The stream fell behind in stretches**, about 0.8× real time, catching up in bursts a two-segment buffer could not cover. - **Ready was a 10-second snapshot.** Nothing asked whether a link keeps real time over minutes. - **A copy counted as an alternative**, and each swap reset the health verdict, so the channel swapped again a minute later. - **A tune always started cold**, so the app learned how a stream plays only once someone watched. ## What changes - **Stream identity (#91).** A verified link records its stream's own clock and the JSON playlist's `stream_id`. Links are the same stream when their URLs, stream ids or clocks (within 20 s) agree. A game remembers the streams it moved away from for the cooldown, and walks hold them back. - **The watch (#94, `watch.py`).** The kept links of played, background and followed live games are polled every 1–3 s and sampled every 45 s. Each is graded Unproven for its first 2 minutes, then Steady or Choppy. A game's grade is its best stream's. - **The best stream (#95).** Followed live games keep a second standby. While nobody watches, a Steady standby replaces a Choppy stream, or a Steady one at least 20% shorter. - **Stay put (#97).** A degrading channel swaps only to a different stream graded Steady. A bursty stream gets a deeper buffer, up to 30 s. A Choppy game says so on its card, in the games list and in the guide. The filler card over a late stream names the standby being checked, or why it won't take over. - **Background channels (#96, `background.py`).** Up to `CHANNEL_BACKGROUND_LIMIT` (5; 0 is off) followed live Ready games play with nobody watching, so a tune finds them warm. They show plain filler, take each stream's shape, never spend a site read, and the Admin page shows them as Warm. ## Load About 25–50 KB/s per watched link (`WATCH_LINKS_LIMIT`, 24) and a stream's bitrate per background channel (about 15 Mbit/s at the limit). Both settings are in `.env.example`. ## Tests `make test` 984 passed, 1 skipped; `npm --prefix frontend test` 197 passed; `make e2e` passed; `openspec validate ready-means-watched --strict` passes. Not yet seen against a live game. ## CI off for now `ci.yml` now runs only when started by hand (Actions → ci → Run workflow) until the runners' disks are fixed. Its first run here timed out four TestClient teardowns past 120 s on the slow runner; the rerun passed both jobs. `publish-image.yml` still builds, checks and pushes the image on every develop push. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Ready means watched: know streams by what they carry, watch them, keep followed games warm
All checks were successful
ci / Unit tests, type check, bundle (pull_request) Successful in 49s
ci / One container, e2e click-to-play inside the image (pull_request) Successful in 1m34s
662d700bcc
From Ole Miss vs. Georgia on 2026-11-07: Ready all evening and
unwatchable, 12 degrading swaps and 3 recoveries in 16 minutes across
10 sites. All 10 carried one stream, publishing at about 0.8x real time
in stretches; each swap went to a copy and reset the health verdict.

- Stream identity (#91): a verified link records its stream's own clock
  (newest segment's first PTS against the wall clock) and the JSON
  playlist's stream_id. Links are the same stream when their URLs,
  stream ids or clocks (within 20 s) agree. A game remembers the streams
  it moved away from for the cooldown; walks hold them back, and an
  urgent walk takes a copy only after 3 more links.
- The watch (#94, watch.py): the kept links of played, background and
  followed live games are polled every 1-3 s and sampled every 45 s; a
  playing channel feeds its own pulls in. Graded over 3 minutes:
  Unproven, then Steady or Choppy (more than 30 s of buffer needed,
  short of frames, or 3 errors). A game's grade is its best stream's.
- The best stream (#95): followed live games keep a second standby; a
  copy in the standby slot gives way to a different stream; while
  nobody watches, a Steady standby trades places with a Choppy stream,
  or a Steady one 20% shorter, with no cooling.
- Stay put (#97): the degrading swap needs a different stream graded
  Steady. A bursty stream gets a deeper buffer (up to 30 s worth). A
  Choppy game says so on its card and in the guide. The filler card
  over a late stream names the standby being checked, or why it will
  not take over.
- Background channels (#96, background.py): up to
  CHANNEL_BACKGROUND_LIMIT (5; 0 is off) followed live Ready games play
  with nobody watching, ranked both teams, one team, league, kickoff.
  They serve plain filler, take each stream's shape, never spend a site
  read, and show as Warm on the Admin page.
- WATCH_LINKS_LIMIT (24) caps the watched links.

OpenSpec change: ready-means-watched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The runners' slow disks time tests out that pass locally (PR #99's first
run: four TestClient teardowns past 120 s; the rerun passed). ci.yml now
runs on workflow_dispatch only; publish-image.yml still builds, checks
and pushes the image on every develop push. The old triggers are kept
in a comment to restore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
cmoriarty merged commit 732ab0aebc into develop 2026-11-07 23:17:40 -05: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!99
No description provided.