gramps
a5c2061b55
Slice 5a, scaffolding only. 607 green.
- `Source.IsReplayLayer` + schema column + roundtrip: a media layer that shows saved clips instead of a
chosen file. The compositor needs to know nothing — it is a media layer whose path the VM owns.
- **Two spec corrections from the creator (2026-11-10), recorded in the task:**
1. The immediate replay of a fresh clip happens **only in the Live scene**. While it plays, **F10 is
inert** ("replay in progress").
2. That guard replaces the "layer excluded from its own clip" idea, which is **impossible** with one
encoder and two muxes: the clip is a second mux of the same frames, so it necessarily contains what
viewers saw. No second encode, no fiction about a clean feed.
Remaining for 65: the add-layer menu entry, `ClipSaved` → play (Live: once then hide; elsewhere: loop the
kept set), `SessionCompleted` → advance or hide, and silent-by-default audio.
72 lines
3.7 KiB
Markdown
72 lines
3.7 KiB
Markdown
# TASK 65 — Replay clips: buffer the last 15 seconds, show it, save it
|
||
|
||
> Catalog: [`TASKS.md`](../TASKS.md) — status and requirements live here.
|
||
> Spec settled with the creator 2026-11-09. **Not a Twitch-clip clone:** the platform owns viewer
|
||
> clips; this is the creator-side replay buffer YouTube does not give you.
|
||
|
||
## The rule
|
||
|
||
**15 seconds is a clip.** Options 10 / 15 / 20, default **15**, no slider, no 30. A clip is a moment,
|
||
not a segment — 3-minute Shorts are the platform's problem, not ours.
|
||
|
||
## Why the ring holds encoded bytes, not frames
|
||
|
||
A 1080p BGRA composite frame is 8.3 MB; fifteen seconds at 60 fps is **~7.4 GB** of raw frames. The
|
||
15 MB figure is *after* compression. So the ring keeps **fragmented MP4** (`frag_keyframe+empty_moov`)
|
||
that ffmpeg writes to a pipe, in a **byte ring in RAM** — never on disk, never raw.
|
||
|
||
- Fragments are **1 s** (not 2): the ring can only hand back whole fragments, so a longer fragment
|
||
means the save can miss the punchline.
|
||
- The buffer is capped **by bytes**, not seconds — bitrate moves. When 15 s would exceed the cap, the
|
||
clip is simply shorter.
|
||
- The ring is a member of the process: it dies with the app, so a crash leaves no debris and needs no
|
||
sweep. **Nothing touches the disk until F10.**
|
||
|
||
## Trigger
|
||
|
||
**F10** saves the clip (F1–F9 are taken; F11 is the fallback if a game steals F10). No focus switch, no
|
||
mouse. Deferred deliberately: **voice triggering** (always-listening in a streaming app is a privacy
|
||
liability, and the game's own audio produces false positives) and **`!clip`** (only for viewers/mods,
|
||
never the creator, who cannot reach a keyboard mid-moment).
|
||
|
||
## The replay layer
|
||
|
||
**Scope settled 2026-11-10:** the immediate replay of a fresh clip happens **only in the Live scene**.
|
||
While that replay is playing, **F10 is inert** ("replay in progress") — that is what replaces the
|
||
hall-of-mirrors exclusion, which is impossible with one encoder and two muxes: the clip *is* what the
|
||
stream got.
|
||
|
||
One layer type, added by the creator to the scenes they want; behaviour comes from the scene:
|
||
|
||
| Scene | Behaviour |
|
||
|---|---|
|
||
| **Live** | plays the new clip **once**, then **hides** — you're there to see it or you're not |
|
||
| Every other scene | loops the last **1–3** saved clips **in order** (highlight reel), configurable |
|
||
|
||
- **Audio off by default**, toggleable per layer. The show's sound design is the creator's; a replay
|
||
should not re-mix it uninvited.
|
||
- **No exclusion, no second encode.** The clip is a second mux of the frames the stream already got, so
|
||
it contains whatever viewers saw. Double-clipping is prevented instead: F10 does nothing while the
|
||
Live replay is playing.
|
||
|
||
## Storage and retention
|
||
|
||
- Saved to `clips\` beside recordings, as a normal `.mp4`.
|
||
- **The three most recent are kept**; the fourth deletes the oldest.
|
||
- **Auto-clip on monetization events** (off by default): a Super Chat / membership / raid saves the
|
||
preceding 15 s hands-free. Same retention, so it cannot accumulate.
|
||
- **Disk discipline:** no steady writes while live (the ring is RAM); the free-space guard that already
|
||
protects REC also disables the ring when space is low — **the recording always wins**.
|
||
|
||
## Privacy
|
||
|
||
Named in `PRIVACY.md`: clips are local only, the three most recent are kept, older ones are deleted
|
||
automatically, and nothing is uploaded. The first save says the same in one line, so the policy is not
|
||
only a document.
|
||
|
||
## Tests
|
||
|
||
- Ring: fragment boundaries respected, byte cap enforced, save emits a playable MP4, oldest pruned.
|
||
- Layer: once-then-hide in Live, in-order loop elsewhere, silent by default, layer excluded from the clip.
|
||
- Failure: save with an empty ring (just started) says so instead of writing a 0-byte file.
|