⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

lyric-music-video

alesha-pro@alesha-pro⭐ 700 stars· last commit 1mo ago· 0 open issues

>-

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 700 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

lyric-music-video

An agent skill for making a code-rendered lyric music video for a finished song. Every sung word lands on screen on its own syllable inside animated graphics; a recurring character is built from generated stills; the video is a deterministic function of song time, so the browser preview and the 1080p60 export match. No video model.

The agent interviews the user (song, references, character, energy, credits), explores styles with styleframes, aligns lyrics and beats, builds one section to approval, then the rest (optionally with parallel sub-agents), checks everything on contact sheets and renders drafts and final variants, locally or on a remote GPU box.

Contents

  • SKILL.md: the workflow and invariants for the agent.
  • references/: intake, style exploration, engine, edit and motion, art, parallel agents, QA, render, delivery.
  • assets/engine.patch: changes to mexicat/pdoom-video (MIT): preload hook, fonts with weights, HUD overlay for a watermark, end card past the song, the calm energy knob, Linux GPU / CPU render flags.
  • assets/analysis-example.patch: the example song's changes to the alignment and beat tools, including a variable-tempo beat tracker for generated songs.
  • assets/lib/kit.ts: motion (slap, pop, pulses, camera keys, whips, cut flashes) and three example world toolkits (phone UI, scrapbook, pop-art comic). assets/lib/brand.ts: watermark and platform marks. assets/scenes/: end card and sync test.
  • assets/fonts/pop/: Bricolage Grotesque and Instrument Serif instances (SIL OFL 1.1). Other fonts are downloaded from Google Fonts by scripts/fetch-fonts.sh.
  • scripts/: new-project.sh, render-chunks.sh, phone-copy.sh, fetch-fonts.sh.
  • examples/pink-boots/: the worked example's timeline and chorus scene, and how the project went.

Quick start

bash scripts/new-project.sh ~/videos/my-song     # needs bun, Chrome, ffmpeg (uv for the analysis tools)
cd ~/videos/my-song/engine/app && bunx vite      # preview

Then follow SKILL.md. Install the skill by copying this folder into ~/.agents/skills/ or .agents/skills/ inside a project.

// HOW IT'S BUILT

// FILES

30 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • skills/lyric-music-video/SKILL.md7.1 KBdc6f84de6f36upstream ↗
    ---
    name: lyric-music-video
    description: >-
      Make a code-rendered lyric music video for a finished song: every sung word lands on screen on its own
      syllable, inside dense animated graphics, with a recurring character built from generated stills. Covers the
      intake interview, style exploration with styleframes, word/beat alignment, a deterministic three.js + Canvas
      engine, per-section scenes (optionally built by parallel agents), contact-sheet QA and offline 1080p60 renders
      (local or on a remote GPU box), plus variants, watermark and end card. Use for "make a music video / lyric
      video / clip for my song", Suno or other AI songs, karaoke-style videos. Not for generating video with a video
      model, slide decks or UI animation.
    ---
    
    # Lyric music video
    
    A music video that is a pure function of song time: `frame = render(t)`. The browser preview and the offline
    export are identical, so every idea can be checked on a contact sheet before a long render. Motion comes from
    code (springs, cameras, cuts, typography); pictures come from generated **stills** (character poses, props,
    stickers, textures). No video model is involved, which keeps the result sharp, on the beat and cheap to change.
    
    The engine is [mexicat/pdoom-video](https://github.com/mexicat/pdoom-video) (MIT) plus this skill's patch.
    The worked example is "Pink Boots, Export Doors" (a 3-minute synth-pop song, 3 worlds: phone OS, Y2K scrapbook,
    pop-art comic). It is an example, not the house style: [examples/pink-boots/README.md](examples/pink-boots/README.md).
    
    ## References
    
    | Read | When |
    |---|---|
    | [intake.md](references/intake.md) | Always first: what to ask, what to infer, the brief |
    | [style-exploration.md](references/style-exploration.md) | Choosing the look: references, directions, styleframes |
    | [engine.md](references/engine.md) | Project setup, alignment data, engine APIs, what the patch adds |
    | [edit-and-motion.md](references/edit-and-motion.md) | Timeline, per-word events, camera, transitions, chorus variations |
    | [art.md](references/art.md) | Character and prop stills: generation, references, QA |
    | [section-agents.md](references/section-agents.md) | Splitting the song between parallel agents, the brief template |
    | [qa.md](references/qa.md) | Contact sheets, the checklist, seams between sections |
    | [render.md](references/render.md) | Local and remote renders, motion blur, chunks, sizes, speed |
    | [delivery.md](references/delivery.md) | Watermark, end card, variants (lighter / no blur), phone copies, caption |
    
    ## Workflow
    
    1. **Intake.** Get the song file and the lyrics. Ask the questions in [intake.md](references/intake.md) that
       the user has not answered yet, in one short batch. Ask for references (videos, accounts, images) and what
       exactly they like in each. Write the brief into the project folder.
    2. **Set up.** `scripts/new-project.sh <dir>` clones the engine, applies `assets/engine.patch`, copies the
       world kit, brand and end-card files, fetches the fonts and installs dependencies. Align the lyrics to
       words (and syllables where a word is sung long) and analyse beats, downbeats and sections
       ([engine.md](references/engine.md)). Check the alignment with the sync-test scene before any design work.
    3. **Find the look.** Study the references for principles, never copy their scenes. Propose 2 or 3 distinct
       directions, make one styleframe per direction for the same 2 lyric lines, show them side by side and let
       the user choose or combine ([style-exploration.md](references/style-exploration.md)). A combination of
       directions is often the answer: cut between them on sung words.
    4. **Character and art.** Generate the recurring character once as a model sheet, then poses per world as
       transparent stills, plus props, stickers and textures ([art.md](references/art.md)). QA every image.
    5. **One section to approval.** Build the chorus (or the densest section) completely: every word an event,
       camera on the beat, transitions, colour flashes. Render a contact sheet, then a short MP4, and get the
       user's reaction before building anything else. This scene becomes the quality bar.
    6. **The rest of the song.** Write the timeline (cuts on the beat before each section's first word), then
       build the other sections, yourself or with parallel agents using the brief in
       [section-agents.md](references/section-agents.md). Repeated choruses get escalating variants.
    7. **QA.** Contact sheets for every section, the seams between sections, the words that land near a cut, and
       legibility at phone size ([qa.md](references/qa.md)). Fix, re-check.
    8. **Render.** A fast draft first (30 fps, no motion blur) for the user to watch; then final quality
       (60 fps, 4 sub-frames of motion blur). Prefer a GPU machine; never run the final render on a laptop that is
       short of memory ([render.md](references/render.md)).
    9. **Deliver.** Watermark, end card with the author's handles, the requested variants, phone-size copies, and
       a caption if asked ([delivery.md](references/delivery.md)).
    
    ## Invariants
    
    - **Every sung word is on screen, on its own start time**, inside the graphics (a bubble, a stamp, a sticker,
      a sound effect), never as subtitles on top. Word times come from the alignment data; never hard-code times.
      Find lines by text and pick the occurrence inside the scene's window.
    - **Deterministic.** No `Math.random`, no state across frames, no wall clock. Seeded hashes only. Any frame
      can be rendered alone.
    - **Density and motion by default.** At least one visual event per beat; a camera move per word; cuts per line
      (per word on hooks). Energy is tunable afterwards with the `calm` knob; it is hard to add later.
    - **Stills plus code, not video generation.** If the user wants the character to move, give poses per phrase
      with spring motion, cuts and camera. That reads as intentional in collage, comic and UI worlds.
    - **The user's taste decides.** Show frames early and often. Ask before spending paid generation credits.
    - **Rights.** No real company logos, no real people's likeness, no government seals or real flags unless the
      user owns them. Political lines stay playful. Platform icons are fine for the author's own handles.
    - **Verify before claiming.** Look at every contact sheet you produce. A render is done when the file decodes,
      has the right duration, frame count and audio, and spot frames look right.
    
    ## Lessons from the example project
    
    - A mesh-warped "animated" character looked cheap; image-to-video clips were rejected ("I don't want generated
      video"); glossy 3D props with confetti were called boring. What worked: three flat, graphic worlds with the
      character as stickers and panels, cut on the words.
    - "Be inspired, don't copy": take principles from references (text inside the graphics, micro-typography,
      one world per line, a live camera), not their scenes.
    - Small wording matters to users: "AI" had to be one word, not "A-I"; "B300" had to read as B300, not
      "B-THREE-HUNDRED", even though it is sung in syllables. Build the word from its syllables instead.
    - Viewers found the full-energy cut "too fast"; a second render with `calm=0.65` and a version without motion
      blur were requested. Plan for variants: they are cheap with the knob.
    
  • skills/lyric-music-video/examples/pink-boots/README.md3.0 KBf01efc94be3fupstream ↗
    # Example: "Pink Boots, Export Doors"
    
    A 3-minute synth-pop song (~135 BPM, generated with Suno) about the US-China AI chip race sung as a flirty pop
    song. 1080p60, 3:04 with the end card. This is one worked example of the skill, not a house style.
    
    The two files here are for reading, not running (they need the project's art):
    
    - `timeline.ts`: the edit. Section boundaries from lyric lines snapped to the beat, one scene module reused
      for 3 choruses via `params.n`, an end card after the song.
    - `chorus.ts`: the approved reference scene (~870 lines). Six shots in three worlds for one chorus, every
      word an event, per-word camera keys, whips, cut flashes, and the chorus 2/3 variants (pencil-sketch shader
      with a colour wipe; phone-in-scrapbook compositing and a kaleidoscope).
    
    ## How it went
    
    1. **Rejected:** a mesh-warped "animated" singer; image-to-video clips of the singer ("I don't want to
       generate video"); a glossy 3D props opener ("the content is boring"); porting scenes from the reference
       video ("don't copy, be inspired").
    2. **Styleframes:** three directions for the same two lines: A. her phone OS, B. a Y2K scrapbook,
       C. Lichtenstein pop art crossed with a semiconductor datasheet. The answer was "I want ALL of this", so the
       video cuts between the three worlds on sung words.
    3. **Character:** one model sheet, then poses per world as transparent stills (comic-kick, scrap-kiss,
       phone-selfie, …), about 30 in total, plus stickers, tape, bubble letters, props.
    4. **The chorus first**, iterated on sheets and one MP4 to "gorgeous, keep going". Note from the user: "AI" as
       one word.
    5. **Parallel agents** built verse 1, pre-chorus + chorus tails, verse 2, bridge + outro from one brief
       while the lead built the chorus variants. Each section was reviewed on sheets; small fixes (cropped ransom
       text, overlapping stamps, the last word before each chorus visible for only 5 frames).
    6. **Draft render** on a remote GPU box (the laptop ran out of memory), then notes: "B300" not
       "B-THREE-HUNDRED", a watermark, an end card with handles, a stamp whose text overflowed its frame.
    7. **Final renders:** full with motion blur, full without blur, and a lighter cut (`calm 0.65`) after viewers
       said the first draft was too fast.
    
    ## The worlds
    
    | World | Word appears as | Signature moves |
    |---|---|---|
    | Phone | chat bubbles, notification titles, keyboard keys, live-text labels, a thermal camera readout | notifications on downbeats, FaceTime tile bobbing on the beat, tapbacks |
    | Scrapbook | ransom letters, gel-pen strokes, glitter bubble-letter stickers, stamps | stickers slap with overshoot, washi tape, doodles drawing themselves |
    | Comic | SFX lettering, balloons, captions | panels, Ben-Day dots, bursts, speed lines, panels flying apart |
    
    Humour came from colliding the chip-war vocabulary (export licences, ECCN codes, the Entity List, HBM,
    capex) with teen pop culture (dating apps, horoscopes, karaoke, lip gloss). Real companies appear only as
    words in the lyrics, never as logos; a real CEO appears only as an empty leather jacket.
    
  • skills/lyric-music-video/README.md2.2 KB26d8849070efupstream ↗
    # lyric-music-video
    
    An agent skill for making a code-rendered lyric music video for a finished song. Every sung word lands on
    screen on its own syllable inside animated graphics; a recurring character is built from generated stills;
    the video is a deterministic function of song time, so the browser preview and the 1080p60 export match.
    No video model.
    
    The agent interviews the user (song, references, character, energy, credits), explores styles with
    styleframes, aligns lyrics and beats, builds one section to approval, then the rest (optionally with parallel
    sub-agents), checks everything on contact sheets and renders drafts and final variants, locally or on a
    remote GPU box.
    
    ## Contents
    
    - `SKILL.md`: the workflow and invariants for the agent.
    - `references/`: intake, style exploration, engine, edit and motion, art, parallel agents, QA, render,
      delivery.
    - `assets/engine.patch`: changes to [mexicat/pdoom-video](https://github.com/mexicat/pdoom-video) (MIT):
      preload hook, fonts with weights, HUD overlay for a watermark, end card past the song, the `calm` energy
      knob, Linux GPU / CPU render flags.
    - `assets/analysis-example.patch`: the example song's changes to the alignment and beat tools, including a
      variable-tempo beat tracker for generated songs.
    - `assets/lib/kit.ts`: motion (slap, pop, pulses, camera keys, whips, cut flashes) and three example world
      toolkits (phone UI, scrapbook, pop-art comic). `assets/lib/brand.ts`: watermark and platform marks.
      `assets/scenes/`: end card and sync test.
    - `assets/fonts/pop/`: Bricolage Grotesque and Instrument Serif instances (SIL OFL 1.1). Other fonts are
      downloaded from Google Fonts by `scripts/fetch-fonts.sh`.
    - `scripts/`: `new-project.sh`, `render-chunks.sh`, `phone-copy.sh`, `fetch-fonts.sh`.
    - `examples/pink-boots/`: the worked example's timeline and chorus scene, and how the project went.
    
    ## Quick start
    
    ```bash
    bash scripts/new-project.sh ~/videos/my-song     # needs bun, Chrome, ffmpeg (uv for the analysis tools)
    cd ~/videos/my-song/engine/app && bunx vite      # preview
    ```
    
    Then follow `SKILL.md`. Install the skill by copying this folder into `~/.agents/skills/` or
    `.agents/skills/` inside a project.
    
  • skills/lyric-music-video/scripts/fetch-fonts.sh843 Bf1bd7bbf746dupstream ↗
    #!/bin/bash
    # Download the display fonts the world kit uses (OFL / Apache, from github.com/google/fonts) into <dir>.
    # usage: fetch-fonts.sh app/public/fonts/kit
    set -euo pipefail
    DIR=${1:?usage: fetch-fonts.sh <dir>}
    mkdir -p "$DIR"
    G=https://raw.githubusercontent.com/google/fonts/main
    get() { curl -fsSL "$G/$1" -o "$DIR/$2"; echo "  $2"; }
    get ofl/bangers/Bangers-Regular.ttf Bangers-Regular.ttf
    get "ofl/caveat/Caveat%5Bwght%5D.ttf" Caveat.ttf
    get ofl/comicneue/ComicNeue-Bold.ttf ComicNeue-Bold.ttf
    get ofl/gochihand/GochiHand-Regular.ttf GochiHand-Regular.ttf
    get "ofl/inter/Inter%5Bopsz,wght%5D.ttf" Inter.ttf
    get apache/luckiestguy/LuckiestGuy-Regular.ttf LuckiestGuy-Regular.ttf
    get apache/permanentmarker/PermanentMarker-Regular.ttf PermanentMarker-Regular.ttf
    get ofl/rubikbubbles/RubikBubbles-Regular.ttf RubikBubbles-Regular.ttf
    
  • skills/lyric-music-video/scripts/new-project.sh1.6 KB411b3ab6f44bupstream ↗
    #!/bin/bash
    # Set up a new lyric-video project: the pdoom-video engine (MIT) + this skill's patch, kit, fonts and folders.
    # usage: new-project.sh <project-dir>
    # Afterwards: put the song in <project-dir>/engine/audio/, align it (references/engine.md), write timeline.ts.
    set -euo pipefail
    DIR=${1:?usage: new-project.sh <project-dir>}
    SK=$(cd "$(dirname "$0")/.." && pwd)
    UPSTREAM=https://github.com/mexicat/pdoom-video
    BASE=bdbad53                                   # the upstream commit engine.patch is made against
    mkdir -p "$DIR"; DIR=$(cd "$DIR" && pwd)
    git clone -q "$UPSTREAM" "$DIR/engine"
    cd "$DIR/engine"
    git checkout -q "$BASE"
    git apply "$SK/assets/engine.patch"
    cp "$SK"/assets/lib/*.ts app/src/lib/ 2>/dev/null || { mkdir -p app/src/lib; cp "$SK"/assets/lib/*.ts app/src/lib/; }
    cp "$SK/assets/scenes/credits.ts" "$SK/assets/scenes/synctest.ts" app/src/scenes/
    bash "$SK/scripts/fetch-fonts.sh" app/public/fonts/kit
    mkdir -p app/public/fonts/pop && cp "$SK"/assets/fonts/pop/*.ttf app/public/fonts/pop/   # Bricolage, Instrument Serif (OFL)
    mkdir -p "$DIR"/{assets,styleframes,renders,references}
    ln -sfn ../../../assets app/public/art          # art/<world>/<name>.png is served from <project>/assets
    # an upstream bun.lock from a newer bun is rejected by older ones: fall back to a fresh resolve
    (cd app && { bun install --silent 2>/dev/null || { rm -f bun.lock; bun install --silent; }; })
    echo
    echo "ready: $DIR"
    echo "  engine/app        renderer (bunx vite for the preview)"
    echo "  assets/<world>/   generated art, loaded with loadArt(['<world>/<name>'])"
    echo "  styleframes/      style exploration frames"
    echo "  renders/          output"
    
  • skills/lyric-music-video/scripts/phone-copy.sh580 B3bfd56f1de7fupstream ↗
    #!/bin/bash
    # 720p two-pass copy for phones and chat uploads, sized under ~30 MB for a 3-minute video.
    # usage: phone-copy.sh <in.mp4> <out.mp4> [video kbps, default 1100]
    set -euo pipefail
    IN=$1; OUTF=$2; VB=${3:-1100}
    LOG=$(mktemp -d)/pass
    ffmpeg -y -loglevel error -i "$IN" -vf scale=1280:720:flags=lanczos -c:v libx264 -preset slow -b:v ${VB}k -pass 1 -passlogfile "$LOG" -an -f null /dev/null
    ffmpeg -y -loglevel error -i "$IN" -vf scale=1280:720:flags=lanczos -c:v libx264 -preset slow -b:v ${VB}k -pass 2 -passlogfile "$LOG" -c:a aac -b:a 128k -movflags +faststart "$OUTF"
    
  • skills/lyric-music-video/scripts/render-chunks.sh2.9 KB049f1a423393upstream ↗
    #!/bin/bash
    # Render the full video in chunks with P parallel headless Chromes, then concat and add the audio (+ a phone copy).
    # Works locally (macOS, Metal) and on a Linux GPU box (Chrome + ANGLE/Vulkan beside other GPU jobs, ~300 MB VRAM).
    #
    # usage: render-chunks.sh <project-dir> <name>
    # env:   FPS=60 SAMPLES=4 CRF=16 PRESET=slow TUNE=grain   final quality (defaults)
    #        FPS=30 SAMPLES=1 CRF=22 PRESET=medium TUNE=none  quick draft
    #        CALMV=0.65     lighter variant           P=2        parallel Chromes (keep 1-2 on one GPU)
    #        CARD=3.2       end-card seconds after the song (0 if none)
    #        RENDER_ANGLE=vulkan CHROME_PATH=...                 Linux GPU; RENDER_CPU=1 = SwiftShader (very slow)
    set -u
    PROJ=$(cd "${1:?usage: render-chunks.sh <project-dir> <name>}" && pwd); NAME=${2:?name}
    APP=$PROJ/engine/app; OUT=$PROJ/renders/chunks-$NAME; R=$PROJ/renders
    FPS=${FPS:-60}; SAMPLES=${SAMPLES:-4}; CRF=${CRF:-16}; PRESET=${PRESET:-slow}; TUNE=${TUNE:-grain}; P=${P:-2}; CARD=${CARD:-3.2}
    AUDIO=$(ls "$PROJ"/engine/audio/*.{wav,mp3,m4a} 2>/dev/null | head -1)
    SONG=$(ffprobe -v error -show_entries format=duration -of csv=p=0 "$AUDIO")
    DUR=${DUR:-$(python3 -c "print(round($SONG + $CARD, 3))")}
    TOTAL=$(python3 -c "print(round($DUR*$FPS))")
    PORT=${PORT:-$((5600 + RANDOM % 300))}
    export PDOOM_NO_HMR=1                                   # a file saved mid-render must not reload the pages
    rm -rf "$OUT"; mkdir -p "$OUT"; cd "$APP"
    bunx vite --port $PORT --strictPort > "$OUT/vite.log" 2>&1 &
    VITE=$!
    trap 'kill $VITE 2>/dev/null' EXIT
    until curl -sf http://localhost:$PORT >/dev/null; do sleep 0.5; done
    echo "render $NAME: $DUR s, $TOTAL frames @ $FPS fps, samples $SAMPLES, calm ${CALMV:-1}, $P workers"
    per=$(( (TOTAL + P - 1) / P ))
    export FPS SAMPLES CRF PRESET TUNE DUR OUT PORT CALMV
    for i in $(seq 0 $((P-1))); do a=$((i*per)); b=$(( (i+1)*per )); [ $b -gt $TOTAL ] && b=$TOTAL; echo "$i $a $b"; done |
    xargs -P $P -L 1 bash -c '
      i=$(printf %02d $0)
      f=$(python3 -c "print($1/$FPS)"); t=$(python3 -c "print(min($2/$FPS, $DUR))")    # never past the timeline end
      for try in 1 2; do
        bun scripts/render.ts video --from $f --to $t --fps $FPS --samples $SAMPLES --crf $CRF --preset $PRESET --tune $TUNE \
          --noaudio ${CALMV:+--calm $CALMV} --url http://localhost:$PORT --out $OUT/c$i.mp4 > $OUT/c$i.log 2>&1 \
          && { touch $OUT/c$i.done; echo "chunk $i ok"; exit 0; }
        echo "chunk $i failed (try $try), see $OUT/c$i.log"
      done'
    n=$(ls "$OUT"/*.done 2>/dev/null | wc -l | tr -d " ")
    [ "$n" -eq "$P" ] || { echo "only $n/$P chunks done"; exit 1; }
    ls "$OUT"/c*.mp4 | sort | sed "s/^/file '/;s/$/'/" > "$OUT/list.txt"
    ffmpeg -y -loglevel error -f concat -safe 0 -i "$OUT/list.txt" -i "$AUDIO" -map 0:v -map 1:a -c:v copy \
      -af apad -c:a aac -b:a 256k -shortest -movflags +faststart "$R/$NAME.mp4" || exit 1
    bash "$(dirname "$0")/phone-copy.sh" "$R/$NAME.mp4" "$R/$NAME-phone.mp4"
    echo "done: $R/$NAME.mp4 ($(du -h "$R/$NAME.mp4" | cut -f1)), $R/$NAME-phone.mp4"
    
  • skills/lyric-music-video/references/art.md2.8 KBc3eecab06aadupstream ↗
    # Art: character, props, stickers
    
    Code draws all lyric text and all UI and typography. Generated stills provide characters, props, stickers and
    textures. Motion comes from code.
    
    ## The character
    
    1. **Model sheet first:** front, 3/4, a couple of expressions, the outfit, on a plain background. Iterate with
       the user until it is "her/him". Keep it as the identity reference for every later image.
    2. **Poses per world and per moment,** each a separate transparent PNG: singing, pointing, kicking, eye-roll,
       blowing a kiss, holding a prop. Name by world and action: `girl/comic-kick.png`, `girl/scrap-kiss.png`,
       `girl/verse2-shock.png`.
    3. Match each pose to its world's rendering (comic inks and halftone, scrapbook die-cut sticker with a white
       rim, phone selfie photo look).
    
    Prompt essentials for every character image: "EXACTLY the character in the reference", the outfit, "correct
    anatomy: exactly two arms, two legs, five fingers per hand", "transparent background, clean alpha", "no text"
    (unless text is the prop). Always pass the model sheet and one existing pose in the target style as
    references.
    
    ## Props and stickers
    
    Stickers (glitter hearts, holo stars, chips, planes), tape textures, paper textures, bubble letters (one image
    per letter: `gl-A.png`), stamps, a door, a boot sole, empty clothing instead of a real person. One object per
    image, transparent, centred, a little padding.
    
    ## Tools
    
    Any image model works. Codex CLI image generation from a terminal:
    
    ```bash
    codex e --skip-git-repo-check --ephemeral -C <out-dir> \
      "<prompt ... save to /abs/path/name.png>" -i ref1.png ref2.png
    ```
    
    The prompt must come **before** `-i` (it takes several paths and swallows what follows). Run several jobs in
    the background in parallel (each takes minutes), then poll for the files.
    
    Ask the user before spending paid credits on any service.
    
    ## QA every image
    
    Open each generated file and check: anatomy (count arms, hands, fingers), identity against the model sheet,
    real transparency (not a painted checkerboard), no stray text or watermark, no real logos, faces or flags,
    style match with its world. Regenerate failures; do not fix in code what the image got wrong.
    
    ## Serving
    
    Files go to `<project>/assets/<world>/<name>.png` and are served at `art/<world>/<name>.png`. Load them in the
    scene's `init()` with `loadArt(['girl/comic-kick', 'scrap/st-heart'])`, draw with `art('girl/comic-kick')`.
    A missing file comes back from Vite as HTML: `loadArt` detects that, retries flaky reads and leaves the image
    null, and the draw helpers skip null images, so a typo shows as a missing sticker, not a crash. Look for
    `missing art` warnings in the render log.
    
    Offline processing for effects that would be slow per frame (a thermal-camera colour map, a blur) can be baked
    into extra PNGs with PIL.
    
  • skills/lyric-music-video/references/delivery.md2.2 KB6da396de11a4upstream ↗
    # Delivery
    
    ## Watermark
    
    `app/src/lib/brand.ts`: set `X_HANDLE` (and `TG_HANDLE` or other handles for the end card). The watermark is a
    small pill in the top-right corner with the platform mark and the handle, drawn on the HUD layer, so shake,
    zoom, whips and colour split never move it. It is hidden during the end card. Change the corner or the look in
    `watermark()`; keep it small (about 56 px high at 1080p) and readable on white and on saturated colours.
    
    ## End card
    
    `scenes/credits.ts`, a timeline entry after the song (`E('credits', 'credits', audio.duration,
    audio.duration + 3.2)`). The example: the singer's kiss sticker, "made with ♥ by" in gel pen, the X and
    Telegram handles slapped in one after another as white stickers with their marks, tape, floating hearts, a
    small line with the song title. Keep it in the video's world, 3 s, no new music.
    
    ## Variants
    
    All from the same code, rendered one after another:
    
    | Variant | How |
    |---|---|
    | full energy, motion blur | `FPS=60 SAMPLES=4` |
    | full energy, no motion blur (crisper, some viewers prefer it) | `FPS=60 SAMPLES=1` |
    | lighter ("too fast" feedback) | `CALMV=0.65`, blur on |
    
    `calm` scales every beat/word/downbeat punch and decay, spring overshoot, whip roll and the cut flashes by the
    factor, so camera punches, shake and colour split drop together. 0.65 is "a bit lighter" and keeps the
    character; 0.4 to 0.5 is calm. Do not also scale shake and zoom in the post pass: they already come from the
    scaled hits, and a second factor makes the result much calmer than asked. Motion blur alone also makes the
    video feel smoother than a draft without it.
    
    ## Files for the user
    
    - Full 1080p60 per variant, named `<song>-v1.mp4`, `-v1-noblur`, `-v1-light`.
    - A phone copy per variant (`scripts/phone-copy.sh`: 720p two-pass, ~28 MB for 3 minutes, under common 30 MB
      upload limits).
    - Say where each file is, its duration, size and what differs between variants.
    
    ## Caption
    
    If the user asks for a post caption: short, a line from the chorus or a question from the lyrics as the hook,
    one line about what it is. Keep claims true: "no video model" is true for this pipeline; if stills were
    generated, say so when asked. Follow the user's own writing rules if they have them.
    
  • skills/lyric-music-video/references/edit-and-motion.md4.8 KB1d9d2f4a6042upstream ↗
    # Edit and motion
    
    ## The edit (`timeline.ts`)
    
    Entries `{ id, load, start, end, params }`, one per section. Rules that worked:
    
    - Boundaries come from the data, never typed in: cut on the **last beat at or before a section's first sung
      word** (`audio.timeOfBeat(Math.floor(audio.beatAt(wordStart + 0.02)))`).
    - A section may start a beat early to set up its first word (the example's chorus opens with a phone ringing
      one beat before "My bot").
    - Re-use one scene module for repeated sections with `params` (`{ n: 1 | 2 | 3 }` for the choruses).
    - The last word of a section that ends right at a cut gets only a few frames. Either end the section later or
      have the next scene hold that word for a moment (the example's chorus lock screen shows the previous line's
      last word: "this HARD?", "shipping ADDRESS?", "karaoke, OKAY?").
    - An end card may run past the song (`credits`, 3.2 s after `audio.duration`); the export pads the audio.
    
    See `examples/pink-boots/timeline.ts`.
    
    ## Every word is an event
    
    Find the line inside the scene's window and take word times from it:
    
    ```ts
    const from = this.ctx.start - 1;
    const pick = (q: string) => ly.find(q).find((l) => l.start > from)!;   // works for chorus 1, 2 and 3
    const T = { kick: pick('Pink boots').words[2].start, ... };
    ```
    
    Ways a word appears, per world (the example's; invent your own per look):
    
    - **Phone:** a chat bubble per word, a notification title that builds word by word, keyboard keys lighting as
      if typed, a search bar with autocomplete, live-text labels in a camera app.
    - **Scrapbook:** ransom-note letters cut one by one, gel-pen handwriting drawn stroke by stroke, glitter
      bubble-letter stickers slapped on, washi tape, stamps.
    - **Comic:** SFX lettering (outline, misregistered shadow), balloons, captions, panels breaking apart.
    
    A word sung in syllables is built from its syllables as one word: "B" + "3" + "00" = B300; "A" then "I" = AI.
    Do not print the syllables as separate words unless that is the joke.
    
    Tiny secondary text rewards pausing: fake UI copy, form fields, footnotes, in-jokes of the song's world.
    
    ## Motion vocabulary (kit.ts)
    
    - `slap(t, t0, big, rot)`: sticker lands: scale overshoot from `1 + big`, rotation settles, shadow lifts.
    - `pop(t, t0)`: spring from 0 to 1 with overshoot (UI bubbles, tiles).
    - `hit(t, t0, hl)`: decaying 1 → 0 pulse (shake amounts, flashes, colour split).
    - `sticker(c, img, x, y, h, t, t0, { rot, big })`: draw an image with a slap.
    - Beat and word punches: `pulse(audio.beats, t)`, `pulse(audio.downbeats, t, 0.1)`, `wordHit(line, t)` (the
      strongest recent decay). Use them for camera zoom (`z *= 1 + 0.05 * wordHit`), shake amplitude and `ca`.
    - `camKeys(t, [[time, {x, y, z, r}], ...])`: camera keys eased per word (`outExpo` over ~0.2 s, a few frames
      early); add slow drift and sway on top; `applyCam(c, cam, whip)` sets the canvas transform.
    - `whipAt(t, cuts, dirs)`: **whips** between worlds, the outgoing frame flung ±1500 px with a roll over the
      last 4 frames, the new one lands over ~7 frames.
    - `cutFlash(c, t, [[time, colour], ...])`: 2 frames of a solid palette colour on a world change.
    - Post: return `shake`, `zoom` (1 + small beat punch), `ca` (colour split on hits), `grain`.
    
    World toolkits in the kit (examples, replace for another look): `PH` (glass panels, wallpaper, status bar,
    bubbles, typing dots, notifications, video tiles), `SC` (ransom text, washi tape, gel pen strokes, doodles
    drawing themselves, glints), `CO` (Ben-Day dots, tone fills, speed lines, bursts, SFX, balloons, panels,
    captions).
    
    Density rule: at least one event per beat, a camera move per word, cut worlds at least every line, per word
    on hooks. Energy can be lowered later with `calm`; it is hard to add.
    
    ## Repeated choruses
    
    Same words, escalating treatment. The example:
    
    - **Chorus 1:** full colour, the reference scene.
    - **Chorus 2:** the soft first half as a live pencil sketch of the same frames (a full-screen shader: Sobel
      edges, graphite and pink ink, hatching, grain); on the hook the colour opens from the centre in 0.3 s.
    - **Chorus 3:** the soft half plays on the singer's phone taped into the scrapbook (REC dot, doodles per
      beat); on the hook a kaleidoscope of the frame, 2x2 tiles, then 3x3 on the last word, hue-shifted. Do not
      mirror tiles that contain words: mirrored words are unreadable.
    - Counts that grow per chorus (paper planes = chorus number, bigger sticker bombs).
    
    ## Bridge and build
    
    A bridge can be one continuous camera move over a single large drawing (a map) instead of cuts, for contrast.
    A build before the last chorus: accelerating cuts (eighths, then sixteenths) through props of the video with a
    "loading chorus 3" bar.
    
    ## Deterministic randomness
    
    `mulberry32(seed)` and `hash(i, j)`; seed by index (sticker i, beat i), never by time alone, so a frame renders
    the same alone or in sequence.
    
  • skills/lyric-music-video/references/engine.md6.5 KB5928fe879c5fupstream ↗
    # Engine
    
    ## Set up
    
    ```bash
    bash scripts/new-project.sh ~/videos/my-song
    ```
    
    This clones [mexicat/pdoom-video](https://github.com/mexicat/pdoom-video) (MIT) at the commit the patch is made
    against, applies `assets/engine.patch`, copies `assets/lib/kit.ts`, `assets/lib/brand.ts`,
    `assets/scenes/credits.ts`, fetches the display fonts (Google Fonts, OFL/Apache), copies the pop fonts, links
    `app/public/art -> <project>/assets` and runs `bun install`. Requirements: bun, Google Chrome, ffmpeg with
    libx264; the analysis tools need uv and Python.
    
    Layout after setup:
    
    ```
    <project>/
      BRIEF.md            the brief (intake.md)
      styleframes/        style exploration
      assets/<world>/     generated stills, served at art/<world>/<name>.png
      renders/            outputs
      engine/
        audio/            the song (replace pdoom.mp3; keep one file, wav preferred)
        data/             lyrics.json + audio.json (generated by analysis/)
        analysis/         alignment + beat analysis (Python, uv)
        app/src/engine/   renderer core (patched)
        app/src/lib/      kit.ts (world kit), brand.ts (handles, watermark)
        app/src/scenes/   one module per section; the upstream pdoom scenes are examples, delete when done
        app/src/timeline.ts  the edit
        app/scripts/render.ts  offline renderer
    ```
    
    The upstream scenes (`open`, `loss`, `prompt` …) still compile and render after the patch; they are good
    reading for scene technique. Replace `timeline.ts` with your own edit and delete the scenes you do not use.
    
    ## Timing data
    
    Two files drive everything:
    
    - `data/lyrics.json`: lines → words, each word `{ w, start, end, conf, syl? }`. `syl` holds syllable or part
      times for words sung in pieces (B-three-hundred, A-I, acronyms). The engine applies a display lead
      (`LYRIC_LEAD`, default 0.13 s): a word shown exactly on its acoustic onset reads late.
    - `data/audio.json`: `duration`, `bpm`, `beats[]`, `downbeats[]`, `sections[]`, 100 fps envelopes
      (rms, low, mid, high, vocal, drums, bass, other) and onsets (kick, snare, hat, vocal).
    
    Produce them with the upstream analysis tools (Demucs stems, CTC forced alignment with two acoustic models,
    Whisper cross-check, beat/downbeat/section analysis). They are written for the upstream song; adapt:
    
    | File | Change for a new song |
    |---|---|
    | `lyrics/lyrics.src.js` | the lyric lines (approximate line times are enough) |
    | `analysis/common.py` | `AUDIO` path, stems folder name; `STEM_OFFSET_SAMPLES = 0` for a wav (the mp3 value compensates the LAME encoder delay) |
    | `analysis/ctcalign.py` | `N_FRAMES = duration / 0.02` |
    | `analysis/whisper_run.py` | the prompt: the song's unusual words (brand names, acronyms) |
    | `analysis/pron.py` | phonetic spellings for acronyms and odd words (`"A-I": "ay i"`, `"Qwen": "kwen"`) |
    | `analysis/align.py` | clear the upstream `FIX` anchors; add your own after checking the QA plots |
    | `analysis/analyze.py` | the section map in bars; the beat tracker (see below) |
    
    `assets/analysis-example.patch` is the full set of these edits from the example song. Two parts are worth
    reusing as they are:
    
    - **Variable-tempo beat tracking.** Generated songs (Suno) drift: the example went from ~133 to ~137.7 BPM.
      The upstream tracker assumes a constant tempo. `track_beats()` in the patch is a phase-locked loop on a
      drum + mix onset envelope with a Gaussian prior around each predicted beat, then a local quadratic smoothing.
    - **Chorus consensus.** Repeated choruses are near copies; the patch replaces outlier word positions with the
      consensus bar position across choruses. Buried words get fixed this way.
    
    Check the result before designing anything: render the `synctest` scene over a chorus (every word pops on its
    start) and watch it with sound. Fix alignment first; nothing downstream can hide a late word.
    
    ## Scene API (short)
    
    A scene is a class with `render(f: Frame, out: RenderTarget)` returning optional post overrides.
    
    - `f.t` song time, `f.lt` time since the entry start, `f.beat`/`f.bar` continuous indices, `f.a` audio sample
      (envelopes and onset hits at t).
    - `this.ctx`: `renderer`, `comp` (compositor), `lyrics`, `audio`, `params` (from the timeline entry),
      `start`, `end`.
    - `init()` async, once: load art (`await loadArt([...])`), find lines, precompute stroke text.
    - `prepare(t0, t1)` async, optional (added by the patch): preload what frames in [t0, t1] need. The export awaits
      it per frame; the preview calls it ahead without waiting.
    - Drawing: a `Layer2D` (Canvas2D at the output scale, logical 1920x1080 coordinates), `L.clear()`,
      draw, `comp.draw(renderer, L.upload(), out)`. `clearRT(renderer, out, LIN.paper)` for the background.
      `FSPass(glsl, uniforms)` for full-screen shader passes (sketch looks, colour wipes); `GLSL_COMMON` provides
      `hash12`, `sat`, colour constants.
    - Return `{ shake: [x, y], zoom, ca, grain, flash, ... }` to drive the post pass (camera shake, punch zoom,
      chromatic split, grain, white flash).
    - Lyrics: `lyrics.find(text)` all lines containing text, `lyrics.get(text, nth)`, `line.words[i].start`,
      `word.syl`. Audio: `audio.beats`, `audio.downbeats`, `audio.beatAt(t)`, `audio.timeOfBeat(i)`.
    
    The kit (`app/src/lib/kit.ts`) adds motion and three example world toolkits; see
    [edit-and-motion.md](edit-and-motion.md).
    
    ## What the patch adds to the engine
    
    | Feature | Where |
    |---|---|
    | `Scene.prepare(t0, t1)` preload hook, awaited by export, `still()` async | `scene.ts`, `engine.ts`, `main.ts` |
    | Fonts with weight ranges (variable Inter, Caveat), `fontW(family, px, weight)`, kit fonts registered | `type.ts` |
    | Pop palette tokens (`HEX.pink`, `cobalt`, `lemon`, `mint`, `lilac`, `ink`) and GLSL constants | `palette.ts`, `glsl/common.ts` |
    | HUD overlay hook (`engine.hud.overlay`) drawn above everything, not affected by shake or zoom: the watermark | `hud.ts`, `post.ts`, `main.ts` |
    | Timeline may run past the song (end card); audio padded with silence on export | `engine.ts`, `render.ts` |
    | `CALM` energy knob (`?calm=0.65`, `--calm`): scales hits, springs, whip roll, cut flashes | `util.ts`, `engine.ts`, kit |
    | Renderer flags: `RENDER_ANGLE=vulkan` (Linux GPU), `RENDER_CPU=1` (SwiftShader), `CHROME_PATH`, `--tune none`, `--calm` | `render.ts` |
    | Lyric helpers used by the kit | `lyrics.ts` |
    
    Palette and fonts are the example's; change the tokens for your look, keep the names or update the kit.
    
    ## Preview
    
    ```bash
    cd engine/app && bunx vite          # http://localhost:5173, ?t=<seconds> to start somewhere
    ```
    
    Space play/pause, arrows seek, `,` `.` step a frame, `[` `]` previous/next scene, `l` loop the scene.
    
  • skills/lyric-music-video/references/intake.md2.9 KB49f4f23b31a2upstream ↗
    # Intake
    
    Ask only what the user has not already said, and ask it in one batch (a multiple-choice tool is ideal).
    Infer the rest and state the assumptions in the brief. Most users know what they like when they see it, not in
    advance, so the questions exist to pick a starting point and to collect references, not to design by committee.
    
    ## Must have before starting
    
    - **The song file** (wav or mp3, final master) and **the lyrics as text**. If the lyrics came from a generator
      (Suno, Udio), the sung words can differ from the text: the alignment will show where.
    - **Where it will be posted** and the format: 16:9 1920x1080 (X, YouTube), 9:16 1080x1920 (Reels, TikTok,
      Shorts) or 1:1. Pick one primary format; a second format needs its own composition pass, not a crop.
    - **Length:** the full song, or a cut (for example chorus only, 30 to 60 s for a teaser).
    
    ## Ask (skip what is answered)
    
    1. **What is the song about, in the user's words**, and what should a viewer feel: laugh, dance, cry, "wow".
    2. **References.** Links to videos, accounts, images, and *what exactly* they like in each (the typography, the
       pace, the colours, the humour). Ask for 2 to 5. If they have none, offer 3 short directions to react to
       ([style-exploration.md](style-exploration.md)).
    3. **A character?** A singer or mascot on screen, or pure graphics and typography. If a character: do they
       have one (images, a model sheet), or should one be designed? Any constraints (no real person, no likeness).
    4. **Tone of the jokes and copy**, if the song is funny: in-jokes of which community, how edgy.
    5. **Energy:** "calm and elegant" to "wild, an event every beat". Default to dense; say that a lighter
       variant is cheap later.
    6. **Must-haves and no-gos:** words that must read a certain way (brand names, "AI" as one word), logos,
       colours, anything off limits.
    7. **Credits:** author handles for a watermark and an end card, and where each goes.
    8. **Budget:** paid image or video generation credits available? (Always ask before spending.) Hardware for
       rendering: this machine, or a remote GPU box.
    9. **Deadline**, and whether a quick draft is wanted first.
    
    ## The brief (write to `<project>/BRIEF.md`)
    
    ```
    song:        <file>, <duration>, <bpm>, <key sections with times>
    lyrics:      <file>; words to spell a specific way: ...
    format:      1920x1080 @60, full song | cut <from>-<to>
    posted on:   ...
    about:       <one paragraph in the user's words>
    feel:        ...
    references:  <link> - what they like in it
    character:   none | existing (<files>) | design one: <notes>
    look:        (after style exploration) <chosen direction(s)>
    energy:      dense (default) | <notes>; lighter variant: yes/no
    no-gos:      ...
    credits:     watermark <handle>, end card <handles>
    budget:      image gen: <tool/credits>; render on: <machine>
    deadline:    ...
    ```
    
    Update the brief when the user corrects something; it is the reference for any agent that joins later.
    
  • skills/lyric-music-video/references/qa.md2.5 KB41dbca7710faupstream ↗
    # QA
    
    The contact sheet is the main instrument. A render is judged by looking at frames, not by reading code.
    
    ```bash
    cd engine/app
    bun scripts/render.ts sheet --times 38.9,42.5,43.0,50.9,53.45 --cols 4 --url http://localhost:5191 --out /tmp/sheet.png
    bun scripts/render.ts sheet --from 38 --to 60 --n 16 --cols 4 --out /tmp/chorus.png
    bun scripts/render.ts stills --t 59.0 --out /tmp/stills        # full-size frames for detail
    bun scripts/render.ts sheet ... --calm 0.65                    # the lighter variant
    ```
    
    Pick times deliberately: each word's start + 0.1 s, the middle of held notes, both sides of every cut, the
    peak of each whip. The sheet renders frames independently, so it also proves determinism.
    
    ## Checklist per section
    
    - [ ] Every sung word visible, on its start (not before, not a beat late), spelled the way the user wants.
    - [ ] Words sung in syllables read as one word at the end (B300, AI).
    - [ ] No text cropped by the frame edge after the camera settles; no two stamps or labels overlapping
          unreadably; text inside its stamp or bubble frame (measure the text, size the frame from it).
    - [ ] Legible at phone size: view the sheet at 480 px per frame; small print is decoration, the sung word must
          read.
    - [ ] At least one event per beat; no stretch longer than a beat where nothing moves.
    - [ ] Section seams: the previous section's last word is not cut off; flashes and whips land on the cut.
    - [ ] Mirrored or hue-rotated effects never mirror words.
    - [ ] No missing art (`missing art` / `bad art` warnings in the render log).
    - [ ] Rights: no real logos, faces, seals, flags; platform icons only for the author's handles.
    
    ## Motion QA
    
    A sheet cannot show timing or energy. After sheets pass, render a short MP4 of the section (draft settings)
    and watch it with sound, or ask the user to. Look for: jitter at camera keys, springs that never settle,
    strobing (flash + whip + shake on the same frame too often), a word that pops before it is sung.
    
    ## Final file QA
    
    ```bash
    ffprobe -v error -show_entries format=duration:stream=codec_type,r_frame_rate,width,height -of compact out.mp4
    ffprobe -v error -count_frames -select_streams v -show_entries stream=nb_read_frames -of csv=p=0 out.mp4
    for t in 4.9 55.9 59 183; do ffmpeg -v error -y -ss $t -i out.mp4 -frames:v 1 -vf scale=480:-1 /tmp/f_$t.png; done
    ```
    
    Duration = song + end card, frame count = round(duration x fps), audio stream present, spot frames correct.
    A file without a `moov` atom was cut off mid-write (killed render): it is not a video, delete it and re-render.
    
  • skills/lyric-music-video/references/render.md3.2 KB89624e411e51upstream ↗
    # Render
    
    The renderer drives the app in headless Chrome, streams raw frames over a WebSocket into ffmpeg (libx264,
    BT.709 tagged). Each frame can average N sub-frames over the shutter for motion blur.
    
    ## Two passes
    
    | | Draft | Final |
    |---|---|---|
    | purpose | the user watches the whole thing, gives notes | delivery |
    | settings | `FPS=30 SAMPLES=1 CRF=22 PRESET=medium TUNE=none` | `FPS=60 SAMPLES=4 CRF=16 PRESET=slow TUNE=grain` |
    | 3-min 1080p size | ~240 MB | ~1.4 GB |
    | work | 1x | ~8x (2x frames, 4x sub-frames) |
    
    Always send a draft first; notes after a draft are normal ("AI one word", "the stamp text overflows") and cost
    minutes instead of an hour.
    
    ```bash
    bash scripts/render-chunks.sh <project> pink-boots-draft               # env as in the table
    FPS=60 SAMPLES=4 bash scripts/render-chunks.sh <project> pink-boots-v1
    ```
    
    It splits the frames into `P` chunks, renders them in parallel, concatenates without re-encoding, adds the
    audio (padded with silence for the end card) and writes a phone copy.
    
    ## Where to render
    
    - **A laptop can run out of memory** on a full 60 fps, 4-sample render (the example Mac died twice at ~92%,
      leaving a 1.4 GB file without a `moov` atom). Use it for sheets and short clips.
    - **A Linux GPU box** works well even while other jobs use the GPUs: Chrome with ANGLE on Vulkan needs about
      300 MB of VRAM. Use Playwright's Chromium:
      ```bash
      export CHROME_PATH=~/.cache/ms-playwright/chromium-*/chrome-linux64/chrome RENDER_ANGLE=vulkan
      ```
      Measured on an RTX 3090 shared with LLM servers: ~10 fps at 1 sample for a lone Chrome.
    - `RENDER_ANGLE=gl-egl` also works, about 3x slower than Vulkan.
    - `RENDER_CPU=1` (SwiftShader) renders correctly but at 1.3 to 2.6 s per frame at 4 samples: only for a
      machine without a GPU and a lot of time.
    
    ## Parallelism
    
    - Chrome always takes the first GPU; there is no flag to pick another one, and identical cards have the same
      device ID. Parallel Chromes on one GPU choke each other: 3 to 6 workers dropped to ~1 fps each, while a lone
      chunk did 10.5 fps. Use `P=1` or `P=2`.
    - Throughput also depends on what else runs on that GPU; the same final render took 12 minutes once and 50
      minutes when the GPU was busy. Check the per-chunk fps in `chunks-<name>/c*.log` after a minute and plan.
    - Render variants one after another, not at the same time.
    
    ## Gotchas
    
    - Renders must use a dev server without live reload (`PDOOM_NO_HMR=1`; the scripts set it). A file saved
      mid-render otherwise reloads the page and kills the render.
    - The last chunk must not end past the timeline (`--to` is clamped to the duration); a chunk that asks for
      frames after the end fails with `evaluate: undefined`.
    - `still()` is async after the patch: sheet and stills modes await it; custom scripts must too.
    - Watch renders by their logs and the frame counter, not just by process lists: a hung render and a slow one
      look the same from `ps`.
    - Stopping processes with `pkill -f "<pattern>"` over ssh can kill the ssh command itself, because its own
      command line contains the pattern. Use a small script that skips its own PID.
    - Moving files: a 1.4 GB MP4 per variant; copy only what the user needs and leave drafts on the render box.
    
  • skills/lyric-music-video/references/section-agents.md3.8 KB0259d348e87fupstream ↗
    # Parallel section agents
    
    A 3-minute song is 6 to 10 sections. Once one section is approved and the timeline exists, the rest can be
    built in parallel by sub-agents, each owning one or two sections. In the example 4 agents built verse 1,
    pre-chorus + chorus tails, verse 2, bridge + outro in about 30 minutes while the lead agent built the chorus
    variants.
    
    ## Before spawning
    
    - The approved reference scene exists and is on disk (for example `scenes/chorus.ts`).
    - `timeline.ts` is final: every entry exists, placeholders re-export the sync test
      (`export { default } from './synctest';`).
    - Shared files are frozen for the duration: `engine/*`, `lib/kit.ts`, `timeline.ts`, the reference scene.
    - Each agent gets its own preview port (5192, 5193, …) so renders never share a dev server.
    
    ## Brief template
    
    Write it once to a file and point each agent at it plus its own section list.
    
    ```
    # Build one section of the "<song>" music video
    
    You own: <section ids and scene files>, entry windows from timeline.ts.
    Match the approved <reference scene> exactly in quality, density and energy.
    
    Read first, in order:
    1. <reference scene>: copy its patterns (world functions, camera keys per word, beat/word punches,
       slap/pop springs, 2-frame colour flashes on world changes, whips, shake + ca returned to post).
    2. lib/kit.ts (motion + world toolkits). 3. styleframes/*.png. 4. BRIEF.md and the treatment.
    5. engine basics: scene.ts, lyrics.ts, audio.ts, stroke.ts, type.ts (available fonts).
    
    The look: <worlds, palette, how a word appears in each world>.
    Humour and copy: <the song's world, in-jokes, tone>. Tiny secondary text everywhere. No slogans.
    
    Hard rules:
    - EVERY sung word on screen inside the graphics, on its own start time, from the lyric data. Find lines with
      lyrics.find(q) and pick the occurrence inside your window. Never hard-code times.
    - At least one event per beat; camera never static; cut worlds at least every line.
    - Deterministic: no Math.random, no state across frames.
    - The character is the star: use her art generously (assets/girl/*.png).
    - No real logos, real people's likeness, seals, real flags. <topic-specific limits>.
    - DO NOT EDIT shared files: lib/kit.ts, engine/*, timeline.ts, <reference scene>, other sections' scenes.
      Put helpers in your scene file or lib/<section>-*.ts. Wanted kit changes go in your final report.
    - Art only in assets/<your-section>/ and assets/girl/<section>-*.png. Scratch files in your scratchpad.
    - New art: <image tool command>, prompt before -i, references = styleframe + model sheet + a pose.
      QA every image (anatomy, transparency, style). Ask before paid credits.
    
    Verify (required):
    - typecheck: cd engine/app && bunx tsc --noEmit -p .
    - contact sheet on YOUR port:
      bun scripts/render.ts sheet --times a,b,c,... --cols 4 --url http://localhost:<PORT> --out <scratch>/sheet.png
      Look at it. Check every line, framing, overlaps, empty frames, legibility. Iterate.
    - final: bun scripts/render.ts video --from <start> --to <end> --fps 60 --samples 4 --url ... --out renders/<section>-v1.mp4
    
    Final report (short): what each line shows, files created, render path, known issues, wished kit changes.
    ```
    
    ## When agents report
    
    - Treat the report as a claim. Render your own contact sheet of their section and look at it.
    - Typical fixes: text cropped at the frame edge at a camera key, two stamps overlapping, a word that only
      shows for a few frames at a section boundary, a frame that looks empty (usually mid-whip: check the
      neighbouring frames before "fixing" it).
    - Check the seams: the last beat of each section and the first beat of the next in one sheet.
    - Agents that render in parallel on one machine can reload each other's pages through the dev server's live
      reload: renders must use a server with `PDOOM_NO_HMR=1` (the renderer starts one if the URL is not up).
    
  • skills/lyric-music-video/references/style-exploration.md2.4 KB0869a6e8fc76upstream ↗
    # Style exploration
    
    Goal: the user points at a frame and says "that one" before any scene code exists.
    
    ## Study references for principles
    
    For each reference, write down *why* it works, as transferable principles, and never port its scenes:
    
    - how text lives inside the graphics (typed into a form, stamped, riding a curve, a chat bubble);
    - how dense it is and where the density comes from (many objects, or micro-typography and details);
    - camera behaviour (drift, snaps on hits, whips between worlds);
    - the palette and how many colours carry meaning;
    - how each line gets its own "world" or reference that the audience recognises.
    
    The example's reference (pdoom-video) gave: one world per line, text inside graphics, micro-typography
    everywhere, a live camera, render craft. Its scenes (TikZ unicorns, loss curves) were not reused; the user
    explicitly rejected copying ("be inspired, don't copy").
    
    ## Propose directions
    
    Write 2 or 3 directions that differ in *world*, not in colour: for example "the singer's phone OS", "a teenage
    scrapbook", "a pop-art comic crossed with a datasheet". For each: one sentence, the palette, the type, how a
    sung word appears, where the character appears, and what makes it funny or moving for this song.
    
    ## Styleframes
    
    For each direction, make **the same 2 lyric lines** as finished-looking stills (an image model is fine here;
    text in the frame may be imperfect, that is expected at this stage). Same lines across directions makes the
    comparison fair. Show them side by side and ask which one, or which parts of each.
    
    Save to `<project>/styleframes/<letter>-<direction>-<line>.png` with the prompt next to each image. Do not
    publish styleframes: they can contain things the final video must not (seals, logos, real-looking documents).
    
    ## Deciding
    
    - The user may want all of them ("I want ALL of this"). Then the directions become worlds of one video, and
      the edit cuts between worlds on sung words. This is very effective for pop songs.
    - If the reaction is lukewarm, change the world, not the polish. "The content is boring" means the idea
      is wrong, not the rendering.
    - Write the decision into the brief: worlds, palette tokens, fonts per world, how each world shows a word.
    
    ## A first rendered test
    
    Before building a section, render one line in the chosen look with real word timing (10 to 20 s). This is
    where timing, readability and energy get judged; stills cannot show them.
    
  • skills/lyric-music-video/assets/analysis-example.patch14 KB37f888f715a2upstream ↗
    diff --git a/analysis/align.py b/analysis/align.py
    index e2e7a07..e4207e1 100644
    --- a/analysis/align.py
    +++ b/analysis/align.py
    @@ -28,7 +28,7 @@ from pron import pron
     # mono sum, left and right channel (choruses are double-tracked L/R).
     PRIMARY = "fused6"
     # Independent-ish alternatives, used for agreement-based confidence.
    -ALTS = ("mms", "lv60k", "fused_vocL", "fused_vocR", "fused_lead")
    +ALTS = ("mms", "lv60k", "fused_vocL", "fused_vocR")
     
     # Per-line time windows (seconds) where the automatic path is ambiguous.
     LINE_WINDOWS = {}
    @@ -43,39 +43,36 @@ ANCHORS = {}
     # plots clearly show the automatic result is wrong.  (line, token) ->
     # dict(start=..., end=...)
     FIX = {
    -    # L5 "don't eat me alive": long legato vowels, CTC places eat/alive late /
    -    # early.  /i:/ of "eat" starts right after the t-release at 20.26; "alive"
    -    # starts with the pitch drop to the schwa at 21.35 ("-live" at 21.85).
    -    (5, 3): dict(start=20.27),
    -    (5, 5): dict(start=21.35),
    -    # L11 "shinigami eyes": shi-ni-ga-mi then /a/ of "eyes" at 34.73
    -    (11, 3): dict(start=34.73),
    -    # L40 final chorus "I'm upping my P(doom)": lead is buried under a
    -    # sustained backing "ah" pad (122.8-125.8); CTC finds nothing.  Placed from
    -    # the median-filtered spectrogram + karaoke-lead stem ("doom" /d/ at
    -    # 125.66 seen by both CTC models on the lead stem), rhythm identical to
    -    # chorus 3 (95.46 / 95.70 / 96.10 / 96.32).
    -    (40, 3): dict(start=125.40, syl=[125.66], conf=0.45),
    -    (40, 0): dict(start=124.52, conf=0.35),
    -    (40, 1): dict(start=124.78, conf=0.35),
    -    (40, 2): dict(start=125.20, conf=0.4),
    -    # Chorus pickups "I'm": strong vocal onset 2.5 beats before the DOOM
    -    # downbeat in every chorus (the CTC path smears "I'm" over backing vocals).
    -    (6, 0): dict(start=22.76, conf=0.7),
    -    (17, 0): dict(start=59.13, conf=0.7),
    -    (17, 1): dict(start=59.36),
    -    (28, 0): dict(start=95.47, conf=0.75),
    -    # "lies," voiced /l/ onset (lv60k / L / R channels agree, onset peak 31.16)
    -    (10, 4): dict(start=31.14, conf=0.7),
    -    # "We" / "don't": rest-onset rule fired on reverb tail / breath noise.
    -    (12, 0): dict(start=38.62),
    -    (27, 2): dict(start=92.46),
    -    # "you are" is one long note; vowel change /u/ -> /a/ (spectral centroid
    -    # 1020 -> 1180 Hz) at 83.93.  CTC models disagree (83.94 mms / 84.58 lv).
    -    (25, 6): dict(start=83.93, conf=0.5),
    -    # held notes whose automatic end ran into the next (unlisted) vocal
    -    (33, 2): dict(end=108.45),
    -    (45, 4): dict(end=140.55),
    +    # Choruses are near-identical copies (word positions in bars agree to ~0.02 bar
    +    # across the 3 choruses). Outliers are replaced by the consensus position,
    +    # converted with the downbeat grid (data/audio.json). 'Oh my, oh my, A-I':
    +    # Oh on beat 4, my on 1, oh on 2.5, my on 3, A on 4, I on the next downbeat
    +    # (Whisper + vocal onsets agree in all three choruses).
    +    (11, 0): dict(start=49.9),
    +    (11, 5): dict(start=52.605),
    +    (12, 0): dict(start=53.494),
    +    (12, 1): dict(start=53.886),
    +    (12, 2): dict(start=54.578),
    +    (12, 3): dict(start=54.773),
    +    (12, 4): dict(start=55.288, syl=[55.732]),
    +    (14, 4): dict(start=61.857),
    +    (15, 1): dict(start=64.382),
    +    (15, 2): dict(start=65.004),
    +    (28, 0): dict(start=111.877),
    +    (28, 1): dict(start=112.265),
    +    (28, 2): dict(start=112.953),
    +    (28, 3): dict(start=113.147),
    +    (28, 4): dict(start=113.659, syl=[114.1]),
    +    (30, 2): dict(start=118.932),
    +    (30, 3): dict(start=119.032),
    +    (30, 5): dict(start=120.456),
    +    (30, 7): dict(start=121.149),
    +    (40, 0): dict(start=155.651),
    +    (40, 1): dict(start=156.034),
    +    (40, 2): dict(start=156.716),
    +    (40, 3): dict(start=156.909),
    +    (40, 4): dict(start=157.416, syl=[157.853]),
    +    (43, 4): dict(start=168.039),
     }
     
     # ---------------------------------------------------------------------------
    @@ -240,14 +237,7 @@ def refine(words, f, fix=None):
         return words
     
     
    -EXTRA_DESC = [
    -    # (t0, t1, description) -- identified from QA plots, the karaoke lead stem
    -    # and Whisper / greedy CTC transcripts of the vocal stem.
    -    (34.9, 38.3, "backing-vocal tail / 'ah' ad-lib after 'eyes' over the break (chorus 1 end)"),
    -    (108.5, 110.15, "lead-in before 'Just transformers': Whisper hears a stuttered 'Just, just, just' (low confidence)"),
    -    (122.4, 125.9, "sustained backing 'ah' pad under 'I'm upping my P(doom)' (final chorus) - lead is buried here"),
    -    (140.6, 153.5, "outro chant: repeated 'oh' / 'oh-oh' vocal hook (Whisper: 'Oh, oh, oh...') until the drums stop at ~153"),
    -]
    +EXTRA_DESC = []
     
     
     def detect_extras(words, f):
    diff --git a/analysis/analyze.py b/analysis/analyze.py
    index cafd517..609e6d8 100644
    --- a/analysis/analyze.py
    +++ b/analysis/analyze.py
    @@ -30,21 +30,21 @@ FPS = 100
     # case the pickup stays in the previous section.  The choruses all start with
     # a ~3-beat pickup "I'm upping my P-" over a bass stop, landing "DOOM" on the
     # next downbeat, so the chorus section starts at the pickup bar.
    +BAR_PHASE = 3  # beat index of the first downbeat (mod 4)
     SECTION_BARS = [
    -    ("intro", None, 1),      # 0 .. bar 1 (1-bar synth intro, pickup "I" at 1.41)
    -    ("verse1", 1, 9),        # Eb Bb Cm Ab x1 (2 bars each), no drums until bar 7
    -    ("pre1", 9, 12),         # F F Ab  "ChatGPT, please don't eat me alive"
    -    ("chorus1", 12, 20),     # pickup/stop bar 12, "DOOM" on bar 13
    -    ("break1", 20, 21),      # 1-bar turnaround (tail of held "eyes")
    -    ("verse2", 21, 29),
    -    ("pre2", 29, 32),        # "Sydney, please let me free" (bass out)
    -    ("chorus2", 32, 41),     # incl. bar 40 (held "reckoned", pickup "Forward")
    -    ("verse3", 41, 49),
    -    ("pre3", 49, 52),        # breakdown: drums + bass out, "Gato, please don't let me go"
    -    ("chorus3", 52, 60),     # quiet chorus: light drums, no bass
    -    ("bridge", 60, 68),      # "Just transformers ..." (full band from bar 61)
    -    ("chorus4", 68, 77),     # final chorus, bar 76 = stop bar ("all for show?")
    -    ("outro", 77, None),     # full band + "oh" vocals to bar 84 (152.98), then decay
    +    ("intro", None, 1),        # 1 bar synth, pickup "B-three" at bar 0.83
    +    ("verse1", 1, 17),         # drums from bar 9, bass from bar 12
    +    ("pre1", 17, 21),          # lighter drums; bar 20 = stop bar, pickup "My" at 20.7
    +    ("chorus1", 21, 38),       # full band; bar 37 = break, pickup "DeepSeek"
    +    ("verse2", 38, 50),
    +    ("pre2", 50, 54),          # full band
    +    ("chorus2_soft", 54, 62),  # first half stripped: light drums, no bass
    +    ("chorus2", 62, 70),       # full from "Oh my, oh my, A-I"
    +    ("bridge", 70, 77),        # light drums, no bass
    +    ("build", 77, 79),         # 2-bar drum build
    +    ("chorus3_soft", 79, 86),  # stripped again
    +    ("chorus3", 86, 95),       # maximal: loudest bass of the song
    +    ("outro", 95, None),       # near silence, spoken line at bar 95.2; last hit bar 100
     ]
     
     
    @@ -237,6 +237,57 @@ def vocal_onsets(v, sr):
     
     
     # ---------------------------------------------------------------------------
    +
    +def track_beats(drums, mix, sr, duration, bpm0=133.0):
    +    """Variable-tempo beat grid (Suno tracks drift: here ~133 -> 137.7 BPM).
    +    Phase-locked loop on a drum+mix onset envelope: each beat is searched near
    +    its prediction (Gaussian prior, sd 25 ms), the period follows slowly; then
    +    beat times are smoothed (local quadratic fit over +-8 beats) so the grid is
    +    free of per-beat jitter but follows the tempo curve."""
    +    from scipy.signal import savgol_filter
    +    hop = 64
    +    od = librosa.onset.onset_strength(y=librosa.resample(drums, orig_sr=sr, target_sr=22050),
    +                                      sr=22050, hop_length=hop // 2, lag=1, max_size=1)
    +    om = librosa.onset.onset_strength(y=librosa.resample(mix, orig_sr=sr, target_sr=22050),
    +                                      sr=22050, hop_length=hop // 2, lag=1, max_size=1)
    +    o = od / (np.percentile(od, 99) + 1e-9) + 0.5 * om / (np.percentile(om, 99) + 1e-9)
    +    ofps = 22050 / (hop // 2)
    +    P = 60 / bpm0
    +    # initial phase: best offset over the first 12 s at bpm0
    +    best = (-1, 0.0)
    +    for off in np.arange(0, P, 0.002):
    +        idx = (np.arange(off, 12, P) * ofps).astype(int)
    +        sc = o[idx].mean()
    +        if sc > best[0]:
    +            best = (sc, off)
    +    beats = [best[1]]
    +    while beats[-1] + P < duration - 0.05:
    +        pred = beats[-1] + P
    +        a, b = int((pred - 0.07) * ofps), int((pred + 0.07) * ofps)
    +        tt = np.arange(a, b) / ofps
    +        w = o[a:b] * np.exp(-0.5 * ((tt - pred) / 0.025) ** 2)
    +        if w.max() > 0.15 * np.percentile(o, 95):
    +            t = float(tt[np.argmax(w)])
    +            P = 0.92 * P + 0.08 * (t - beats[-1])
    +        else:
    +            t = pred
    +        beats.append(t)
    +    beats = np.array(beats)
    +    idx = np.arange(len(beats))
    +    sm = savgol_filter(beats, 17, 2)
    +    # phase: the envelope locks onto whichever 8th-note grid is strongest (the
    +    # off-beat hats here). Re-phase on kick attacks: shift every beat by the
    +    # median kick phase (fraction of the local inter-beat interval).
    +    kick_t, _ = band_onsets(drums, sr, None, 120, win=0.012, min_gap=0.2, rel_db=12)
    +    ib = np.interp(kick_t, sm, np.arange(len(sm)))
    +    ok = (ib > 0) & (ib < len(sm) - 1)
    +    ph = np.angle(np.mean(np.exp(2j * np.pi * ib[ok]))) / (2 * np.pi)   # circular mean, -0.5..0.5
    +    ibi = np.gradient(sm)
    +    sm = sm + ph * ibi
    +    print(f"kick phase shift {ph:+.3f} beat")
    +    return sm
    +
    +
     def main(plots=False):
         mix, _ = common.load_mix(SR)
         duration = len(mix) / SR
    @@ -245,13 +296,13 @@ def main(plots=False):
             if len(stems[n]) < len(mix):
                 stems[n] = np.pad(stems[n], (0, len(mix) - len(stems[n])))
     
    -    bpm, P, off, kick_res = fit_grid(stems["drums"], mix, SR, duration)
    -    print(f"tempo {bpm:.3f} BPM  period {P:.5f}s  first beat {off:.4f}s  kick residual sd {kick_res.std()*1000:.1f} ms")
    -    beats = off + P * np.arange(int((duration - off) / P) + 1)
    -    # bar phase: beat index 0 is a downbeat (see NOTES / qa/drums_pattern.png)
    -    beat_in_bar = np.arange(len(beats)) % 4
    +    beats = track_beats(stems["drums"], mix, SR, duration)
    +    ibi = np.diff(beats)
    +    P = float(np.median(ibi)); off = float(beats[0]); bpm = 60 / P
    +    print(f"tempo {60/ibi[:32].mean():.2f} -> {60/ibi[-32:].mean():.2f} BPM, median {bpm:.2f}, first beat {off:.3f}")
    +    beat_in_bar = (np.arange(len(beats)) - BAR_PHASE) % 4
         downbeats = beats[beat_in_bar == 0]
    -    bar_t = lambda k: float(off + 4 * P * k)
    +    bar_t = lambda k: float(downbeats[min(k, len(downbeats) - 1)])
     
         # envelopes -------------------------------------------------------------
         n = int(math.ceil(duration * FPS))
    diff --git a/analysis/common.py b/analysis/common.py
    index 9d6f1c8..a591219 100644
    --- a/analysis/common.py
    +++ b/analysis/common.py
    @@ -16,8 +16,8 @@ for var, sub in [("TORCH_HOME", "torch"), ("HF_HOME", "hf"), ("HF_HUB_CACHE", "h
         os.environ.setdefault(var, str(CACHE / sub))
         (CACHE / sub).mkdir(parents=True, exist_ok=True)
     
    -AUDIO = PROJECT / "audio" / "pdoom.mp3"
    -STEMS = ROOT / "stems" / "htdemucs_ft" / "pdoom"
    +AUDIO = PROJECT.parent / "audio" / "track.wav"
    +STEMS = ROOT / "stems" / "htdemucs_ft" / "track"
     LYRICS_SRC = PROJECT / "lyrics" / "lyrics.src.js"
     DATA = PROJECT / "data"
     QA = ROOT / "qa"
    @@ -40,7 +40,7 @@ def load_lyrics_src():
     # (ffmpeg / libsndfile / browsers) is our time reference, so stems are shifted
     # earlier by 1015 samples @ 44.1 kHz (measured by cross-correlation, constant
     # over the whole song).
    -STEM_OFFSET_SAMPLES = 1015
    +STEM_OFFSET_SAMPLES = 0  # stems rendered from the wav decode: no offset
     STEM_OFFSET_SEC = STEM_OFFSET_SAMPLES / 44100
     
     
    diff --git a/analysis/ctcalign.py b/analysis/ctcalign.py
    index c15c6cd..df51c51 100644
    --- a/analysis/ctcalign.py
    +++ b/analysis/ctcalign.py
    @@ -18,7 +18,7 @@ import torchaudio
     from pron import pron
     
     FRAME = 0.02  # s per emission frame
    -N_FRAMES = 7833
    +N_FRAMES = 9058  # 181.16 s / 20 ms
     ALPHA = ["-"] + list("abcdefghijklmnopqrstuvwxyz'")
     AIDX = {c: i for i, c in enumerate(ALPHA)}
     
    diff --git a/analysis/pron.py b/analysis/pron.py
    index 7c0364f..0f7251e 100644
    --- a/analysis/pron.py
    +++ b/analysis/pron.py
    @@ -6,33 +6,22 @@ pronunciation sub-words made of plain letters (and internal apostrophes).
     import re
     
     PRON = {
    -    "AGI": "ay gee i",
    -    "P(doom)": "pee doom", "P(doom),": "pee doom",
    -    "ChatGPT,": "chat gee pee tee",
    -    "FOOM": "foom",
    -    "NVDA": "en vee dee ay",
    -    "E": "ee",
    -    "MLP,": "em el pee",
    -    "CDR": "see dee are",
    -    "PTO": "pee tee oh",
    -    "GPU": "gee pee you",
    -    "RLHF": "are el aitch eff",
    -    "Killswitch": "kill switch",
    -    "Neumann's": "noymans",
    -    "shoggoth's": "shoggoths",
    -    "Post-Chinchilla,": "post chinchilla",
    -    "super-dense": "super dense",
    -    "pre-training": "pre training",
    -    "self-upgrade": "self upgrade",
    -    "'cause": "cause",
    -    "Gato,": "gato",
    +    "B-three-hundred": "bee three hundred",
    +    "A-I": "ay i",
    +    "Qwen": "kwen",
    +    "Huawei's": "wahways",
    +    "Nine-sixty's": "nine sixties",
    +    "DeepSeek": "deep seek",
    +    "push-up": "push up",
    +    "export-controlled?": "export controlled",
    +    "Wait...": "wait",
    +    "okay?": "okay",
     }
     
     # alternative pronunciations to test (scored by alignment likelihood)
     ALT = {
    -    "NVDA": ["en vee dee ay", "envidia", "nvidia"],
    -    "Neumann's": ["noymans", "newmans"],
    -    "Gato,": ["gato", "gahtoe"],
    +    "Huawei's": ["wahways", "hwaways"],
    +    "Qwen": ["kwen", "chwen"],
     }
     
     
    diff --git a/analysis/whisper_run.py b/analysis/whisper_run.py
    index f55583e..ff81689 100644
    --- a/analysis/whisper_run.py
    +++ b/analysis/whisper_run.py
    @@ -27,7 +27,7 @@ def run(tag, model, prompt=None):
     if __name__ == "__main__":
         which = sys.argv[1] if len(sys.argv) > 1 else "turbo"
         lyr = " ".join(t for _, _, t in common.load_lyrics_src())
    -    prompt = ("Song lyrics about AI doom: P(doom), FOOM, shoggoth, shinigami, Chinchilla, "
    -              "basilisk, Omega Point, RLHF, GPU, CDR, MLP, NVDA, Gato, Sydney, Ilya, Loom.")
    +    prompt = ("Pop song lyrics about AI chips: B300, export license, Huawei Ascend, "
    +              "DeepSeek, Qwen, Jensen, Beijing, Taiwan, karaoke, A-I.")
         run(which, MODELS[which])
         run(which + "_prompt", MODELS[which], prompt)
    
  • skills/lyric-music-video/assets/engine.patch23 KB59b09cf251f4upstream ↗
    diff --git a/app/scripts/render.ts b/app/scripts/render.ts
    index 0c2b32d..e757e37 100644
    --- a/app/scripts/render.ts
    +++ b/app/scripts/render.ts
    @@ -44,17 +44,23 @@ async function ensureServer(): Promise<{ url: string; stop: () => void }> {
     }
     
     async function openPage(url: string) {
    +  // RENDER_CPU=1: software WebGL (SwiftShader), no GPU touched; CHROME_PATH picks a non-system Chrome (e.g. playwright's chromium on the rig)
    +  const cpu = !!process.env.RENDER_CPU;
    +  // RENDER_ANGLE=vulkan|gl-egl: GPU backend on Linux (default metal = macOS)
    +  const angle = process.env.RENDER_ANGLE ?? 'metal';
    +  const gl = cpu ? ['--use-gl=angle', '--use-angle=swiftshader', '--enable-unsafe-swiftshader']
    +    : ['--use-gl=angle', `--use-angle=${angle}`, '--enable-gpu-rasterization', ...(angle === 'vulkan' ? ['--enable-features=Vulkan'] : [])];
       const browser = await chromium.launch({
    -    channel: 'chrome',
    +    ...(process.env.CHROME_PATH ? { executablePath: process.env.CHROME_PATH } : { channel: 'chrome' }),
         headless: !flag('headed'),
    -    args: ['--use-angle=metal', '--enable-gpu-rasterization', '--ignore-gpu-blocklist', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'],
    +    args: [...gl, '--ignore-gpu-blocklist', '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows'],
       });
       const page = await browser.newPage({ viewport: { width: 1920, height: 1080 }, deviceScaleFactor: 1 });
       const logs: string[] = [];
       page.on('console', (m) => { if (m.type() === 'error' || m.type() === 'warning') logs.push(`[${m.type()}] ${m.text()}`); });
       page.on('pageerror', (e) => logs.push(`[pageerror] ${e.message}`));
       const only = opt('only');
    -  await page.goto(`${url}/?export=1${only ? `&only=${only}` : ''}${SCALE !== 1 ? `&scale=${SCALE}` : ''}`);
    +  await page.goto(`${url}/?export=1${only ? `&only=${only}` : ''}${SCALE !== 1 ? `&scale=${SCALE}` : ''}${opt('lead') ? `&lead=${opt('lead')}` : ''}${opt('calm') ? `&calm=${opt('calm')}` : ''}`);
       await page.waitForFunction(() => (window as any).__pdoom?.ready || (window as any).__pdoom?.error, null, { timeout: 120000 });
       const err = await page.evaluate(() => (window as any).__pdoom.error);
       if (err) throw new Error(`app failed to boot:\n${err}\n${logs.join('\n')}`);
    @@ -90,12 +96,13 @@ async function sheet(page: Page, times: number[], cols: number, out: string) {
         const c = cv.getContext('2d')!;
         c.fillStyle = '#222'; c.fillRect(0, 0, cv.width, cv.height);
         const src = document.getElementById('c') as HTMLCanvasElement;
    -    times.forEach((t: number, i: number) => {
    -      P.still(t);
    +    for (let i = 0; i < times.length; i++) {
    +      const t = times[i]!;
    +      await P.still(t);
           const x = pad + (i % cols) * (cw + pad), y = pad + Math.floor(i / cols) * (ch + lab + pad);
           c.drawImage(src, x, y + lab, cw, ch);
           c.fillStyle = '#ddd'; c.font = '13px monospace'; c.fillText(`${t.toFixed(2)}s`, x + 2, y + 13);
    -    });
    +    }
         return cv.toDataURL('image/png');
       }, { times, cols });
       mkdirSync(path.dirname(out), { recursive: true });
    @@ -105,14 +112,16 @@ async function sheet(page: Page, times: number[], cols: number, out: string) {
     async function video(page: Page, from: number, to: number, fps: number, out: string) {
       mkdirSync(path.dirname(out), { recursive: true });
       const crf = opt('crf', '16')!;
    -  const audio = path.join(ROOT, 'audio/pdoom.mp3');
    +  const audio = path.join(ROOT, 'audio/track.wav');
       const args = ['ffmpeg', '-y', '-loglevel', 'error', '-f', 'rawvideo', '-pix_fmt', 'rgba', '-s', `${OW}x${OH}`, '-r', String(fps), '-i', 'pipe:0'];
       if (!flag('noaudio')) args.push('-ss', String(from), '-t', String(to - from), '-i', audio);
       // Frames are sRGB (toSRGB in the final pass): convert with the BT.709 matrix and tag the stream,
       // otherwise ffmpeg converts with BT.601 while players and YouTube decode untagged HD as BT.709.
       // scale tags the matrix and range; primaries and transfer need setparams (the -color_* output flags don't reach the stream).
    -  args.push('-vf', 'vflip,scale=out_color_matrix=bt709,setparams=color_primaries=bt709:color_trc=bt709', '-c:v', 'libx264', '-preset', opt('preset', 'slow')!, '-crf', crf, '-pix_fmt', 'yuv420p', '-tune', 'grain', '-x264-params', opt('x264', 'aq-mode=3')!);
    -  if (!flag('noaudio')) args.push('-c:a', 'aac', '-b:a', '320k', '-shortest');
    +  // --tune none drops -tune grain (smaller files for drafts)
    +  args.push('-vf', 'vflip,scale=out_color_matrix=bt709,setparams=color_primaries=bt709:color_trc=bt709', '-c:v', 'libx264', '-preset', opt('preset', 'slow')!, '-crf', crf, '-pix_fmt', 'yuv420p', ...(opt('tune', 'grain') === 'none' ? [] : ['-tune', opt('tune', 'grain')!]), '-x264-params', opt('x264', 'aq-mode=3')!);
    +  // apad: the audio is padded with silence so an end card after the song is not cut by -shortest
    +  if (!flag('noaudio')) args.push('-af', 'apad', '-c:a', 'aac', '-b:a', '320k', '-shortest');
       args.push('-movflags', '+faststart', out);
       const ff = Bun.spawn(args, { stdin: 'pipe', stdout: 'inherit', stderr: 'inherit' });
       let frames = 0;
    diff --git a/app/src/engine/engine.ts b/app/src/engine/engine.ts
    index daedf65..800a948 100644
    --- a/app/src/engine/engine.ts
    +++ b/app/src/engine/engine.ts
    @@ -5,6 +5,7 @@ import { AudioData } from './audio';
     import { Lyrics } from './lyrics';
     import { Compositor, FSPass, W, H, PW, PH, SCALE, SS_TAP, makeRT, clearRT } from './gl';
     import { DEFAULT_POST, Post, SHOULDER_GLSL, type PostParams } from './post';
    +import { CALM } from './util';
     import { Hud, PDoom, type Caption } from './hud';
     import type { Frame, Scene, SceneClass, SceneCtx, PostOverrides } from './scene';
     import { loadFonts } from './type';
    @@ -176,7 +177,8 @@ export class Engine {
         this.lastT = -1;
       }
     
    -  get duration() { return this.audio.duration; }
    +  /** The song, or longer when the timeline runs past it (an end card after the music). */
    +  get duration() { return Math.max(this.audio.duration, ...this.timeline.map((e) => e.end)); }
     
       private frameFor(e: TimelineEntry, t: number, dt: number, seeked: boolean, preroll: boolean, under: THREE.Texture | null, tin: number, tout: number): Frame {
         const beat = this.audio.beatAt(t), bar = this.audio.barAt(t);
    @@ -266,6 +268,9 @@ export class Engine {
           outTex = this.avgRT.texture;
         }
         this.lastSamples = n;
    +    // global energy knob (?calm=): shake / zoom / colour split already come from CALM-scaled hits in the scenes;
    +    // the post flash does not, so soften it here
    +    if (CALM !== 1) post = { ...post, flash: post.flash * CALM };
         const hudTex = this.hud.draw(t, { opacity: this.hudOff ? 0 : post.hud, frame: post.frame, readout: post.pdoom, paper: post.paper, pdoomOverride: post.pdoomText, corruption: post.hudCorruption });
         this.post.render(r, outTex, hudTex, this.finalRT, post, t);
         this.lastPost = post;
    @@ -296,6 +301,12 @@ export class Engine {
         return m;
       }
     
    +  /** Let every scene overlapping [t0, t1] preload what it needs (see Scene.prepare). */
    +  async prepare(t0: number, t1: number): Promise<void> {
    +    const on = this.timeline.filter((e) => e.end > t0 && e.start <= t1);
    +    await Promise.all(on.map((e) => this.loaded.get(e.id)?.scene?.prepare?.(t0, t1)));
    +  }
    +
       /**
        * Render and composite all scenes active at t into an HDR texture (no post). `dt` is the step handed to
        * scenes (the frame step, or the sub-frame spacing); `seeked` says time jumped before this call.
    diff --git a/app/src/engine/glsl/common.ts b/app/src/engine/glsl/common.ts
    index 015403a..753e47f 100644
    --- a/app/src/engine/glsl/common.ts
    +++ b/app/src/engine/glsl/common.ts
    @@ -24,6 +24,14 @@ const vec3 C_SIGNAL = ${v3(LIN.signal)};
     const vec3 C_EMBER = ${v3(LIN.ember)};
     const vec3 C_BLOOD = ${v3(LIN.blood)};
     const vec3 C_ACID = ${v3(LIN.acid)};
    +const vec3 C_PAPER = ${v3(LIN.paper)};
    +const vec3 C_LINE = ${v3(LIN.line)};
    +const vec3 C_PINK = ${v3(LIN.pink)};
    +const vec3 C_COBALT = ${v3(LIN.cobalt)};
    +const vec3 C_LEMON = ${v3(LIN.lemon)};
    +const vec3 C_MINT = ${v3(LIN.mint)};
    +const vec3 C_TANGERINE = ${v3(LIN.tangerine)};
    +const vec3 C_LILAC = ${v3(LIN.lilac)};
     
     /** Rotated-grid supersample offset k (0..3) within one pixel, in pixels. See SS_TAP (gl.ts). */
     vec2 rgss(int k) { return k == 0 ? vec2(0.125, -0.375) : k == 1 ? vec2(0.375, 0.125) : k == 2 ? vec2(-0.125, 0.375) : vec2(-0.375, -0.125); }
    diff --git a/app/src/engine/hud.ts b/app/src/engine/hud.ts
    index 5a3cc71..8cdd85f 100644
    --- a/app/src/engine/hud.ts
    +++ b/app/src/engine/hud.ts
    @@ -86,18 +86,24 @@ export interface HudState {
     export class Hud {
       layer = new Layer2D();
       private ink = false;
    +  /** App overlay drawn on every frame above everything (e.g. a watermark), independent of the HUD opacity. */
    +  overlay?: (c: CanvasRenderingContext2D, t: number) => void;
       constructor(public pdoom: PDoom, public captions: Caption[]) {}
     
       draw(t: number, st: HudState) {
         const L = this.layer;
         L.clear();
         const c = L.ctx;
    -    if (st.opacity <= 0.001) return L.upload();
    -    c.globalAlpha = st.opacity;
    -    this.ink = st.paper > 0.5;
    -    if (st.frame > 0.001) this.cropMarks(c, st.frame);
    -    if (st.readout > 0.001) { c.save(); c.globalAlpha *= st.readout; this.readout(c, t, st); c.restore(); }
    -    this.caption(c, t);
    +    if (st.opacity > 0.001) {
    +      c.save();
    +      c.globalAlpha = st.opacity;
    +      this.ink = st.paper > 0.5;
    +      if (st.frame > 0.001) this.cropMarks(c, st.frame);
    +      if (st.readout > 0.001) { c.save(); c.globalAlpha *= st.readout; this.readout(c, t, st); c.restore(); }
    +      this.caption(c, t);
    +      c.restore();
    +    }
    +    if (this.overlay) { c.save(); this.overlay(c, t); c.restore(); }
         return L.upload();
       }
     
    diff --git a/app/src/engine/lyrics.ts b/app/src/engine/lyrics.ts
    index 5d556d9..e982ea6 100644
    --- a/app/src/engine/lyrics.ts
    +++ b/app/src/engine/lyrics.ts
    @@ -20,6 +20,17 @@ export interface Line {
       words: Word[];
     }
     
    +/**
    + * Visual lead (s): every lyric time is shifted this much EARLIER for display. The aligned
    + * times are the acoustic word onsets; a word that lights up exactly on its onset reads as
    + * late (the eye registers a flash later than the ear a syllable), so karaoke leads the voice.
    + * Override in the preview with ?lead=0.05.
    + */
    +export const LYRIC_LEAD = (() => {
    +  const q = typeof location !== 'undefined' ? new URLSearchParams(location.search).get('lead') : null;
    +  return q !== null && q !== '' && isFinite(+q) ? +q : 0.13;
    +})();
    +
     export class Lyrics {
       lines: Line[];
       words: Word[];
    @@ -30,7 +41,13 @@ export class Lyrics {
           ...l,
           i: li,
           text: smart(l.text),
    -      words: (l.words as any[]).map((w, wi) => ({ ...w, w: smart(w.w), line: li, index: wi, gi: 0 })),
    +      start: l.start - LYRIC_LEAD,
    +      end: l.end - LYRIC_LEAD,
    +      words: (l.words as any[]).map((w, wi) => ({
    +        ...w, w: smart(w.w), line: li, index: wi, gi: 0,
    +        start: w.start - LYRIC_LEAD, end: w.end - LYRIC_LEAD,
    +        ...(w.syl ? { syl: (w.syl as [number, number][]).map(([a, b]) => [a - LYRIC_LEAD, b - LYRIC_LEAD]) } : {}),
    +      })),
         }));
         this.words = this.lines.flatMap((l) => l.words);
         this.words.forEach((w, i) => (w.gi = i));
    diff --git a/app/src/engine/palette.ts b/app/src/engine/palette.ts
    index fb70121..d6f55a1 100644
    --- a/app/src/engine/palette.ts
    +++ b/app/src/engine/palette.ts
    @@ -12,6 +12,15 @@ export const HEX = {
       ember: '#FF8A3D', // hotter, lighter orange for cores/highlights
       blood: '#C21D0B', // deep red-orange for shadows of signal
       acid: '#D8FF3C', // acid: only for the shrooms moment
    +  // ---- Pink Boots, Export Doors: the white page ----
    +  paper: '#FFFFFF', // the page: stays pure white
    +  line: '#15131A', // drawing line / body text
    +  pink: '#FF2E93', // her colour: boots, the sung word
    +  cobalt: '#2440FF', // the state / "your bot"
    +  lemon: '#FFE21A',
    +  mint: '#2EE6A8',
    +  tangerine: '#FF7A1A', // rare
    +  lilac: '#B79CFF', // holo stop
     } as const;
     
     export type PaletteKey = keyof typeof HEX;
    diff --git a/app/src/engine/post.ts b/app/src/engine/post.ts
    index e3f155b..29b7e2b 100644
    --- a/app/src/engine/post.ts
    +++ b/app/src/engine/post.ts
    @@ -6,9 +6,10 @@ import { FSPass, makeRT, W, H, SCALE } from './gl';
     /** The tone shoulder (linear HDR -> 0..1 linear), shared with the engine's sampling error estimate. */
     export const SHOULDER_GLSL = /* glsl */ `
     vec3 shoulder(vec3 x) {
    -  // identity below k, smooth exponential shoulder above; very bright values desaturate toward white
    -  const float k = 0.72;
    -  vec3 y = mix(x, k + (1.0 - k) * (1.0 - exp(-(x - k) / (1.0 - k))), step(k, x));
    +  // identity below k, smooth exponential shoulder above; very bright values desaturate toward white.
    +  // White page: k = 1 so paper white (1.0) stays pure white; only HDR highlights (> 1) are compressed.
    +  const float k = 1.0;
    +  vec3 y = mix(x, k + 0.25 * (1.0 - exp(-(x - k) / 0.25)), step(k, x));
       float over = max(max(x.r, x.g), x.b);
       return mix(y, vec3(1.0), smoothstep(2.0, 12.0, over) * 0.85);
     }`;
    @@ -42,16 +43,17 @@ export interface PostParams {
     }
     
     export const DEFAULT_POST: PostParams = {
    +  // white page: no bloom/halation/vignette (they grey the paper), a whisper of grain
       exposure: 1,
    -  bloom: 0.55,
    -  bloomThreshold: 0.85,
    -  bloomKnee: 0.5,
    -  bloomRadius: 0.75,
    -  halation: 0.25,
    -  ca: 1.2,
    -  grain: 0.055,
    -  vignette: 0.35,
    -  hud: 1,
    +  bloom: 0,
    +  bloomThreshold: 1.2,
    +  bloomKnee: 0.4,
    +  bloomRadius: 0.6,
    +  halation: 0,
    +  ca: 0,
    +  grain: 0.018,
    +  vignette: 0,
    +  hud: 0,
       frame: 0,
       pdoom: 0,
       paper: 0,
    @@ -145,7 +147,7 @@ ${SCALE === 1 ? `        c += texture(src, vUv + texel * vec2(-1, -1)).rgb; c +=
             col = mix(col, h.rgb / max(h.a, 1e-4), h.a * hud);
             col = shoulder(col);
             col = mix(col, vec3(0.8515) - col * 0.84, invert); // ink<->bone in linear-ish space
    -        col += C_BONE * flash;
    +        col = mix(col, C_PAPER, sat(flash));
             // vignette
             float v = smoothstep(0.95, 0.25, length(dc * vec2(1.0, 0.8)));
             col *= mix(1.0, v, vignette);
    @@ -206,7 +208,7 @@ ${SCALE === 1 ? `        float g1 = hash12(gl_FragCoord.xy + fract(time * 13.37)
         f.ca!.value = p.ca;
         f.grain!.value = p.grain;
         f.vignette!.value = p.vignette;
    -    f.hud!.value = p.hud;
    +    f.hud!.value = 1; // HUD opacity is applied inside the HUD layer (Hud.draw), the overlay always shows
         f.fade!.value = p.fade;
         f.flash!.value = p.flash;
         f.time!.value = time;
    diff --git a/app/src/engine/scene.ts b/app/src/engine/scene.ts
    index 8ebd18f..d4e8cd8 100644
    --- a/app/src/engine/scene.ts
    +++ b/app/src/engine/scene.ts
    @@ -70,6 +70,13 @@ export abstract class Scene {
       /** Load/create resources. Called once before first render. */
       init(): Promise<void> | void {}
     
    +  /**
    +   * Optional async preload for the time range [t0, t1] (e.g. decode the video frames a shot needs).
    +   * Export awaits it before every frame; the preview calls it ahead of the playhead without waiting,
    +   * so render() must draw something sensible when the data is not there yet.
    +   */
    +  prepare?(t0: number, t1: number): Promise<void> | void;
    +
       /** Reset internal state (called on seeks for stateful scenes). */
       reset(): void {}
     
    diff --git a/app/src/engine/type.ts b/app/src/engine/type.ts
    index a74cc32..48fbe27 100644
    --- a/app/src/engine/type.ts
    +++ b/app/src/engine/type.ts
    @@ -10,7 +10,7 @@ export const ARCHIVO_WIDTHS = [620, 750, 875, 1000, 1125, 1250] as const;
     export const ARCHIVO_WEIGHTS = [300, 500, 700, 900] as const;
     
     /** `features`: OpenType features switched on for the face (Canvas2D has no font-feature-settings). */
    -type FontDef = { family: string; file: string; features?: string };
    +type FontDef = { family: string; file: string; features?: string; weight?: string };
     const DEFS: FontDef[] = [];
     for (const w of ARCHIVO_WIDTHS) for (const wt of ARCHIVO_WEIGHTS) DEFS.push({ family: `Archivo-${w}-${wt}`, file: `Archivo-w${w}-${wt}.ttf` });
     for (const w of [750, 1000]) for (const wt of [400, 800]) DEFS.push({ family: `ArchivoItalic-${w}-${wt}`, file: `ArchivoItalic-w${w}-${wt}.ttf` });
    @@ -22,9 +22,27 @@ for (const wt of [400, 600]) {
     for (const [n, f] of [['300', 'Light'], ['400', 'Regular'], ['500', 'Medium'], ['600', 'SemiBold'], ['700', 'Bold']] as const)
       DEFS.push({ family: `Plex-${n}`, file: `src/IBMPlexMono-${f}.ttf` });
     DEFS.push({ family: 'PlexItalic-400', file: 'src/IBMPlexMono-Italic.ttf' });
    +// Pink Boots: Bricolage Grotesque (display, static instances at opsz 96) + Instrument Serif
    +for (const wd of [75, 100]) for (const wt of [500, 800]) DEFS.push({ family: `Bricolage-${wd}-${wt}`, file: `pop/Bricolage-w${wd}-${wt}.ttf` });
    +DEFS.push({ family: 'InstrumentSerif', file: 'pop/InstrumentSerif-Regular.ttf' });
    +DEFS.push({ family: 'InstrumentSerifItalic', file: 'pop/InstrumentSerif-Italic.ttf' });
    +// world kits (phone / scrapbook / comic): OFL + Apache Google Fonts
    +for (const [family, file] of [['Bangers', 'Bangers-Regular'], ['ComicNeue', 'ComicNeue-Bold'], ['GochiHand', 'GochiHand-Regular'],
    +  ['LuckiestGuy', 'LuckiestGuy-Regular'], ['PermanentMarker', 'PermanentMarker-Regular'], ['RubikBubbles', 'RubikBubbles-Regular']] as const)
    +  DEFS.push({ family, file: `kit/${file}.ttf` });
    +DEFS.push({ family: 'Caveat', file: 'kit/Caveat.ttf', weight: '400 700' });
    +DEFS.push({ family: 'Inter', file: 'kit/Inter.ttf', weight: '100 900' });
     
     /** Convenience family names. */
     export const F = {
    +  /** Bricolage Grotesque: condensed (75) or normal (100) width, 500 or 800 weight. */
    +  pop(width = 100, weight = 800): string {
    +    return `Bricolage-${width < 88 ? 75 : 100}-${weight < 650 ? 500 : 800}`;
    +  },
    +  /** Instrument Serif (italic by default): the sweet aside. */
    +  sweet(italic = true): string {
    +    return italic ? 'InstrumentSerifItalic' : 'InstrumentSerif';
    +  },
       /** Archivo at nearest available width/weight. width in [62..125] (percent), weight 300..900 */
       archivo(width = 100, weight = 700): string {
         const w = nearest(ARCHIVO_WIDTHS as unknown as number[], width * 10);
    @@ -51,6 +69,8 @@ function nearest(list: number[], v: number) {
     
     /** CSS font string for Canvas2D. */
     export const font = (family: string, sizePx: number) => `${sizePx}px "${family}"`;
    +/** CSS font string with an explicit weight (for the variable faces: Inter, Caveat). */
    +export const fontW = (family: string, sizePx: number, weight: number) => `${weight} ${sizePx}px "${family}"`;
     
     const otCache = new Map<string, opentype.Font>();
     const bufCache = new Map<string, ArrayBuffer>();
    @@ -60,7 +80,10 @@ export async function loadFonts(): Promise<void> {
         DEFS.map(async (d) => {
           const buf = await (await fetch(`fonts/${d.file}`)).arrayBuffer();
           bufCache.set(d.family, buf);
    -      const ff = new FontFace(d.family, buf, d.features ? { featureSettings: d.features } : undefined);
    +      const desc: FontFaceDescriptors = {};
    +      if (d.features) desc.featureSettings = d.features;
    +      if (d.weight) desc.weight = d.weight;
    +      const ff = new FontFace(d.family, buf, desc);
           await ff.load();
           document.fonts.add(ff);
         }),
    diff --git a/app/src/engine/util.ts b/app/src/engine/util.ts
    index c403d73..58aa429 100644
    --- a/app/src/engine/util.ts
    +++ b/app/src/engine/util.ts
    @@ -171,3 +171,12 @@ export function hexToLinear(hex: string): [number, number, number] {
       });
       return c as [number, number, number];
     }
    +
    +/**
    + * Global energy knob (?calm=0.65): scales the punches (beat/word/downbeat hits, decays), spring overshoot,
    + * whip roll, cut flashes and the post punch (shake, zoom, colour split). 1 = the full cut.
    + */
    +export const CALM = (() => {
    +  const q = typeof location !== 'undefined' ? new URLSearchParams(location.search).get('calm') : null;
    +  return q !== null && q !== '' && isFinite(+q) ? Math.max(0, +q) : 1;
    +})();
    diff --git a/app/src/main.ts b/app/src/main.ts
    index 010d21f..3d29806 100644
    --- a/app/src/main.ts
    +++ b/app/src/main.ts
    @@ -2,6 +2,8 @@
     import { Engine, type AdaptiveSampling } from './engine/engine';
     import { PW, PH, SCALE } from './engine/gl';
     import { makeTimeline } from './timeline';
    +import { watermark } from './lib/brand';
    +import { W } from './engine/gl';
     
     const params = new URLSearchParams(location.search);
     const EXPORT = params.has('export');
    @@ -24,6 +26,8 @@ let TIMELINE: typeof engine.timeline = [];
     async function boot() {
       const onlySet = ONLY ? new Set(ONLY.split(',')) : null;
       await engine.init(onlySet ? (e) => onlySet.has(e.id) : undefined);
    +  // author watermark, top-right, while the song plays (the end card shows the handles itself)
    +  engine.hud.overlay = (c, t) => { if (t < engine.audio.duration) watermark(c, W); };
       TIMELINE = engine.timeline;
       if (EXPORT) setupExport();
       else setupPlayer();
    @@ -42,7 +46,7 @@ function setupExport() {
         height: PH,
         timeline: TIMELINE.map(({ id, start, end }) => ({ id, start, end })),
         /** Render a single frame at t (seeks as needed). */
    -    still(t: number, samples: number | AdaptiveSampling = 1, shutter = 0.5) { return engine.render(t, 1 / 60, true, samples, shutter); },
    +    async still(t: number, samples: number | AdaptiveSampling = 1, shutter = 0.5) { await engine.prepare(t - 1 / 60, t + 1 / 60); return engine.render(t, 1 / 60, true, samples, shutter); },
         /** The last rendered frame as a full-resolution (PW x PH) PNG, base64 (for stills at scale > 1). */
         async png() {
           const px = await engine.readPixelsAsync(), row = PW * 4;
    @@ -74,9 +78,10 @@ function setupExport() {
           // warm-up: render one frame before the range so the first frame is sequential for stateful scenes
           const S = opts.samples ?? 1, SH = opts.shutter ?? 0.5;
           // (adaptive sampling only runs stateless scenes: one sample is enough for the warm-up)
    -      if (n0 > 0) engine.render((n0 - 1) * dt, dt, false, typeof S === 'number' ? S : 1, SH);
    +      if (n0 > 0) { await engine.prepare((n0 - 2) * dt, n0 * dt); engine.render((n0 - 1) * dt, dt, false, typeof S === 'number' ? S : 1, SH); }
           const used: Record<number, number> = {}; // sub-frames per frame -> frames
           for (let n = n0; n < n1; n++) {
    +        await engine.prepare((n - 1) * dt, (n + 1) * dt);
             const k = engine.render(n * dt, dt, false, S, SH);
             used[k] = (used[k] ?? 0) + 1;
             await engine.readPixelsAsync(buf);
    @@ -95,7 +100,7 @@ function setupExport() {
     
     // ------------------------------------------------------------------ preview player
     function setupPlayer() {
    -  const audio = new Audio('audio/pdoom.mp3');
    +  const audio = new Audio('audio/track.wav');
       audio.preload = 'auto';
       const ui = document.getElementById('ui')!;
       const scrub = document.getElementById('scrub') as HTMLInputElement;
    @@ -152,6 +157,7 @@ function setupPlayer() {
           if (loop && t >= loop[1]) seek(loop[0]);
           if (audio.ended) playing = false;
         }
    +    void engine.prepare(t, t + 0.6);
         engine.render(t, 1 / 60);
         scrub.value = String(t);
         frames++;
    
  • skills/lyric-music-video/assets/fonts/pop/Bricolage-w100-500.ttf89 KB419a1ad5ba71upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/assets/fonts/pop/Bricolage-w100-800.ttf89 KB0cc073f4d12fupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/assets/fonts/pop/Bricolage-w75-500.ttf88 KBe33a2cec1474upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/assets/fonts/pop/Bricolage-w75-800.ttf88 KB40fae09c3075upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/assets/fonts/pop/InstrumentSerif-Italic.ttf70 KB192c3eda9864upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/assets/fonts/pop/InstrumentSerif-Regular.ttf68 KB36fac00ef9b7upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/assets/lib/brand.ts2.8 KB9b05b32252e6upstream ↗
    // Author branding: the X / Telegram marks, the corner watermark (every frame, via the HUD) and the handles.
    import { fontW } from '../engine/type';
    
    // Set these to the author's handles (the watermark shows X_HANDLE; the end card shows both). Empty = hidden.
    export const X_HANDLE = '@your_handle';
    export const TG_HANDLE = 't.me/your_channel';
    
    // X mark (viewBox 0 0 1200 1227) and the Telegram plane (viewBox 0 0 240 240, on a blue disc)
    const X_PATH = new Path2D('M714.163 519.284L1160.89 0H1055.03L667.137 450.887L357.328 0H0L468.492 681.821L0 1226.37H105.866L515.491 750.218L842.672 1226.37H1200L714.137 519.284H714.163ZM569.165 687.828L521.697 619.934L144.011 79.6944H306.615L611.412 515.685L658.88 583.579L1055.08 1150.3H892.476L569.165 687.854V687.828Z');
    const TG_PLANE = new Path2D('M54.3 118.8c35-15.2 58.3-25.3 70-30.2 33.3-13.9 40.3-16.3 44.8-16.4 1 0 3.2.2 4.7 1.4 1.2 1 1.5 2.3 1.7 3.3s.4 3.1.2 4.7c-1.8 19-9.6 65.1-13.6 86.3-1.7 9-5 12-8.2 12.3-7 .6-12.3-4.6-19-9-10.6-6.9-16.5-11.2-26.8-18-11.9-7.8-4.2-12.1 2.6-19.1 1.8-1.8 32.5-29.8 33.1-32.3.1-.3.1-1.5-.6-2.1-.7-.6-1.7-.4-2.5-.2-1.1.2-17.9 11.4-50.6 33.5-4.8 3.3-9.1 4.9-13 4.8-4.3-.1-12.5-2.4-18.7-4.4-7.5-2.4-13.5-3.7-13-7.9.3-2.2 3.3-4.4 8.9-6.7z');
    export const TG_BLUE = '#2AABEE';
    
    /** X mark on a black rounded square, `s` px wide, top-left at (x, y). */
    export function xBadge(c: CanvasRenderingContext2D, x: number, y: number, s: number) {
      c.save();
      c.fillStyle = '#000'; c.beginPath(); c.roundRect(x, y, s, s, s * 0.24); c.fill();
      const g = s * 0.56, k = g / 1227;
      c.translate(x + (s - 1200 * k) / 2, y + (s - g) / 2); c.scale(k, k);
      c.fillStyle = '#fff'; c.fill(X_PATH);
      c.restore();
    }
    
    /** Telegram mark: blue disc with the white plane, `s` px wide, top-left at (x, y). */
    export function tgBadge(c: CanvasRenderingContext2D, x: number, y: number, s: number) {
      c.save();
      c.fillStyle = TG_BLUE; c.beginPath(); c.arc(x + s / 2, y + s / 2, s / 2, 0, Math.PI * 2); c.fill();
      c.translate(x, y); c.scale(s / 240, s / 240);
      c.fillStyle = '#fff'; c.fill(TG_PLANE);
      c.restore();
    }
    
    /** Corner watermark: X badge + handle on a soft white pill, top-right. */
    export function watermark(c: CanvasRenderingContext2D, W: number) {
      if (!X_HANDLE) return;
      const h = 56, pad = 9, gap = 14;
      c.save();
      c.font = fontW('Inter', 29, 800);
      const tw = c.measureText(X_HANDLE).width;
      const w = pad + (h - 2 * pad) + gap + tw + 18;
      const x = W - 28 - w, y = 24;
      c.shadowColor = 'rgba(21,19,26,0.18)'; c.shadowBlur = 12; c.shadowOffsetY = 3;
      c.fillStyle = 'rgba(255,255,255,0.86)'; c.beginPath(); c.roundRect(x, y, w, h, h / 2); c.fill();
      c.shadowColor = 'transparent';
      xBadge(c, x + pad, y + pad, h - 2 * pad);
      c.fillStyle = '#15131A'; c.textBaseline = 'middle'; c.textAlign = 'left';
      c.fillText(X_HANDLE, x + pad + (h - 2 * pad) + gap, y + h / 2 + 1);
      c.restore();
    }
    
  • skills/lyric-music-video/assets/lib/kit.ts26 KB64a50bda2325upstream ↗
    // World kit: the three visual languages of the video, drawn in Canvas2D (logical 1920x1080 px).
    //   PHONE     her phone's OS: glass panels, chat bubbles, notifications, status bar, FaceTime tiles
    //   SCRAPBOOK Y2K notebook: stickers that slap on, washi tape, polaroids, ransom letters, gel pen
    //   COMIC     pop-art datasheet: panels with gutters, halftone fills, bursts, balloons, SFX lettering
    // Plus shared motion (slap / pop springs) and image loading for the generated art in public/art.
    // Everything is a pure function of song time t: pass event times in, never keep state.
    import { font, fontW } from '../engine/type';
    import { HEX } from '../engine/palette';
    import { clamp, ease, hash, mulberry32, springStep, TAU, CALM } from '../engine/util';
    import { drawStrokeText, type StrokeText } from '../engine/stroke';
    
    export type Ctx = CanvasRenderingContext2D;
    export type Img = ImageBitmap;
    
    // ---------------- images ----------------
    const images = new Map<string, Img>();
    /** Load art/<path>.png files (relative to public/art) once. */
    export async function loadArt(paths: string[]) {
      await Promise.all(paths.filter((p) => !images.has(p)).map(async (p) => {
        // a flaky read (e.g. ERR_CACHE_WRITE_FAILURE under parallel renders) must not drop a sticker from the video: retry
        for (let k = 0; k < 4; k++) {
          try {
            const r = await fetch(`art/${p}.png`, { cache: 'no-store' });
            // a missing file comes back as Vite's index.html (200, text/html): skip it, the draw code tolerates null
            if (!r.ok || !(r.headers.get('content-type') ?? '').startsWith('image/')) { console.warn('missing art', p); return; }
            images.set(p, await createImageBitmap(await r.blob()));
            return;
          } catch { await new Promise((ok) => setTimeout(ok, 200 * (k + 1))); }
        }
        console.warn('bad art', p);
      }));
    }
    export const art = (p: string) => images.get(p) ?? null;
    
    // ---------------- motion ----------------
    /** Sticker slap: scale overshoots from big to 1, a little rotation settles, fades in over 2 frames. */
    export function slap(t: number, t0: number, big = 0.35, rot = 0.12) {
      if (t < t0) return null;
      const u = t - t0;
      const s = springStep(u, 3.2, 0.34);
      return { k: 1 + big * CALM * (1 - s), r: rot * CALM * (1 - s), a: clamp(u * 30), fresh: Math.exp(-u * 12) };
    }
    /** Pop in from zero (UI bubbles). */
    export function pop(t: number, t0: number, freq = 3.4, damp = 0.42) {
      if (t < t0) return 0;
      const s = springStep(t - t0, freq, damp);
      return s > 1 ? 1 + (s - 1) * CALM : s;
    }
    /** Decaying hit 1 → 0. */
    export const hit = (t: number, t0: number, hl = 0.1) => (t < t0 ? 0 : CALM * Math.pow(0.5, (t - t0) / hl));
    
    /** Draw an image by its centre at height h (or width w if given), with rotation / scale / alpha. */
    export function drawArt(c: Ctx, im: Img | null, x: number, y: number, h: number, o: { rot?: number; k?: number; a?: number; w?: number; ax?: number; ay?: number; flip?: boolean } = {}) {
      if (!im) return;
      const k = o.k ?? 1;
      const hh = o.w ? (o.w / im.width) * im.height : h, ww = o.w ?? (h / im.height) * im.width;
      c.save();
      c.globalAlpha *= o.a ?? 1;
      c.translate(x, y); c.rotate(o.rot ?? 0); c.scale(k * (o.flip ? -1 : 1), k);
      c.drawImage(im, -ww * (o.ax ?? 0.5), -hh * (o.ay ?? 0.5), ww, hh);
      c.restore();
    }
    
    /** A sticker: soft drop shadow that lifts while the slap is fresh. */
    export function sticker(c: Ctx, im: Img | null, x: number, y: number, h: number, t: number, t0: number, o: { rot?: number; big?: number; w?: number } = {}) {
      const s = slap(t, t0, o.big ?? 0.35);
      if (!s || !im) return;
      c.save();
      c.shadowColor = 'rgba(40,10,40,0.28)';
      c.shadowBlur = 14 + 30 * s.fresh;
      c.shadowOffsetX = 4 + 14 * s.fresh; c.shadowOffsetY = 8 + 22 * s.fresh;
      drawArt(c, im, x, y, h, { rot: (o.rot ?? 0) + s.r, k: s.k, a: s.a, w: o.w });
      c.restore();
    }
    
    // ---------------- text utils ----------------
    export function fitFont(c: Ctx, text: string, fam: string, maxW: number, maxSize: number) {
      c.font = font(fam, 100);
      const w = c.measureText(text).width;
      return Math.min(maxSize, (100 * maxW) / Math.max(1, w));
    }
    
    // =====================================================================================
    // PHONE
    // =====================================================================================
    export const PH = {
      glass(c: Ctx, x: number, y: number, w: number, h: number, r = 34, a = 0.62) {
        c.save();
        c.shadowColor = 'rgba(120,20,80,0.18)'; c.shadowBlur = 40; c.shadowOffsetY = 18;
        c.fillStyle = `rgba(255,255,255,${a})`;
        c.beginPath(); c.roundRect(x, y, w, h, r); c.fill();
        c.restore();
        c.save();
        const g = c.createLinearGradient(x, y, x, y + h);
        g.addColorStop(0, 'rgba(255,255,255,0.55)'); g.addColorStop(0.5, 'rgba(255,255,255,0.08)'); g.addColorStop(1, 'rgba(255,255,255,0.3)');
        c.strokeStyle = g; c.lineWidth = 2;
        c.beginPath(); c.roundRect(x + 1, y + 1, w - 2, h - 2, r - 1); c.stroke();
        c.restore();
      },
      /** Holographic pink wallpaper with drifting blobs (the phone's background). */
      wallpaper(c: Ctx, t: number, W: number, H: number, hue = 0) {
        c.save();
        const g = c.createLinearGradient(0, 0, W, H);
        g.addColorStop(0, '#FFE3F1'); g.addColorStop(0.5, '#FFF4FA'); g.addColorStop(1, '#E9E4FF');
        c.fillStyle = g; c.fillRect(0, 0, W, H);
        const blobs = [[HEX.pink, 0.35], ['#FF9ACB', 0.4], [HEX.lilac, 0.35], ['#FFD0E6', 0.5], [HEX.cobalt, 0.12]] as const;
        c.globalCompositeOperation = 'multiply';
        blobs.forEach(([col, a], i) => {
          const x = W * (0.5 + 0.42 * Math.sin(t * 0.21 + i * 1.7 + hue)), y = H * (0.5 + 0.4 * Math.cos(t * 0.17 + i * 2.3));
          const r = 420 + 140 * Math.sin(t * 0.3 + i);
          const rg = c.createRadialGradient(x, y, 0, x, y, r);
          rg.addColorStop(0, hexA(col, a)); rg.addColorStop(1, hexA(col, 0));
          c.fillStyle = rg; c.fillRect(0, 0, W, H);
        });
        c.restore();
      },
      statusBar(c: Ctx, W: number, t: number, clock = '9:41', battery = 99) {
        c.save();
        c.fillStyle = HEX.line; c.font = fontW('Inter', 30, 700); c.textBaseline = 'middle';
        c.fillText(clock, 70, 42);
        c.textAlign = 'right';
        c.font = fontW('Inter', 24, 700); c.fillText(`5G`, W - 190, 42);
        // signal bars
        for (let i = 0; i < 4; i++) c.fillRect(W - 300 + i * 14, 50 - 8 - i * 6, 9, 8 + i * 6);
        // battery
        c.strokeStyle = HEX.line; c.lineWidth = 2.5; c.beginPath(); c.roundRect(W - 160, 28, 62, 28, 8); c.stroke();
        c.fillStyle = battery > 20 ? '#34C759' : '#FF3B30'; c.beginPath(); c.roundRect(W - 156, 32, 54 * battery / 100, 20, 5); c.fill();
        c.fillStyle = HEX.line; c.fillRect(W - 95, 36, 4, 12);
        c.font = fontW('Inter', 22, 700); c.fillText(`${battery}%`, W - 172, 42);
        void t;
        c.restore();
      },
      /**
       * iMessage-style bubble. side 'l' = grey incoming, 'r' = coloured outgoing. Returns its height.
       * `k` = pop scale (0..1+), anchored at the tail.
       */
      bubble(c: Ctx, text: string, x: number, y: number, o: { side?: 'l' | 'r'; color?: string; ink?: string; size?: number; maxW?: number; k?: number; fam?: string; weight?: number } = {}) {
        const side = o.side ?? 'r', size = o.size ?? 44, k = o.k ?? 1;
        const fam = o.fam ?? 'Inter', wt = o.weight ?? 700;
        c.save();
        c.font = fontW(fam, size, wt);
        const lines = wrap(c, text, (o.maxW ?? 900) - size);
        const tw = Math.max(...lines.map((l) => c.measureText(l).width));
        const padX = size * 0.62, padY = size * 0.42, lh = size * 1.12;
        const w = tw + padX * 2, h = lines.length * lh + padY * 2;
        const bx = side === 'r' ? x - w : x;
        const ax = side === 'r' ? x : x, ay = y + h;
        c.translate(ax, ay); c.scale(k, k); c.translate(-ax, -ay);
        const col = o.color ?? (side === 'r' ? HEX.pink : '#E9E9EF');
        c.fillStyle = col;
        c.shadowColor = 'rgba(80,0,50,0.12)'; c.shadowBlur = 16; c.shadowOffsetY = 6;
        c.beginPath(); c.roundRect(bx, y, w, h, Math.min(size * 0.9, h / 2)); c.fill();
        // tail
        c.beginPath();
        if (side === 'r') { c.moveTo(x - 30, y + h - 26); c.quadraticCurveTo(x - 4, y + h - 4, x + 14, y + h + 2); c.quadraticCurveTo(x - 20, y + h + 4, x - 52, y + h - 8); }
        else { c.moveTo(x + 30, y + h - 26); c.quadraticCurveTo(x + 4, y + h - 4, x - 14, y + h + 2); c.quadraticCurveTo(x + 20, y + h + 4, x + 52, y + h - 8); }
        c.fill();
        c.shadowColor = 'transparent';
        c.fillStyle = o.ink ?? (side === 'r' ? '#fff' : HEX.line);
        c.textBaseline = 'alphabetic';
        lines.forEach((l, i) => c.fillText(l, bx + padX, y + padY + size * 0.9 + i * lh));
        c.restore();
        return h;
      },
      typing(c: Ctx, x: number, y: number, t: number, s = 1) {
        c.save(); c.translate(x, y); c.scale(s, s);
        c.fillStyle = '#E9E9EF'; c.beginPath(); c.roundRect(0, 0, 130, 70, 35); c.fill();
        c.beginPath(); c.arc(8, 64, 12, 0, TAU); c.fill(); c.beginPath(); c.arc(-4, 78, 6, 0, TAU); c.fill();
        for (let i = 0; i < 3; i++) {
          const b = 0.5 + 0.5 * Math.sin(t * 9 - i * 0.9);
          c.fillStyle = `rgba(120,120,135,${0.45 + 0.5 * b})`;
          c.beginPath(); c.arc(38 + i * 27, 35 - 4 * b, 9, 0, TAU); c.fill();
        }
        c.restore();
      },
      /** Notification banner. Returns height. */
      notif(c: Ctx, x: number, y: number, w: number, n: { app: string; title: string; body?: string; time?: string; icon?: string; iconBg?: string }, k = 1) {
        const h = n.body ? 150 : 110;
        c.save();
        c.translate(x + w / 2, y); c.scale(k, k); c.translate(-(x + w / 2), -y);
        PH.glass(c, x, y, w, h, 34, 0.78);
        c.fillStyle = n.iconBg ?? HEX.pink; c.beginPath(); c.roundRect(x + 24, y + 24, 62, 62, 16); c.fill();
        c.fillStyle = '#fff'; c.font = fontW('Inter', 34, 800); c.textAlign = 'center'; c.textBaseline = 'middle';
        c.fillText(n.icon ?? '♥', x + 55, y + 57);
        c.textAlign = 'left'; c.textBaseline = 'alphabetic';
        c.fillStyle = 'rgba(21,19,26,0.55)'; c.font = fontW('Inter', 20, 600); c.fillText(n.app.toUpperCase(), x + 108, y + 44);
        c.textAlign = 'right'; c.fillText(n.time ?? 'now', x + w - 28, y + 44); c.textAlign = 'left';
        c.fillStyle = HEX.line; c.font = fontW('Inter', 30, 800); c.fillText(n.title, x + 108, y + 84, w - 140);
        if (n.body) { c.fillStyle = 'rgba(21,19,26,0.75)'; c.font = fontW('Inter', 26, 500); c.fillText(n.body, x + 108, y + 122, w - 140); }
        c.restore();
        return h;
      },
      /** Rounded image tile (FaceTime / photo), cover-fit. */
      tile(c: Ctx, im: Img | null, x: number, y: number, w: number, h: number, r = 40, o: { zoom?: number; fx?: number; fy?: number } = {}) {
        c.save();
        c.shadowColor = 'rgba(80,0,50,0.25)'; c.shadowBlur = 40; c.shadowOffsetY = 16;
        c.fillStyle = '#fff'; c.beginPath(); c.roundRect(x, y, w, h, r); c.fill();
        c.shadowColor = 'transparent';
        c.clip();
        if (im) {
          const z = o.zoom ?? 1, sc = Math.max(w / im.width, h / im.height) * z;
          const iw = im.width * sc, ih = im.height * sc;
          c.drawImage(im, x + (w - iw) * (o.fx ?? 0.5), y + (h - ih) * (o.fy ?? 0.4), iw, ih);
        }
        c.restore();
      },
    };
    
    // =====================================================================================
    // SCRAPBOOK
    // =====================================================================================
    const RANSOM_FONTS = ['Archivo-1250-900', 'Cormorant-600', 'Bricolage-75-800', 'Plex-700', 'Bangers', 'InstrumentSerif', 'Archivo-620-900', 'LuckiestGuy'];
    const RANSOM_BG = ['#FFFFFF', '#FFE21A', HEX.pink, '#15131A', '#B79CFF', '#FFD0E6', '#2440FF', '#FFF4D6'];
    export const SC = {
      /** Magazine cut-out letters, each on its own paper chip; letter i appears at times[i]. */
      ransom(c: Ctx, text: string, x: number, y: number, size: number, t: number, times: number[], seed = 1, align: 'left' | 'center' = 'left') {
        const R = mulberry32(seed);
        const chars = Array.from(text);
        const specs = chars.map((ch) => {
          const fi = Math.floor(R() * RANSOM_FONTS.length), bi = Math.floor(R() * RANSOM_BG.length);
          const s = size * (0.85 + 0.3 * R());
          return { ch, fam: RANSOM_FONTS[fi]!, bg: RANSOM_BG[bi]!, s, rot: (R() - 0.5) * 0.22, dy: (R() - 0.5) * size * 0.12, upper: R() > 0.4 };
        });
        let total = 0;
        const widths = specs.map((sp) => { c.font = font(sp.fam, sp.s); const w = sp.ch === ' ' ? size * 0.35 : c.measureText(sp.upper ? sp.ch.toUpperCase() : sp.ch).width + sp.s * 0.28; total += w; return w; });
        let cx = align === 'center' ? x - total / 2 : x;
        specs.forEach((sp, i) => {
          const w = widths[i]!;
          const t0 = times[i] ?? times[times.length - 1] ?? 0;
          const s = slap(t, t0, 0.5, sp.rot * 2);
          if (s && sp.ch !== ' ') {
            c.save();
            c.translate(cx + w / 2, y + sp.dy); c.rotate(sp.rot + s.r); c.scale(s.k, s.k);
            c.shadowColor = 'rgba(40,10,40,0.25)'; c.shadowBlur = 6; c.shadowOffsetY = 4;
            c.fillStyle = sp.bg;
            const hh = sp.s * 1.12;
            // torn-ish chip
            c.beginPath();
            const RR = mulberry32(seed * 100 + i);
            const pts: [number, number][] = [[-w / 2, -hh * 0.62], [w / 2, -hh * 0.6], [w / 2, hh * 0.45], [-w / 2, hh * 0.46]];
            pts.forEach(([px, py], j) => { const jx = px + (RR() - 0.5) * 8, jy = py + (RR() - 0.5) * 8; j ? c.lineTo(jx, jy) : c.moveTo(jx, jy); });
            c.closePath(); c.fill();
            c.shadowColor = 'transparent';
            const dark = sp.bg === '#15131A' || sp.bg === '#2440FF' || sp.bg === HEX.pink;
            c.fillStyle = dark ? '#FFFFFF' : (RR() > 0.5 ? HEX.line : HEX.pink);
            c.font = font(sp.fam, sp.s); c.textAlign = 'center'; c.textBaseline = 'middle';
            c.fillText(sp.upper ? sp.ch.toUpperCase() : sp.ch, 0, -hh * 0.06);
            c.restore();
          }
          cx += w;
        });
        return total;
      },
      /** Washi tape strip (image), slapped at t0. */
      tape(c: Ctx, im: Img | null, x: number, y: number, len: number, rot: number, t: number, t0: number) {
        const s = slap(t, t0, 0.15, 0.05);
        if (!s || !im) return;
        c.save(); c.globalAlpha *= 0.92 * s.a;
        drawArt(c, im, x, y, 0, { w: len * s.k, rot: rot + s.r });
        c.restore();
      },
      /** Gel-pen writing: a stroke-font text written up to `len`, with a glossy double line. */
      gel(c: Ctx, st: StrokeText, len: number, color: string = HEX.pink, width = 6) {
        c.save();
        c.lineCap = 'round'; c.lineJoin = 'round';
        c.strokeStyle = color; c.lineWidth = width; drawStrokeText(c, st, len);
        c.strokeStyle = 'rgba(255,255,255,0.45)'; c.lineWidth = width * 0.28; c.translate(-width * 0.12, -width * 0.12); drawStrokeText(c, st, len);
        c.restore();
      },
      /** Hand-drawn doodle polyline written progressively (heart/star/arrow/squiggle). */
      doodle(c: Ctx, pts: [number, number][], p: number, color: string = HEX.pink, width = 6) {
        if (p <= 0 || pts.length < 2) return;
        let L = 0; const seg: number[] = [0];
        for (let i = 1; i < pts.length; i++) { L += Math.hypot(pts[i]![0] - pts[i - 1]![0], pts[i]![1] - pts[i - 1]![1]); seg.push(L); }
        const target = L * clamp(p);
        c.save(); c.strokeStyle = color; c.lineWidth = width; c.lineCap = 'round'; c.lineJoin = 'round';
        c.beginPath(); c.moveTo(pts[0]![0], pts[0]![1]);
        for (let i = 1; i < pts.length; i++) {
          if (seg[i]! <= target) c.lineTo(pts[i]![0], pts[i]![1]);
          else { const u = (target - seg[i - 1]!) / (seg[i]! - seg[i - 1]!); c.lineTo(pts[i - 1]![0] + (pts[i]![0] - pts[i - 1]![0]) * u, pts[i - 1]![1] + (pts[i]![1] - pts[i - 1]![1]) * u); break; }
        }
        c.stroke(); c.restore();
      },
      heartPts(cx: number, cy: number, s: number, seed = 1): [number, number][] {
        const R = mulberry32(seed); const out: [number, number][] = [];
        for (let i = 0; i <= 60; i++) {
          const a = (i / 60) * TAU;
          const x = 16 * Math.pow(Math.sin(a), 3), y = -(13 * Math.cos(a) - 5 * Math.cos(2 * a) - 2 * Math.cos(3 * a) - Math.cos(4 * a));
          out.push([cx + x * s / 16 + (R() - 0.5) * s * 0.05, cy + y * s / 16 + (R() - 0.5) * s * 0.05]);
        }
        return out;
      },
      starPts(cx: number, cy: number, r: number, rot = 0): [number, number][] {
        const out: [number, number][] = [];
        for (let i = 0; i <= 10; i++) { const a = rot - Math.PI / 2 + (i / 10) * TAU; const rr = i % 2 ? r * 0.42 : r; out.push([cx + Math.cos(a) * rr, cy + Math.sin(a) * rr]); }
        return out;
      },
      /** Twinkling glints over a glitter sticker's box. */
      glints(c: Ctx, x: number, y: number, w: number, h: number, t: number, seed: number, n = 6) {
        c.save();
        for (let i = 0; i < n; i++) {
          const ph = hash(seed, i) * TAU, sp = 3 + 4 * hash(seed, i + 50);
          const b = Math.pow(Math.max(0, Math.sin(t * sp + ph)), 8);
          if (b < 0.02) continue;
          const gx = x + hash(seed, i + 100) * w, gy = y + hash(seed, i + 200) * h, r = 14 + 22 * b;
          c.fillStyle = `rgba(255,255,255,${0.9 * b})`;
          c.beginPath();
          for (let k = 0; k < 8; k++) { const a = (k / 8) * TAU; const rr = k % 2 ? r * 0.16 : r; c.lineTo(gx + Math.cos(a) * rr, gy + Math.sin(a) * rr); }
          c.closePath(); c.fill();
        }
        c.restore();
      },
    };
    
    // =====================================================================================
    // COMIC
    // =====================================================================================
    const dotCache = new Map<string, CanvasPattern>();
    export const CO = {
      /** Ben-Day dot pattern (cached) for fills: colour dots on transparent. */
      dots(c: Ctx, color: string, cell = 18, r = 5.5, angle = 0.26) {
        const key = `${color}|${cell}|${r}|${angle}`;
        let p = dotCache.get(key);
        if (!p) {
          const cv = document.createElement('canvas'); cv.width = cell; cv.height = cell;
          const g = cv.getContext('2d')!;
          g.fillStyle = color; g.beginPath(); g.arc(cell / 2, cell / 2, r, 0, TAU); g.fill();
          p = c.createPattern(cv, 'repeat')!;
          p.setTransform(new DOMMatrix().rotate(angle * 57.3));
          dotCache.set(key, p);
        }
        return p;
      },
      /** Fill a path with a flat colour + a dot layer (the classic pop-art tone). */
      toneFill(c: Ctx, path: Path2D, base: string, dotColor: string, cell = 18, r = 5.5) {
        c.save(); c.fillStyle = base; c.fill(path); c.fillStyle = CO.dots(c, dotColor, cell, r); c.fill(path); c.restore();
      },
      /** Radial halftone gradient: dots grow toward the edge (a spotlight). */
      radialDots(c: Ctx, cx: number, cy: number, r0: number, r1: number, color: string, cell = 22, x0 = 0, y0 = 0, x1 = 1920, y1 = 1080) {
        c.save(); c.fillStyle = color;
        for (let y = y0 + cell / 2; y < y1; y += cell) for (let x = x0 + cell / 2 + ((Math.floor(y / cell) % 2) * cell) / 2; x < x1; x += cell) {
          const d = Math.hypot(x - cx, y - cy);
          const k = clamp((d - r0) / (r1 - r0));
          if (k <= 0.02) continue;
          c.beginPath(); c.arc(x, y, (cell / 2) * 0.95 * k, 0, TAU); c.fill();
        }
        c.restore();
      },
      /** Speed lines toward a vanishing point. */
      speed(c: Ctx, cx: number, cy: number, t: number, n = 80, color: string = HEX.line, rIn = 260, seed = 3) {
        c.save(); c.fillStyle = color;
        for (let i = 0; i < n; i++) {
          const a = hash(seed, i) * TAU + t * 0.05, w = 0.004 + 0.012 * hash(seed, i + 9);
          const r0 = rIn + 200 * hash(seed, i + 3) + 60 * Math.sin(t * 20 + i);
          c.beginPath(); c.moveTo(cx + Math.cos(a) * r0, cy + Math.sin(a) * r0);
          c.lineTo(cx + Math.cos(a - w) * 3000, cy + Math.sin(a - w) * 3000); c.lineTo(cx + Math.cos(a + w) * 3000, cy + Math.sin(a + w) * 3000);
          c.closePath(); c.fill();
        }
        c.restore();
      },
      burstPath(cx: number, cy: number, r0: number, r1: number, n = 14, seed = 1, rot = 0) {
        const R = mulberry32(seed); const p = new Path2D();
        for (let i = 0; i < n * 2; i++) {
          const a = rot + (i / (n * 2)) * TAU + (R() - 0.5) * 0.12;
          const r = i % 2 ? r0 * (0.85 + 0.3 * R()) : r1 * (0.8 + 0.4 * R());
          const x = cx + Math.cos(a) * r, y = cy + Math.sin(a) * r;
          i ? p.lineTo(x, y) : p.moveTo(x, y);
        }
        p.closePath(); return p;
      },
      burst(c: Ctx, cx: number, cy: number, r0: number, r1: number, fill: string, o: { n?: number; seed?: number; rot?: number; k?: number; dots?: string; line?: number } = {}) {
        c.save(); c.translate(cx, cy); c.scale(o.k ?? 1, o.k ?? 1); c.translate(-cx, -cy);
        const p = CO.burstPath(cx, cy, r0, r1, o.n ?? 14, o.seed ?? 1, o.rot ?? 0);
        if (o.dots) CO.toneFill(c, p, fill, o.dots, 16, 4.5); else { c.fillStyle = fill; c.fill(p); }
        c.lineWidth = o.line ?? 9; c.lineJoin = 'miter'; c.strokeStyle = HEX.line; c.stroke(p);
        c.restore();
      },
      /** Comic SFX lettering: thick ink outline, misregistered colour shadow, optional skew. */
      sfx(c: Ctx, text: string, x: number, y: number, size: number, fill: string, o: { rot?: number; k?: number; shadow?: string; fam?: string; align?: CanvasTextAlign; skew?: number; line?: number } = {}) {
        c.save();
        c.translate(x, y); c.rotate(o.rot ?? 0); c.scale(o.k ?? 1, o.k ?? 1);
        if (o.skew) c.transform(1, 0, o.skew, 1, 0, 0);
        c.font = font(o.fam ?? 'Bangers', size); c.textAlign = o.align ?? 'center'; c.textBaseline = 'alphabetic';
        c.lineJoin = 'round';
        c.fillStyle = o.shadow ?? HEX.line; c.fillText(text, size * 0.06, size * 0.07);
        c.lineWidth = o.line ?? size * 0.1; c.strokeStyle = HEX.line; c.strokeText(text, 0, 0);
        c.fillStyle = fill; c.fillText(text, 0, 0);
        c.restore();
      },
      /** Speech balloon with a tail toward (tx, ty). */
      balloon(c: Ctx, x: number, y: number, w: number, h: number, tx: number, ty: number, k = 1, fill = '#fff') {
        c.save(); c.translate(x, y); c.scale(k, k); c.translate(-x, -y);
        const p = new Path2D();
        p.ellipse(x, y, w / 2, h / 2, 0, 0, TAU);
        const a = Math.atan2(ty - y, tx - x);
        const bx = x + Math.cos(a) * w * 0.3, by = y + Math.sin(a) * h * 0.3;
        const n = { x: -Math.sin(a), y: Math.cos(a) };
        const tail = new Path2D();
        tail.moveTo(bx + n.x * 36, by + n.y * 36); tail.lineTo(tx, ty); tail.lineTo(bx - n.x * 36, by - n.y * 36); tail.closePath();
        c.fillStyle = fill; c.lineWidth = 8; c.strokeStyle = HEX.line;
        c.stroke(tail); c.stroke(p); c.fill(tail); c.fill(p);
        c.restore();
      },
      /** A panel: clip to polygon, draw inside, then the ink border. */
      panel(c: Ctx, poly: [number, number][], draw: () => void, border = 9) {
        const p = new Path2D(); poly.forEach(([x, y], i) => (i ? p.lineTo(x, y) : p.moveTo(x, y))); p.closePath();
        c.save(); c.clip(p); draw(); c.restore();
        c.save(); c.lineWidth = border; c.strokeStyle = HEX.line; c.lineJoin = 'miter'; c.stroke(p); c.restore();
        return p;
      },
      /** Caption box (yellow, ink border, caps). */
      caption(c: Ctx, text: string, x: number, y: number, size = 40, fill: string = HEX.lemon, rot = -0.02, k = 1) {
        c.save(); c.translate(x, y); c.rotate(rot); c.scale(k, k);
        c.font = font('ComicNeue', size);
        const w = c.measureText(text).width + size * 1.1, h = size * 1.6;
        c.fillStyle = fill; c.fillRect(0, 0, w, h);
        c.lineWidth = 6; c.strokeStyle = HEX.line; c.strokeRect(0, 0, w, h);
        c.fillStyle = HEX.line; c.textBaseline = 'middle'; c.fillText(text, size * 0.55, h / 2 + 2);
        c.restore();
        return w;
      },
    };
    
    // ---------------- helpers ----------------
    function hexA(hex: string, a: number) {
      const n = parseInt(hex.replace('#', ''), 16);
      return `rgba(${(n >> 16) & 255},${(n >> 8) & 255},${n & 255},${a})`;
    }
    export { hexA };
    function wrap(c: Ctx, text: string, maxW: number) {
      const words = text.split(' ');
      const lines: string[] = [];
      let cur = '';
      for (const w of words) {
        const tryL = cur ? cur + ' ' + w : w;
        if (c.measureText(tryL).width > maxW && cur) { lines.push(cur); cur = w; } else cur = tryL;
      }
      if (cur) lines.push(cur);
      return lines;
    }
    export const EASE = ease;
    
    // ---------------- rhythm + camera (shared by all sections) ----------------
    /** Punch from a list of event times: the strongest recent decay (half-life hl), scaled by CALM. */
    export function pulse(times: number[], t: number, hl = 0.07, win = 0.6) {
      let p = 0;
      for (const b of times) { if (b > t) break; if (t - b < win) p = Math.max(p, Math.pow(0.5, (t - b) / hl)); }
      return p * CALM;
    }
    /** Punch on every sung word of a line. */
    export const wordHit = (line: { words: { start: number }[] }, t: number, hl = 0.08) => pulse(line.words.map((w) => w.start), t, hl, 10);
    
    export interface Cam { x: number; y: number; z: number; r: number }
    /** Camera from keys [time, cam]: each key is reached with a fast expo ease right on its time (a few frames early). */
    export function camKeys(t: number, keys: [number, Cam][], dur = 0.22, lead = 0.03): Cam {
      let cam = { ...keys[0]![1] };
      for (let i = 1; i < keys.length; i++) {
        const [kt, kc] = keys[i]!;
        const u = ease.outExpo(clamp((t - (kt - lead)) / (dur + lead)));
        if (u > 0) cam = { x: cam.x + (kc.x - cam.x) * u, y: cam.y + (kc.y - cam.y) * u, z: Math.exp(Math.log(cam.z) + (Math.log(kc.z) - Math.log(cam.z)) * u), r: cam.r + (kc.r - cam.r) * u };
      }
      return cam;
    }
    /** Whip between worlds at each cut: the outgoing frame is flung in the last 4.5 frames, the new one lands over ~7. dir ±1. */
    export function whipAt(t: number, cuts: number[], dirs: number[] = []) {
      let dx = 0, r = 0;
      cuts.forEach((tb, i) => {
        const d = dirs[i] ?? (i % 2 ? -1 : 1);
        if (t >= tb - 0.075 && t < tb) { const u = ease.inQuad((t - (tb - 0.075)) / 0.075); dx -= d * 1500 * u; r -= d * 0.12 * CALM * u; }
        if (t >= tb && t < tb + 0.12) { const u = 1 - ease.outCubic((t - tb) / 0.12); dx += d * 1500 * u; r += d * 0.12 * CALM * u; }
      });
      return { dx, r };
    }
    /** Set the canvas transform: logical 1920x1080, camera centred on (x, y) at zoom z and roll r, plus a whip offset. */
    export function applyCam(c: Ctx, cam: Cam, whip = { dx: 0, r: 0 }, W = 1920, H = 1080) {
      c.setTransform(1, 0, 0, 1, 0, 0);
      c.translate(W / 2 + whip.dx, H / 2); c.rotate(cam.r + whip.r); c.scale(cam.z, cam.z); c.translate(-cam.x, -cam.y);
    }
    /** 2-frame solid colour on each cut (softened by CALM). */
    export function cutFlash(c: Ctx, t: number, cuts: [number, string][], W = 1920, H = 1080) {
      for (const [tc, col] of cuts) if (t >= tc && t < tc + 2 / 60) {
        c.save(); c.setTransform(1, 0, 0, 1, 0, 0); c.globalAlpha = CALM; c.fillStyle = col; c.fillRect(0, 0, W, H); c.restore();
      }
    }
    
  • skills/lyric-music-video/assets/scenes/credits.ts4.4 KB48dc331ac64aupstream ↗
    // End card after the music: who made it. Example from the pink-boots video: the singer's sticker + the X and
    // Telegram handles (lib/brand.ts) slapped onto a notebook page. Replace the art paths with your own world's art,
    // keep the structure: 3 s, handles slap in one after another, no music (render.ts pads the audio with silence).
    import * as THREE from 'three';
    import { Scene, type Frame } from '../engine/scene';
    import { Layer2D, W, H, clearRT } from '../engine/gl';
    import { fontW } from '../engine/type';
    import { HEX, LIN } from '../engine/palette';
    import { ease, mulberry32, prog } from '../engine/util';
    import { art, loadArt, drawArt, sticker, slap, SC } from '../lib/kit';
    import { xBadge, tgBadge, X_HANDLE, TG_HANDLE } from '../lib/brand';
    
    export default class Credits extends Scene {
      L = new Layer2D();
    
      override async init() {
        await loadArt(['scrap/notebook', 'girl/scrap-kiss', 'scrap/washi-gingham', 'scrap/washi-stars', 'scrap/st-heart-glitter', 'scrap/st-star-yellow']);
      }
    
      /** A handle row: badge + text, slapped in at t0; returns nothing, draws around (x, y) = left-middle. */
      private row(c: CanvasRenderingContext2D, t: number, t0: number, x: number, y: number, badge: 'x' | 'tg', text: string, size: number, rot: number) {
        const s = slap(t, t0, 1, rot);
        if (!s) return;
        c.save(); c.translate(x, y); c.rotate(s.r + rot); c.scale(s.k, s.k);
        const b = size * 1.25;
        c.font = fontW('Inter', size, 900);
        const tw = c.measureText(text).width;
        // white sticker backing with a lifted shadow
        c.shadowColor = 'rgba(40,10,40,0.25)'; c.shadowBlur = 24; c.shadowOffsetY = 10 + 20 * (1 - s.a);
        c.fillStyle = '#fff'; c.beginPath(); c.roundRect(-28, -b / 2 - 24, b + 36 + tw + 56, b + 48, 34); c.fill();
        c.shadowColor = 'transparent';
        if (badge === 'x') xBadge(c, 0, -b / 2, b); else tgBadge(c, 0, -b / 2, b);
        c.fillStyle = badge === 'x' ? HEX.line : '#1C8FCF'; c.textBaseline = 'middle'; c.textAlign = 'left';
        c.fillText(text, b + 36, 4);
        c.restore();
      }
    
      override render(f: Frame, out: THREE.WebGLRenderTarget) {
        const { renderer, comp } = this.ctx;
        const t = f.lt, L = this.L, c = L.ctx;
        L.clear();
        const z = 1.0 + 0.035 * ease.outCubic(prog(t, 0, 3.2)) + 0.03 * Math.pow(0.5, t / 0.08);
        c.translate(W / 2, H / 2); c.scale(z, z); c.rotate(-0.01 + 0.006 * Math.sin(t * 2)); c.translate(-W / 2, -H / 2);
    
        const nb = art('scrap/notebook');
        if (nb) drawArt(c, nb, W / 2, H / 2, H * 1.25); else { c.fillStyle = '#FFFDF6'; c.fillRect(-300, -300, W + 600, H + 600); }
    
        // her, blowing a kiss
        sticker(c, art('girl/scrap-kiss'), 470, 590, 900, t, 0.02, { rot: -0.05, big: 0.7 });
    
        // "made by" in gel pen, then the two handles
        const mb = slap(t, 0.12, 0.6, -0.04);
        if (mb) {
          c.save(); c.translate(900, 300); c.rotate(-0.05 + mb.r); c.scale(mb.k, mb.k);
          c.font = fontW('Caveat', 92, 700); c.fillStyle = HEX.pink; c.textBaseline = 'alphabetic';
          c.fillText('made with ♥ by', 0, 0);
          c.restore();
        }
        this.row(c, t, 0.3, 910, 460, 'x', X_HANDLE, 92, -0.02);
        this.row(c, t, 0.62, 910, 680, 'tg', TG_HANDLE, 74, 0.025);
        SC.tape(c, art('scrap/washi-gingham'), 900, 395, 220, -0.6, t, 0.36);
        SC.tape(c, art('scrap/washi-stars'), 1700, 400, 200, 0.55, t, 0.68);
    
        // small stickers and the credit line
        sticker(c, art('scrap/st-heart-glitter'), 1760, 250, 150, t, 0.85, { rot: 0.2, big: 0.8 });
        sticker(c, art('scrap/st-star-yellow'), 790, 960, 110, t, 0.95, { rot: -0.3, big: 0.8 });
        if (t > 1.0) {
          c.save(); c.globalAlpha = Math.min(1, (t - 1.0) * 3);
          c.font = fontW('Inter', 26, 600); c.fillStyle = 'rgba(21,19,26,0.6)'; c.textBaseline = 'alphabetic';
          c.fillText('“Pink Boots, Export Doors” · song + video', 912, 870);
          c.restore();
        }
        // hearts drifting up
        for (let i = 0; i < 14; i++) {
          const R = mulberry32(i * 7 + 1), t0 = 0.4 + R() * 1.6;
          if (t < t0) continue;
          const u = t - t0, x = 760 + R() * 1100 + 30 * Math.sin(u * 3 + i), y = 1100 - u * (220 + 160 * R());
          c.save(); c.globalAlpha = Math.max(0, 1 - u / 2.2); c.translate(x, y); c.rotate(0.3 * Math.sin(u * 2 + i));
          c.fillStyle = [HEX.pink, HEX.lilac, HEX.cobalt][i % 3]!; c.font = fontW('Inter', 34 + 26 * R(), 900); c.fillText('♥', 0, 0);
          c.restore();
        }
    
        clearRT(renderer, out, LIN.paper);
        comp.draw(renderer, L.upload(), out);
        return { grain: 0.02, flash: t < 0.034 ? 1 : 0 };
      }
    }
    
  • skills/lyric-music-video/assets/scenes/synctest.ts2.2 KBb3bedd62db79upstream ↗
    // Sync test: white page, the current line big, each word pops on its sung start.
    import * as THREE from 'three';
    import { Scene, type Frame } from '../engine/scene';
    import { Layer2D, W, H, clearRT } from '../engine/gl';
    import { Lyrics, LYRIC_LEAD } from '../engine/lyrics';
    import { F, font } from '../engine/type';
    import { rgba, LIN } from '../engine/palette';
    import { ease, clamp } from '../engine/util';
    
    export default class SyncTest extends Scene {
      text = new Layer2D();
    
      render(f: Frame, out: THREE.WebGLRenderTarget) {
        const { renderer, comp, lyrics, audio } = this.ctx;
        clearRT(renderer, out, LIN.paper);
        const c = this.text.ctx;
        this.text.clear();
        const line = lyrics.lineAt(f.t) ?? lyrics.lastLine(f.t);
        if (line) {
          const size = 96;
          c.font = font(F.pop(100, 800), size);
          c.textBaseline = 'alphabetic';
          const widths = line.words.map((w) => c.measureText(w.w + ' ').width);
          const total = widths.reduce((a, b) => a + b, 0);
          let x = Math.max(96, (W - total) / 2);
          for (const [i, w] of line.words.entries()) {
            const p = Lyrics.wordProgress(w, f.t);
            const on = f.t >= w.start;
            const pop = on ? 1 + 0.25 * Math.exp(-(f.t - w.start) * 14) : 1;
            c.save();
            c.translate(x + widths[i]! / 2, H / 2);
            c.scale(pop, pop);
            c.fillStyle = on ? rgba('pink') : rgba('line', 0.18);
            c.textAlign = 'center';
            c.fillText(w.w, 0, 0);
            c.restore();
            x += widths[i]!;
            void p;
          }
        }
        // beat ticks + section name
        const sec = audio.sections.find((s) => f.t >= s.start && f.t < s.end);
        c.font = font(F.mono(500), 22);
        c.fillStyle = rgba('line', 0.6);
        c.textAlign = 'left';
        c.fillText(`${sec?.name ?? ''}  bar ${Math.floor(f.bar)}  beat ${(Math.floor(f.beat) % 4 + 4) % 4 + 1}   lead ${Math.round(LYRIC_LEAD * 1000)} ms`, 96, H - 96);
        const k = clamp(1 - f.beatPhase * 3, 0, 1);
        c.fillStyle = Math.floor(f.beat) % 4 === 3 ? rgba('cobalt', k) : rgba('lemon', k);
        c.beginPath(); c.arc(W - 140, H - 104, 22 + 10 * ease.outCubic(k), 0, Math.PI * 2); c.fill();
        comp.draw(renderer, this.text.upload(), out);
        return { hud: 0 };
      }
    }
    
  • skills/lyric-music-video/examples/pink-boots/chorus.ts51 KBf65cf85f81a0upstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

  • skills/lyric-music-video/examples/pink-boots/timeline.ts2.3 KB7044fa7aa917upstream ↗
    // The edit: which scene plays when. Boundaries come from the aligned lyrics and the
    // section map (data/lyrics.json, data/audio.json); never hard-code times here.
    import type { TimelineEntry } from './engine/engine';
    import type { SceneClass } from './engine/scene';
    import type { Lyrics } from './engine/lyrics';
    import type { AudioData } from './engine/audio';
    
    const modules = import.meta.glob<{ default: SceneClass }>('./scenes/*.ts');
    const scene = (name: string) => () => {
      const m = modules[`./scenes/${name}.ts`];
      return m ? m() : Promise.reject(new Error(`scene module not found: scenes/${name}.ts`));
    };
    
    export function makeTimeline(ly: Lyrics, au: AudioData): TimelineEntry[] {
      const E = (id: string, file: string, start: number, end: number, extra: Partial<TimelineEntry> = {}): TimelineEntry =>
        ({ id, load: scene(file), start, end, ...extra });
      /** Cut on the last beat at/before the first word of the matching line (never after the word). */
      const cut = (q: string, nth = 0, tol = 0.02) => {
        const s = ly.get(q, nth).words[0]!.start;
        return au.timeOfBeat(Math.floor(au.beatAt(s + tol)));
      };
      // The edit. Section scenes own their lines; boundaries sit on beats right before the first sung word.
      const chorusIn = (n: number) => cut('My bot, my bot, better', n) - 0.45; // one beat of lead-in (the call / the drop)
      const future = (n: number) => ly.get('You want the future', n).start;
      const b = {
        pre1: cut('Export controls'),
        c1: chorusIn(0), t1: future(0), v2: cut('DeepSeek'),
        c2: chorusIn(1), t2: future(1), bridge: cut('If Beijing'),
        c3: chorusIn(2), t3: future(2), outro: cut('is this lip gloss'),
      };
      return [
        E('verse1', 'verse1', 0, b.pre1),
        E('pre1', 'pre1', b.pre1, b.c1),
        E('chorus1', 'chorus', b.c1, b.t1, { params: { n: 1 } }),
        E('tail1', 'chorus-tail', b.t1, b.v2, { params: { n: 1 } }),
        E('verse2', 'verse2', b.v2, b.c2),
        E('chorus2', 'chorus', b.c2, b.t2, { params: { n: 2 } }),
        E('tail2', 'chorus-tail', b.t2, b.bridge, { params: { n: 2 } }),
        E('bridge', 'bridge', b.bridge, b.c3),
        E('chorus3', 'chorus', b.c3, b.t3, { params: { n: 3 } }),
        E('tail3', 'chorus-tail', b.t3, b.outro, { params: { n: 3 } }),
        E('outro', 'outro', b.outro, au.duration),
        E('credits', 'credits', au.duration, au.duration + 3.2), // end card after the music: authorship
      ];
    }
    

Plain-text copy, no login: /skill-bundles/alesha-pro-tools-skills-lyric-music-video.md

// REPO STATS

700 stars
0 open issues
Last commit: 1mo ago