{
  "$schema": "../../schema.json",
  "version": "1.0.0",
  "license": "MIT",
  "id": "kinetic-captions",
  "type": "block",
  "title": "Kinetic captions",
  "summary": "Captions timed to a voice: the phrase sits dim, each word lights as it is said, key words land bigger, phrases change on a clean cut.",
  "tags": [
    "block",
    "text",
    "captions",
    "subtitles",
    "voice",
    "social"
  ],
  "params": [
    {
      "name": "background",
      "type": "string",
      "default": "",
      "description": "a background id from the registry; empty uses the brand's first",
      "group": "advanced",
      "control": "select"
    },
    {
      "name": "script",
      "type": "string",
      "default": "Your agent writes the brief. You pick the look. It renders every frame. That is paper-motion.",
      "description": "script",
      "group": "main",
      "control": "text"
    },
    {
      "name": "perPage",
      "type": "number",
      "default": 24,
      "description": "most characters on one page of captions",
      "group": "main"
    },
    {
      "name": "format",
      "type": "enum",
      "default": "1080x1920",
      "options": [
        "1920x1080",
        "1080x1920",
        "1080x1080"
      ],
      "description": "output size; the layout recomposes for each",
      "group": "main",
      "control": "segmented"
    }
  ],
  "install": {
    "kind": "scene"
  },
  "files": [
    {
      "path": "pieces/kinetic-captions/scene.html",
      "content": "<!doctype html>\n<html>\n<head>\n<meta charset=\"utf-8\">\n<title>kinetic-captions</title>\n<!--\n  Text · kinetic captions (6.6 s, vertical). Captions timed to a voice, a few words at a time: each word pops in as it\n  is spoken, the word being said sits on an accent pill that slides from word to word, key words land bigger, and the\n  next phrase replaces it on a clean cut. Feed it word timings (`words`: [{ w, t }], as the engine's alignment\n  writes them) and the voice track; without timings it spaces the script evenly.\n  Horizontal: the same band reads as one line of captions; square: type a little smaller so long words clear the edges.\n  Pages follow the words · Hold to 6.6 s.\n-->\n<style>\n  #stage { overflow: hidden; }\n  .abs { position: absolute; box-sizing: border-box; }\n  #cap { position: absolute; left: 6%; right: 6%; display: flex; flex-wrap: wrap; justify-content: center; align-content: center; align-items: baseline; gap: 0.12em 0.28em; text-align: center; }\n  .w { position: relative; display: inline-block; white-space: nowrap; }\n  .w span { position: relative; z-index: 1; }\n  #pill { position: absolute; border-radius: 0.22em; z-index: 0; }\n</style>\n</head>\n<body>\n<main id=\"stage\">\n  <div id=\"bg\" class=\"abs\" style=\"inset:0\"></div>\n  <div id=\"vig\" class=\"abs\" style=\"inset:0\"></div>\n  <div id=\"cap\"></div>\n</main>\n<script type=\"module\">\nimport { scene, progress, ease, spring } from 'paper-motion';\nimport { loadBrand } from 'paper-motion/brand';\n\nconst CONFIG = {\n  background: null,                      // a shader-set id, or null for the brand's first entry\n  script: 'Your agent writes the brief. You pick the look. It renders every frame. That is paper-motion.',\n  words: null,                           // [{ w, t }] word timings from the voice; null spaces the script evenly\n  emphasis: ['every', 'frame.', 'paper-motion.'],   // words that land bigger, in the accent\n  perPage: 24,                           // most characters on one page of captions\n  format: [1080, 1920],\n};\n\nconst B = await loadBrand();\nconst [W, H] = CONFIG.format, SHORT = Math.min(W, H), D = 6.6;\nconst s = scene({ width: W, height: H, fps: 30, duration: D, background: B.color('ground') });\nconst bgId = CONFIG.background ?? B.set.entries.find((e) => e.shader && !e.image)?.id;\nif (bgId) B.shader(s, '#bg', bgId);\nconst $ = (id) => document.getElementById(id);\n$('bg').style.opacity = 0.55;\n$('vig').style.background = 'linear-gradient(to bottom, rgba(0,0,0,0.1) 0%, rgba(0,0,0,0) 40%, rgba(0,0,0,0.65) 100%)';\nconst accent = B.color('accent', '#E9E4D8'), ground = B.color('ground'), figure = B.color('figure');\n\n// the words and when each is said: from the voice's timings, or an even, natural pace\nconst list = CONFIG.words?.filter((x) => x.w.trim()).map((x) => ({ w: x.w.trim(), t: x.t }))\n  ?? (() => { let t = 0.35; return CONFIG.script.split(/\\s+/).map((w) => { const o = { w, t }; t += 0.13 + w.length * 0.035 + (/[.,!?]$/.test(w) ? 0.28 : 0); return o; }); })();\n// pages: break at the end of a sentence or when the page would run long\nconst pages = []; let cur = [];\nconst lenOf = (ids) => ids.reduce((a, k) => a + list[k].w.length + 1, 0);\nlist.forEach((x, i) => { if (cur.length && lenOf([...cur, i]) > CONFIG.perPage) { pages.push(cur); cur = []; } cur.push(i); if (/[.!?]$/.test(x.w)) { pages.push(cur); cur = []; } });\nif (cur.length) pages.push(cur);\nconst pageEnd = (p) => (pages[p + 1] ? list[pages[p + 1][0]].t - 0.02 : D);\n\nconst cap = $('cap'), fs = SHORT * (W === H ? 0.095 : 0.115);   // square: a little smaller so the longest word clears the edges\nObject.assign(cap.style, { top: `${H * 0.56}px`, height: `${H * 0.22}px`, fontSize: `${fs}px` });\nB.style(cap, 'display', { short: SHORT, color: 'figure' }); cap.style.fontSize = `${fs}px`; cap.style.lineHeight = 1.05;\nconst pill = document.createElement('div'); pill.id = 'pill'; pill.style.background = accent; cap.append(pill);\nconst els = list.map((x) => {\n  const el = document.createElement('div'); el.className = 'w';\n  const big = CONFIG.emphasis.includes(x.w);\n  el.innerHTML = `<span>${x.w}</span>`;\n  if (big) { el.style.fontSize = '1.25em'; el.firstChild.style.color = accent; }\n  cap.append(el); return { el, big };\n});\nawait document.fonts.ready;\n\ns.update((t) => {\n  let p = 0; while (p < pages.length - 1 && t >= list[pages[p + 1][0]].t - 0.02) p++;\n  const ids = new Set(pages[p]);\n  // the page's words are laid out together; the others leave the flow\n  els.forEach(({ el }, i) => { el.style.display = ids.has(i) ? '' : 'none'; });\n  const out = 0;                                                    // pages change on a clean cut, no exit move\n  let active = -1;\n  els.forEach(({ el, big }, i) => {\n    if (!ids.has(i)) return;\n    // the whole phrase is there from the page's start, dim; each word lights and hops as it is said\n    const a = list[i].t, k = t >= a ? spring(t - a, { stiffness: 380, damping: big ? 11 : 16 }) : 0;\n    const inPage = 1;\n    el.style.opacity = String((0.32 * inPage + 0.68 * Math.min(1, k * 2)) * (1 - out));\n    el.style.transform = `translateY(${(1 - inPage) * 0.3 - Math.sin(Math.min(1, k) * Math.PI) * 0.12 - out * 0.4}em) scale(${1 + (big ? 0.06 : 0.03) * Math.sin(Math.min(1, k) * Math.PI)})`;\n    if (t >= a) active = i;\n  });\n  // the pill sits behind the word being said, sliding to the next\n  if (active >= 0 && !els[active].big) {\n    const el = els[active].el, k = spring(t - list[active].t, { stiffness: 420, damping: 22 });\n    pill.style.opacity = String(Math.min(1, k * 3) * (1 - out));\n    Object.assign(pill.style, { left: `${el.offsetLeft - fs * 0.08}px`, top: `${el.offsetTop + fs * 0.06}px`, width: `${el.offsetWidth + fs * 0.16}px`, height: `${el.offsetHeight - fs * 0.04}px` });\n    pill.style.transform = `scale(${0.85 + 0.15 * k})`;\n    els.forEach(({ el: e, big }, i) => { if (!big && ids.has(i)) e.firstChild.style.color = i === active ? ground : figure; });\n  } else { pill.style.opacity = '0'; els.forEach(({ el: e, big }, i) => { if (!big && ids.has(i)) e.firstChild.style.color = figure; }); }\n  $('bg').style.transform = `scale(${1.1 + 0.06 * progress(t, 0, D)})`;\n});\npages.forEach((pg) => B.cue(s, 'text', list[pg[0]].t));\nB.sound(s);\nawait s.start();\n</script>\n</body>\n</html>\n"
    },
    {
      "path": "pieces/kinetic-captions/brief.md",
      "content": "# Kinetic captions\n\nBlock: kinetic-captions (6.6 s), from paper-motion.app. The look, fonts and sound come from `brand/`.\n\nCaptions timed to a voice: the phrase sits dim, each word lights as it is said, key words land bigger, phrases change on a clean cut.\n\nA block is one ready-made moment. Edit `CONFIG` (its words, numbers and format: 16:9, 9:16 or 1:1, the layout recomposes for each); check `npx paper-motion still` at 6.2 and 6.6 s; render.\n"
    }
  ],
  "requires": {
    "engine": ">=0.2.6"
  },
  "usage": "npx paper-motion add kinetic-captions --name my-kinetic-captions\n# edit CONFIG in pieces/my-kinetic-captions/scene.html, then:\nnpx paper-motion render pieces/my-kinetic-captions/scene.html --motion-blur 5",
  "notes": [
    "Wired to the brand folder: needs brand/tokens.json (a palette and a font pair work) and, for the field, a shader-set entry.",
    "Recomposes for 16:9, 9:16 and 1:1: set `format` and the layout and camera follow."
  ],
  "related": [
    "word-swap",
    "marker-highlight"
  ],
  "preview": {
    "video": "previews/kinetic-captions.webm",
    "poster": "previews/kinetic-captions.jpg",
    "at": 4.6,
    "values": {}
  },
  "mood": [
    "playful",
    "minimal"
  ],
  "duration": 6.6,
  "formats": [
    "16:9",
    "9:16",
    "1:1"
  ],
  "beats": [
    {
      "name": "Captions",
      "from": 0.35,
      "to": 6.2,
      "what": "each word lights as it is said; phrases change on a cut"
    },
    {
      "name": "Hold",
      "from": 6.2,
      "to": 6.6,
      "what": "the last phrase holds"
    }
  ],
  "when": [
    "voice-over videos for social",
    "talking points in vertical"
  ],
  "needs": [
    {
      "kind": "voice",
      "fill": {
        "script": "$script",
        "words": "$words",
        "emphasis": "$emphasis"
      }
    }
  ]
}