Skip to content

AbubakrChan/product-launch-motion / legacy

product-launch-motion-v1

Verified

Legacy v1 (voiceover-led, GSAP + HyperFrames). Use when making, directing or rescuing a product launch video, promo, teaser, demo reel, sizzle, feature-announcement film or animated product explainer built from code — and when an existing one looks basic, reads as a slideshow, has reveals that miss the voiceover, an invisible cursor, an inaudible sound effect, a clipped or too-quiet mix, or every video coming out looking the same. Covers SaaS, apps, hardware, e-commerce, dev tools, services. Keywords include motion design, storyboard, voiceover sync, kinetic typography, GSAP, HyperFrames, Remotion, film grain, LUFS, ffmpeg.

FileKindSize
CASE-STUDY.mdmarkdown12.8 KB
SKILL.mdskill md17.4 KB
assets/BRIEF.mdmarkdown3.0 KB
assets/STORYBOARD.mdmarkdown2.7 KB
assets/cues.example.jsonconfig3.2 KB
assets/film.example.jsonconfig3.4 KB
assets/frame-skeleton.htmlother17.3 KB
evals/BASELINE.mdmarkdown7.5 KB
evals/evals.jsonconfig5.3 KB
film-preview.webpbinary975.7 KB
references/01-renderer-contract.mdmarkdown14.8 KB
references/02-story-and-truth.mdmarkdown20.7 KB
references/03-word-locked-sync.mdmarkdown9.2 KB
references/04-motion-grammar.mdmarkdown19.6 KB
references/05-camera-3d-cursor.mdmarkdown12.4 KB
references/06-look-and-grade.mdmarkdown18.3 KB
references/07-sound-and-master.mdmarkdown10.3 KB
references/08-qa-and-direction.mdmarkdown11.7 KB
references/09-shot-catalog.mdmarkdown38.9 KB
references/10-traps.mdmarkdown14.6 KB
references/11-creative-direction.mdmarkdown17.4 KB
references/12-deliverables.mdmarkdown7.1 KB
scripts/assemble.mjsexecutablescript9.3 KB
scripts/level-sfx.mjsexecutablescript8.5 KB
scripts/master.shexecutablescript3.8 KB
scripts/transitions.mjsexecutablescript7.2 KB
scripts/verify-cue.shexecutablescript3.4 KB
scripts/wire-audio.mjsexecutablescript5.3 KB
scripts/wire-grade.mjsexecutablescript9.7 KB
scripts/word-timings.mjsexecutablescript4.6 KB
still-1.jpgbinary16.9 KB

scripts/assemble.mjs

View on GitHub
#!/usr/bin/env node
// assemble.mjs — write index.html from a manifest and the measured voiceover.
//
// This script exists to enforce one law in code rather than in prose: a frame's length is
// MEASURED from its narration, never estimated. Give it the VO file and it does the
// arithmetic that references/03-word-locked-sync.md describes:
//
//   hold           = measured VO length + a pad, so the shot does not cut on the last syllable
//   frame.duration = hold + the outgoing transition's duration
//   next.start     = this.start + hold                        (NOT + duration)
//
// The surplus is the overlap the transition lives in. Get this wrong by hand once and every
// downstream cue is wrong by the same amount, silently, for the rest of the film.
//
// The index is GENERATED. Anything hand-added to it dies on the next run — which is exactly
// why wire-audio, wire-grade and transitions all write into their own marked blocks and are
// safe to re-run. After any edit to film.json, re-run the whole chain in order:
//
//   node scripts/assemble.mjs
//   node scripts/transitions.mjs
//   node scripts/wire-audio.mjs
//   node scripts/wire-grade.mjs
//
// film.json:
//   {
//     "width": 1920, "height": 1080,
//     "background": "#FAFAFB",              // the film's base colour, behind every frame
//     "gsap": "vendor/gsap.min.js",         // vendored, not a CDN — renders must be offline-safe
//     "pad": 0.25,                          // breath after the last word; per-frame overridable
//     "frames": [
//       { "id": "01-hook",  "src": "compositions/frames/01-hook.html",
//         "vo": "assets/voice/01.wav",
//         "out": { "type": "dissolve", "duration": 0.5 } },
//       { "id": "02-pain",  "src": "…", "vo": "…", "pad": 0.6,          // land this beat
//         "out": { "type": "push", "duration": 0.5 } },
//       { "id": "03-title", "src": "…", "duration": 2.4 }        // no VO: state it explicitly
//     ]
//   }
//
// usage:
//   node scripts/assemble.mjs [--manifest film.json] [--out index.html] [--dry]

import { readFileSync, writeFileSync, existsSync } from "node:fs";
import { spawnSync } from "node:child_process";

const argv = process.argv.slice(2);
// `--help` prints the header comment above. One source of truth for the usage text, and it
// exits 0 — a --help that exits non-zero breaks every Makefile and CI job that wraps it.
if (argv.includes("--help") || argv.includes("-h")) {
  const doc = [];
  for (const line of readFileSync(new URL(import.meta.url), "utf8").split("\n").slice(1)) {
    if (!line.startsWith("//")) break;
    doc.push(line.replace(/^\/\/ ?/, ""));
  }
  console.log(doc.join("\n").trim());
  process.exit(0);
}

const flag = (name, fallback) => {
  const i = argv.indexOf(`--${name}`);
  return i === -1 ? fallback : argv[i + 1];
};

const MANIFEST = flag("manifest", "film.json");
const OUT = flag("out", "index.html");
const dry = argv.includes("--dry");

if (!existsSync(MANIFEST)) {
  console.error(`no ${MANIFEST} — copy assets/film.example.json and edit it,\n` +
    `or run: node scripts/assemble.mjs --help`);
  process.exit(1);
}
const film = JSON.parse(readFileSync(MANIFEST, "utf8"));

const W = film.width ?? 1920;
const H = film.height ?? 1080;
const BG = film.background ?? "#000";
const GSAP = film.gsap ?? "vendor/gsap.min.js";
const frames = film.frames ?? [];
if (!frames.length) {
  console.error(`${MANIFEST} has no frames`);
  process.exit(1);
}

// Trailing zeros are noise in a diff and make every re-run look like a change.
const t = (n) => String(Number(n.toFixed(3)));

/** Measured length of an audio file, in seconds. */
function probeDuration(file) {
  if (!existsSync(file)) throw new Error(`missing voiceover: ${file}`);
  const r = spawnSync(
    "ffprobe",
    ["-v", "error", "-show_entries", "format=duration", "-of", "csv=p=0", file],
    { encoding: "utf8" },
  );
  if (r.error) throw new Error(`ffprobe not found — install ffmpeg`);
  const secs = Number((r.stdout || "").trim());
  if (!Number.isFinite(secs) || secs <= 0) {
    throw new Error(`ffprobe could not read a duration from ${file}: ${(r.stderr || "").trim()}`);
  }
  return secs;
}

// ── the timing pass ────────────────────────────────────────────────────────────────────
let cursor = 0;
const timed = frames.map((f, i) => {
  if (!f.id) throw new Error(`frame ${i} has no id`);
  if (!f.src) throw new Error(`frame ${f.id} has no src`);

  // A frame is as long as what is SAID over it, plus a breath. `duration` is the escape
  // hatch for a frame with no narration (a title card, a music-only film) — and it has to
  // be stated, because an unmeasured guess is the failure this script exists to prevent.
  //
  // The pad is not slack. A shot that cuts on the last syllable reads as rushed even when
  // every tween in it was perfect, because the viewer is still reading the frame when it
  // leaves. ~0.25s is a breath; raise it on a beat you want to land (the turn, the end
  // card) and the film gains rhythm rather than length.
  const measured = f.vo ? probeDuration(f.vo) : f.duration;
  if (!Number.isFinite(measured)) {
    throw new Error(`frame ${f.id} has neither "vo" nor an explicit "duration"`);
  }
  const pad = f.vo ? (f.pad ?? film.pad ?? 0.25) : 0;
  const hold = measured + pad;

  const overlap = i === frames.length - 1 ? 0 : (f.out?.duration ?? 0.5);
  const entry = {
    ...f,
    index: i,
    start: cursor,
    measured, // what is said
    hold, // what is heard, plus the breath after it
    duration: hold + overlap, // what is seen — longer again, by the transition
    overlap,
    pad,
  };
  cursor += hold; // the next frame starts when the narration ends, not when the clip does
  return entry;
});

const TOTAL = timed[timed.length - 1].start + timed[timed.length - 1].duration;

// ── emit ───────────────────────────────────────────────────────────────────────────────
const sceneEls = timed
  .map((f) => {
    const scene = `      <div
        id="el-${f.id}"
        class="scene"
        data-composition-id="${f.id}"
        data-composition-src="${f.src}"
        data-start="${t(f.start)}"
        data-duration="${t(f.duration)}"
        data-track-index="${f.index}"
      ></div>`;
    // The VO clip is the MEASURED file length — not the frame's `hold` and certainly not its
    // `duration`. The pad and the transition overlap are picture, not speech; stretching the
    // audio clip over them is how a narration ends up bleeding into the next frame's first
    // word on a renderer that loops or holds the tail.
    const voice = f.vo
      ? `
      <audio
        id="el-${f.id}-voice"
        src="${f.vo}"
        data-start="${t(f.start)}"
        data-duration="${t(f.measured)}"
        data-track-index="10"
        data-volume="${f.voVolume ?? 1}"
      ></audio>`
      : "";
    return scene + voice;
  })
  .join("\n\n");

const html = `<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=${W}, height=${H}" />
    <script src="${GSAP}"></script>
    <style>
      * { margin: 0; padding: 0; box-sizing: border-box; }
      html, body {
        width: ${W}px;
        height: ${H}px;
        overflow: hidden;
        background: #000;
      }
      #root {
        position: relative;
        width: ${W}px;
        height: ${H}px;
        overflow: hidden;
        background: ${BG};
      }
      .scene { position: absolute; inset: 0; width: 100%; height: 100%; }
    </style>
  </head>
  <body>
    <div
      id="root"
      data-composition-id="main"
      data-start="0"
      data-duration="${t(TOTAL)}"
      data-width="${W}"
      data-height="${H}"
    >
${sceneEls}
    </div>

    <script>
      window.__timelines = window.__timelines || {};
      window.__timelines["main"] = gsap.timeline({ paused: true });
      (function () {
        var tl = window.__timelines["main"];
        /* transitions:start */
        /* transitions:end */
        /* Full-span anchor: without it the root timeline is only as long as its last tween,
           and the renderer takes THAT as the film's length — truncating the final hold. */
        tl.to({}, { duration: ${t(TOTAL)} }, 0);
      })();
    </script>
  </body>
</html>
`;

const overrun = timed.filter((f) => f.overlap > f.hold);
for (const f of overrun) {
  console.warn(
    `  ! ${f.id}: transition ${t(f.overlap)}s is longer than its ${t(f.hold)}s of narration —` +
      ` the shot is over before it has landed.`,
  );
}

console.log(`assemble: ${timed.length} frames · ${t(TOTAL)}s`);
for (const f of timed) {
  console.log(
    `  ${String(f.index).padStart(2)} ${f.id.padEnd(22)} ` +
      `start ${t(f.start).padStart(6)}  vo ${t(f.measured).padStart(5)}` +
      ` +pad ${t(f.pad).padStart(4)}  hold ${t(f.hold).padStart(5)}  ` +
      `dur ${t(f.duration).padStart(5)}`,
  );
}
if (dry) process.exit(0);
writeFileSync(OUT, html);
console.log(`✓ wrote ${OUT}`);
console.log(`  now: transitions.mjs → wire-audio.mjs → wire-grade.mjs (this file is generated;`);
console.log(`  anything you hand-add to it is gone on the next assemble)`);
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall