A Python smoke test for story-beat order in an automatically edited recap

Anlin — Sun, 08 Nov 2026 11:51:50 +0000

A recap editor can preserve every required shot while losing the cause-and-effect order. A small check against a review export can flag those cases before a person watches the first cut. In a fictional mystery, the key mark must appear before the detective tries the door. We also want to know if a required beat disappeared.

This example uses synthetic markers in milliseconds on the edited output timeline and Python’s standard library.

required_order = ('find_notebook', 'key_mark', 'try_door')
export_markers_ms = {'find_notebook': 14000, 'try_door': 42000, 'key_mark': 46000}

missing = [beat for beat in required_order if beat not in export_markers_ms]
out_of_order = [
    (before, after)
    for before, after in zip(required_order, required_order[1:])
    if before in export_markers_ms and after in export_markers_ms
    and export_markers_ms[before] >= export_markers_ms[after]
]

print('Missing:', missing)
print('Out of order:', out_of_order)

Expected output:

Missing: []
Out of order: [('key_mark', 'try_door')]

Correct the sequence on the timeline, export again, and run the check with timestamps from the revised export. Then ask a viewer why the detective tried that door. Marker order can catch a broken sequence, but it cannot tell whether a clue is visible long enough to understand. If the story deliberately withholds the reason until later, define that intended sequence in required_order first.

The cover is an illustrative workflow diagram. This article and its synthetic example were generated with AI.

How to catch caption timing drift in a 29.97 fps video export with Python

Anlin — Sun, 08 Nov 2026 05:13:20 +0000

A caption that looks fine at the start of a movie recap can land noticeably early or late near the end. Measure the error at several known frames before shifting individual cues. A constant error suggests a shifted start time. An error that grows with elapsed time suggests a clock or frame-rate conversion problem.

Cover: AI-generated schematic showing caption cues moving progressively ahead of the frame clock. The gaps are exaggerated and not to scale.

Use the exact frame rate

Assume a constant-frame-rate export at 30000/1001 fps. Frame 0 and subtitle time 0 share the same origin. Each expected caption onset is a zero-based frame index on the output timeline. The actual onset comes from the subtitle export in milliseconds.

Keep the math exact until reporting the result. At frame 17,982, the expected time is 17982 × 1001 / 30000, or 599.9994 seconds. Treating the same frame index as 30 fps gives 599.4 seconds. The clocks differ by 599.4 milliseconds after about ten minutes.

Check three known onsets

This example uses fictional data and runs with Python's standard library. Positive error means the caption starts late. One frame is a simple tolerance for this example. Set your real tolerance based on the cues and delivery requirements of the project.

from fractions import Fraction

fps = Fraction(30_000, 1_001)
frame_ms = 1_000 / fps

# (name, expected output frame index, actual subtitle start in ms)
anchors = [
    ('opening cue', 0, 0),
    ('middle cue', 8_991, 299_700),
    ('final cue', 17_982, 599_400),
]

for name, frame, actual_ms in anchors:
    expected_ms = frame * frame_ms
    error_ms = actual_ms - expected_ms
    result = 'REVIEW' if abs(error_ms) > frame_ms else 'OK'
    print(f'{name:<12} {float(error_ms):+8.1f} ms  {result}')

opening cue      +0.0 ms  OK
middle cue     -299.7 ms  REVIEW
final cue      -599.4 ms  REVIEW

Here the captions start early, and the error grows nearly linearly. The fictional subtitle times were deliberately calculated at 30 fps. In a real export, compare the frame-rate metadata and subtitle timing first. If all three errors instead cluster around the same offset, check whether the video, audio, and subtitle exports started at the same point.

Know when to use presentation timestamps

The frame formula works for constant frame rate with a shared origin. For variable-frame-rate footage, use each output frame's presentation timestamp and apply the track's time base. B-frames can appear in decode order that differs from presentation order, so compare frames in the order viewers see them. Normalize any nonzero stream start to the subtitle timeline before measuring the difference.

After fixing a suspected conversion or offset, export again and check the same anchors. Watch one short excerpt around a story cue to make sure the caption lands when the viewer needs it.

AI disclosure: AI generated this article and its example. The Python example was executed to verify the output.

DEV Community: Anlin

A Python smoke test for story-beat order in an automatically edited recap

How to catch caption timing drift in a 29.97 fps video export with Python

Use the exact frame rate

Check three known onsets

Know when to use presentation timestamps