gramps
ed32151136
Design settled with the creator. Two findings drove it:
- **Resolution is not a bandwidth lever.** 1080p30 and 720p60 are both 6 Mbps in the shipped table,
so "step down to 720p" relieves nothing against congestion; and 60→30 at the same bitrate relieves
nothing either. Congestion therefore steps **bitrate only** (8.0 → 6.4 → 5.1 → 4.1, ~20%), which is
what OBS Dynamic Bitrate does — cited, adopted, with its climb-back discarded for v1.
- **The other half has no OBS equivalent**: machine starvation (the game and the app on one PC) steps
fps, then resolution, and sheds LlamaCasty's own capture cost *first*. That is the app taking
responsibility for a stream it is helping to starve.
Budgets as ruled: 3 steps for a 1080 start, 1 for 720 and vertical, hard floors at 720p30 /
Vertical 1080p30, hold-and-warn at the floor, never disconnect. Trigger ≥5% drops over 15 s twice,
30 s cooldown, ambiguous evidence does nothing.
New rule in `ui-surface.md`: a toast names the cause, the culprit and the remedy. Mechanism strings
("All pipe instances are busy", HTTP codes, exit codes) are log findings, never user-facing copy.
69 lines
3.8 KiB
Markdown
69 lines
3.8 KiB
Markdown
# TASK 33 — Automatic step-down when the show can't hold its tier (queued 2026-09-01; v1)
|
|
|
|
> Catalog: [`TASKS.md`](../TASKS.md) — status and requirements live here.
|
|
> Design settled with the creator 2026-11-09. **Not a magenta question of taste: this is the app
|
|
> admitting it is part of the problem when it is.**
|
|
|
|
**Goal:** the stream degrades *predictably and honestly* instead of drowning viewers in freeze frames
|
|
— and when LlamaCasty itself is the starving process, it says so out loud instead of blaming the
|
|
creator's connection. The `variable` reusable stream (shipped) makes every step zero-API: a tier or
|
|
bitrate change is just an encoder relaunch at the same URL.
|
|
|
|
## Cause first, lever second
|
|
|
|
| Cause | Signal | Lever |
|
|
|---|---|---|
|
|
| **Machine starvation** — the PC (often the game) can't make the frame | pump stalls, render time over the frame budget, frames never produced | reduce work: **60 → 30 fps**, then **1080 → 720** |
|
|
| **Upload congestion** — the socket can't carry the bits | frames produced on schedule but rejected; encoder queue full; **rising submit block time** (pump already logs `avg submit` / `avg wait`) | reduce bits: **8.0 → 6.4 → 5.1 → 4.1 Mbps** (~20% steps), geometry untouched |
|
|
|
|
Resolution is **not** a bandwidth lever: 1080p30 and 720p60 are both 6 Mbps in the shipped table, so
|
|
that step relieves nothing. Fps is **not** a congestion lever: same bitrate, same socket.
|
|
|
|
## Shed our own load before asking the viewer to pay
|
|
|
|
1. If our capture/convert cadence is what starves, **halve our own capture rate first** — same output
|
|
tier, less of the creator's machine. This is the "budget streamer self-streaming gameplay" case.
|
|
2. Only then step fps, then resolution.
|
|
|
|
## Budgets, floors, terminal state
|
|
|
|
| Start | Steps allowed | Worst case it can reach |
|
|
|---|---|---|
|
|
| 1080p60 | **3, any mix of the two ladders** | 720p30 @ 6.4 Mbps |
|
|
| 720p60 | **1** | 720p30 @ 4.8 Mbps |
|
|
| Vertical 1080p60 | **1** | Vertical 1080p30 @ 6.4 Mbps |
|
|
|
|
- Floors: 16:9 never below **720p30**; vertical never below **Vertical 1080p30**.
|
|
- Budget exhausted → **hold**, keep streaming, one persistent warning naming the cause, manual
|
|
step-up stays available. Never disconnect, never nag repeatedly.
|
|
- Trigger: ≥5% dropped over 15 s, twice, 30 s cooldown between steps. Mixed/ambiguous evidence does
|
|
nothing. One-way within a broadcast (no climb-back; revisit with session data).
|
|
|
|
## Own the mistake in plain words
|
|
|
|
A toast that reports a mechanism is a bug in the toast. Every message names **what happened, who
|
|
caused it, and what the app already did** — no exception text, no error codes:
|
|
|
|
- ours: *"LlamaCasty couldn't keep up with your scene, so it lowered the frame rate to 30. Your
|
|
connection wasn't the problem."*
|
|
- theirs: *"Your upload couldn't hold 8 Mbps, so LlamaCasty dropped it to 6.4 to stop the freezing.
|
|
It will stay there for this stream."*
|
|
|
|
One toast per step, plus one session-report line (`quality stepped down 12:04 — encoder` / `—
|
|
upload`) so support answers from data, not memory. Wording rules live in
|
|
[`docs/ai/ui-surface.md`](../docs/ai/ui-surface.md) → Toast notifications.
|
|
|
|
## Tests
|
|
|
|
Pure `StepDownPolicy` units (classifier, both ladders, budgets, floors, cooldown, one-way, ambiguity →
|
|
no action) + the ONE integration: a fake health stream with sustained drops of each cause produces the
|
|
matching step and exactly one encoder restart.
|
|
|
|
## Reference
|
|
|
|
OBS Dynamic Bitrate (27.2) is the established answer for the congestion half: bitrate-only, small
|
|
steps, hysteresis. **Adopted:** bitrate as the sole congestion lever, stepped with cooldown.
|
|
**Discarded for v1:** its automatic climb-back (the creator's one-way ruling). **Ours:** the
|
|
machine-side ladder and "shed our own cost first" — OBS has no equivalent, and that is the half that
|
|
matters when the game and the app share one machine.
|