DEV Community: Joey

Write an SRT Linter That Checks Timing Against the Media File

Joey — Tue, 27 Oct 2026 02:00:00 +0000

Shorten an edit and an old subtitle file can remain perfectly readable while its final cue now ends after the video.

I want that caught before playback. The check needs the exported media's duration, not the duration I remember from the timeline.

Keep the comparison in milliseconds

This linter reads ordinary numbered UTF-8 SRT blocks, including files with a BOM. It checks timestamp syntax, cue order, positive duration, and the end of the media. Overlapping cues and a configurable reading-speed threshold produce warnings.

It uses ffprobe's container duration as the boundary. This assumes the subtitle file belongs to that export and starts on the same zero-based timeline.

Save this as srt_lint.py. Python's standard library is enough; ffprobe must be on your PATH.

import argparse
from decimal import Decimal, InvalidOperation
import json
import math
from pathlib import Path
import re
import subprocess

STAMP = r"[0-9]{2,}:[0-5][0-9]:[0-5][0-9],[0-9]{3}"
TIMING = re.compile(rf"({STAMP})\s+-->\s+({STAMP})")


def milliseconds(stamp):
    hours, minutes, rest = stamp.split(":")
    seconds, millis = rest.split(",")
    return ((int(hours) * 60 + int(minutes)) * 60 + int(seconds)) * 1000 + int(millis)


def duration_ms(media):
    result = subprocess.run([
        "ffprobe", "-v", "error", "-show_entries", "format=duration",
        "-of", "json", str(Path(media).resolve()),
    ], check=True, capture_output=True, text=True)
    duration = Decimal(json.loads(result.stdout)["format"]["duration"])
    if not duration.is_finite() or duration <= 0:
        raise ValueError("media duration must be positive and finite")
    return int(duration * 1000)


def lint(text, limit_ms, cps=20):
    if not math.isfinite(cps) or cps <= 0:
        raise ValueError("cps must be positive and finite")
    blocks, block = [], []
    for line, value in enumerate(text.splitlines() + [""], 1):
        if value.strip():
            block.append((line, value))
        elif block:
            blocks.append(block)
            block = []
    issues, previous_start, latest_end = [], None, 0
    if not blocks:
        return [("ERROR", 1, "no cues found")]
    for expected, block in enumerate(blocks, 1):
        line = block[0][0]
        if block[0][1] != str(expected):
            issues.append(("ERROR", line, f"expected cue index {expected}"))
        if len(block) < 3:
            issues.append(("ERROR", line, "cue needs index, timing and text"))
            continue
        line = block[1][0]
        match = TIMING.fullmatch(block[1][1])
        if not match:
            issues.append(("ERROR", line, "invalid timestamp line"))
            continue
        start, end = map(milliseconds, match.groups())
        if end <= start:
            issues.append(("ERROR", line, "end must be after start"))
        if end > limit_ms:
            issues.append(("ERROR", line, "cue ends after media"))
        if previous_start is not None:
            if start < previous_start:
                issues.append(("ERROR", line, "cue starts out of order"))
            elif start < latest_end:
                issues.append(("WARN", line, "overlaps an earlier cue"))
        previous_start = start
        if end > start:
            latest_end = max(latest_end, end)
        visible = re.sub(r"<[^>]*>", "", "".join(v for _, v in block[2:]))
        if end > start:
            rate = len(visible) * 1000 / (end - start)
            if rate > cps:
                issues.append(("WARN", line, f"{rate:.1f} cps exceeds {cps:g}"))
    return issues


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("subtitles")
    parser.add_argument("media")
    parser.add_argument("--cps", type=float, default=20)
    args = parser.parse_args()
    try:
        text = Path(args.subtitles).read_text(encoding="utf-8-sig")
        issues = lint(text, duration_ms(args.media), args.cps)
    except (OSError, ValueError, KeyError, InvalidOperation,
            subprocess.CalledProcessError) as error:
        parser.exit(2, f"error: {error}\n")
    for level, line, message in issues:
        print(f"{level} line {line}: {message}")
    if not issues:
        print("OK: no issues found")
    raise SystemExit(1 if any(level == "ERROR" for level, _, _ in issues) else 0)

Catch an overrun

For a media file exactly three seconds long, save this as late.srt:

1
00:00:00,000 --> 00:00:01,000
Hello.

2
00:00:02,500 --> 00:00:03,500
Goodbye.

Then run:

python srt_lint.py late.srt three_seconds.mp4

Output:

ERROR line 6: cue ends after media

The line number points to the timestamp that needs attention. The process exits with 1 for validation errors, 2 for a read or probe failure, and 0 when there are no errors. Warnings alone keep exit code 0.

Leave reading speed configurable

python srt_lint.py captions.srt export.mp4 --cps 18

That threshold is an editorial setting, not a universal subtitle standard. The count includes spaces and Unicode code points, omits line breaks, and strips simple markup tags. It does not measure spoken words or listening accuracy.

I keep overlaps as warnings because simultaneous speakers may be intentional. For an unusually long cue containing shorter cues, the linter retains the furthest earlier end time, so later overlaps are not missed.

The local checks covered valid Unicode text, malformed timestamps, zero-length cues, reversed order, nested overlaps, and a cue beyond a real three-second export. Once those mechanical problems are cleared, I can spend the playback pass checking whether the captions actually follow the voice.

References: SubRip structure and ffprobe documentation.

Build a Clip-Join Review Sheet With FFmpeg

Joey — Mon, 26 Oct 2026 02:00:00 +0000

Two clips can look acceptable on their own and still make an awkward cut. The subject lands in a different place, a hand changes position, or the next shot begins halfway through another action.

For that review, I want the last few frames of the outgoing clip beside the first few of the incoming clip. A contact sheet makes small spatial changes easier to inspect without scrubbing back and forth.

Take actual frames from both sides

This script selects the last three decoded frames from the first clip and the first three from the second. Shorter clips contribute however many frames they have.

It gets timestamps from ffprobe instead of calculating a last-frame time from duration and average frame rate. FFmpeg then selects the corresponding zero-based frame indices.

Install Pillow and make sure ffmpeg and ffprobe are available on your PATH:

python -m pip install Pillow
ffmpeg -version
ffprobe -version

Save this as join_sheet.py:

import argparse
import json
import math
from pathlib import Path
import subprocess
import tempfile
from PIL import Image, ImageDraw, ImageOps


def probe(path):
    result = subprocess.run([
        "ffprobe", "-v", "error", "-select_streams", "v:0",
        "-show_frames", "-show_entries",
        "frame=best_effort_timestamp_time", "-of", "json", str(path),
    ], check=True, capture_output=True, text=True)
    frames = json.loads(result.stdout).get("frames", [])
    if not frames:
        raise ValueError(f"no video frames: {path}")
    times = [float(frame["best_effort_timestamp_time"]) for frame in frames]
    if not all(math.isfinite(t) for t in times):
        raise ValueError("non-finite frame timestamp")
    return times


def build(left, right, output):
    paths = [Path(left).resolve(), Path(right).resolve()]
    times = [probe(path) for path in paths]
    picks = [list(range(max(0, len(times[0]) - 3), len(times[0]))),
             list(range(min(3, len(times[1]))))]
    sheet = Image.new("RGB", (960, 448), "#151a1d")
    draw = ImageDraw.Draw(sheet)
    manifest = []
    with tempfile.TemporaryDirectory() as temporary:
        for row, (path, stamps, indices) in enumerate(zip(paths, times, picks)):
            selection = "+".join(f"eq(n\\,{index})" for index in indices)
            pattern = str(Path(temporary) / f"row{row}-%02d.png")
            subprocess.run([
                "ffmpeg", "-v", "error", "-i", str(path), "-map", "0:v:0",
                "-vf", f"select={selection}", "-fps_mode", "vfr",
                "-frames:v", str(len(indices)), pattern,
            ], check=True)
            for column, index in enumerate(indices):
                frame = Path(temporary) / f"row{row}-{column + 1:02d}.png"
                with Image.open(frame) as image:
                    thumb = ImageOps.contain(image.convert("RGB"), (320, 180))
                x = column * 320 + (320 - thumb.width) // 2
                y = row * 224
                sheet.paste(thumb, (x, y))
                side = "OUT" if row == 0 else "IN"
                draw.text((column * 320 + 8, y + 188),
                          f"{side} frame {index} | PTS {stamps[index]:.6f}s")
                manifest.append({"side": side, "file": str(path),
                                 "frame": index, "pts_seconds": stamps[index]})
    output = Path(output)
    output.mkdir(parents=True, exist_ok=False)
    sheet.save(output / "join.png")
    (output / "frames.json").write_text(json.dumps(manifest, indent=2) + "\n")
    return manifest


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    for name in ("left", "right", "output"):
        parser.add_argument(name)
    args = parser.parse_args()
    try:
        result = build(args.left, args.right, args.output)
    except (OSError, ValueError, KeyError, subprocess.CalledProcessError) as error:
        parser.exit(2, f"error: {error}\n")
    print(f"Saved {len(result)} frames to {args.output}/join.png")

Review the cut

python join_sheet.py outgoing.mp4 incoming.mp4 join-review

The new directory contains join.png and frames.json. The top row is OUT; the bottom row is IN. Both rows run chronologically from left to right. Each label gives the frame index and its source presentation timestamp in seconds, which need not start at zero.

I use three checks while looking at the sheet:

Position and scale: does the subject jump without a motivated change of viewpoint?
Action phase: does the incoming movement follow the outgoing movement, or restart it?
Light and background: is there an accidental change that distracts from the cut?

The small synthetic check used two clips with a rectangle in the same position, then moved the incoming rectangle to the opposite side. The sheet exposes that displacement. One-frame and variable-frame-rate inputs were also checked.

This version decodes the clips rather than seeking, so I use it for short takes. It reviews the files' outer boundaries: export trimmed segments first if the intended edit falls inside either file.

Once a mismatch is visible, I can try a different in-point or take. I still play the cut at speed to decide whether the movement works; the sheet gives me a precise place to investigate.

References: ffprobe frame output and FFmpeg's select filter.

Audit Image Edits Outside the Requested Region With Python

Joey — Sun, 25 Oct 2026 05:28:08 +0000

A local image edit gives me two things to review: the requested change and everything that was meant to stay untouched. Looking only at the edited object makes the second part easy to miss.

I want a map of changes outside the allowed region. A binary mask makes that region explicit: white means editable; black means preserve.

Compare the preserved pixels

Install Pillow:

python -m pip install Pillow

Save this as image_audit.py:

import argparse
import json
from pathlib import Path
from PIL import Image, ImageChops, ImageOps


def load(path, mode):
    with Image.open(path) as image:
        return ImageOps.exif_transpose(image).convert(mode)


def audit(before, after, mask, output, threshold=8):
    if not 0 <= threshold <= 255:
        raise ValueError("threshold must be between 0 and 255")
    a, b = load(before, "RGBA"), load(after, "RGBA")
    allowed = load(mask, "L")
    if a.size != b.size or a.size != allowed.size:
        raise ValueError("images and mask must have identical dimensions")
    allowed = allowed.point(lambda p: 255 if p >= 128 else 0)
    outside = ImageOps.invert(allowed)
    count = outside.histogram()[255]
    if not count:
        raise ValueError("mask leaves no preserved pixels to check")

    channels = ImageChops.difference(a, b).split()
    delta = channels[0]
    for channel in channels[1:]:
        delta = ImageChops.lighter(delta, channel)
    changed = delta.point(lambda p: 255 if p > threshold else 0)
    changed_outside = ImageChops.multiply(changed, outside)
    hits = changed_outside.histogram()[255]
    heatmap = Image.merge("RGB", (
        ImageChops.multiply(delta, outside),
        ImageChops.multiply(delta, allowed),
        Image.new("L", a.size),
    ))
    report = {
        "threshold": threshold,
        "preserved_pixels": count,
        "changed_outside": hits,
        "changed_outside_percent": round(100 * hits / count, 4),
    }
    output = Path(output)
    output.mkdir(parents=True, exist_ok=False)
    heatmap.save(output / "heatmap.png")
    (output / "report.json").write_text(json.dumps(report, indent=2) + "\n")
    return report


if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    for name in ("before", "after", "mask", "output"):
        parser.add_argument(name)
    parser.add_argument("--threshold", type=int, default=8)
    args = parser.parse_args()
    try:
        result = audit(args.before, args.after, args.mask,
                       args.output, args.threshold)
    except (OSError, ValueError) as error:
        parser.exit(2, f"error: {error}\n")
    print(json.dumps(result, indent=2))

The difference uses the largest absolute change across RGBA channels. A change in just one channel still counts. The report includes pixels strictly above the chosen threshold; the heatmap keeps the raw difference strength, with red outside the editable area and green inside.

I deliberately stop on a size mismatch. Resizing one image to make the comparison work would introduce another change before the audit even starts.

Try a known change

This fixture changes 100 allowed pixels, six preserved pixels, and one extra preserved pixel by only five channel values:

from PIL import Image, ImageDraw

a = Image.new("RGB", (100, 60), (128, 128, 128))
a.save("before.png")
mask = Image.new("L", a.size, 0)
ImageDraw.Draw(mask).rectangle((20, 10, 39, 29), fill=255)
mask.save("mask.png")
b = a.copy()
ImageDraw.Draw(b).rectangle((20, 10, 29, 19), fill=(200, 128, 128))
ImageDraw.Draw(b).rectangle((0, 0, 1, 2), fill=(128, 170, 128))
b.putpixel((99, 59), (133, 128, 128))
b.save("after.png")

Run it with a new output directory:

python image_audit.py before.png after.png mask.png audit --threshold 8

The result is:

{
  "threshold": 8,
  "preserved_pixels": 5600,
  "changed_outside": 6,
  "changed_outside_percent": 0.1071
}

That percentage uses only the preserved region as its denominator. A large editable area cannot dilute it.

The threshold of eight is a starting choice, not a quality standard. If nearly the whole preserved region lights up, I check alignment, compression, and export settings before treating every red pixel as an editing mistake. For transparent images, this compares stored RGBA values, including RGB hidden under transparency.

The useful output is where to look next. Six changed pixels near a logo may matter more than a much larger change in background grain.

Reference: Pillow ImageChops documentation.

Split a Storyboard Grid Into Clean Frames With Pillow

Joey — Sat, 24 Oct 2026 13:43:38 +0000

When I split a storyboard sheet, I want each exported file to start at the edge of the actual frame. Dividing the full image width by the column count also divides the borders and gaps, which can leave strips of neighboring panels in the output.

I calculate the usable area first:

usable width = image width - 2 * margin - (columns - 1) * gap

Then I divide that width by the column count and apply the same calculation to the height.

For this example, the sheet is 1024 x 412 pixels: two rows, three columns, a 20-pixel outer margin, and 12-pixel gaps. Each frame is 320 x 180.

Install Pillow:

python -m pip install Pillow

Save this as split_storyboard.py, put board.png beside it, and run it from that directory. The script creates a new shots folder; for another run, choose a different destination name.

import json
from pathlib import Path

from PIL import Image


def split_grid(source, destination, rows, cols, margin=0, gap=0):
    if rows <= 0 or cols <= 0 or margin < 0 or gap < 0:
        raise ValueError("Use positive rows/cols and non-negative margin/gap.")

    with Image.open(source) as image:
        width, height = image.size
        usable_w = width - 2 * margin - (cols - 1) * gap
        usable_h = height - 2 * margin - (rows - 1) * gap

        if usable_w <= 0 or usable_h <= 0:
            raise ValueError("Margins and gaps leave no usable image area.")

        cell_w, remainder_w = divmod(usable_w, cols)
        cell_h, remainder_h = divmod(usable_h, rows)
        if remainder_w or remainder_h:
            raise ValueError("Grid does not divide evenly. Check margin/gap.")

        output = Path(destination)
        output.mkdir(parents=True, exist_ok=False)
        frames = []

        for row in range(rows):
            for col in range(cols):
                left = margin + col * (cell_w + gap)
                top = margin + row * (cell_h + gap)
                box = (left, top, left + cell_w, top + cell_h)
                name = f"shot_{row * cols + col + 1:02d}.png"
                image.crop(box).save(output / name)
                frames.append({"file": name, "box": list(box)})

        manifest = {
            "source": str(source),
            "size": [width, height],
            "frames": frames,
        }
        (output / "manifest.json").write_text(
            json.dumps(manifest, indent=2), encoding="utf-8"
        )

    print(f"Saved {len(frames)} frames ({cell_w}x{cell_h})")


if __name__ == "__main__":
    split_grid("board.png", "shots", rows=2, cols=3, margin=20, gap=12)

Run:

python split_storyboard.py

For the example dimensions, the output is:

Saved 6 frames (320x180)

Files run from shot_01.png to shot_06.png, reading left to right, then top to bottom. The first crop's box is [20, 20, 340, 200]; the last is [684, 212, 1004, 392]. Both are recorded in manifest.json.

I use divmod() because rounding down would hide a layout mismatch. Change the example's width to 1025 pixels and the script stops with:

ValueError: Grid does not divide evenly. Check margin/gap.

That sends me back to the measurements before I export six slightly wrong frames.

This version expects equal-sized panels, the same margin on all four sides, and one gap size in both directions. A number or caption drawn inside a panel remains part of that panel; excluding the gutters won't remove it.

5 Things I Learned From Bad AI Video Generations

Joey — Wed, 23 Sep 2026 00:44:20 +0000

AI video prompts can look completely reasonable and still produce a result that is not what you expected.

I ran into this while testing a skiing video.

The skier moved downhill correctly, the snow reacted to the skis, and the overall scene looked good. The problem was the camera. I wanted it to move in behind the skier, come closer, pass near the subject, and then pull away.

Instead, it barely moved.

My prompt included the phrase "dynamic tracking shot," so at first I thought the model had simply ignored the camera instruction. But when I looked at the prompt again, I realized that I had not actually described the camera movement in much detail.

That test changed the way I write AI video prompts.

I now spend less time adding descriptive words and more time separating the different kinds of movement inside the shot.

Here are five things that have helped me.

1. Describe What Actually Moves

One problem with AI video prompts is that they can sound like video prompts while still mostly describing a static image.

For example:

A skier on a snowy mountain, cinematic lighting, dramatic winter landscape, dynamic movement.

There is nothing technically wrong with this prompt, but most of it describes the appearance of the scene.

The model still has to decide what dynamic movement means.

I usually get a more useful result when I describe the action directly.

Instead of:

A skier moving through the snow.

I would write:

The skier accelerates downhill from left to right, leans into a sharp turn, and cuts across the slope.

The second version gives the model more information about direction and sequence.

This does not mean every movement needs to be described in extreme detail. Long prompts can create their own problems. I mainly look for vague verbs or adjectives that are standing in for an action I could describe more clearly.

Words such as dynamic, cinematic, or energetic can help describe the overall feeling of a shot, but they usually do not replace an actual motion instruction.

2. Describe the Camera Path, Not Only the Shot Type

This was the main problem in my skiing test.

The subject motion was already acceptable. The skier moved naturally, and the skis kicked up snow during the turn.

The camera was the part that did not match what I had imagined.

My original instruction was simply:

dynamic tracking shot

I knew what I meant by that. The model did not necessarily know which version of a tracking shot I wanted.

So I rewrote the camera instruction as a path:

The camera approaches from behind the skier, moves alongside them, closes the distance, passes near the subject, then separates as snow bursts across the frame.

The result was much closer to the movement I wanted.

Since then, I still use terms such as tracking shot, dolly shot, or aerial shot, but I do not rely on them when the exact camera movement matters.

For example, there is a fairly big difference between:

The camera tracks the runner.

and:

The camera begins behind the runner, moves toward their left side, briefly matches their speed, then pulls ahead.

Both can describe a tracking shot, but the second one gives the model an actual route through the scene.

3. Check Whether the Environment Should React

Sometimes the main subject is moving correctly and the video still feels strangely static.

In those cases, I check what is happening around the subject.

In the skiing example, this made a noticeable difference.

Compare:

The skier makes a sharp turn.

with:

The skier makes a sharp turn. The skis cut into the snow and throw a burst of powder outward as the skier passes.

The second prompt is not only describing the skier. It is also describing what the movement does to the environment.

This can apply to many types of shots.

A person running may move their clothes or hair. A car may throw up dust or spray water from the road. Someone walking through curtains should probably move the fabric. An object falling into water should affect the surface around it.

I do not add environmental reactions to every prompt because that can make a simple scene unnecessarily complicated.

But when the subject is doing the correct action and the shot still feels flat, this is one of the things I check.

4. Use Reference Images for Identity Instead of Repeating Everything in the Prompt

I noticed a different problem while testing a recurring character called Carrie.

I had several reference images for her, including front-facing, profile, and full-body views.

At first, I still wrote long descriptions of her appearance inside the video prompt:

A young woman with [face description], [hair description], [clothing description]...

After testing the workflow a few times, I found that much of this information was already coming from the reference image.

That meant the prompt could focus more on the action.

For example:

Carrie walks toward the table, pulls out the chair, sits down, and looks toward the window.

The reference image handles the character identity, while the prompt describes what happens in the shot.

I also found that the type of reference image matters.

For a close-up, a clear front-facing reference can be useful. For a walking sequence or another shot where body proportions matter, I prefer a wider or full-body reference.

This also makes failed generations easier to troubleshoot.

If the character identity changes too much, I check the reference setup first.

If the character still looks correct but performs the wrong movement, I look at the motion prompt.

Before I started separating those two problems, my instinct was often to keep adding more description to the same prompt. That usually made it harder to tell which instruction was actually helping.

5. Plan the Sequence in Shots, Even If You Generate It as One Video

I learned this while making a 15-second bookstore sequence.

The basic idea was simple: a character enters a bookstore, walks between the shelves, finds a book, opens it, and ends in a quieter final shot.

When I wrote the whole sequence as one paragraph, it became difficult to see whether the timing and progression actually made sense.

So I planned it as separate beats first:

Shot 1: Establish the bookstore.

Shot 2: Follow the character between the shelves.

Shot 3: Move closer as they reach for a book.

Shot 4: Show them opening it.

Shot 5: End on a quieter frame.

This does not mean I always generate five separate clips.

In this test, generating the shots independently sometimes caused a different problem. The position of the shelves, the character, and the camera changed between clips, so the sequence no longer felt like the same physical space.

A longer continuous generation could keep the environment more coherent.

The shot list was still useful, though, because it gave me a way to plan the timing and progression before deciding how many generations to make.

I now treat shot planning and clip generation as two separate decisions.

A video can be planned as five shots and still be generated as one continuous sequence.

The Prompt Structure I Check First

After these tests, I started using four categories when a motion prompt is not working:

Subject motion + Camera path + Environmental reaction + Temporal sequence

For the skiing video, I might break the prompt down like this:

Subject motion

The skier accelerates downhill and leans into a sharp turn.

Camera path

The camera approaches from behind, moves alongside the skier, then closes the distance as they pass.

Environmental reaction

The skis cut into the snow and throw powder toward the camera.

Temporal sequence

The shot begins wide, moves into a close tracking moment, then pulls away as the skier continues downhill.

I do not necessarily write every prompt in this exact format.

It is more useful as a troubleshooting checklist.

If the skier is moving correctly but the camera is static, I probably do not need to rewrite the subject description.

If the camera moves correctly but the scene still feels lifeless, I can look at environmental reactions.

If all the individual actions are there but they happen in the wrong order, the temporal sequence may need to be clearer.

AI video generation is still unpredictable. A model can ignore an instruction or introduce something that was never in the prompt.

But breaking motion down this way has made failed generations easier for me to diagnose.

And in practice, that has been more useful than simply making the prompt longer.

What usually goes wrong first in your AI video generations: subject motion, camera movement, character consistency, or timing?

#ai #promptengineering #videogeneration #tutorial