DEV Community

Peiguan
Peiguan

Posted on

Does My Bama Bound AI Clip Have a Glitch Frame? Finding Cuts, Flashes, Freezes and Skipped Frames in Python

Checked November 13, 2026 (15:00 CST, UTC+8). I build bamabound.app, which turns one photo of one person into a vertical clip of them holding a red I'M BAMA BOUND banner. Every clip in this post is a synthetic stand-in (a red "TEST BANNER" box swaying over a grainy green field, 720x1280, 30 fps, 8 s), not a real person and not a real generated clip.

People ask some version of this a lot: "There's a weird blink in the middle of my Bama Bound video. Is that a glitch, or did my editor do it?"

An AI clip is about eight seconds long (FAQ). At normal speed, a single odd frame is easy to feel and hard to find. You scrub, it's gone, you scrub back, you can't land on it. What you want is a list: frame 90, white flash, one frame long. Then you can look at exactly that frame, cut it, or send it to whoever made the clip.

This post builds that list with about 150 lines of Python, numpy and ffmpeg. I test it on five planted defects plus two clips that should come back clean, and compare it with ffmpeg's built-in scdet filter, which turned out to catch only two of the four defect types.

Four kinds of "jump", and what they look like in numbers

The whole method rests on one number per frame: how different is this frame from the one before it? Decode the clip very small (36 px wide, so film grain averages out), take the mean absolute RGB difference with the previous frame, and you get a 0-255 value. On my grainy test clip it sits around 1.1 for normal motion.

Defect What you see Shape of the difference curve
Hard cut the picture switches to a different shot one huge spike, and the picture stays different
Flash frame 1-3 frames of white/black/garbage a spike in, a spike out, and the frames either side match each other
Freeze motion stops, then resumes a run of near-zero differences
Skipped frames the banner "teleports" a little one moderate spike, a few times the usual motion

The skip is the sneaky one. Dropping 15 frames of a slowly swaying banner gave a difference of about 4 against a typical 1.1. That's visible to the eye, but nowhere near what a scene-cut detector is tuned for.

Judge each clip by its own motion

A fixed threshold doesn't work. A clip with lots of motion has big frame-to-frame differences everywhere. A calm one has tiny ones. So the script compares each difference with a rolling median over a one-second window around it. A spike counts when it is more than 4x that local median and above an absolute floor of 6. A skip counts at 2.5x local motion, 1.5x the clip's overall median and at least 1.0. A freeze is a run of frames under a tenth of the typical motion that lasts at least 0.3 s.

That 0.3 s number came from a false alarm, which I'll get to below.

The script

#!/usr/bin/env python3
"""jumpcheck.py - find sudden jumps in a short clip: hard cuts, flash frames,
freezes and skipped frames.

It decodes the clip at a small size (default 36 px wide), measures how much each
frame differs from the one before it (mean absolute RGB difference, 0-255),
and compares every difference with the clip's own typical motion (a rolling
median), so a slow clip and a busy clip are judged on their own terms.

    python3 jumpcheck.py clip.mp4            # human-readable report
    python3 jumpcheck.py clip.mp4 --json     # machine-readable
    python3 jumpcheck.py clip.mp4 --csv d.csv  # per-frame differences

Exit code 0 = nothing found (keyframe pulses are listed but not counted),
1 = at least one cut/flash/freeze/skip, 2 = could not read clip.
Needs ffmpeg/ffprobe on PATH and numpy.
"""
import argparse, json, subprocess, sys
import numpy as np


def probe(path):
    out = subprocess.run(
        ["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
         "stream=width,height,avg_frame_rate", "-of", "json", path],
        capture_output=True, text=True, check=True).stdout
    s = json.loads(out)["streams"][0]
    num, den = s["avg_frame_rate"].split("/")
    return int(s["width"]), int(s["height"]), float(num) / float(den)


def frames(path, w, h):
    cmd = ["ffmpeg", "-v", "error", "-i", path, "-an", "-vf",
           f"scale={w}:{h}:flags=area", "-pix_fmt", "rgb24", "-f", "rawvideo", "-"]
    raw = subprocess.run(cmd, capture_output=True, check=True).stdout
    n = len(raw) // (w * h * 3)
    return np.frombuffer(raw[: n * w * h * 3], np.uint8).reshape(n, h, w, 3).astype(np.int16)


def keyframes(path):
    """Indices of I-frames. Low-bitrate encodes 'pulse' on every keyframe,
    which looks like a small skip but is just the encoder refreshing detail."""
    out = subprocess.run(
        ["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
         "frame=pict_type", "-of", "csv=p=0", path],
        capture_output=True, text=True, check=True).stdout.split()
    return {i for i, t in enumerate(out) if t.strip(",") == "I"}


def diff(a, b):
    return float(np.abs(a - b).mean())


def analyse(path, small_w=36, spike=4.0, floor=6.0, freeze_ratio=0.1, min_freeze_s=0.3):
    W, H, fps = probe(path)
    small_h = max(2, round(small_w * H / W / 2) * 2)
    f = frames(path, small_w, small_h)
    n = len(f)
    kf = keyframes(path)
    min_freeze = max(2, int(round(min_freeze_s * fps)))
    d = np.zeros(n)
    for i in range(1, n):
        d[i] = diff(f[i], f[i - 1])
    # typical motion around each frame: median of a 1-second window, excluding frame 0
    win = max(5, int(round(fps)))
    base = np.zeros(n)
    for i in range(1, n):
        lo, hi = max(1, i - win), min(n, i + win + 1)
        base[i] = np.median(d[lo:hi])
    typical = float(np.median(d[1:])) if n > 1 else 0.0
    events, i = [], 1
    is_spike = lambda k: d[k] > max(spike * base[k], floor)
    while i < n:
        if is_spike(i):
            # flash: spike in, spike out within 3 frames, and the frames either side match
            back = None
            for k in range(1, 4):
                j = i + k
                if j < n and is_spike(j) and diff(f[i - 1], f[j]) < max(spike * base[i], floor) / 2:
                    back = j
                    break
            if back:
                events.append({"type": "flash", "frame": i, "frames": back - i,
                               "time": round(i / fps, 3), "diff": round(float(d[i]), 2)})
                i = back + 1
                continue
            # does the picture stay changed? compare a frame before with a frame after
            after = min(n - 1, i + 2)
            kind = "cut" if diff(f[i - 1], f[after]) > max(spike * base[i], floor) else "jump"
            events.append({"type": kind, "frame": i, "time": round(i / fps, 3),
                           "diff": round(float(d[i]), 2), "typical": round(float(base[i]), 2)})
        elif d[i] < freeze_ratio * max(typical, 1e-6):
            j = i
            while j < n and d[j] < freeze_ratio * max(typical, 1e-6):
                j += 1
            if j - i + 1 >= min_freeze:
                events.append({"type": "freeze", "frame": i - 1, "frames": j - i + 1,
                               "time": round((i - 1) / fps, 3),
                               "seconds": round((j - i + 1) / fps, 3)})
            i = j
            continue
        elif d[i] > max(2.5 * base[i], 1.5 * typical) and d[i] > 1.0:
            events.append({"type": "keyframe" if i in kf else "skip", "frame": i, "time": round(i / fps, 3),
                           "diff": round(float(d[i]), 2), "typical": round(float(base[i]), 2)})
        i += 1
    return {"file": path, "frames": n, "fps": round(fps, 3), "size": f"{W}x{H}",
            "typical_diff": round(typical, 3), "max_diff": round(float(d.max()), 2),
            "events": events}, d


def main():
    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
    ap.add_argument("clip")
    ap.add_argument("--json", action="store_true")
    ap.add_argument("--csv")
    ap.add_argument("--width", type=int, default=36, help="analysis width in px (smaller = less grain)")
    ap.add_argument("--min-freeze", type=float, default=0.3, help="seconds of no change that count as a freeze")
    ap.add_argument("--spike", type=float, default=4.0, help="x typical motion that counts as a spike")
    a = ap.parse_args()
    try:
        rep, d = analyse(a.clip, small_w=a.width, spike=a.spike, min_freeze_s=a.min_freeze)
    except (subprocess.CalledProcessError, KeyError, IndexError, ValueError) as e:
        print(f"could not read {a.clip}: {e}", file=sys.stderr)
        return 2
    if a.csv:
        with open(a.csv, "w") as fh:
            fh.write("frame,time,diff\n")
            for i, v in enumerate(d):
                fh.write(f"{i},{i / rep['fps']:.3f},{v:.3f}\n")
    if a.json:
        print(json.dumps(rep, indent=2))
    else:
        print(f"{rep['file']}: {rep['frames']} frames @ {rep['fps']} fps, {rep['size']}, "
              f"typical frame-to-frame diff {rep['typical_diff']}, max {rep['max_diff']}")
        if not rep["events"]:
            print("  no cuts, flashes, freezes or skips found")
        for e in rep["events"]:
            extra = {k: v for k, v in e.items() if k not in ("type", "frame", "time")}
            print(f"  {e['type']:6} at {e['time']:6.3f}s (frame {e['frame']})  {extra}")
    real = [e for e in rep["events"] if e["type"] != "keyframe"]
    if any(e["type"] == "keyframe" for e in rep["events"]):
        print("  (keyframe = small pulse on an I-frame, usually encoder refresh; not counted)")
    return 1 if real else 0


if __name__ == "__main__":
    sys.exit(main())
Enter fullscreen mode Exit fullscreen mode

Run it:

python3 jumpcheck.py clip.mp4          # report, exit 1 if anything found
python3 jumpcheck.py clip.mp4 --json   # for CI or a batch script
python3 jumpcheck.py clip.mp4 --csv diffs.csv   # plot the curve yourself
Enter fullscreen mode Exit fullscreen mode

Planting defects to test it

You can't trust a detector you've only run on clean clips. make_glitch.sh takes any clip and plants one known defect at a known frame:

#!/usr/bin/env bash
# Make a test copy of a clip with one known defect, to check a jump detector.
#   ./make_glitch.sh in.mp4 cut|flash|freeze|drop|lowbitrate N out.mp4
#   cut        N ignored: from 4 s on, the picture is flipped and hue-rotated (a "different shot")
#   flash      N white frames starting at frame 90
#   freeze     frame 150 held for N frames (same total length)
#   drop       N frames removed starting at frame 120 (clip gets shorter, motion jumps)
#   lowbitrate N ignored: CRF 38 with a keyframe every 30 frames (encoder pulse, not a defect)
set -euo pipefail
in=$1; kind=$2; n=$3; out=$4
enc=(-c:v libx264 -preset veryfast -crf 20 -pix_fmt yuv420p)
case $kind in
  cut) ffmpeg -v error -y -i "$in" -filter_complex \
        "[0:v]split[a][b];[a]trim=0:4,setpts=PTS-STARTPTS[a2];[b]trim=4,setpts=PTS-STARTPTS,vflip,hue=h=120[b2];[a2][b2]concat=n=2:v=1:a=0,fps=30[v]" \
        -map "[v]" -map 0:a? "${enc[@]}" -c:a copy "$out" ;;
  flash) ffmpeg -v error -y -i "$in" -vf "drawbox=0:0:iw:ih:color=white:t=fill:enable='between(n,90,$((90+n-1)))'" \
        "${enc[@]}" -c:a copy "$out" ;;
  freeze) ffmpeg -v error -y -i "$in" -filter_complex "[0:v]split[a][b];[a][b]freezeframes=first=150:last=$((150+n-1)):replace=150[v]" \
        -map "[v]" -map 0:a? "${enc[@]}" -c:a copy "$out" ;;
  drop) ffmpeg -v error -y -i "$in" -vf "select='not(between(n,120,$((120+n-1))))',setpts=N/30/TB" -an -r 30 "${enc[@]}" "$out" ;;
  lowbitrate) ffmpeg -v error -y -i "$in" -c:v libx264 -preset veryfast -crf 38 -g 30 -pix_fmt yuv420p -c:a copy "$out" ;;
  *) echo "unknown kind $kind" >&2; exit 2 ;;
esac
echo "wrote $out ($kind $n)"
Enter fullscreen mode Exit fullscreen mode

The base clip comes from a small synthetic generator (make_field_test_clip.sh: gradient sky, noisy field, red box with white text swaying on a sine, beeps over a hum). It's in the same folder as the scripts.

Results

Same base clip, one defect at a time:

Test clip jumpcheck.py found Exit
clean clip, grain 18 nothing (typical diff 1.07, max 1.54) 0
hard cut at 4.0 s cut at frame 120, diff 102.3 vs local 1.12 1
1 white frame at 3.0 s flash at frame 90, 1 frame 1
2 white frames at 3.0 s flash at frame 90, 2 frames 1
frame 150 held 15 frames freeze at 5.0 s, 0.5 s 1
15 frames dropped at 4.0 s skip at frame 120, diff 4.06 vs 1.11 1
clean clip, no grain nothing (typical 0.245) 0
clean clip scaled to 480x854 nothing 0
clean clip re-encoded CRF 38, keyframe every 30 7 keyframe pulses listed, not counted 0
file that doesn't exist error message 2

For comparison: ffmpeg's scdet

ffmpeg ships a scene-change filter, so the obvious question is why not just use it:

ffmpeg -i clip.mp4 -vf "scdet=threshold=10,metadata=print:file=scd.txt" -f null -
Enter fullscreen mode Exit fullscreen mode

On the same planted clips at threshold=10:

Defect Highest lavfi.scd.score Flagged?
clean 0.17 no
hard cut 24.5 (frame 120) yes
1 white frame 36.8 (frame 90) yes, but only the entry. The exit frame scored low, so it looks just like a cut
15-frame freeze 2.4 no
15 dropped frames 0.9 no

That isn't a bug. scdet is built to find scene changes, and its score is roughly "how much did the frame difference jump compared with the previous difference". The return from a flash is a big difference right after another big difference, so it scores low. Freezes and small skips aren't scene changes at all. If all you need is real cuts, scdet is fine. To tell a flash from a cut, or catch the quieter defects, you need the raw curve.

Two false alarms that shaped the defaults

1. Low-bitrate keyframe "pulses." I re-encoded the clean clip at CRF 38 with a keyframe every 30 frames. The first version of the script reported seven "skips" at frames 29, 58, 87 and so on, exactly 29 frames apart. ffprobe -show_entries frame=pict_type showed an I-frame at every one of them. At low bitrate, every keyframe refreshes detail the P-frames had smeared away, and that registers as a small jump. The script now asks ffprobe for I-frame positions, labels those events keyframe and leaves them out of the exit code.

The cost of that choice is that a real skip landing on a keyframe gets hidden. This happened once in the dataset grid I mention below. Before I made the test clip deterministic, a 10-frame drop got labelled keyframe because x264 had put an I-frame right at the jump. If you have a clip that already feels wrong, also read the keyframe lines.

2. Slow motion looks like a freeze. With grain turned off, the test banner moves less than a pixel per frame at the slow ends of its sway. After encoding, some frames come out identical. The first version flagged eight "freezes" of 3-7 frames (0.1-0.23 s) in a perfectly fine clip. Raising the minimum to 0.3 s removed all of them and still caught the planted 15-frame freeze. A 0.1 s pause in an AI clip is rarely what people mean by "it froze".

Where it stops working

  • Tiny skips are invisible. On the grainy clip, dropping 1, 2 or 5 frames wasn't detected. The motion jump is smaller than the grain. On the grain-free clip, 5 dropped frames were caught (diff 1.59 vs typical 0.244) but 1-2 weren't. Freezes of 3 and 6 frames were not reported (by design, under 0.3 s); 9 and 15 were. A full grid of these cases is in the dataset linked at the end.
  • A cut to a similar-looking shot can slip through. My cut fixture flips the picture and rotates the hue, so it's an obvious change. A cut between two nearly identical framings won't produce a big spike.
  • The freeze after-effect. When a freeze ends, the motion catches up in one frame. On the grain-free clip that catch-up was also reported as a skip. It isn't a second defect, just the other end of the same freeze.
  • Thresholds were tuned on synthetic clips. Real footage with camera shake will need --spike raised.

What to do with the list

  • It's your own edit. Look at the reported frame first. Flashes and freezes usually come from a transition, a bad cut point or a dropped frame in the export. Trim with frame accuracy (re-encode, don't stream-copy) and run the check again.
  • The clip came out of the generator like that. The studio's help page separates a failed generation from one that looks wrong. Looking different from your photo isn't a failed order on its own. If you write to support, a frame number and a timestamp make the report concrete. The address is on the help page.

For reference, the pricing page listed these per-clip prices when I checked on November 13, 2026: 480p $7.98, 720p $9.98, 1080p $16.98, 4k $24.98, tax added at checkout. Check the page itself before you rely on them.

Measured grid

I ran the planted defects at several sizes (flash 1-3 frames, freeze 3-15, drop 1-15) on a grainy and a grain-free source, with fixed random seeds so it reproduces exactly. The 30 rows are in the bamabound-guides dataset on Hugging Face (config jump_detection), along with the script that rebuilds them.

Top comments (0)