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/level-sfx.mjs

View on GitHub
#!/usr/bin/env node
// level-sfx.mjs — fix the quiet-source problem.
//
// A cue's volume cannot rescue a quiet source file. This is arithmetic, not mixing taste:
// summing a -38 dB signal into a -17 dB narration bed changes the total by hundredths of a
// decibel. In the film this skill came from, raising a typing cue from 0.35 to 0.85 moved
// the delivered mix by 0.1 dB — measured. There was no cue volume that would have worked.
//
// So: level the ASSET. This trims it to the part you need, gains it, limits the peaks so
// transients survive without clipping, and prints before/after so the decision is on the
// record rather than in someone's memory.
//
// usage:
//   node scripts/level-sfx.mjs audio/sfx/keyboard-typing.mp3 \
//     [--out audio/sfx/keyboard-typing-loud.mp3] [--gain 22] [--trim 1.1] [--fade 0.15]
//     [--bed -16.7] [--from 0] [--keep-head]
//
//   --bed        the narration level in the window this cue plays under. Given it, the
//                script reports whether the levelled asset will actually be audible.
//   --from       explicit start offset in the source, in seconds.
//   --keep-head  do NOT auto-trim leading near-silence (see below).
//
// HEAD SILENCE — the trap this script exists to also prevent. Field-recorded SFX usually
// open with room tone before the first hit. Cut from 0 and you have levelled silence: the
// asset is loud, the measurement passes, and the cue still lands late because its first
// transient is 400ms in. That defect shipped in a real film and survived a window-peak
// check, because the window's PEAK was fine — the front of it was empty. So by default
// this finds the first real transient and starts there.

import { execFileSync, spawnSync } from "node:child_process";
import { readFileSync, existsSync } from "node:fs";
import { basename, dirname, extname, join } from "node:path";

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 input = argv.find((a) => !a.startsWith("--"));
const flag = (name, fallback) => {
  const i = argv.indexOf(`--${name}`);
  return i === -1 ? fallback : argv[i + 1];
};
const num = (name, fallback) => {
  const v = flag(name, null);
  return v === null ? fallback : Number(v);
};

if (!input || !existsSync(input)) {
  console.error("usage: node scripts/level-sfx.mjs <input.mp3> [--out …] [--gain 22] [--trim 1.1] [--fade 0.15] [--bed -16.7]");
  process.exit(1);
}

const ext = extname(input);
const defaultOut = join(dirname(input), `${basename(input, ext)}-loud${ext}`);
const output = flag("out", defaultOut);
const gain = num("gain", 22);
const trim = num("trim", 1.1);
const fade = num("fade", 0.15);
const bed = flag("bed", null) === null ? null : num("bed", null);

// ffmpeg writes volumedetect's report to STDERR, not stdout, and still exits 0 — so
// reading only stdout silently yields NaN rather than an error. Read both streams.
function measure(file, extra = []) {
  const r = spawnSync(
    "ffmpeg",
    ["-hide_banner", ...extra, "-i", file, "-af", "volumedetect", "-f", "null", "/dev/null"],
    { encoding: "utf8" },
  );
  const text = `${r.stdout ?? ""}${r.stderr ?? ""}`;
  const mean = Number(text.match(/mean_volume:\s*(-?[\d.]+) dB/)?.[1] ?? NaN);
  const max = Number(text.match(/max_volume:\s*(-?[\d.]+) dB/)?.[1] ?? NaN);
  if (!Number.isFinite(mean)) {
    throw new Error(`could not measure ${file} — is ffmpeg installed and the file readable?`);
  }
  return { mean, max };
}

const before = measure(input);

/**
 * Find the first real transient: scan the source in 50ms slices and return the start of
 * the first slice whose peak is within `window` dB of the file's overall peak.
 * A cue must START on a hit, not on the room tone that preceded it in the field.
 */
function firstTransient(file, overallPeak, window = 12, step = 0.05, limit = 3) {
  for (let t = 0; t < limit; t += step) {
    const r = spawnSync(
      "ffmpeg",
      ["-hide_banner", "-ss", t.toFixed(3), "-t", String(step), "-i", file,
       "-af", "volumedetect", "-f", "null", "/dev/null"],
      { encoding: "utf8" },
    );
    const text = `${r.stdout ?? ""}${r.stderr ?? ""}`;
    const max = Number(text.match(/max_volume:\s*(-?[\d.]+) dB/)?.[1] ?? NaN);
    if (Number.isFinite(max) && max >= overallPeak - window) return t;
  }
  return 0;
}

const explicitFrom = flag("from", null);
const keepHead = argv.includes("--keep-head");
let from = explicitFrom === null ? 0 : Number(explicitFrom);
if (explicitFrom === null && !keepHead) {
  from = firstTransient(input, before.max);
  if (from > 0) {
    console.log(`head: first transient at ${from.toFixed(2)}s — trimming the room tone`);
    console.log(`      (--keep-head to disable; a silent head makes the cue land late)`);
  }
}

const filter =
  `volume=${gain}dB,` +
  `alimiter=level_out=0.9:limit=0.9,` +
  `afade=t=out:st=${Math.max(0, trim - fade).toFixed(3)}:d=${fade}`;

execFileSync(
  "ffmpeg",
  ["-hide_banner", "-y", "-ss", String(from), "-t", String(trim), "-i", input,
   "-af", filter, "-c:a", "libmp3lame", "-b:a", "192k", output],
  { stdio: ["ignore", "ignore", "pipe"] },
);

const after = measure(output);
// prove the OUTPUT starts on a hit: its first 100ms should be near its own peak
const headPeak = measure(output, ["-ss", "0", "-t", "0.1"]).max;

const fmt = (v) => (Number.isFinite(v) ? `${v.toFixed(1)} dB` : "?");
console.log(`in   ${input}`);
console.log(`     mean ${fmt(before.mean)}   peak ${fmt(before.max)}`);
console.log(`out  ${output}`);
console.log(`     mean ${fmt(after.mean)}   peak ${fmt(after.max)}   (+${(after.mean - before.mean).toFixed(1)} dB mean)`);
console.log(`     first 100ms peak ${fmt(headPeak)}   ${headPeak >= after.max - 12 ? "✓ starts on a hit" : "✗ SILENT HEAD — this cue will land late"}`);

if (bed !== null) {
  // Compare LIKE WITH LIKE. An earlier version of this script compared the asset's PEAK to
  // the bed's MEAN, which passes almost anything: a room recording with a 28 dB crest
  // factor scored "audible" at a volume that measurably moved the delivered mix by 0.1 dB.
  // `--bed` is read as the bed's mean; its peaks run roughly 8-12 dB above that, so peak
  // comparisons use an estimated bed peak.
  const BED_CREST = 10; // dB, typical narration mean→peak
  const bedPeak = bed + BED_CREST;
  console.log(`\nagainst a narration bed of mean ${bed} dB (peak ≈ ${bedPeak.toFixed(1)} dB):`);
  console.log(`  vol    transient    vs bed peak    mean    vs bed mean`);
  for (const v of [0.35, 0.45, 0.55, 0.7]) {
    const g = 20 * Math.log10(v);
    const peakAt = after.max + g;
    const meanAt = after.mean + g;
    console.log(
      `  ${String(v).padEnd(6)} ${peakAt.toFixed(1).padStart(6)} dB   ` +
        `${(peakAt - bedPeak >= 0 ? "+" : "") + (peakAt - bedPeak).toFixed(1).padStart(6)} dB   ` +
        `${meanAt.toFixed(1).padStart(6)} dB   ` +
        `${(meanAt - bed >= 0 ? "+" : "") + (meanAt - bed).toFixed(1).padStart(6)} dB`,
    );
  }
  console.log(`
Rules of thumb, NOT a verdict — this script deliberately does not tell you "audible":
  · a percussive cue reads as an event when its transients sit at or above the bed's peaks
  · if its MEAN is more than ~20 dB under the bed's mean, it will not register at all,
    however healthy the peaks look — that combination is what a quiet room recording is
  · masking is not predictable from levels alone, and any script claiming otherwise is
    guessing. The reference film's cue passed a naive peak check and moved the delivered
    mix by 0.1 dB.

The only proof is the delivered file. After you render:
  ./scripts/verify-cue.sh <master.mp4> <cue start> <cue dur> [previous-master.mp4]
and read the ENVELOPE, not the window.

Measure --bed on the ISOLATED narration stem, not the mastered film: cue volumes are
applied pre-master, so a post-master figure compares the wrong things (in the reference
film the stem was -21.3 dB and the mastered window -16.7 dB — a 4.6 dB error in exactly
the direction that flatters the cue).`);
}

console.log(`\nnext: cue the -loud variant, re-render, then PROVE it landed:`);
console.log(`  ./scripts/verify-cue.sh <master.mp4> <cue start> <cue dur> [previous-master.mp4]`);
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