# The clip bench

`/browse/<project>/clip/<id>`.

"How much context does this clip need" used to be a loop of hand-editing JSON,
re-running two CLIs and watching an mp4. This is that loop in one place.

## One screen, from `lg` up

Walking a cut is sixty clips in a row, and the bench used to stack two 16:9
players and three paragraphs of prose — so the attribution fields, the point of
the walk, were below the fold on every one of them and "did I check that" became
a scroll position.

The bench is now exactly the space the page has left: a header line (where you
are, the neighbours, and the renderer's own line, live), then a two-column grid
sized to the viewport. Nothing outside a column scrolls. The player takes
whatever height is left (`object-contain`, not an aspect ratio), its window
readout and buttons are one row under it, and the **second** player — looked at
once per clip, after a render — folds into a `<details>` strip with the
`resolve-windows` locks. The warnings stay unfolded and one line each: a warning
behind a summary is a warning nobody reads. Below `lg` it is a single scrolling
column; a phone cannot hold this and pretending otherwise would cost the desk
case something.

## Absolute source seconds, everywhere

The manifest's numbers, the cue file's, the QR's. The cached file's own start
(`fetchStart`) is the **only** relative number in the component, and it exists
solely to set `video.currentTime`. The moment those two are allowed to mix is the
moment a window is off by the pad and nobody can see why.

## The preview is the cached file, served whole

`out/clips-raw/<video>_<a>-<b>.mp4`, with byte ranges, and all windowing happens
in the browser. No ffmpeg per drag.

**A 206 is not optional** — without one the `<video>` element will not seek in a
stream it did not fully download, and that is the entire interaction. The file is
immutable (its window is in its name), so it is cached hard and `analyseMedia`'s
envelope can never miss twice for the same window.

`file` must be a member of the server's own scan of that clip's cached windows.
Never a path from the client.

**The scan is filtered to the files that hold THIS clip.** `clips-raw` is keyed
by *video*, and a report cites one stream more than once — ElfpireEva cites
`07ZaDnyzO1g` four times — so the directory holds a file per clip and "the
widest file for this video" is another clip's file as often as not. The bench
then sets `currentTime = start - fetchStart` and seeks 1146 s into a 44-second
file. `windowsFor()` keeps only files that overlap `[start, end]` and sorts
*containing* first, then by overlap, then by width. A clip with nothing cached
gets an empty list — "nothing fetched for this clip yet", which is true — rather
than somebody else's window. A caller with no window at all (a ledger claim asks
for its video's files and picks by cite) still gets every file, widest first.

## A drag never downloads

Dragging past the cached window **clamps** and offers a button. A handle that
silently starts a 12-second network fetch is a handle you stop trusting.

The fetch **asks the editor** (`POST /api/media/fetch-window`), which downloads
the window through its managed path — the channel's cookie policy, its extra
args, the per-platform sleeps, the 429 cooldown and the backoff — and writes it
into the corpus at `channels/<slug>/data/<id>/clips/<from>-<to>.mp4` with a
sidecar saying who asked and why. Containing-window reuse then makes that
generous fetch **be** the build's cache rather than a second one, and because
the corpus is keyed by video it is the *next report's* cache too: `out/clips-raw`
is one project's directory, and a report that cites the same stream used to pay
for the same seconds again.

The window is not a download. No `metadata.info.json` is written, so the video
stays exactly as undownloaded — and as absent from the archive index — as it
was. See [report-video.md](report-video.md#where-the-bytes-come-from-the-editor-not-yt-dlp).

`UMTOOL_LOCAL_FETCH=1` runs the pipeline's own `--fetch-only` path instead, for a
machine with no editor to ask. Same file naming, same format pin, same Rumble
HLS retry, same NDJSON events.

**"Fetch N unfetched clips via the editor"**, above the cut on the project page,
closes the whole `ready N of M` gap in one press — the clips that need judgement
with nothing cached holding them, one at a time, awaiting each before starting
the next. Stop abandons rather than kills: the in-flight fetch is already paid
for, so Stop means *start no more*.

Past the source's own duration the handle stops for good.

**The pad is measured from the CLIP, not from the cache**, and that cost one
confusing session: `--fetch-only --pad P` means `[start-P, end+P]`, the pipeline
reuses any file that already contains it, and the button used to ask for a flat
20 every time. On a window already fetched at pad 20 — or at the pad 10 an
earlier CLI run used — the second press downloaded nothing, exited 0, and the
bench said *"fetched"* over a cache that had not moved. So the button computes
its pad from what is on disk right now and **says the number** ("fetch to
±40 s"), the route refuses a window it can already serve (*"already cached to
±N s"*) rather than running a job to prove it, and a job that did run still has
to produce a wider file before the bench claims anything arrived. At
`FETCH_MAX_PAD` it says so instead of offering a press that cannot help.

**One edge at a time.** Extending a window is nearly always one-sided — you
want the sentence that follows, not another twenty seconds of the lead-in you
already heard — so a symmetric pad made every "20 more" twice what was asked
for. `--fetch-only` takes `--pad-before` and `--pad-after` (with `--pad` as the
shorthand that sets both), `POST /api/report/fetch` takes `padBefore` /
`padAfter`, and the bench offers two controls: *"← fetch to −23 s"* and *"fetch
to +23 s →"*, each computing its own side from what is cached on that side and
passing the OTHER side through unchanged, so the file that lands still contains
the one it replaces. A side that cannot grow says which reason it is — *"the
recording starts here"* or the pad cap — rather than offering a press that
cannot help. The message after a fetch names the side that moved.

**And a third control, for when neither edge is the answer.** *"fetch whole
source via editor"* posts `full: true`, which the editor answers by putting the
ENTIRE recording in its saved-video store — not in `clips/`, because that is
where big containers already live with a retention rule that leaves an
explicitly-requested one alone. It skips the cached-window check on the way
(that check asks "does a file hold this span", and a whole recording is not a
span), and `clipWindowDirs` reads the pointer back so the build treats the
container as the window `[0, duration]`: every clip of that video is then
fetched at once, and re-cutting costs nothing. It is a separate, plainly
labelled button rather than a smarter default because a recording can be
gigabytes of somebody's bandwidth. There is no `UMTOOL_LOCAL_FETCH` twin — a
machine with no editor has nowhere to put a full source that anything else
would find.

**The words run as words, under the rail.** The rail is a timeline — it
squeezes each cue into a column a few characters wide, which is right for
dragging an edge against and useless for reading, and reading is why anybody
peeks ahead. So the same cues also run in a transcript pane below it, in the
export site's own layout (`common/components/TranscriptModal.tsx`): a monospace
`m:ss` column, the text beside it, the selection lit, the playing line marked
and followed, sibling clips' lines badged with their id, and a single rule
where the cache ends rather than a shade of grey to squint at. Clicking a line
inside the cache plays from it; clicking one outside fetches to it. The pane
and the player share the leftover height 2:3, so neither is a strip.

**Read ahead before you pay for it.** The cue rail runs ±60 s past the cached
file (one request to `/api/report/cues`, text from the archive and cheap beside
media). Everything outside the cache is dimmed, both cache edges are marked, and
the cached stretch — the part the waveform above is showing — is shaded, so the
two scales cannot be mistaken for one. Clicking a dimmed cue fetches exactly far
enough to reach it plus two seconds, **on that cue's side only**; "peek further",
in the pane's own sticky footer, widens the reading by another 60 s without
downloading anything.

## Three things the JSON cannot show you

**Ends mid-sentence**, quoting the cue the cut lands inside — because "ends
mid-sentence" alone does not tell you what you are cutting off. One 14-clip cut
shipped with 8 clips ending mid-thought. `lockEnd` is the acknowledgement and
silences it.

**This source has no punctuation**, when the ASR emitted no terminators at all.
Then *every* clip "ends mid-sentence" and the fact says nothing about the cut, so
the answer is `null` — cannot be known — rather than a confident `false`. Set
those edges by ear and lock them.

**What the widener would do**, computed in-process because `widen()` is pure once
the cues are read. Moving an edge somewhere `resolve-windows` would not produce
means the next `--write` reverts it, so the bench offers to set the matching lock.
That is why five of six real manifests are 100% locked. "Run the widener and see"
stops being a leap of faith.

## The attribution, beside the edges

Watching a clip is when you find out *both* that it starts too late *and* that
the header calls it by the archive's title and the archive's upload date — which
for a VOD mirror is years after the stream. So the five fields that decide the
burned-in line — `title`, `date`, `cite`, `citeUrl`, `quote` — are in the same
panel as the handles, each saving on blur or <kbd>Enter</kbd>, each showing what
it was when it differs from what is saved.

Above them is a **live preview of the exact line ffmpeg will draw**, built by
calling the renderer's own `attributionLine()` from
`report-to-video/attribution.mjs`. Not a reimplementation: a preview that
disagrees with the header by one character is worth less than no preview,
because the only way to discover it is a twenty-minute build.

Beside the preview is the archive's own answer — *"the archive says `<title>` ·
`<uploadDate>`"* — because "the date is wrong" is only visible when you can see
which date it would otherwise use. An empty field goes back to it.

`date` is refused unless it is a real calendar day, and `citeUrl` unless it is
`http(s)`; the message comes back from the writer and lands under the controls,
with what you typed left in the box to fix.

## On-screen title and subtitle

When the on-screen deck is on (`render.chrome` — see
[report-video.md](report-video.md#the-on-screen-deck-renderchrome)) the bench
gets two more fields beside the attribution ones: `onscreen.title` and
`onscreen.subtitle`. Same save rule — on blur or <kbd>Enter</kbd>, empty
deletes the key — and each shows the auto line it falls back to as its
placeholder, so a blank box reads as "using the automatic line" rather than as
"empty".

Beside them is a live strip of the deck itself at this clip's moment, fed by
`postMessage` rather than a server round trip: the SAME composition the build
renders, so a keystroke is seen in its real face and its real text fit before
anything is saved.

## `correction` — a message to the next report pass

The sixth field in that panel is not about this video at all. It records what the
**report** got wrong about this clip — wrong speaker, wrong addressee, wrong date
— and nothing renders it. The project page collects every one under *corrections
for the next pass*, and `umtool corrections <project>` prints the same list as
markdown with each clip's own moment link, ready to paste into the next sweep.

It is not filed as a decision because nothing here can close it: the fix belongs
to the next sweep, not to this manifest.

## Re-render this one clip, and watch it

The `preview` preset is one clip and nothing else, and a segment is
content-addressed by its clip id — so the button overwrites exactly the file you
are looking at and touches no deliverable. The job is polled the way the wider
fetch is, and when it finishes the built segment plays in a second player.

That is the only place the attribution can be *checked* rather than believed: the
header is drawn by ffmpeg from a text file, and no amount of HTML can promise it
wrapped the same way.

`GET /api/report/segment` serves it — names not paths, byte ranges, the same
root resolution `/raw` uses. A re-render writes the **same path**, so the file's
mtime is in the URL: a request whose `v` matches is immutable for an hour, and one
whose `v` does not is served `no-store` rather than handing back the cut from
before the edit.

## Walking the cut

`p` and `n` (and the links in the header line) move to the previous and next
clip **on the walk**, computed server-side. Reviewing a cut is watching nineteen
clips in a row, and going back to the project page between each one is nineteen
round trips to re-find your place. The project page starts the walk: one
**"Walk the cut → start at `<first clip on it>`"** button above the rows,
because the per-row links are the right control for "go to that one" and the
wrong one for "start".

### What the walk skips

The walk visits the clips that still **need judgement** and are **fetched**, in
timeline order — so `p`, `n`, both header links, the start button and the jump
<kbd>y</kbd> makes after it confirms all go to the nearest one of those.

- **Needs judgement** means no verdict: the same rule `N reviewed` counts by.
  Walking back onto a clip somebody already answered is the round trip the walk
  exists to remove.
- **Fetched** means some file in `out/clips-raw` holds this clip's own window
  end to end. Not the *padded* window a build would download, and not an
  overlap: a half-covered clip cannot be watched through, so there is nothing
  to judge. Landing on one is a dead end whose only move is `n` again.

A **URL still opens any clip**, judged or unfetched — the bench renders it, says
*"nothing fetched for this clip yet"* and carries a **not fetched yet** pill,
and its two links point at the fetched, unjudged neighbours either side. The
per-row link on the project page is that URL, so "go to that one" is unchanged.

Both pages read **`ready N of M needing judgement`**: `M` is the clips with no
verdict, `N` the ones among them that can be judged today. The gap between the
two is what is waiting on a download rather than on you — every row the project
page marks **not fetched yet**.

### Is this accurate?

A clip is a **claim** — the report said somebody said this, here — so the right
column opens with what this clip is *supposed to be* (its `quote`, and its
`note`: why it is in the cut) and then asks the one question the walk exists to
answer.

<kbd>y</kbd> confirms and **advances** — to the next clip on the walk, which is
the next one that needs an answer and has something to play — because in the yes
case that clip is what you want and a walk of sixty clips should be one finger. <kbd>x</kbd> puts
the cursor in the `correction` box and marks it **required**, because the note
*is* the no answer — and saving it stays put, so it can be read back against the
clip. That save is ONE patch, `{correction, verdict: "incorrect"}`, so the
manifest never holds a complaint with no verdict.

An edge you nudged but never saved is confirmed WITH the clip: if the selection
differs from the stored window, <kbd>y</kbd> carries `start`/`end` (and clears a
cut the new extent no longer contains) in the same patch as the verdict, so
walking on never loses the window you just chose.

A note on a clip that is already **confirmed** is just a note — why its window
moved, a caveat for the writers — and writing one there leaves the verdict
alone. The state line reads *not yet reviewed*, *confirmed*, *confirmed · with
note* or *incorrect*, and the header counts how much of the cut has been
reviewed. See
[report-video.md](report-video.md#verdict--what-the-walk-said) for what is
stored and what the writer refuses.

## The extent you reviewed, and the cut that plays

The window you drag is the clip's **extent** — how much of this recording is
worth having. What the video plays is the **cut**, derived from where the quote
actually is inside it (see
[extent vs cut](report-video.md#extent-vs-cut--startend-and-cutstartcutend)).

Under the window readout the bench says which is which: *"cut 0:14.20–0:19.80
(5.60s, quote match 0.87)"*, or *"no cut — the whole window plays"*. **Cut to
quote** runs the same matcher the CLI pass runs, over this clip only, and
writes through the one writer with the same token; a quote the transcript does
not contain comes back as a refusal carrying its best partial rather than a
guessed cut. The rail draws the cut as an inner pair of markers inside the
window, so the two are visible at once. **Clear cut** goes back to playing the
whole extent, and dragging the extent inward past the cut clears it in the same
save and says so — the extent is the judgement being made right now, and the
cut was derived from a wider one.

## What else the cut takes from this recording

"Should this clip be wider, or is what it is missing already in the cut?" is
the one question a single clip cannot answer, and the two cases look identical
from inside it: twenty seconds of context that nothing picks up is a hole, and
twenty seconds the next entry already covers is a duplicate.

`siblingsOf()` reads it off the manifest — every other `type: "clip"` with the
same `video` (and the same `channel` when the entries carry one, because two
uploads of the same event are two clocks). The bench shows them three ways:

- **Under the description**, as a list: id (a link to its bench page), its
  position on the source clock, the gap to this clip's edges, where it sits in
  the *cut* ("next in cut", "3 later") and its quote. When the nearest one is
  within 15 s it says so in words — *"the next 12 s are not in the cut; c03
  starts at 17:32"* — because that is a decision waiting to be made rather than
  a number to notice. With none: *"no other clip in the cut uses this video"*.
- **As bands on the cue rail**, labelled `c03 · next in cut`, so where the cut
  already reaches is visible against the window you are dragging. A band the
  selection overlaps is **hatched**: a widened window that runs into the next
  clip is a duplicate, and that is exactly what somebody widening cannot see.
- **In the peek tooltips**: a dimmed cue inside another clip's window reads
  *"already in the cut as c03"*, so reading ahead answers "is this missing?"
  rather than only "what is out there?".

## The cue rail

Every cue in view, positioned by time. Inside the selection in full contrast,
outside dimmed — so "what am I cutting off" is *read*, not inferred from a
waveform. A `¶` marks a cue that closes a sentence, using the same regex
`resolve-windows.mjs` uses (imported, not re-written, so the rail and the widener
cannot disagree). Clicking a cue snaps the nearer edge to it.

## Keyboard

`[` `]` move the start · `,` `.` move the end · shift for 0.5 s instead of 0.05 ·
`space` auditions the whole selection · `R` resets to the saved window ·
`p` `n` walk · `y` confirm · `x` note what is wrong · `-` `=` playback speed ·
`a` auto-audition.

Audition happens on pointer-**up**, never during a drag — the Deck's rule, because
a sound restarting on every `pointermove` is unusable.

**A move auditions the edge that moved.** Every change used to play the first
six seconds, so nudging the end — the edge that decides whether a clip stops
mid-thought — played the start and answered a question nobody asked. A moved end
plays the four seconds *ending* on it; a moved start plays the four after it.

**Playback speed and auto-audition are per browser**, in `localStorage`
(`umtool.bench.playback`), never in the manifest: how fast somebody listens is a
fact about the person at the desk. The speed applies to the rendered-segment
player too. Auto-audition is off by default and, when on, plays a clip once on
arrival — after `canplay`, not racing it, because a `play()` before the element
is ready is a silent no-op that reads as a broken option.

## Saving

`PUT /api/report/window` with `{project, clip, start, end, lock…, title, date,
cite, citeUrl, quote, correction, verdict, token}`. It never sends a path and it cannot ask
for an entry to move. The whitelist is mirrored from `lib/report/manifest.mjs`,
which is where the values are actually checked.

The window and the attribution go through **one** function and **one** token,
because they are one edit: somebody watching a clip fixes its edges and its
header in the same sitting, and two writers would be two chances to lose the
other's write. In the component this is why a window save no longer resets the
attribution drafts and an attribution save no longer discards nudged edges.

See [report-video.md](report-video.md) for the four rules the writer keeps (2 dp,
the CLI's formatting, tmp+rename under a lock, an mtime token). A stale token is a
**409 with both values**, never a silent overwrite: the other writer is usually
somebody's judgement.

## Deliver — the half that starts when the walk ends

The bench answers one question per clip. What a report owes its readers after
that is a different list, and it lives on the **project page** as `Deliver`
(`components/projects/DeliverSection.tsx`, `/api/report/deliver`):

| | |
|---|---|
| **counts by section** | folded on the id's letter prefix, because `69 of 163 confirmed` says nothing about the section where eleven of nineteen clips were thrown out — and that is the section whose argument has to change. Section HEADINGS are read out of the report's own `content.py`, nth heading to nth letter. |
| **cut N confirmed clips from cache** | one job, **one step per clip**, so `k of n` and Stop are the job runner's own (`stepIndex`, and a cancel that kills the step's process group). Stop abandons the REST; the next press is the server's list again — "confirmed, no file" — so it resumes without re-cutting. |
| **not fetched** | a confirmed clip with nothing cached that holds it. Listed, never downloaded here — the managed fetch is the editor's, on the clip page. |
| **build share batch** | `share-<name>/{orig,std,small}/<Section>/<id>_<date>_<title>.mp4` + `LIST.md`. |
| **apply rulings** | runs the project's own `apply-manifest.py`, then `umtool corrections`. |
| **rebuild reports** | runs the project's own `build.py`, once per `content*.py`. |

**A confirmed clip's frames are already on this disk.** Nobody can judge a clip
until its window is cached, so `clips/<id>.mp4` — what the written report's
players read — is a cut, not a download. `lib/report/cut.mjs` asks the project
cache for the tightest window containing the clip and cuts at
`clip.start − window.from`, through build-video's own `cutArgs()`: one spelling
of the arithmetic, shared with the render's segment pass.

**The cut is measured, not predicted.** It stream-copies first and then probes
the result; more than 50 ms off the length asked for and it re-encodes. A copy
can only begin on a keyframe, and even a keyframe-aligned copy comes out long
when the aac frames do not end there (0.14 s, measured on the fixture) —
predicting that from the window's keyframes would have been wrong in exactly
the cases that matter.

**The two share profiles are `lib/report/encode.mjs`, and only there.** They
came off `~/reports/elfpire-eva/share-report-clips/reencode.py`, which is where
the first batch was actually encoded; ported rather than spawned, because a
python file beside one project's deliverables is not a profile the next project
can reach.

**Exclusions are the folders, not a list.** The next batch skips every id an
existing `share-*/LIST.md` already shipped and every clip ruled `incorrect`. A
`shared.json` would have been a second record to drift from them. Three ways an
id counts as shipped, in order of how much they can be trusted: the file NAMES
a list gives, the `<!-- shared-ids: … -->` marker this writes, and — narrowly —
the phrase `already shared (…)`, taking only the tokens shaped like a clip id.
(the parenthesis has to follow the phrase within ~120 characters, so one line
wrap is fine and a paragraph away is not). The last one is not decoration: six
ElfpireEva clips went out in an earlier set
under DIFFERENT ids (`em01`, `ie01` — a separate cut of the same moments), and
the sentence the next batch wrote down is the only thing on disk tying the two.
Without it, the next batch re-ships all six. A batch this writes phrases it the
same way, so its own list round-trips.

**Nothing rewrites prose.** `apply-manifest.py` prints the lines of
`content*.py` that cite each clip the walk threw out, and the panel shows the
same grep itself. What a wrong clip does to an argument is a judgement about
the argument.

**Apply is refused while the walk is unfinished** unless `apply partial` is
ticked: the script syncs `clips.json` from the manifest and deletes the mp4 of
every clip whose window moved, so running it over a half-walked cut bakes
"nobody has looked at this yet" into the deliverable as though it were a
verdict.

**One job at a time, machine-wide in this process** (`lib/jobs.ts`): a bench
fetch and a Deliver cut cannot run together, and the second one gets a 409
naming the first. That is not a limitation to route around — both write the
same `clips/` directory.

**What the fixture cannot cover.** `apply-manifest.py` and `build.py` are the
REPORT's own, hand-written, living in an unversioned `~/reports/<project>/`
directory and differing per report. `e2e/deliver.spec.ts` runs two-line
stand-ins: what is under test is that the panel finds them, runs them in order,
refuses the first over a half-walked cut and shows their output verbatim —
never what they do. A project whose scripts are absent gets the buttons hidden
or a 400, not a guess.

## Discovered by getting it wrong once

**The page and the inbox must answer the same question the same way.** `umtool
show` pilled four ferret-rescue clips "ends mid-sentence" while the decisions
inbox stayed silent about them, because the inbox had a punctuation gate and the
detail did not. The inbox was right.

**Two blur handlers can fire before either PUT returns.** Tab out of `title`
straight into `date` and both save; both would carry the same token and the
second would come back a 409 — the stale-token guard doing exactly its job,
against the only writer that cannot have lost anybody's judgement. Saves are
queued and the token is a ref, not state. Disabling the inputs while one is in
flight was the other candidate fix, and it is worse: it steals the focus the
operator just moved.

**A deleted key has to disappear from the form.** Merging a saved entry with
`{...clip, ...entry}` leaves the old `title` on screen after an empty save
deletes it — the write succeeded and the page said otherwise. The entry is
mapped field by field instead.

**The bench's prediction is testable, and is tested.** It says 3.00–6.00 widens to
3.00–9.00; saving 3.00–9.00 makes `resolve-windows` a no-op on that clip. That
round trip is the whole argument for the bench.