paper-motion

Kinetic captions

kinetic-captions

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.

Install
$ npx paper-motion add kinetic-captions

Writes a scene to pieces/, wired to your brand folder.

Tune it, then add it to your kit
Parameters
script
perPage
format
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>kinetic-captions</title>
<!--
  Text · kinetic captions (6.6 s, vertical). Captions timed to a voice, a few words at a time: each word pops in as it
  is spoken, the word being said sits on an accent pill that slides from word to word, key words land bigger, and the
  next phrase replaces it on a clean cut. Feed it word timings (`words`: [{ w, t }], as the engine's alignment
  writes them) and the voice track; without timings it spaces the script evenly.
  Horizontal: the same band reads as one line of captions; square: type a little smaller so long words clear the edges.
  Pages follow the words · Hold to 6.6 s.
-->
<style>
  #stage { overflow: hidden; }
  .abs { position: absolute; box-sizing: border-box; }
  #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; }
  .w { position: relative; display: inline-block; white-space: nowrap; }
  .w span { position: relative; z-index: 1; }
  #pill { position: absolute; border-radius: 0.22em; z-index: 0; }
</style>
</head>
<body>
<main id="stage">
  <div id="bg" class="abs" style="inset:0"></div>
  <div id="vig" class="abs" style="inset:0"></div>
  <div id="cap"></div>
</main>
<script type="module">
import { scene, progress, ease, spring } from 'paper-motion';
import { loadBrand } from 'paper-motion/brand';

const CONFIG = {
  background: null,
  script: 'Your agent writes the brief. You pick the look. It renders every frame. That is paper-motion.',
  words: null,                           // [{ w, t }] word timings from the voice; null spaces the script evenly
  emphasis: ['every', 'frame.', 'paper-motion.'],   // words that land bigger, in the accent
  perPage: 24,
  format: [1080, 1920],
};

const B = await loadBrand();
const [W, H] = CONFIG.format, SHORT = Math.min(W, H), D = 6.6;
const s = scene({ width: W, height: H, fps: 30, duration: D, background: B.color('ground') });
const bgId = CONFIG.background ?? B.set.entries.find((e) => e.shader && !e.image)?.id;
if (bgId) B.shader(s, '#bg', bgId);
const $ = (id) => document.getElementById(id);
$('bg').style.opacity = 0.55;
$('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%)';
const accent = B.color('accent', '#E9E4D8'), ground = B.color('ground'), figure = B.color('figure');

// the words and when each is said: from the voice's timings, or an even, natural pace
const list = CONFIG.words?.filter((x) => x.w.trim()).map((x) => ({ w: x.w.trim(), t: x.t }))
  ?? (() => { 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; }); })();
// pages: break at the end of a sentence or when the page would run long
const pages = []; let cur = [];
const lenOf = (ids) => ids.reduce((a, k) => a + list[k].w.length + 1, 0);
list.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 = []; } });
if (cur.length) pages.push(cur);
const pageEnd = (p) => (pages[p + 1] ? list[pages[p + 1][0]].t - 0.02 : D);

const cap = $('cap'), fs = SHORT * (W === H ? 0.095 : 0.115);   // square: a little smaller so the longest word clears the edges
Object.assign(cap.style, { top: `${H * 0.56}px`, height: `${H * 0.22}px`, fontSize: `${fs}px` });
B.style(cap, 'display', { short: SHORT, color: 'figure' }); cap.style.fontSize = `${fs}px`; cap.style.lineHeight = 1.05;
const pill = document.createElement('div'); pill.id = 'pill'; pill.style.background = accent; cap.append(pill);
const els = list.map((x) => {
  const el = document.createElement('div'); el.className = 'w';
  const big = CONFIG.emphasis.includes(x.w);
  el.innerHTML = `<span>${x.w}</span>`;
  if (big) { el.style.fontSize = '1.25em'; el.firstChild.style.color = accent; }
  cap.append(el); return { el, big };
});
await document.fonts.ready;

s.update((t) => {
  let p = 0; while (p < pages.length - 1 && t >= list[pages[p + 1][0]].t - 0.02) p++;
  const ids = new Set(pages[p]);
  // the page's words are laid out together; the others leave the flow
  els.forEach(({ el }, i) => { el.style.display = ids.has(i) ? '' : 'none'; });
  const out = 0;                                                    // pages change on a clean cut, no exit move
  let active = -1;
  els.forEach(({ el, big }, i) => {
    if (!ids.has(i)) return;
    // the whole phrase is there from the page's start, dim; each word lights and hops as it is said
    const a = list[i].t, k = t >= a ? spring(t - a, { stiffness: 380, damping: big ? 11 : 16 }) : 0;
    const inPage = 1;
    el.style.opacity = String((0.32 * inPage + 0.68 * Math.min(1, k * 2)) * (1 - out));
    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)})`;
    if (t >= a) active = i;
  });
  // the pill sits behind the word being said, sliding to the next
  if (active >= 0 && !els[active].big) {
    const el = els[active].el, k = spring(t - list[active].t, { stiffness: 420, damping: 22 });
    pill.style.opacity = String(Math.min(1, k * 3) * (1 - out));
    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` });
    pill.style.transform = `scale(${0.85 + 0.15 * k})`;
    els.forEach(({ el: e, big }, i) => { if (!big && ids.has(i)) e.firstChild.style.color = i === active ? ground : figure; });
  } else { pill.style.opacity = '0'; els.forEach(({ el: e, big }, i) => { if (!big && ids.has(i)) e.firstChild.style.color = figure; }); }
  $('bg').style.transform = `scale(${1.1 + 0.06 * progress(t, 0, D)})`;
});
pages.forEach((pg) => B.cue(s, 'text', list[pg[0]].t));
B.sound(s);
await s.start();
</script>
</body>
</html>
Defaults

Structure

Kinetic captions02 / 02
Hold
the last phrase holds
0.0 / 6.6 s
01Captions
0 s6.6 s
  1. 010.35–6.2 sCaptionseach word lights as it is said; phrases change on a cut
  2. 026.2–6.6 sHoldthe last phrase holds

The script, sketched: the beats in order and their length, in the brand's colors and type. The clip above is the engine's render of the same recipe.

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.

Spec

Id
kinetic-captions
Type
Blocks
Version
1.0.0
Engine
>=0.2.6
License
MIT

Related