Originally published on hexisteme notes.

The final assembly of a short explainer video failed once on a sound check. The check was sfx_hierarchy, which asks whether every sound effect sits at the level its layer is supposed to have. Two reaction cues, a camera shutter and a stamp slam, had been pushed up by +12 dB, which is the maximum boost my mixer allows. Nothing about those two sounds needed that. The cause was one line in the audibility measurement: it computed the start sample with int(t·sr), while the code that placed the cue in the mix computed it with round(t·sr).

When I traced it, there were three defects in the pipeline, and a later Codex review found more of the same kind. They share one shape. The place where the pipeline put a sound and the place where it measured that sound were not the same place, sometimes by one sample, sometimes by a different file entirely. This is the record of those defects and the tests that now pin them.

What the audibility check does

Each reaction cue in these videos is a short sound effect tied to an on-screen event. A check measures whether that cue is audible over the music and under the narration, in a phone-speaker frequency band. The margin function is short:

def audible_margin_db(fx: float, mu: float, vo: float) -> float: return min(fx - mu - SOUND_OVER_MUSIC_DB, fx - vo - SOUND_UNDER_VOICE_DB) 

A margin of zero or more means the cue is heard. If it is not heard, the mixer lifts it, up to a cap.

The measurement used to average the first 0.4 s after the event. According to the function's docstring, that average read short sounds low, because it averaged in the silence after them, and it read sounds that swell late (a whoosh, steam) low as well. So the measurement was changed to cut the cue into overlapping slices of SOUND_SLICE_S and measure each slice. Slices only cover the length of the cue's own asset, because anything past that is another event's sound.

The window measurement returns a fixed floor for an empty range:

def phone_window_db(x: np.ndarray, a: int, b: int) -> float: from . import audio seg = x[a:b].mean(axis=1) if x.ndim == 2 else x[a:b] if len(seg) == 0: return -120.0 band = audio.phone_band(seg) return float(20.0 * np.log10(np.sqrt((band ** 2).mean()) + 1e-9)) 

Defect 1: int() for the slice, round() for the placement

The placement code put a cue at round(t·sr). The slicer started at int(t·sr). int() drops the fractional part and round() goes to the nearest sample, so whenever an event time fell more than half a sample past a sample boundary, the two disagreed by one. The first slice then started one sample before the asset.

The record states the result: that first slice measured as empty, at −120 dB. I have not re-derived from the slicing arithmetic why a one-sample shift produced an empty window instead of a slightly shorter one, so I will report what was observed and not a mechanism.

For long cues this was one bad slice among several. For the camera shutter, which is 0.14 s long, there was only one slice. The whole cue therefore measured −120 dB, the mixer concluded it was inaudible, and it lifted the cue all the way to the +12 dB cap. The stamp slam was over-amplified by +12 dB in the same way.

The fix was to use round in both places. This is the slicer after the fix (docstring and an internal comment omitted):

def sound_slices(t_s: float, dur_s: float, asset_s: float | None, sr: int) -> list[tuple[int, int]]: span = min(float(dur_s), float(asset_s)) if asset_s else float(dur_s) a0, total, k = round(float(t_s) * sr), max(1, int(span * sr)), max(1, int(SOUND_SLICE_S * sr)) if total <= k: return [(a0, a0 + total)] return [(a0 + i, a0 + i + k) for i in range(0, total - k + 1, max(1, k // 2))] 

The total <= k branch is the single-slice case the shutter fell into. The regression test puts an event 0.6 of a sample past a boundary and asserts that the first slice starts where the placement would put the cue:

def test_sound_slices_start_on_the_sample_the_cue_is_placed_at(): sr = 48000 t = 0.5 + 0.6 / sr assert reactions.sound_slices(t, 0.14, 0.14, sr)[0][0] == round(t * sr) 

A second test, test_short_reaction_cue_is_not_lifted_by_a_slice_before_its_first_sample, checks the consequence instead of the index. I come back to it below, because the first version of it was too weak.

Defect 2: the check measured a different sound

shotfilm.cue_asset_id wrote every cue of kind reaction as a cue_reaction_* synthetic click. The real mix used the catalog sound for each reaction, and the mix itself was fine. But loudness measurement, sync measurement and the rights record were all looking at the synthetic click, a sound that was not in the mix.

The fix maps a reaction cue to its catalog asset_id. The test is test_reaction_cue_asset_is_its_catalog_sound_not_a_synth_click.

Defect 3: an audibility floor against a layer target

The third failure was a rule conflict. The audibility floor said a reaction cue must be heard. The layer rule said each sound effect layer must sit within ±2 dB of its target. A light-bulb ding sat under a loud stretch of narration and needed to be at −5.2 dB to be heard, which the layer rule would not allow.

The fix makes the boost explicit. Placement records a lift_db for each cue. The lift has a ceiling of the layer above's target minus 3 dB (transition −5, ui −11, and for peak, target +2). The hierarchy check accepts a level raised by the recorded lift, but only up to that ceiling. If a cue would need more than the ceiling to be heard, the reaction_sfx_masked check reports it.

Two tests pin this: test_reaction_lift_is_recorded_and_stops_at_the_layer_ceiling and test_sfx_hierarchy_allows_a_recorded_audibility_lift_up_to_the_ceiling. A music-floor test also had its music changed to −12 dB relative to speech, which is the range of the real mix. After these three fixes the full suite was 1083 passed.

(The same assembly also failed a separate visual craft check with 7 hard findings, such as stacked decoration dots and a camera move still accelerating at a cut. Those were fixed in the episode's script and are not part of this story.)

The Codex review found the same shape again

Before upload I gave the whole thing to Codex for a read-only final review. I adopted its findings, and the remaining items it checked needed no change. The ones that matter here were about sound:

  • Any cue could claim a lift_db exemption, not only reactions. Now the lift counts only for items with kind reaction, and the timeline and loudness measurement carry kind and reaction_id through. Test: test_sfx_hierarchy_ignores_a_lift_on_a_non_reaction_cue.
  • Audibility was measured at the event time, which had 0.1 ms resolution. The compile step placed the cue at at_s rounded to the millisecond. The two could be up to 24 samples apart. measure_reaction_audibility(placed=) now measures at the actual placement times from the assembly report. The mix did not change.
  • Placement times were recorded rounded to 0.1 ms, which showed up as 25600 against 25598 samples. Reaction t_s is now recorded to 1 µs. The final sound effect stem was already placed from the exact time, so this changed the record and the offset measurement, not the mix.
  • The short-cue test from defect 1 still passed with the lift removed.

The 24-sample case is defect 1 again at a larger scale: the measurement was taken at one time and the sound was placed at another. Its test builds a 24-sample burst and an event time that does not land on it:

def test_audibility_is_measured_where_the_cue_was_placed_not_at_the_unrounded_event_time(): sr = 48000 n = sr sfx = np.zeros((n, 2)) burst = np.random.default_rng(7).normal(0, 0.5, 24) sfx[24000:24024] = np.stack([burst] * 2, axis=1) quiet = np.zeros((n, 2)) evs = [{"id": "E1", "sfx": "camera_shutter", "t_s": 0.50049, "dur_s": 0.1, "shot_id": "A"}] placed = [{"reaction_id": "E1", "asset_id": "camera_shutter", "t_s": 0.5}] stems = {"sfx": sfx, "music": quiet, "voice": quiet} assert {x["code"] for x in reactions.measure_reaction_audibility(evs, stems, sr, lengths={"camera_shutter": 0.1})["hard"]} == {"reaction_sfx_masked"} assert reactions.measure_reaction_audibility(evs, stems, sr, lengths={"camera_shutter": 0.1}, placed=placed)["hard"] == [] 

Measured at the event time, the cue is reported as masked. Measured at the placement, it is not.

Making the weak test able to fail

The last finding was the one I would most likely have missed myself. The consequence test for defect 1 compared lifts, but in its setup no lift was needed at all, so it could not tell a correct slicer from a broken one.

The strengthened test raises part of the narration by ×1.3 so that a real lift is needed but stays under the ceiling, between 0.5 dB and 2.5 dB. It then places the same cue on a sample and 0.6 of a sample past one, and asserts the two lifts differ by less than 0.1 dB:

 room = qc.lift_ceiling_db("transition") - audio.SFX_LAYER_DB["transition"] on_sample, between = lift_at(0.5), lift_at(0.5 + 0.6 / SR) assert 0.5 < on_sample < room - 0.5 assert abs(between - on_sample) < 0.1 

If the slicer is off by a sample, the between-sample placement climbs to the ceiling and the second assertion fails. I checked that directly by putting int back: the test failed. That mutation check is the evidence the test now guards the bug and not just the happy path.

After the review fixes the suite was 1086 passed.

Confirming the mix did not move

The fixes from that final Codex review were to measurement and records, and I wanted proof that they had not changed the mix. I reassembled the video through the final render, shot assembly, craft check, script and final reaction measurement. The SHA hashes of the final video file and the sound effect stem were identical before and after.

On that reassembly the reaction measurement passed with 28 events. Loudness was −14.0 LUFS and −1.65 dBTP. All 15 reaction cues carried their kind. Only two cues were lifted: the stamp slam by +0.64 dB and the bulb ding by +2.77 dB, both under the −5 dB ceiling. The stamp slam had been at +12 dB when the slicer was wrong.

What is still open

Every automated gate passed except one, human_review, which is my own watch-through of the finished cut. That is still ahead of the private upload and scheduling, and no gate result here says anything about whether the video is good to watch.

The other open item is the one I flagged above. The record says the one-sample-early slice was empty and read −120 dB; it does not explain why a slice shifted by one sample came out empty rather than nearly full. The fix and the tests do not depend on that answer, but I have not confirmed the mechanism.

The habit I am taking from this is narrow: when a measurement reports on a sound, check that it computes position, time and asset the same way the code that placed the sound did. Three of the defects in this one assembly were exactly that mismatch.

Email list for these notes: hexisteme.beehiiv.com — no issue has gone out yet, so you would be on it before the first one. No welcome sequence, no course, no upsell.

More notes at hexisteme.github.io/notes.