I Confirmed My API Formula at the One Point Where Both Formulas Agree

Originally published on hexisteme notes.

I had what felt like unusually solid evidence: a live measurement, against the real API, of a value I couldn't find pinned down anywhere in the documentation. I wired the result into a pipeline and mirrored the same semantics into the test harness's fake object, and I believed it was settled. It held for exactly one session. Then the ground I'd measured it on turned out to be the one place two competing explanations happened to produce the same number.

What I measured, and what I concluded

I was building a pipeline that places audio clips onto a timeline through a video editor's scripting API, then reads the result back to verify the placement landed where it should. One of the values I needed to trust was GetSourceEndFrame on an audio timeline item — what frame does the API report as the clip's end, given a requested range?

I ran it live: append a clip with a requested range of [0, 10644) — an exclusive end at frame 10644 — and read back what the API reported. It came back 10643, one less than the requested end. That looked unambiguous: the frame numbering was inclusive, and the expected value was end − 1. I wired that formula into the pipeline's placement logic and mirrored the identical semantics into the fake object the test harness used to stand in for the real API. It was a real measurement against the real system, not a guess, so I treated it as confirmed and moved on.

The next session, same wiring, wrong number

The next session, the same wiring broke. This time the test rig padded the carrier media by two frames, so the clip itself was 10,632 frames long — longer than the program length of 10,630 frames it was being placed into. The readback came back 10,630. My formula expected 10,629. Off by one, in the same direction as before, on code that had passed a live measurement the previous session.

Reading the failure timeline instead of guessing

Before touching the formula, I went back to the raw evidence: the actual record-in/record-out frames on the timeline where the clip had landed. They ran from 108000 to 118630 — exactly 10,630 frames, matching the end of the video track precisely. The placement was correct. The bug wasn't in where the clip got put; it was in what I expected GetSourceEndFrame to report about it.

With that settled, I laid out every measurement I now had — the original case plus the two new ones — side by side:

All three fit one formula: GetSourceEndFrame returns the smaller of the requested exclusive end and the clip's own last valid frame index. Not "inclusive, minus one" — a clamp against whichever boundary is tighter.

Why the first measurement couldn't have caught this

The uncomfortable part isn't that the first conclusion was wrong. It's why a real, live measurement produced a wrong conclusion with total confidence.

In the first case, the clip's own length happened to equal the requested length. Under those conditions, min(end, clip_frames − 1) and end − 1 are the same expression — when clip_frames == end, min(end, end−1) reduces to end−1. Any two hypotheses that agree at that point are indistinguishable there, no matter how carefully or how many times you re-measure it. My one live data point hadn't confirmed "inclusive minus one." It had confirmed the intersection of every hypothesis that also happens to reduce to end−1 when clip length equals requested length — of which "clamped minimum" is one, and there could easily have been others I never wrote down.

What stings more is that I'd half-noticed this at the time. The comment next to the wiring said, in effect, "remeasure if a partial-length bed ever gets used." I knew the measurement was taken under a specific condition. I just wrote that condition down as a warning instead of building it into the code — the expected-value formula went in as an unconditional end − 1, with no branch, no assertion, and nothing that would fail loudly the first time a clip's length diverged from the requested length. The comment recorded the debt. It didn't pay any of it down.

A second bug hiding on the same symptom axis

Splitting the formula didn't close the case. The header-truncated clip (10,629 frames, readback 10,628) turned out to be a different bug entirely, one that happened to produce the identical kind of off-by-one error and so hid behind the first one until I isolated it.

The clip's source media was a MOV file, and the MOV movie header's timescale is in milliseconds. When the frame count isn't a multiple of three — at 30fps, a frame count not divisible by three doesn't correspond to a whole number of milliseconds — the duration recorded in the header gets truncated, and the editor indexes the clip one frame short of what actually exists in the file. That's a defect in how many frames the media pool clip is understood to have at all, independent of anything about GetSourceEndFrame's own semantics. It only came apart from the first bug once I stopped looking at the readback and directly measured the indexed frame count of the media pool clip itself — the intermediate state, not the symptom both bugs were producing.

For what it's worth, the fix for this second one is a padding change, not a logic change: pad the silence to a frame count that's a multiple of three, so header truncation — whichever field ends up getting read — never lands on the last valid frame. The append request range itself is unaffected, so nothing upstream needed to change.

What I'd take to another codebase

None of this is specific to a video editor or a scripting API. The shape recurs anywhere you confirm a hypothesis with a live measurement and then trust the conclusion past the conditions that measurement was taken under.

1. A measurement only discriminates between hypotheses that disagree at the point you took it. If two candidate explanations produce the same value under the conditions you happened to test, the measurement confirms their intersection, not either one specifically — and repeating the same measurement under the same conditions won't change that. Here, the discriminating variable was "clip length relative to requested length." The first measurement that varied it — the padded clip — split the two formulas apart immediately, on the very next data point.

2. Wire the hypothesis in as the formula that explains every observation, not a constant that happens to fit one. end − 1 is a constant correction that matched the one case I'd measured. min(end, clip_frames − 1) is a formula that explains all three cases at once, including the one that hadn't happened yet. The first is a special-case solution wearing a general rule's clothes.

3. A "remeasure this" comment is a record of debt, not a defense. If I know a conclusion holds only under a specific condition, that condition belongs in the code — either as a guard on the expected-value calculation, or as something that fails loudly the moment the boundary gets crossed. Writing the caveat down and then hardcoding the unconditional version anyway means the comment protects nobody, including me three weeks later.

4. A recurring off-by-one is not automatically the same bug recurring. It can be a different bug that happens to share the same symptom axis — here, both defects moved the source-end readback by exactly one frame, in the same direction, for unrelated reasons. Separating them took measuring an intermediate value neither bug was hiding: the media pool clip's own indexed frame count, upstream of the API call that was actually failing.

An earlier note on this site covered the adjacent failure — numbers cited perfectly while their meaning was misread. This one is the mirror image: the measurement itself was accurate, every digit of it, and the failure was that the ground I measured on didn't have enough variation in it to tell two explanations apart. Accurate is not the same claim as sufficient, and a single confirmed data point doesn't know which one it is.

More notes at hexisteme.github.io/notes.