# Cutpoint Desk

> A cut lands on the beat or it does not, and the difference is measurable in frames. This fits a
> beat list to a real grid by least squares, measures every cut against the lattice, keeps the
> audio-truth error and the frame-quantisation error apart, and spots when a dozen misses are one
> shared offset. Five lanes over one grid-and-cuts sheet, plus a free browser-side linter.

URL: https://cutpoint-desk.skillsafe.ai/
API: https://cutpoint-desk.skillsafe.ai/api.html

Derived from Vincentwei1021/video-shotcraft (https://github.com/Vincentwei1021/video-shotcraft),
Apache-2.0: its references/music-beat-sync.md, which is a measured methodology rather than advice.
Not affiliated with or endorsed by Vincentwei1021.

## What the free linter does

It runs entirely in the browser, on the sheet you type, with no account and no credits.

1. **Fits the grid** rather than reading it. A detector's tempo scalar can be 2% out - 129.2
   against a true 131.97 in the upstream measurement - while its beat times are good, so a
   least-squares fit of `t_i = t0 + i*T` over the whole sequence recovers the real tempo and phase.
2. **Reports the residual**, which nothing else provides. Under 15ms the piece holds one tempo;
   above it, one grid is the wrong model and the sections need fitting separately.
3. **Measures every cut** against the lattice, in milliseconds and in frames.
4. **Keeps the two errors apart**: distance to the beat tests the analysis, distance introduced by
   rounding to a frame tests the frame rate. They have different fixes.
5. **States the quantisation floor** for the delivery frame rate, so nobody claims a precision the
   format cannot reach.
6. **Detects a shared offset** across the timeline and reports it as one finding instead of many.
7. **Counts the full-frame impacts** against their budget, which is the other way this goes wrong.

## The arithmetic

```text
t_i = t0 + i*T          least squares over every detected beat
BPM = 60 / T
residual_i = t_i - (t0 + i*T)

quantisation floor = 0.5 / fps      30fps -> 16.7ms, 60fps -> 8.3ms, 120fps -> 4.2ms
```

Verdicts: ideal at or under 1.5 frames, passes at or under 3 frames (the perceptual threshold),
must fix above it.

Grid acceptance: worst residual under 15ms, mean error under 10ms, drift under 5ms across the
whole piece, and the first beat landing on a real attack.

## The lattice

phrase (every 16 beats) > bar (4) > beat (1) > half (0.5) > quarter (0.25).

A tool that calls a phrase top and a beat-three cut both "on the beat" has thrown away what made
the edit read as deliberate.

## Designed positions and measured ones

`beat=` is a design position; `t=` is a measured one. A DESIGNED cut on a half or a quarter is
where its author put it, so it is scored against that off-beat. A MEASURED time near a quarter is a
miss, not a choice, and is scored against the integer beat. Reading a measurement the other way
turns a four-frame miss into a design decision and hides it, which is the one thing a retest must
never do.

## A shared offset is one bug, not many

Every measured cut late by about the same amount is an output audio offset - encoder priming is
roughly 1.28 frames at 48kHz - not a dozen bad anchors. The fix is one constant. Hand-correcting
each anchor bakes the offset into the design and it comes back the next time the codec changes, so
keep the source analysis and the render offset in separate constants.

It is diagnosed by the shape of the error table: same sign, tight spread, most of the cuts. One
anchor genuinely out of place does not disprove a shared offset in the others - both are true and
they are separate pieces of work.

## How much the film can carry

In a strong-drum track the kick is on nearly every beat, and matching the picture to it produces a
film that appears to shake rather than one that is hit three times. The detected hits are a
candidate pool, not a trigger list. Full-frame impacts are capped at 3 per film, at least 16 beats
apart; pump runs are 1 per film and at most 4 beats. Everything else on the beat happens at the
element level.

## The lanes

- `fit` - beat list in, a grid worth trusting out, with the residual that decides
- `audit` - every cut against the lattice, the impacts against their budget, the timeline rewritten
- `plan` - a brief and a grid in, a beat-numbered timeline out
- `retest` - times measured off the render in, an error table out, with the shared offset separated
- `budget` - which hits earn a slam and what everything else does instead

## What it does not do

It does not detect beats, decode audio or render anything. It takes the numbers you already have
and does the arithmetic nobody does on them, and it is only as good as those numbers: a beat list
from a bad detection produces a confident fit of the wrong grid, which is why the residual is
reported first.