DEV Community: Jacob Yang

Build a Hook Generator in Python That Checks the First Three Seconds

Jacob Yang — Sun, 08 Nov 2026 05:07:18 +0000

A script can be short on the page and still miss the opening shot. “Before you replace your old desk mat, try this” feels concise until you read it aloud, pause before the reveal, and discover the product has not appeared yet.

This tutorial builds a deliberately small Python hook generator: three templates, a transparent scoring function, and a few tests. It does not predict virality. It catches avoidable production problems before someone records a batch of openings that are too long, too vague, or based on claims the product cannot support.

I work on UGCfy AI. The code here is a standalone teaching implementation, not a copy of its production system, an unofficial API client, or an ad-performance model. The examples use a hypothetical desk mat. None of the scores below come from an advertising campaign.

Separate writing from permission to make a claim

Start with a brief, not a prompt that says “make this viral.” For our fictional desk mat, the brief contains a problem: a mat that slides while someone types. The desired outcome is a steadier keyboard. The demonstration is a side-by-side push on the actual desk. The product team still needs to establish that the advertised mat does what the demonstration implies.

The brief should also list forbidden claims. No invented customer counts. No “sold out again” without inventory evidence. No first-person testimonial unless the speaker actually had that experience. A template can make a fabricated statement sound casual; that does not make it acceptable.

I keep a candidate's wording separate from its review flags. The program cannot look at a sentence and know whether the product really passed a test. Someone has to check the evidence and mark the claim supported. Making that judgment explicit is better than hiding it inside a keyword match that rewards any hook containing “proven.”

For a production tool, store the evidence reference next to the flag: a test recording, a reviewed product specification, or an approved claim document. A boolean is sufficient for this tutorial, but it is not a substitute for a traceable review.

Generate a small, inspectable candidate set

There is no language-model dependency in this version. Templates make it easy to see where every phrase came from and to test the same brief repeatedly. That is useful when the goal is learning the pipeline rather than maximizing variety.

import re

def words(text):
    return re.findall(r"[A-Za-z0-9]+(?:['’-][A-Za-z0-9]+)*", text)

def generate(problem, outcome, action):
    fields = (problem, outcome, action)
    if not all(isinstance(x, str) and x.strip() for x in fields):
        raise ValueError("nonempty brief fields required")
    return [
        f"Still dealing with {problem.strip()}?",
        f"Want {outcome.strip()}? Watch this.",
        f"Before you {action.strip()}, try this.",
    ]

Those templates cover a problem call-out, a desired outcome, and an interruption before an action. They are structures, not guarantees of quality. A poorly chosen problem will remain a poorly chosen problem after the function adds a question mark.

Notice the grammar contract. problem should be a noun phrase such as “a sliding desk mat,” not a complete sentence. action should be a verb phrase such as “replace your desk mat.” If the caller passes “your mat keeps sliding,” the first template becomes awkward. In a larger tool, document that contract or store structured phrase types instead of accepting arbitrary strings.

The tokenizer is intentionally English-oriented. It counts contractions and hyphenated expressions as one token. That choice keeps the example consistent, but it does not establish actual pronunciation length. A long product name, a number, or an unfamiliar acronym can take longer to say than its token count suggests.

Turn three seconds into a budget, not a slogan

A word cap is only a rough timing proxy. Here the configurable speaking-rate assumption is 160 words per minute. At that assumed pace, eight words occupy three seconds before any pauses. That is arithmetic, not a measured average for creators or a platform rule.

The estimate is 60 × word_count / words_per_minute. A different speaker, language, or delivery changes the budget. If the creator pauses for emphasis or the opening needs a visual demonstration, fewer spoken words may be appropriate. Do not speed the voice up merely to satisfy the score.

I assign forty points to fitting the estimated window, twenty-five to specificity, twenty to having a matching opening shot, and fifteen to supported claims. Those weights are editorial choices. There is no training set behind them. The full explanation travels with the score so a reviewer can disagree with a rule rather than treating a number as authority.

def score(text, *, specific, visual, supported, wpm=160):
    if wpm <= 0:
        raise ValueError("wpm must be positive")
    count = len(words(text))
    seconds = 60 * count / wpm
    points, reasons = 0, []
    checks = (
        (0 < count and seconds <= 3, 40, "fits estimated three seconds"),
        (specific, 25, "specific audience problem or outcome"),
        (visual, 20, "matching opening shot available"),
        (supported, 15, "claims supported by brief"),
    )
    for passed, weight, label in checks:
        if passed:
            points += weight
            reasons.append(label)
    return dict(
        text=text, words=count, estimated_seconds=round(seconds, 2),
        score=points, eligible=bool(count and supported), reasons=reasons,
    )

Eligibility is separate from ranking. Unsupported claims are not rescued by a good length score. An empty string is also ineligible even if someone has accidentally checked the “supported” box. Only compare eligible candidates, and still review them before recording.

Specificity and visual availability are human inputs here. Passing True is an annotation, not something the function discovered. That distinction matters when showing results to a teammate who might otherwise assume the program watched the footage or understood the product.

The test run, including the awkward candidate

The complete executable file is saved as hooks.py beside this draft. I ran it using the following hypothetical brief:

hooks = generate(
    "a sliding desk mat",
    "a steadier keyboard",
    "replace your old desk mat",
)
results = [
    score(h, specific=True, visual=True, supported=True)
    for h in hooks
]

For this fixture, all three review flags were deliberately set to true. That makes it a test of generation and timing arithmetic, not an independent review of a real product.

Generated hook	Words	Estimated seconds at assumed pace	Rule score
Still dealing with a sliding desk mat?	7	2.62	100
Want a steadier keyboard? Watch this.	6	2.25	100
Before you replace your old desk mat, try this.	9	3.38	60

The third candidate fails the timing check. That is useful behavior: generation does not force every output through the same length mold, and scoring gives a specific reason to revise one. “Desk mat sliding? Try this.” is a possible edit, but it needs its own read-through and matching shot.

The script also asserts that an unsupported claim is ineligible and that an empty hook is ineligible. Those assertions passed in the same run. They establish a few code invariants; they say nothing about click-through rate, early retention, cost per thousand impressions, or sales.

A score of one hundred means only that a candidate satisfied this rule set under the supplied annotations. It does not mean a perfect advertisement. Two candidates can tie while producing very different experiences on screen.

Review the opening as a shot, not just a line

For “Still dealing with a sliding desk mat?”, the first frame should make the sliding mat legible. If the video opens on a face, then cuts to a wide room view, then finally shows the mat, the spoken line and the visual are competing instead of cooperating.

Write a tiny shot specification beside each candidate. Record the first image, the action, any on-screen text, and the point where the product becomes identifiable. A useful specification might say: close crop on typing hands; the old mat shifts; no text covering the movement; the replacement enters in the next shot.

Test the opening without sound. Can a viewer identify the problem? Then listen without the picture. Does the sentence still make sense? You do not need both channels to explain everything independently, but an essential detail should not depend on tiny text that disappears before anyone can read it.

Finally record a rough take. Use the actual speaker and intended delivery. A stopwatch or waveform replaces the speaking-rate estimate at this stage. If the line takes too long, cut words or redesign the reveal. The point of the estimate is to make that correction cheap, not to overrule the recording.

Where a hosted generator fits

If you want a wider candidate pool without maintaining templates, UGCfy AI's hook generator takes a product description and platform choice and returns hook suggestions with their associated psychological angles. It is an alternative writing surface; the review process still belongs to you.

Do not treat any generated first-person story, social-proof line, or before-and-after statement as automatically approved. The same evidence check applies whether the words came from a template, a language model, a freelance writer, or a brainstorm in a meeting. The tool proposes language; your brief determines what you can responsibly say.

Replace the heuristic with an experiment, carefully

Shortlist openings that communicate genuinely different angles. Changing “still” to “always” rarely teaches as much as comparing a visible problem against a clear desired outcome. Keep the script body and offer consistent enough that you can interpret the opening change.

Define the outcome before the test. Early retention can help diagnose attention; qualified visits or purchases answer different business questions. A dramatic opening may earn a pause while attracting the wrong audience. Record both the attention signal and the downstream outcome relevant to the campaign.

Keep the platform's actual metric definition in your notes. A view is not interchangeable across placements or reporting interfaces. Avoid declaring a winner from a handful of events, and do not interpret unequal automated delivery as a clean randomized experiment. The delivery system may be selecting audiences as well as allocating impressions.

The practical result is a short audit trail: the brief, generated wording, reviewer flags, estimated duration, recorded duration, first shot, and observed campaign results. The Python score belongs near the beginning of that trail. Its job is to reject obvious problems before production, not to impersonate evidence from the end.

Add Sound Effects to Video With Python and ffmpeg: Measuring the Alignment Error

Jacob Yang — Thu, 05 Nov 2026 01:26:41 +0000

AI video generators are very good at motion and often silent. If you generate a clip of a ball bouncing, a door closing, or a glass being set on a table, you usually get pixels and no audio. Adding the right "thud" by hand in an editor is fine for one clip. It doesn't scale to a batch.

This post builds a small Python + ffmpeg pipeline that does three things:

Finds the frames where an impact happens.
Mixes a short sound effect at exactly those times.
Measures how far the audio actually lands from the true impact time.

That third step is the one most tutorials skip. "It sounds about right" isn't a number. I wanted one.

All code below ran on a Linux box with Python 3.13, NumPy and ffmpeg 7.1. Everything is in three files you can copy.

The test clip is synthetic, on purpose

To measure alignment error you need ground truth: the exact moment each impact really happens. Real AI video doesn't give you that. So the test clip is synthetic: a white ball bouncing on a grey floor, rendered frame by frame with NumPy, piped into ffmpeg.

The bounce period is 1.27 s. At 30 fps that's 38.1 frames, so impacts deliberately fall between frames. A period like 1.3 s (exactly 39 frames) would land every impact on a frame and make any detector look perfect. I tried that first and got 0.0 ms error everywhere, which tells you nothing.

"""Render a synthetic silent clip: a ball bouncing on a floor. Ground-truth impact times are known exactly."""
import json, subprocess, numpy as np
W, H, FPS, DUR = 640, 360, 30, 8.0
FLOOR, R, PERIOD = 300, 18, 1.27         # one bounce every 1.27 s (not frame-aligned on purpose)
N = int(FPS * DUR)
def y_at(t):
    ph = (t % PERIOD) / PERIOD             # 0 -> 1 within a bounce
    return FLOOR - R - 220 * 4 * ph * (1 - ph)   # parabola, touches floor at ph=0
impacts = [round(k * PERIOD, 4) for k in range(1, int(DUR / PERIOD) + 1) if k * PERIOD < DUR]
ff = subprocess.Popen(["ffmpeg", "-y", "-loglevel", "error", "-f", "rawvideo", "-pix_fmt", "gray",
    "-s", f"{W}x{H}", "-r", str(FPS), "-i", "-", "-c:v", "libx264", "-pix_fmt", "yuv420p", "silent.mp4"],
    stdin=subprocess.PIPE)
yy, xx = np.mgrid[0:H, 0:W]
for i in range(N):
    t = i / FPS
    f = np.full((H, W), 30, np.uint8); f[FLOOR:, :] = 90
    cx, cy = 80 + i * 2, y_at(t)
    f[(xx - cx) ** 2 + (yy - cy) ** 2 <= R * R] = 230
    ff.stdin.write(f.tobytes())
ff.stdin.close(); ff.wait()
json.dump({"fps": FPS, "impacts_s": impacts}, open("ground_truth.json", "w"), indent=1)
print("impacts:", impacts)

Output:

impacts: [1.27, 2.54, 3.81, 5.08, 6.35, 7.62]

Step 1: detect impacts from motion

For this clip, detection is simple: threshold the bright ball, take its vertical centroid per frame, and call an impact wherever downward motion flips to upward. ffmpeg decodes to raw grayscale and Python reads it from a pipe, so there are no temporary image files.

The key detail is sub-frame refinement. The detected frame is only accurate to ±half a frame (±16.7 ms at 30 fps). Fitting a parabola through the three samples around the lowest point gives a fractional frame index. It's a cheap trick, and the measurements below show whether it pays off.

Step 2: mix the effect with adelay + amix

The sound effect here is also synthetic: a 120 ms decaying 70 Hz sine with a short click on top, generated with NumPy and written as a WAV. In a real pipeline you'd swap in a recorded or generated effect.

Each impact gets its own adelay branch (delay in milliseconds), then amix sums them. normalize=0 matters: without it, amix scales each input down by the number of inputs, so six thuds come out much quieter than one. The ffmpeg filters documentation covers both filters.

"""Detect impact frames in a silent video and mix a short 'thud' at each one with ffmpeg."""
import json, subprocess, sys, wave, numpy as np
SRC, OUT = sys.argv[1], sys.argv[2]
W, H = 640, 360
def probe_fps(path):
    r = subprocess.run(["ffprobe", "-v", "error", "-select_streams", "v:0", "-show_entries",
        "stream=r_frame_rate", "-of", "csv=p=0", path], capture_output=True, text=True).stdout.strip()
    a, b = r.split("/"); return int(a) / int(b)
def frames(path):
    p = subprocess.Popen(["ffmpeg", "-loglevel", "error", "-i", path, "-f", "rawvideo",
        "-pix_fmt", "gray", "-"], stdout=subprocess.PIPE)
    while (buf := p.stdout.read(W * H)) and len(buf) == W * H:
        yield np.frombuffer(buf, np.uint8).reshape(H, W)
fps = probe_fps(SRC)
# 1) track the brightest blob's vertical centroid per frame
ys = []
for f in frames(SRC):
    m = f > 180
    ys.append(np.nonzero(m)[0].mean() if m.any() else np.nan)
ys = np.array(ys)
# 2) an impact = local maximum of y (lowest on screen) where motion reverses from down to up
v = np.diff(ys)
hits = [i for i in range(1, len(v)) if v[i - 1] > 0 and v[i] <= 0]
# refine to sub-frame with a parabola through the 3 samples around the peak
def refine(i):
    a, b, c = ys[i - 1], ys[i], ys[i + 1]
    d = a - 2 * b + c
    return i + (0.5 * (a - c) / d if d else 0.0)
REFINE = "--no-refine" not in sys.argv
times = [(refine(i) if REFINE else i) / fps for i in hits if 0 < i < len(ys) - 1]
# 3) synthesize a 120 ms thud (decaying 70 Hz sine + click) as the effect
SR = 48000
t = np.arange(int(0.12 * SR)) / SR
thud = (np.sin(2 * np.pi * 70 * t) * np.exp(-t * 35) + 0.3 * np.exp(-t * 900)) * 0.8
with wave.open("thud.wav", "wb") as w:
    w.setnchannels(1); w.setsampwidth(2); w.setframerate(SR)
    w.writeframes((thud * 32767).astype(np.int16).tobytes())
# 4) one adelay branch per hit, then amix, then mux onto the original video stream
dur = len(ys) / fps
inputs = ["-i", SRC] + sum([["-i", "thud.wav"] for _ in times], [])
graph = ";".join(f"[{k+1}:a]adelay={int(round(tt*1000))}:all=1[a{k}]" for k, tt in enumerate(times))
graph += ";" + "".join(f"[a{k}]" for k in range(len(times))) + \
    f"amix=inputs={len(times)}:normalize=0,apad,atrim=0:{dur:.3f}[mix]"
subprocess.run(["ffmpeg", "-y", "-loglevel", "error", *inputs, "-filter_complex", graph,
    "-map", "0:v", "-map", "[mix]", "-c:v", "copy", "-c:a", "aac", "-b:a", "128k", OUT], check=True)
json.dump({"fps": fps, "detected_s": [round(x, 4) for x in times]}, open("detected.json", "w"), indent=1)
print(f"fps={fps} hits={len(times)}", [round(x, 3) for x in times])

Note -c:v copy: the video stream isn't re-encoded, so frames stay identical to the input.

Step 3: measure where the audio really lands

Here's the part I cared about. measure.py decodes the final MP4's audio track (after AAC encoding, not the intermediate WAV), finds each thud's onset with a simple amplitude threshold, and compares it with the ground truth.

"""Decode the output audio and measure where each thud actually starts vs ground truth."""
import json, subprocess, sys, numpy as np
OUT = sys.argv[1]; SR = 48000
raw = subprocess.run(["ffmpeg", "-loglevel", "error", "-i", OUT, "-f", "f32le", "-ac", "1",
    "-ar", str(SR), "-"], capture_output=True).stdout
x = np.abs(np.frombuffer(raw, np.float32))
thr = 0.1 * x.max(); onsets = []; i = 0
while i < len(x):
    if x[i] > thr: onsets.append(i / SR); i += int(0.3 * SR)
    else: i += 1
gt = json.load(open("ground_truth.json"))["impacts_s"]
det = json.load(open("detected.json"))["detected_s"]
rows = []
for g in gt:
    o = min(onsets, key=lambda t: abs(t - g)) if onsets else float("nan")
    d = min(det, key=lambda t: abs(t - g)) if det else float("nan")
    rows.append((g, d, o, (d - g) * 1000, (o - g) * 1000))
print("truth_s  detected_s  audio_onset_s  detect_err_ms  audio_err_ms")
for r in rows: print(f"{r[0]:7.3f}  {r[1]:10.3f}  {r[2]:13.3f}  {r[3]:13.1f}  {r[4]:12.1f}")
e = np.array([r[4] for r in rows])
print(f"onsets found={len(onsets)} truth={len(gt)} | audio err mean={e.mean():.1f} ms, "
      f"max |err|={np.abs(e).max():.1f} ms, frame={1000/json.load(open('ground_truth.json'))['fps']:.1f} ms")
json.dump({"rows": rows, "onsets": onsets}, open("measure.json", "w"))

Results

I ran the pipeline twice on the same clip: once snapping to the nearest frame (--no-refine), once with sub-frame refinement. These are the actual outputs:

== mode --no-refine
truth_s  detected_s  audio_onset_s  detect_err_ms  audio_err_ms
  1.270       1.267          1.267           -3.3          -3.0
  2.540       2.533          2.533           -6.7          -7.0
  3.810       3.800          3.800          -10.0         -10.0
  5.080       5.067          5.067          -13.3         -13.0
  6.350       6.333          6.333          -16.7         -17.0
  7.620       7.633          7.633           13.3          13.0
onsets found=6 truth=6 | audio err mean=-6.2 ms, max |err|=17.0 ms, frame=33.3 ms
== mode refine
truth_s  detected_s  audio_onset_s  detect_err_ms  audio_err_ms
  1.270       1.268          1.268           -1.5          -2.0
  2.540       2.537          2.537           -2.6          -3.0
  3.810       3.807          3.807           -2.9          -3.0
  5.080       5.078          5.078           -2.2          -2.0
  6.350       6.350          6.350            0.0           0.0
  7.620       7.622          7.622            2.2           2.0
onsets found=6 truth=6 | audio err mean=-1.3 ms, max |err|=3.0 ms, frame=33.3 ms

What the numbers say:

Nearest-frame snapping: mean error −6.2 ms, worst case 17.0 ms. The error drifts because the 1.27 s period slides against the 33.3 ms frame grid, then wraps when the nearest frame flips to the other side.
Sub-frame parabola: mean error −1.3 ms, worst case 3.0 ms. Roughly a 5–6× smaller worst case for a three-line function.
The audio errors are whole milliseconds because adelay takes integer ms here. Detection error and final audio error match to within 1 ms, so the AAC encode and mux added no measurable offset in this run.

Both modes stay under one frame (33.3 ms) here, but the refined version leaves far more headroom for the extra error a real detector will add.

What this doesn't tell you (caveats)

I want to be clear about the limits, because the clean numbers above come from a clean test:

The clip is synthetic. One bright object, a static background, no motion blur, no compression artifacts beyond one H.264 encode. Real AI video is messier, and a centroid tracker will fail on it. You'd replace step 1 with optical flow, an object detector, or a model that labels events.
Six impacts is a small sample. The numbers are exact for this run, not a statistical benchmark.
The onset detector is naive. A 10% amplitude threshold works for a sharp synthetic thud. Soft sounds (rain, ambience) don't have a clean onset to measure.
Physical timing isn't perceptual timing. Some sounds feel better slightly early. The measurement tells you where the audio is, not where it should be for a given viewer.

When to build it, when to use a tool

This pipeline is useful when you control the footage, the events are visually obvious, and you want reproducible timing across a batch, such as product demos with taps and clicks, or procedurally generated clips.

When the "event" is semantic, like a pour, a crowd, or a city street, writing the detector is the hard part, and matching the kind of sound to the scene is harder still. That's where a hosted tool that reads the clip and generates context-matched audio makes more sense. If that's your case, iMideo has a page for when you want to add sound effects to video from a text prompt (it currently lists clips up to 8 seconds for audio generation). Disclosure: I work on iMideo.

Either way, measure. Even a rough measurement turns "it sounds about right" into a number you can track when you change the detector.

If you run this on real footage, I'd be curious what your worst-case error looks like. Drop it in the comments.

I Wrote a Claude Code SEO Skill, and Testing It Found Two Bugs on Day One

Jacob Yang — Sun, 01 Nov 2026 05:00:01 +0000

Claude Code skills are just folders. A SKILL.md with a name and a description, plus whatever scripts you want the model to run. When the description matches what you asked for, Claude loads the instructions and follows them. That's the whole mechanism, and it's why SEO is a good fit: most on-page checks are deterministic, and a model is much better at explaining a result than at counting characters in a <title> tag.

So I wrote one. It checks a single URL for the on-page basics and hands Claude a JSON report to turn into a fix list. Then I ran it against five real pages and one fake one before trusting it. It broke twice, on pages I'd have assumed were safe.

The layout

.claude/skills/seo-page-check/
â”œâ”€â”€ SKILL.md
â””â”€â”€ scripts/
    â””â”€â”€ check_page.py

Project-level skills live in .claude/skills/ inside the repo; personal ones go in ~/.claude/skills/. Claude Code reads the frontmatter of every skill at startup and only pulls in the body when the description matches the task, so a skill you're not using costs almost nothing.

SKILL.md

name: seo-page-check
description: Check one URL for on-page SEO problems (title, meta description, canonical, robots/noindex, H1, JSON-LD, image alt text) and return a prioritized fix list. Use when the user asks to audit, check, or review the SEO of a specific page or URL.

# SEO page check

1. Run the checker on the URL the user gave:
   `python3 .claude/skills/seo-page-check/scripts/check_page.py <url>`
2. Read the JSON it prints. Do not re-fetch the page yourself unless the script failed.
3. Report in this order, and skip any section with nothing in it:
   - **Blockers**: anything in `blockers` (noindex, non-200 status, canonical pointing to another host).
   - **Fix next**: items in `warnings`, one line each, with the current value quoted.
   - **Fine**: one line listing what passed.
4. For each title or description warning, suggest one rewrite that keeps the page's main keyword. Do not invent keywords that are not on the page.
5. Never claim a ranking impact. Say what is wrong and what to change.

Two choices in there are deliberate.

The description lists the actual checks. Claude decides whether to load a skill from the description alone, so "SEO helper" would be a bad one. It's vague, and it would match half of what you type in a marketing repo. Naming the checks and the trigger ("a specific page or URL") keeps it from firing when you ask for keyword ideas.

Rule 5 is there because models love writing "this will improve your rankings." Nobody knows that from a page check, so the skill forbids it.

The script

Standard library only, so it runs anywhere Claude Code does without a pip install:

#!/usr/bin/env python3
"""Fetch one URL and report on-page SEO issues as JSON. Standard library only."""
import json, sys, urllib.error, urllib.request
from html.parser import HTMLParser
from urllib.parse import urlparse

class Page(HTMLParser):
    def __init__(self):
        super().__init__()
        self.title, self.in_title, self.in_h1 = "", False, False
        self.meta, self.canonical, self.h1s, self.jsonld = {}, None, [], 0
        self.imgs, self.imgs_no_alt, self.title_done = 0, 0, False
    def handle_starttag(self, tag, attrs):
        a = dict(attrs)
        if tag == "title" and not self.title_done: self.in_title = True  # skip SVG <title>s
        elif tag == "meta" and a.get("name"):
            self.meta[a["name"].lower()] = a.get("content") or ""
        elif tag == "link" and "canonical" in (a.get("rel") or "").lower().split():
            self.canonical = a.get("href")
        elif tag == "h1": self.in_h1 = True; self.h1s.append("")
        elif tag == "script" and a.get("type") == "application/ld+json": self.jsonld += 1
        elif tag == "img":
            self.imgs += 1
            if not (a.get("alt") or "").strip(): self.imgs_no_alt += 1
    def handle_endtag(self, tag):
        if tag == "title" and self.in_title: self.in_title, self.title_done = False, True
        elif tag == "h1": self.in_h1 = False
    def handle_data(self, data):
        if self.in_title: self.title += data
        if self.in_h1: self.h1s[-1] += data

The check() function fetches the page, runs the parser, and sorts findings into blockers (things that stop a page from being indexed at all) and warnings (things worth fixing). The thresholds are plain: title 30â€“60 characters, description 70â€“160, exactly one H1, a canonical on the same host, at least one JSON-LD block. You'll want to tune them; I picked them because they're common and easy to argue about.

Test 1: five real pages

I ran the first version against example.com, MDN's HTML docs, Wikipedia's SEO article, Hacker News, and an httpbin URL that returns a 404.

Most of it was fine. Example.com and Hacker News got exactly the warnings you'd expect: short titles, no description, no canonical, no H1. Wikipedia came back with no meta description and "8 of 16 images have no alt text," which is real.

Then MDN:

"title": "HTML: HyperText Markup Language | MDNMDNMDNMozilla",

The page's title is HTML: HyperText Markup Language | MDN. The extra "MDNMDNMozilla" came from the inline SVG logos in the body, because SVG has its own <title> element for accessibility, and my parser was appending every <title> it saw. Any site with inline SVG icons would get a wrong title length and possibly a wrong "title too long" warning. The fix is to stop collecting after the first </title> closes, which is what the title_done flag above does.

The 404 was worse:

{"url": "https://httpbin.org/status/404", "error": "<HTTPError 404: 'Not Found'>"}

urllib raises on any 4xx or 5xx, so the most important blocker, "this page doesn't load," came back as a crash instead of a finding. Following rule 2 of the skill, Claude would then fall back to fetching the page itself, which is exactly what I wanted to avoid. HTTPError is also a response object, so the fix is to catch it and keep going:

    try:
        r = urllib.request.urlopen(req, timeout=20)
    except urllib.error.HTTPError as e:  # 4xx/5xx still has a status worth reporting
        r = e

Test 2: a page built to fail

None of the real pages had a noindex or a cross-domain canonical, and those are the two checks I care about most. So I wrote a fake staging page and served it with python3 -m http.server:

<title>Staging copy of our pricing page</title>
<meta name="robots" content="noindex, nofollow">
<meta name="description" content="short">
<link rel="canonical" href="https://other-domain.example/pricing">
<h1>Pricing</h1><h1>Plans</h1><img src="a.png">

After the fixes, the three test pages came back like this:

Page	Status	Blockers	Warnings	Time
MDN HTML docs	200	none	description 276 chars, no JSON-LD	105 ms
httpbin 404	404	`status 404`	5 (all from the empty error page)	389 ms
Fake staging page	200	noindex; canonical to another host	short description, 2 H1s, no JSON-LD, 1 image without alt	50 ms

Every planted problem showed up, and the MDN title now reads correctly. The checker also looks at the X-Robots-Tag response header, not only the meta tag, because a noindex set at the server level never appears in the HTML.

What testing a skill actually means

There are two halves, and they need different tests.

The script is ordinary code. Give it known-good pages, known-bad pages and a broken URL, and compare the JSON with what you expect. Both bugs above were in this half, and neither would have shown up if I'd only tried it on my own site.

The trigger is the description. The way to test it is to open a fresh Claude Code session in the repo and try prompts that should and shouldn't load it: "check the SEO of https://â€¦" should; "give me blog post ideas about SEO" shouldn't. If it fires too often, narrow the description; if it never fires, the description is probably too abstract. I'd keep a short list of those prompts next to the skill and rerun them whenever you edit the frontmatter.

Where this stops

A single-page checker is the easy part of SEO. It won't tell you which pages lost clicks last month, who you're competing with for a query, or whether a page is even worth fixing. That needs Search Console data and competitor research, and both are harder to make deterministic.

If you want something along those lines without writing it, Tracetify publishes free claude seo skills on GitHub. One compares Search Console periods and ranks the pages worth working on; another traces a competitor's launch history from public sources. Each installs with a single npx skills add command, works in Codex as well as Claude Code, and doesn't need an account. Reading how they structure their SKILL.md files is also a decent way to see how someone else handles the description-and-trigger problem.

For my own checker, the next step is a non-zero exit code whenever blockers is non-empty, so the same script can fail a CI run before a noindex ships to production.

How gaming highlight detection actually works (and why it's harder than it looks)

Jacob Yang — Fri, 27 Mar 2026 04:49:51 +0000

I've been thinking about what makes a gaming highlight "good" from a technical standpoint, and the answer is more complicated than I expected when I started building FragCut.

The intuitive answer is "exciting moments" — kills, clutch plays, comebacks. But excitement is subjective, and ML models don't do subjective. They do signals. The question is: what signals actually correlate with highlight-worthy content?

What the model is really detecting

The naive approach is to treat this as a binary classification problem: highlight vs. non-highlight. Train on labeled clips, deploy, done. This sort of works but has a high false positive rate because it learns superficial correlations instead of the underlying patterns.

A better framing: you're detecting anomalies in game state. Most gameplay is mundane — moving between objectives, farming resources, waiting. Highlights happen when multiple high-signal events cluster together in a short time window.

The signals that matter depend heavily on the game, but there are common patterns across genres:

Rapid health changes (damage events)
Score state changes (kills, objectives)
Audio spikes — particularly crowd audio, kill sounds, ability sounds
Player speed and trajectory (sudden acceleration, unusual paths)
Camera behavior in games where it's reactive to action

The challenge is that these signals don't have equal weight and don't combine linearly. A kill at 80% health is less significant than the same kill at 5% health. An objective capture when your team is down 3-0 is more significant than one when you're up 5-0.

The temporal window problem

Video is a sequence, not a frame. You can't classify a 30-second clip by looking at one frame — you need temporal context. This is where simpler approaches break down.

If you use a sliding window (say, 10 seconds), you get a lot of redundant detections and the boundaries are arbitrary. The clip "starts" when your detector fires, which is usually mid-action rather than before it builds.

The approach that works better: train the model to predict not just "is this exciting?" but also "how many seconds until the highlight peaks?" This gives you a offset you can use to trim the clip so the best moment lands near the 70% mark — early enough to build context, late enough to feel payoff.

Audio is underrated

Most highlight detection papers focus on video frames. Audio is where you get a lot of signal for free.

Games have highly predictable audio cues: kill sounds, ability sounds, crowd reactions in sports games, environmental audio that only plays in specific game states. A model that can correlate audio events with game state changes gets much better precision than one that's purely visual.

The downside: audio is game-specific. Kill sound in Call of Duty doesn't generalize to kill sound in League of Legends. You need either game-specific audio models or a way to normalize across titles.

What we do with false positives

Even a good model produces false positives — clips that score high but aren't actually interesting. The best mitigation isn't better ML, it's better UX.

Showing users 5 candidates they can quickly approve or reject is better than showing them 1 "best" clip and having them feel stuck with it. Human preference data from those interactions becomes training signal for the next model version. FragCut is built around this loop — the model gets better as more creators use it and tell it when it's wrong.

This is probably the most important design decision in the whole system. Treat the model as a filter that narrows the search space, not an oracle that delivers a final answer.

The benchmark problem

There's no standardized benchmark for gaming highlight detection. Different papers use different games, different definitions of "highlight," different evaluation metrics. This makes it genuinely hard to compare approaches or know if you're making real progress.

The pragmatic answer is user satisfaction metrics: do people who use your tool share more, does their audience engagement go up, how often do they edit the output before posting? Those are noisy signals but they're measuring the right thing.

From static images to motion: what I learned building an image-to-video AI pipeline

Jacob Yang — Fri, 27 Mar 2026 04:48:04 +0000

The question I get asked most when I tell people I'm building AI video tools is some version of: "Wait, you can actually make a static photo move now?" The answer is yes, and it's both more impressive and more limited than you'd expect.

Here's what I've learned after spending months working on iMideo, an image-to-video generation platform.

How the models actually work

The core technology is a diffusion model that's been trained not just on images but on video sequences. Instead of generating a single frame, the model learns temporal coherence — how pixels should evolve over time while maintaining object identity and scene consistency.

The main challenge is that video generation requires the model to make decisions about motion that aren't specified in the input. A photo of ocean waves could produce gentle ripples, crashing surf, or something in between. The model has to pick something. This is why prompt engineering matters so much for video generation — you're not just describing what you want to see, you're describing how it should move.

What works well and what doesn't

Some source material generates great video reliably: nature scenes with obvious motion patterns (water, clouds, foliage), portraits where a slight head turn or blink reads as natural, product shots where a simple camera move adds depth.

The failure modes are predictable once you understand them. Hands and fingers are notoriously difficult — the model often loses count of them over time. Text in images tends to distort or disappear. Any scene where the implied motion would require revealing occluded information (a character turning to show their back, a camera panning to reveal what's outside the frame) usually produces artifacts.

The pipeline in practice

The workflow for a production image-to-video pipeline looks roughly like:

Input validation: check aspect ratio, resolution, detect faces vs. non-face subjects
Prompt construction: combine user intent with subject-specific templates
Model selection: different models have different strengths (some handle portraits better, some handle motion intensity better)
Generation: typically 16-24 frames at 8fps, then interpolated to 24fps
Quality filtering: automatic rejection of outputs with obvious artifacts before showing to user

Step 5 is underrated. A 30% rejection rate with silent retry is better UX than showing users a broken output.

Latency is the hard problem

A typical generation run takes 20-45 seconds depending on hardware. That's too long for a synchronous API response, which means you need job queuing, webhooks or polling, and a client that handles the async lifecycle gracefully. The user experience of "your video is generating" needs to be designed carefully or it just feels broken.

We use Upstash Redis for job state and QStash for webhook delivery. It handles the retry logic cleanly and the queue is observable. The actual model inference runs on Replicate, which removes the GPU infrastructure overhead but adds some latency unpredictability on cold starts.

The quality ceiling

I want to be honest about current limitations. The outputs from these models look impressive at 3-5 seconds. At 10+ seconds, most models start to degrade — motion consistency breaks down, the subject drifts from the original. The field is moving fast (pun intended), but we're not at the point where you can generate a 60-second coherent clip from a single photo.

For social media content, product showcases, and creative experimentation, the current quality ceiling is genuinely useful. For anything requiring long-form narrative motion, you're still hitting hard limits.

If you want to experiment with image-to-video generation without building the pipeline yourself, iMideo is worth trying. But if you're building your own pipeline, the most important decision is how you handle the async job lifecycle and what your rejection/retry strategy looks like — not which model you pick.

How I think about LinkedIn profile photos as a developer (and what the data actually says)

Jacob Yang — Fri, 27 Mar 2026 04:46:32 +0000

I've updated my LinkedIn photo exactly twice in six years. Both times I used whatever photo happened to look halfway decent on my phone. I suspect most developers I know have done the same thing.

The conventional wisdom is that profile photos "matter for first impressions" — which is technically true but not very useful. What does matter, specifically? I looked into it.

What the research actually shows

LinkedIn's own data says profiles with photos get 21x more views and 36x more messages than profiles without photos. Those numbers are probably inflated (they include accounts that were abandoned before adding a photo), but the directional conclusion seems right: having something is much better than nothing.

The more interesting finding is from a 2022 study by PhotoFeeler, a site where people rate profile photos. They had users evaluate the same individuals across different photo types. Studio-lit headshots consistently scored higher on "competence" and "influence" — not by a little, either. The gap between a casual selfie and a proper headshot was around 40 percentile points on those dimensions.

What the study couldn't control for is whether the rating gap translates to actual job outcomes. I genuinely don't know. But I'd rather have the photo that reads "I take this seriously" than the one that reads "I grabbed this from my cousin's wedding."

The problem with selfies

Most developers default to selfies because they're convenient. The issue isn't really the phone camera — modern smartphone cameras are excellent. The issue is angle, lighting, and the fact that arm's-length photos tend to distort facial proportions.

A selfie taken from slightly below eye level at arm's length creates the "looking down at you" effect that's fine for Instagram but comes across as oddly confrontational in a professional context. Lighting from a phone screen in a dim room adds unflattering shadows. These are solvable problems, but they require some setup effort most people don't bother with.

When AI headshot tools actually make sense

I've been testing a few AI headshot generators because I was curious how far the technology has gotten. For a developer with one decent reference photo and zero interest in booking a photography session, they're genuinely useful now.

The approach that works: upload 10-15 clear photos (varied angles, good lighting, no sunglasses), let the model fine-tune on your face, generate 50-100 options, pick the best 3-4. Tools like ProfessionalHeadshot.io handle this pipeline in one workflow — you upload the source photos, it runs the generation, you download the results. The quality surprised me. A few outputs were noticeably AI-processed (too smooth, slightly uncanny valley), but 5-6 per batch looked like actual studio photos.

The catch: it works much better if your source photos have varied angles and good natural lighting. Upload 15 photos from the same angle in the same bad light, and you'll get 50 variations of the same mediocre result. Garbage in, garbage out.

What I actually changed

I updated my LinkedIn photo after running the test batch. Went from a cropped conference photo to a clean, neutral-background headshot that looks like I planned it. I haven't tracked whether my InMail response rate changed, but I feel better about the profile, which is probably the more honest metric.

If you've been using the same photo for 3+ years and it's clearly a crop from a group photo, it's worth spending 20 minutes on this. Either set up a decent DIY shoot (north-facing window, phone camera on a book stack, timer mode) or use an AI generator if you can't be bothered. Either is better than a 2019 photo where you're clearly in the middle of saying something.

The data suggests it matters. I think it matters. But mostly, a profile photo is just the minimum viable proof that you show up for your professional presence.

Why your selfies look worse than you do (and what AI photo tools actually fix)

Jacob Yang — Fri, 27 Mar 2026 04:43:15 +0000

You look better in person than in your photos. Almost everyone does. This isn't a self-esteem problem — it's physics and psychology combining to work against you.

Camera lenses distort depth. A typical phone lens (around 26-28mm equivalent) exaggerates the distance between the nose and the edges of the face. The result is a slight but real distortion that doesn't match how you look in a mirror or in person. Wide-angle selfie cameras make this significantly worse.

Lighting in casual photos is almost never flattering. Overhead lighting creates shadows under the eyes and nose. Mixed indoor light sources create color casts that make skin look uneven. The soft, directional light that makes portraits look good requires actual setup — most selfies don't have it.

And then there's the compression and sharpening applied by phone cameras and social apps. They're optimizing for metrics (edge sharpness, color saturation, noise reduction) that look impressive in thumbnail previews but not necessarily on faces.

What diffusion models actually do to portraits

Modern AI portrait enhancement tools are built on diffusion models fine-tuned on portrait datasets. If you've used Stable Diffusion or Midjourney, you know what diffusion models produce. For portrait enhancement, the training data is specifically portrait photography — professional headshots, editorial photography — rather than general images.

The key technical piece is LoRA (Low-Rank Adaptation), which lets the model be fine-tuned on a small set of your own photos. Instead of retraining the entire model (which would require massive compute and data), LoRA updates a small set of weight matrices that capture your specific facial features. The model learns the shape of your face, your skin tone, and your distinctive features from maybe 10-20 input photos.

Once that LoRA is trained, the model can generate new images of you in different lighting conditions, with different backgrounds, in different poses — with consistent identity across all of them.

The pipeline in practice

The basic flow:

You submit 10-20 photos of yourself in varied conditions (different lighting, angles, expressions)
A LoRA is trained on those photos, typically taking a few minutes on modern GPU hardware
You select output styles — studio lighting, outdoor, corporate, etc.
The model generates new portrait photos using your LoRA + the style conditioning
You pick the ones that work

Tools like DatePhotos.AI handle this end-to-end. The input photos can be casual — no professional studio required. The output calibrates to styles appropriate for dating profiles: natural, well-lit, showing genuine expression rather than a stiff pose.

What the models are actually fixing

Lighting correction: The model generates you in lighting conditions that are actually flattering — soft key light from the side, clean fill light, no harsh shadows. This isn't a filter; it's generating a new image of you in better light.

Lens distortion correction: Because the output is generated rather than captured, it's not subject to the original camera's perspective distortion. The proportions look correct.

Background control: Instead of whatever was behind you when you took the selfie, you get a clean or contextually appropriate background that doesn't compete with your face.

Noise and compression: Generated images don't carry the compression artifacts from social media resizing. The detail is where it should be.

What the models are not fixing

Your face. The LoRA preserves your actual appearance — the structure of your face, your features, your approximate age. This is a feature, not a limitation. The goal is photos that look like you on a good day with good light, not a fantasy version of you that surprises people when they meet you in person.

If your input photos are all of you making the same slightly uncomfortable "I'm being photographed" face, the outputs will likely carry some of that. The model can do a lot with lighting and technical quality, but expression is still mostly up to you.