Skip to content

rlaope/oh-my-hermes / .claude/agent-skills/omh-show-reel

omh-show-reel

Unverified

[omh] Video to make from an idea or a product: an explainer, motion…

FileKindSize
SKILL.mdskill md12.6 KB
references/art-direction.mdmarkdown9.4 KB
references/assets-and-rights.mdmarkdown1.9 KB
references/audio-production.mdmarkdown5.0 KB
references/brief-and-locales.mdmarkdown5.2 KB
references/craft-audio.mdmarkdown19.9 KB
references/craft-brief.mdmarkdown12.2 KB
references/craft-design.mdmarkdown15.5 KB
references/craft-engine.mdmarkdown26.5 KB
references/craft-images.mdmarkdown9.3 KB
references/craft-qa.mdmarkdown13.2 KB
references/craft-story.mdmarkdown20.6 KB
references/craft-techniques-2.mdmarkdown15.2 KB
references/craft-techniques.mdmarkdown22.6 KB
references/craft-workflow.mdmarkdown32.3 KB
references/cut-sheet.mdmarkdown8.3 KB
references/game-capture.mdmarkdown1.8 KB
references/genres.mdmarkdown4.8 KB
references/kinetic-type.mdmarkdown6.7 KB
references/launch-film.mdmarkdown5.4 KB
references/motion-techniques.mdmarkdown4.3 KB
references/procedure.mdmarkdown17.0 KB
references/render-qa-delivery.mdmarkdown12.2 KB
references/renderer-adapter.mdmarkdown9.4 KB
references/source-package.mdmarkdown1.4 KB
references/storyboard-and-evidence.mdmarkdown6.5 KB
toolkit/LICENSE.upstreamother1.1 KB
toolkit/README.mdmarkdown18.7 KB
toolkit/assets/engine/engine.jsscript21.6 KB
toolkit/assets/engine/fx.jsscript20.9 KB
toolkit/assets/engine/index.htmlother3.0 KB
toolkit/assets/engine/scenes.jsscript12.7 KB
toolkit/assets/sfx_presets.jsonconfig3.3 KB
toolkit/examples/README.mdmarkdown744 B
toolkit/examples/music-spec.jsonconfig372 B
toolkit/examples/timing.jsonconfig146 B
toolkit/scripts/codex_ref_image.shscript2.6 KB
toolkit/scripts/contact_sheet.pyscript8.7 KB
toolkit/scripts/eleven.pyscript19.5 KB
toolkit/scripts/finish.pyscript8.0 KB
toolkit/scripts/font-coverage.mjsscript2.8 KB
toolkit/scripts/mix.pyscript9.5 KB
toolkit/scripts/motion_check.pyscript11.3 KB
toolkit/scripts/music_tools.pyscript29.4 KB
toolkit/scripts/narrate.pyscript12.5 KB
toolkit/scripts/new_project.pyscript10.5 KB
toolkit/scripts/preflight.pyscript5.6 KB
toolkit/scripts/prep_images.pyscript5.8 KB
toolkit/scripts/qa_check.pyscript7.1 KB
toolkit/scripts/render.mjsscript22.6 KB
toolkit/scripts/synth_music.pyscript6.4 KB
toolkit/scripts/timeline.pyscript16.6 KB
toolkit/scripts/tools/cutout.swiftscript1.8 KB
toolkit/upstream-manifest.jsonconfig20.3 KB

toolkit/scripts/timeline.py

View on GitHub
# MIT; Copyright (c) 2026 Minho Hwang (revfactory).
# Modified for OMH from revfactory/showreel@64521220a2f8e91cb9894400c48c15b7f45205d6
# scripts/timeline.py: explicit cue graph (timing.json), plus the upstream script.json
# composition (narration lines, scenes, SFX, music analysis -> timeline.json and reel/timeline.js)
# with a stdlib loudness envelope in place of numpy.
# Full permission/warranty: ../LICENSE.upstream. Standalone, not an OMH import.
"""Validate first, then emit a language-neutral, narration-optional cue timeline.

  timeline.py timing.json [--out compiled.json]          explicit cue graph (seconds/frame/after)
  timeline.py <project>/script.json [--music-analysis audio/music/analysis.json] [--ffmpeg ffmpeg]
      upstream composition: writes <project>/timeline.json (mixer/QA) and <project>/reel/timeline.js
      (window.TL for REEL.cue/bar/beat/level/charTimes). Narration lines need narrate.py output in
      audio/vo first; with "lines": [] only scenes, SFX and music are placed. Errors exit 1.
"""
from __future__ import annotations

import argparse
import array
import errno
import json
import math
import os
from pathlib import Path
import re
import subprocess
import sys


def system_alias(part):
    # macOS ships /etc, /tmp and /var (home of the default temp dir) as links
    # into /private. Only root can create a top-level entry, so trust exactly
    # those three, and only when the link names the same directory there.
    if sys.platform != "darwin" or part.parent != Path("/") or part.name not in ("etc", "tmp", "var"):
        return False
    try:
        return os.readlink(part) in ("private/" + part.name, "/private/" + part.name)
    except OSError:
        return False


def is_link(part):
    # From Python 3.14, Path.is_symlink() swallows every OSError, so an entry
    # under a directory that cannot be searched reads as "not a link". lstat it
    # first: a missing entry is fine, any other error means it cannot be checked.
    try:
        os.lstat(part)
    except OSError as exc:
        if exc.errno not in (errno.ENOENT, errno.ENOTDIR):
            raise ValueError(f"path could not be checked: {exc.strerror}") from exc
    return part.is_symlink()


def read_spec(path, expected=dict):
    path = Path(path).absolute()
    # The file, its folder and that folder's parent; above is the operator's own layout.
    if any(is_link(p) and not system_alias(p) for p in (path, path.parent, path.parent.parent)) or not path.is_file() or path.stat().st_size > 1_048_576:
        raise ValueError("spec must be a regular symlink-free UTF-8 JSON file <=1 MiB")
    def invalid_constant(value):
        raise ValueError(f"nonfinite JSON constant: {value}")
    value = json.loads(path.read_text(encoding="utf-8"), parse_constant=invalid_constant)
    if not isinstance(value, expected):
        raise ValueError("spec has incorrect JSON root type")
    return value


def number(value, label, minimum: float=0, maximum: float=600):
    if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value) or not minimum <= value <= maximum:
        raise ValueError(f"{label} must be finite in [{minimum}, {maximum}]")
    return float(value)


def settings(duration, fps, width=1920, height=1080):
    duration = number(duration, "duration", 1 / 60, 600)
    fps = number(fps, "fps", 1, 60)
    frames = duration * fps
    if abs(frames - round(frames)) > 1e-7 or frames > 36000:
        raise ValueError("duration * fps must be an integer <= 36000 frames")
    for label, size in (("width", width), ("height", height)):
        number(size, label, 16, 4096)
        if int(size) != size or size % 2:
            raise ValueError(f"{label} must be an even integer")
    if width * height * frames > 20_000_000_000:
        raise ValueError("render pixel budget exceeded")
    return {"duration": duration, "fps": fps, "frames": round(frames), "width": int(width), "height": int(height)}


def compile_timeline(spec):
    config = settings(spec["duration"], spec["fps"], spec.get("width", 1920), spec.get("height", 1080))
    rows = spec.get("cues", [])
    if not isinstance(rows, list) or len(rows) > 4096:
        raise ValueError("cues must be a list of <=4096 entries")
    by_id = {}
    for row in rows:
        key = row.get("id")
        if not isinstance(key, str) or not key or len(key) > 128 or any(ord(c) < 32 for c in key) or key in by_id:
            raise ValueError("invalid/duplicate cue id")
        if sum(k in row for k in ("seconds", "frame", "after")) != 1:
            raise ValueError(f"cue {key}: choose exactly seconds, frame or after")
        by_id[key] = row
    resolved = {}
    pending = dict(by_id)
    while pending:
        progressed = False
        for key, row in list(pending.items()):
            if "after" in row:
                if row["after"] not in by_id:
                    raise ValueError(f"unknown cue: {row['after']}")
                if row["after"] not in resolved:
                    continue
                value = resolved[row["after"]] + number(row.get("offset", 0), "offset", -600, 600)
            elif "frame" in row:
                frame = number(row["frame"], "frame", 0, config["frames"])
                if frame != int(frame):
                    raise ValueError("cue frame must be integer")
                value = frame / config["fps"]
            else:
                value = row["seconds"]
            resolved[key] = round(number(value, f"cue {key}", 0, config["duration"]), 10)
            del pending[key]
            progressed = True
        if not progressed:
            raise ValueError("cyclic cue graph")
    return {**config, "cues": resolved, "alignment": spec.get("alignment", []), "alignment_evidence": "caller_supplied_not_verified"}


def envelope(path, dt, db_floor=None, ffmpeg="ffmpeg"):
    """Loudness curve 0..1: narration is peak per block over the line maximum, music is RMS mapped db_floor..0 dB."""
    rate = 8000
    raw = subprocess.run([str(ffmpeg), "-v", "error", "-nostdin", "-i", str(path), "-ac", "1", "-ar", str(rate), "-f", "f32le", "-"],
                         capture_output=True, timeout=120).stdout
    samples = array.array("f")
    samples.frombytes(raw[:len(raw) // 4 * 4])
    if sys.byteorder != "little":
        samples.byteswap()
    hop = int(rate * dt)
    blocks = [samples[i * hop:(i + 1) * hop] for i in range(len(samples) // hop)]
    if len(blocks) < 2:
        return []
    if db_floor is None:
        peaks = [max(abs(v) for v in block) for block in blocks]
        top = max(peaks) + 1e-9
        values = [v / top for v in peaks]
    else:
        db = [20 * math.log10(math.sqrt(sum(v * v for v in block) / hop) + 1e-9) for block in blocks]
        top = max(db)
        values = [min(1.0, max(0.0, (d - top - db_floor) / -db_floor)) for d in db]
    return [round(float(v), 2) for v in values]


def generated(path):
    """timeline.json and reel/timeline.js are regenerated on every run; never through a link."""
    path = Path(path).absolute()
    if any(is_link(p) and not system_alias(p) for p in (path, path.parent, path.parent.parent)):
        raise ValueError(f"generated output refuses symlink: {path}")
    return path


def compose(script_path, music_analysis=None, ffmpeg="ffmpeg"):
    sp = Path(script_path).absolute()
    proj = sp.parent
    cfg = read_spec(sp)
    fps = cfg.get("fps", 30)
    dur = float(cfg.get("duration", 60))
    vo_dir = proj / "audio" / "vo"
    rep = read_spec(vo_dir / "report.json") if (vo_dir / "report.json").exists() else {}
    cues, errors, warns = {}, [], []

    def resolve(x, ctx=""):
        if isinstance(x, (int, float)):
            return float(x)
        m = re.fullmatch(r"\s*([^\s+]+?)\s*(?:([+-])\s*([\d.]+))?\s*", str(x))
        if not m:
            errors.append(f"{ctx}: cannot read time expression '{x}'")
            return None
        name, sign, off = m.groups()
        try:
            base = float(name)
        except ValueError:
            if name not in cues:
                errors.append(f"{ctx}: cue '{name}' is not defined (not yet defined, or a typo)")
                return None
            base = cues[name]
        return base + (float(off) * (1 if sign == "+" else -1) if off else 0.0)

    # Music analysis first, so narration, scenes and SFX can all use "bar9" and "music.hit2".
    music_tl = None
    ma = music_analysis or (cfg.get("music") or {}).get("analysis")
    ma_path = (Path(ma) if Path(ma).is_absolute() else proj / ma) if ma else None
    if ma_path and ma_path.exists():
        an = read_spec(ma_path)
        off = float((cfg.get("music") or {}).get("start", 0))
        hits = [round(h + off, 3) for h in an.get("hits", [])]
        for k, h in enumerate(hits):
            cues[f"music.hit{k + 1}"] = h
        for k, b in enumerate(an.get("downbeats", [])):
            cues[f"bar{k + 1}"] = round(b + off, 3)
        drops = [{**drop, "t": round(drop["t"] + off, 3)} for drop in an.get("drops", [])]
        for k, drop in enumerate(drops):
            cues[f"music.drop{k + 1}"] = drop["t"]
        music_tl = {"bpm": an.get("bpm"), "hits": hits, "beats": [round(b + off, 3) for b in an.get("beats", [])],
                    "downbeats": [round(b + off, 3) for b in an.get("downbeats", [])], "drops": drops}

    vo = []
    prev_end = None
    for line in cfg.get("lines", []):
        lid = line["id"]
        r = rep.get(lid)
        alf = vo_dir / f"{lid}.align.json"
        if not r or not alf.exists():
            errors.append(f"{lid}: narration not generated yet -> run narrate.py first")
            continue
        al = read_spec(alf)
        s0, s1 = r["speech_start"], r["speech_end"]
        if "at" in line:
            start = resolve(line["at"], lid)
            if start is None:
                continue
        elif prev_end is None:
            start = float(cfg.get("first_at", 0.6))
        else:
            start = prev_end + float(line.get("gap", cfg.get("gap", 0.35)))
        end = start + (s1 - s0)
        clip_start = start - s0
        chars = al.get("characters") or []
        cst = al.get("character_start_times_seconds") or []
        cen = al.get("character_end_times_seconds") or []
        joined = "".join(chars)
        words, cur, w0, w1 = [], "", None, None
        for c, a0, a1 in zip(chars, cst, cen):
            if c.isspace():
                if cur:
                    words.append([cur, round(clip_start + w0, 3), round(clip_start + w1, 3)])
                cur, w0 = "", None
                continue
            if w0 is None:
                w0 = a0
            cur += c
            w1 = a1
        if cur:
            words.append([cur, round(clip_start + w0, 3), round(clip_start + w1, 3)])
        for w in words:  # alignment can stretch the last word over trailing silence
            w[2] = round(min(w[2], end), 3)
            w[1] = round(min(w[1], w[2]), 3)
        cues[f"line.{lid}"] = round(start, 3)
        cues[f"line.{lid}.end"] = round(end, 3)
        for name, sub in (line.get("cues") or {}).items():
            k = joined.find(sub)
            if k < 0:
                k2 = joined.replace(" ", "").find(sub.replace(" ", ""))
                if k2 >= 0:
                    k = [j for j, c in enumerate(chars) if not c.isspace()][k2]
            if k < 0:
                errors.append(f"{lid}: cue '{name}' text '{sub}' not found in the pronunciation text (tts); copy the tts string exactly")
                continue
            cues[name] = round(clip_start + cst[k], 3)
        if prev_end is not None and start < prev_end + 0.12:
            errors.append(f"{lid}: overlaps the previous line ({start:.2f}s < previous end {prev_end:.2f}s + 0.12); delay 'at' or shorten the previous line")
        if end > dur - 0.4:
            errors.append(f"{lid}: runs past the target length {dur:g}s (ends {end:.2f}s); shorten it or pull earlier lines forward")
        vo.append({"id": lid, "text": line["text"], "sub": line.get("sub", line["text"]), "nosub": bool(line.get("nosub")), "nosrt": bool(line.get("nosrt")),
                   "start": round(start, 3), "end": round(end, 3), "clip": f"audio/vo/{lid}.mp3",
                   "clip_start": round(clip_start, 3), "gain_db": line.get("gain_db", 0), "words": words})
        prev_end = end

    scenes = []
    for s in cfg.get("scenes", []):
        st = resolve(s["start"], f"scene {s['id']}")
        en = resolve(s["end"], f"scene {s['id']}") if "end" in s else None
        if st is None:
            continue
        cues[f"scene.{s['id']}"] = round(st, 3)
        if en is not None:
            cues[f"scene.{s['id']}.end"] = round(en, 3)
        scenes.append({"id": s["id"], "start": round(st, 3), "end": round(en, 3) if en is not None else None})
    for i, s in enumerate(scenes):
        if s["end"] is None:
            s["end"] = scenes[i + 1]["start"] if i + 1 < len(scenes) else dur
            cues[f"scene.{s['id']}.end"] = round(s["end"], 3)

    sfx = []
    for e in cfg.get("sfx", []):
        t = resolve(e.get("at", 0), f"sfx {e.get('name')}")
        if t is None:
            continue
        t += float(e.get("offset", 0))
        f = e.get("file")
        if not f:  # provider mp3 or synthesized wav
            f = next((c for c in (f"audio/sfx/{e['name']}.mp3", f"audio/sfx/{e['name']}.wav") if (proj / c).exists()), f"audio/sfx/{e['name']}.mp3")
        if not (proj / f).exists():
            warns.append(f"sfx {e['name']}: missing file {f} (make it with synth_music.py or the opt-in eleven.py sfx)")
        sfx.append({"name": e["name"], "file": f, "t": round(t, 3), "gain_db": e.get("gain_db", -6), "align": e.get("align", "start")})

    music = cfg.get("music")
    if music and music.get("file") and not (proj / music["file"]).exists():
        warns.append(f"missing music file: {music['file']}")
    for v in vo:
        v["env"] = {"t0": v["clip_start"], "dt": 0.02, "v": envelope(proj / v["clip"], 0.02, ffmpeg=ffmpeg)}
    if music and music.get("file") and (proj / music["file"]).exists():
        music_tl = music_tl or {}
        music_tl["energy"] = {"t0": float(music.get("start", 0)), "dt": 0.05, "v": envelope(proj / music["file"], 0.05, db_floor=-30, ffmpeg=ffmpeg)}

    tl = {"duration": dur, "fps": fps, "vo": [{k: x for k, x in v.items() if k != "env"} for v in vo], "cues": dict(sorted(cues.items(), key=lambda x: x[1])),
          "scenes": scenes, "sfx": sfx, "music": music,
          "music_tl": {k: x for k, x in music_tl.items() if k != "energy"} if music_tl else None}
    page_tl = {"duration": dur, "cues": tl["cues"], "scenes": scenes, "music": music_tl,
               "vo": [{k: v[k] for k in ("id", "text", "sub", "nosub", "start", "end", "words", "env")} for v in vo]}
    generated(proj / "timeline.json").write_text(json.dumps(tl, ensure_ascii=False, indent=1), encoding="utf-8")
    (proj / "reel").mkdir(exist_ok=True)
    generated(proj / "reel" / "timeline.js").write_text("// Written by timeline.py; edit script.json and rerun instead of editing this file.\nwindow.TL = " + json.dumps(page_tl, ensure_ascii=False) + ";\n", encoding="utf-8")
    return tl, warns, errors


def report(tl, warns, errors, proj):
    vo, dur = tl["vo"], tl["duration"]
    print(f"{'id':6s} {'start':>6s} {'end':>6s} {'len':>5s}  subtitle")
    for v in vo:
        print(f"{v['id']:6s} {v['start']:6.2f} {v['end']:6.2f} {v['end'] - v['start']:5.2f}  {v['sub']}")
    bar = ["."] * int(dur)
    for v in vo:
        for s in range(int(v["start"]), min(int(dur), int(v["end"]) + 1)):
            bar[s] = "#"
    speech = sum(v["end"] - v["start"] for v in vo)
    print("speech map (1 cell = 1 s): " + "".join(bar))
    print(f"speech {speech:.1f}s / {dur:g}s = {speech / dur * 100:.0f}% | {len(tl['cues'])} cues | {len(tl['sfx'])} sfx")
    for w in warns:
        print("WARN " + w)
    for e in errors:
        print("FAIL " + e)
    print(f"-> {proj / 'timeline.json'} | {proj / 'reel' / 'timeline.js'}")


def main():
    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    parser.add_argument("timing", type=Path)
    parser.add_argument("--out", type=Path)
    parser.add_argument("--music-analysis")
    parser.add_argument("--ffmpeg", default="ffmpeg")
    args = parser.parse_args()
    spec = read_spec(args.timing)
    if any(key in spec for key in ("lines", "scenes", "sfx", "music")):
        tl, warns, errors = compose(args.timing, args.music_analysis, args.ffmpeg)
        report(tl, warns, errors, Path(args.timing).absolute().parent)
        raise SystemExit(1 if errors else 0)
    result = compile_timeline(spec)
    text = json.dumps(result, ensure_ascii=False, indent=2) + "\n"
    if args.out:
        with args.out.open("x", encoding="utf-8") as stream:
            stream.write(text)
    else:
        print(text, end="")


if __name__ == "__main__":
    main()
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall