avenox-graphics

name	avenox-graphics
description	Avenox Studio — produce brand-locked motion graphics with HyperFrames and composite them onto a cut video. Use when making cutaway/overlay graphics: title cards, diagrams, data-viz, loops, lower-thirds, outro. Proven cutaway + composite recipe with gotchas. Triggers: "make graphics", "add an animation", "motion graphic", "intro/outro card", "data-viz". Part of avenox-video step 3.

Graphics — HyperFrames cutaways → composite

Brand source of truth: brand/frame.md. Define it once, then never deviate inside a job. (Reference implementation: warm paper #f3efe4, ink #1b1712, one golden accent #e8b23a, a serif display face + a grotesk UI face, plus a mascot. Deliberately anti-AI-slop — no neon, no gradient mesh, no glassmorphism, no 3D gloss.)

Pipeline

1. Project: cd "$STUDIO_JOBS/<job>/graphics" && npx hyperframes init gfx (one-time; installs a headless chromium — slow first run, background it).
2. One composition per beat = a standalone <name>.html. Reuse the brand template below. Each is full-screen 1920×1080 — a cutaway (opaque, replaces footage) or a transparent overlay.
3. Render serially (render reads index.html):

   for f in *.html; do
     n="${f%.html}"; [ "$n" = index ] && continue
     cp "$f" index.html
     npx hyperframes render -f 60 --resolution landscape -o "renders/$n.mp4"
   done
   

4. Composite all cutaways onto the cut via ffmpeg, each at its timecode.

Composition contract (HyperFrames)

• #root with data-composition-id="main" data-start data-duration data-width data-height.
• Every timed element: class="clip" + data-start data-duration data-track-index.
• ONE paused GSAP timeline registered: window.__timelines["main"] = gsap.timeline({paused:true}). HyperFrames seeks it per frame, so everything must be seek-safe: use fromTo/set, and position every tween on tl.
• Deterministic only — no Date.now(), no Math.random(), no runtime fetch. Web fonts via <link> are fine.
• Render flags: -f 60, --resolution landscape (1920×1080), --format mp4 (use mov/webm for alpha overlays).

Brand template

• Fonts via a single <link> to your webfont provider — renders fine in headless chrome.
• html,body{background:<paper>} + a paper div, radial vignette, and an SVG feTurbulence grain at opacity .05 / mix-blend-mode: multiply. Fix the turbulence seed or the grain is nondeterministic and frames will flicker.
• Kicker (grotesk, tracked caps) → title (serif, heavy) → accent underline (scaleX wipe) → mascot (assets/mascot.png).

Mascot transparency (keying a mascot off an ivory plate)

HSV key — saturated body colors and black ink survive, low-saturation cream becomes alpha:

import numpy as np
from PIL import Image
im = Image.open(src).convert('RGB')
a  = np.asarray(im) / 255.
mx = a.max(2)
s  = np.where(mx > 1e-6, (mx - a.min(2)) / np.maximum(mx, 1e-6), 0)
bg = (s < 0.22) & (mx > 0.60)
out = np.dstack([np.asarray(im), np.where(bg, 0, 255).astype('uint8')])
img = Image.fromarray(out, 'RGBA')
img.crop(img.getbbox()).save(dst)

Tune 0.22 / 0.60 to your plate. Too aggressive and you eat highlights on the subject.

Compositing cutaways onto the cut

Per cutaway input: [i:v]setpts=PTS+{START}/TB,format=yuv420p[ovi], then [prev][ovi]overlay=enable='between(t,{START},{END})':eof_action=pass[vi].

Keep the base audio (-map 0:a). Hardware encode with h264_videotoolbox -b:v 18M.

Gotchas

• npx/hyperframes need the SSL cert fix: export SSL_CERT_FILE=$(python3 -c 'import certifi;print(certifi.where())') (and REQUESTS_CA_BUNDLE) or downloads fail.
• hyperframes init first run is slow (chromium download) — background it.
• Blended is the better default. Prefer animated overlays on the live screen (lower-thirds, kinetic titles, callouts — rendered transparent as .mov/.webm with --format mov) for most beats. Reserve full-screen cutaways for the intro, outro, and genuine dead zones where the screen shows nothing useful. Replacing a screen that has useful content loses information — overlay it instead.
• Placement: grab the frame at the target timecode (ffmpeg -ss), look at it, and place graphics in empty safe zones — never over a face or important UI. Optional: HyperFrames remove-background matting to sit graphics behind the subject.
• Don't over-animate. Restraint reads as premium; constant motion reads as a template.
• Render time scales with frame count — keep cutaways short (5–26s). Long sustained pieces get expensive fast.