@crievo/omni 0.0.0-stage → 0.1.0

package/templates/components/voiceavatar/README.md

@@ -0,0 +1,87 @@
+# VoiceAvatar
+
+The audio-reactive orb of a talking voice: a round liquid gradient that flows
+on its own and wakes up with the speech (a ring of light, faster flow, more
+shake on the high frequencies). WebGL2, no libraries, seek-safe.
+
+Measured from a voice-agent orb (principle, not a copied asset): the
+structure and constants come from the reference, the shader code and the
+palette are ours.
+
+## Use in a scene
+
+```html
+<div id="avatar"></div>
+<!-- omnivideo:component voiceavatar -->
+<!-- omnivideo:envelope -->
+<script>
+  VoiceAvatar.mount(document.getElementById("avatar"), {
+    envelope: window.VOICE_ENVELOPE,
+    timeOffset: window.OMNIVIDEO?.start ?? 0,   // the idle flow carries across cuts
+    size: 560,
+    palette: ["#ff5a1f", "#ffa04d", "#c8240f"],
+  });
+  document.fonts.ready.then(() => { window.__ready = true; });
+</script>
+```
+
+Each marker goes alone on its line; `tools/build-motion.mjs` pastes them in:
+
+- `omnivideo:component NAME` → `templates/components/NAME/NAME.js`, inline.
+- `omnivideo:envelope` → `window.VOICE_ENVELOPE` of **this scene**, computed by
+  `tools/voice-envelope.mjs --scene` from the scene's lines (`wav` placed at
+  `start`). While the scene has no voice it is `null` and the orb only idles.
+
+The orb follows the renderer's `--t` by itself. Nothing plays and nothing
+reads a clock, so a frame depends only on `t`.
+
+## Options
+
+| option | what |
+|---|---|
+| `envelope` | `{ fps, low, mid, high, all }`, per-frame values 0..1; absent = silence |
+| `audioStart` | scene second where the envelope's frame 0 plays (default 0; the build's envelope is already on the scene clock) |
+| `timeOffset` | seconds added to `t` for the idle flow; the video's `--scene-start` makes it continuous across scenes |
+| `palette` | three CSS colors; the whole orb is made of them |
+| `grain` | light film grain, 0–0.2 (default 0.08); static and fixed to the pixel, so it never flickers |
+| `seed` | integer; same palette, other blob layout |
+| `size` | side in CSS px; omitted = the element's own width |
+| `exposure` | default 0.15 |
+| `autoSeek` | `false` to drive it by hand with `avatar.seek(t)` |
+
+## How the voice becomes motion
+
+`voice-envelope.mjs` emulates a browser `AnalyserNode` (48 kHz, fftSize 256,
+Blackman, smoothing 0.8, −100…−30 dB) and averages four bands per 1/60 s frame:
+low 0–200 Hz, mid 200–2000 Hz, high 2–20 kHz, all. In the shader:
+
+| band | drives |
+|---|---|
+| `all` | brightness of the ring (`min(all·4, 1)`) and its spin |
+| `mid` | how far the ring sits from the centre |
+| `low` | ring noise scale and the flow's clock |
+| `high` | shake of the simplex drift and the second flow clock |
+
+The live orb smooths these with per-frame lerps (0.55 for the level, 0.25 for
+the running clock). Those are IIR filters, so here they are computed once over
+the whole envelope and a seek is a lookup.
+
+## What was left out on purpose
+
+The reference also runs a 128² fluid simulation whose only effect on the image
+is a 0.001 UV nudge and a 10 % hard-light tint. It accumulates state, so every
+seek would have to replay it. It is cut; the difference is not visible.
+
+## Demo
+
+```bash
+node tools/voice-envelope.mjs <voice.wav> --out templates/components/voiceavatar/envelope.js
+node tools/render.mjs templates/components/voiceavatar/demo.html --sheet sheet.png \
+     --at 0,0.6,1.2,1.8,2.4,3,4,5 --w 1080 --h 1920
+```
+
+`render.mjs` switches to software WebGL (SwiftShader) on its own when the scene
+source mentions `webgl` or `VoiceAvatar` (`--gl` forces it): its default Chrome
+runs with `--disable-gpu`, which has no WebGL at all. Software GL is slower
+(about 0.1 s per 1080×1920 frame with 3 Chromes); `envelope.js` is generated
+per voice and is not committed.

package/templates/components/voiceavatar/demo.html

@@ -0,0 +1,50 @@
+<!doctype html>
+<html lang="pt-BR">
+<head>
+<meta charset="utf-8">
+<title>voiceavatar demo</title>
+<!-- ============================================================
+     VoiceAvatar demo scene: the orb alone on the base canvas.
+
+       node tools/voice-envelope.mjs <voice.wav> --out templates/components/voiceavatar/envelope.js
+       node tools/render.mjs templates/components/voiceavatar/demo.html --sheet sheet.png \
+            --at 0,0.5,1,1.5,2,3,4,5 --w 1080 --h 1920
+
+     The voice starts at AUDIO_START (scene seconds).
+     ============================================================ -->
+<style>
+:root{ --t:0s; --bg:#F5F5F3; }
+html,body{ margin:0; width:100vw; height:100vh; overflow:hidden; background:var(--bg); }
+.stage{ position:absolute; inset:0; display:flex; align-items:center; justify-content:center; }
+#avatar{
+  position:relative; width:58vmin; aspect-ratio:1; border-radius:50%; overflow:hidden;
+  /* soft inner edge, like the reference's inner shadow */
+  box-shadow:0 0 0 1px rgba(0,0,0,.06);
+}
+#avatar::after{
+  content:""; position:absolute; inset:0; border-radius:50%; pointer-events:none;
+  box-shadow:inset 0 0 14px rgba(0,0,0,.18);
+}
+</style>
+</head>
+<body>
+<main class="stage"><div id="avatar"></div></main>
+
+<script src="voiceavatar.js"></script>
+<script src="envelope.js"></script>
+<script>
+const AUDIO_START = 0.4;
+const el = document.getElementById("avatar");
+VoiceAvatar.mount(el, {
+  envelope: window.VOICE_ENVELOPE,
+  audioStart: AUDIO_START,
+  size: Math.round(Math.min(innerWidth, innerHeight) * 0.58),
+  palette: ["#ff5a1f", "#ffa04d", "#c8240f"],
+});
+
+const q = new URLSearchParams(location.search);
+if (q.has("t")) document.documentElement.style.setProperty("--t", q.get("t") + "s");
+document.fonts.ready.then(() => { window.__ready = true; });
+</script>
+</body>
+</html>

package/templates/components/voiceavatar/voiceavatar.js

@@ -0,0 +1,415 @@
+/* ============================================================================
+   VoiceAvatar: the audio-reactive orb of a talking voice (WebGL2, no libs).
+
+   A round gradient that looks like liquid and moves with the speech: the
+   texture is warped by domain-warped fbm and simplex noise, a soft white ring
+   turns inside it and lights up with the voice. Measured from a voice-agent
+   orb in the wild (principle, not a copied asset): the structure and the
+   constants are what the reference showed, the code and the palette are ours.
+
+   Seek-safe: the frame depends only on t. There is no clock and no
+   requestAnimationFrame. `seek(t)` draws one frame; by default the avatar
+   follows the renderer's `--t` (a MutationObserver on <html>'s style, the same
+   contract as a paused GSAP timeline).
+
+   The audio is not played: it comes as an envelope (tools/voice-envelope.mjs
+   writes it from the voice WAV, emulating a browser AnalyserNode with
+   fftSize 256), so the same frames come out on every render.
+
+     const avatar = VoiceAvatar.mount(document.getElementById("avatar"), {
+       envelope: window.VOICE_ENVELOPE,   // { fps, low, mid, high, all }, 0..1
+       audioStart: 0.4,                   // second of the scene where the voice begins
+       palette: ["#ff5a1f", "#ffa04d", "#c8240f"],
+     });
+     avatar.seek(2.1);                    // by hand (preview, stills)
+
+   In a scene: a <div id="avatar"> plus the two markers on a line of their own,
+   component and envelope (see README.md); the build pastes them in.
+
+   Options
+     envelope    { fps, low, mid, high, all } per-frame values 0..1; absent = silence
+     audioStart  scene second where the envelope's frame 0 plays (default 0)
+     timeOffset  seconds added to t for the idle motion; use the video's
+                 --scene-start so the orb flows on across a cut (default 0)
+     palette     three CSS colors (the whole orb is made of them)
+     seed        integer; the same palette with another seed moves the blobs
+     size        CSS px of the side; omitted = the element's own size
+     exposure    default 0.15
+     grain       light film grain, 0 to 0.2 (default 0.08); static, fixed to the pixel
+     fill        true = fill the whole frame instead of a round orb (no circular crop)
+     autoSeek    follow --t on <html> (default true)
+   ============================================================================ */
+(function (root) {
+  "use strict";
+
+  /* what the reference measured; the audio terms are in the shader */
+  const CFG = {
+    timeScale: 1.4,
+    sphereScale: 0.9,
+    spherePower: 1.1,
+    noiseSpeed: 0.25,
+    noiseAmplitude: 0.15,
+    noiseScale: 0.65,
+    fbmScale: 3.25,
+    fbmPower: 2.75,
+    fbmAmplitude: 0.65,
+    fbmSpeed: 4.5,
+    ringOpacity: 0.4,
+    grain: 0.08,
+    overallSound: 1.8 /* how hard the voice drives everything below */,
+    voiceWarp: 0.9 /* extra liquid distortion at the loudest */,
+    voiceShake: 0.9 /* extra drift from the high frequencies */,
+    avgLerp: 0.55 /* per-frame lerp toward the band values */,
+    cumLerp: 0.25 /* same for the running (cumulative) clock */,
+    envFps: 60,
+  };
+
+  const VERT = `#version 300 es
+in vec2 aPos;
+out vec2 vUv;
+void main(){ vUv = aPos * .5 + .5; gl_Position = vec4(aPos, 0., 1.); }`;
+
+  const f = n => (Number.isInteger(n) ? n.toFixed(1) : String(n));
+
+  const FRAG = `#version 300 es
+precision highp float;
+in vec2 vUv;
+out vec4 outColor;
+
+uniform float uTime;      // seconds * timeScale
+uniform vec4  uAudio;     // smoothed low, mid, high, all
+uniform vec4  uCum;       // running clock per band
+uniform float uExposure;
+uniform float uFill;      // 0 = round orb, 1 = fills the whole frame (no circular crop)
+uniform float uGrain;     // film grain amplitude; fixed to the pixel, so it never flickers
+uniform sampler2D uTexture;
+
+// --- simplex noise 3D (Ashima Arts / Stefan Gustavson, MIT) ---
+vec4 permute(vec4 x){ return mod(((x*34.0)+1.0)*x, 289.0); }
+vec4 taylorInvSqrt(vec4 r){ return 1.79284291400159 - 0.85373472095314 * r; }
+float snoise(vec3 v){
+  const vec2 C = vec2(1.0/6.0, 1.0/3.0);
+  const vec4 D = vec4(0.0, 0.5, 1.0, 2.0);
+  vec3 i  = floor(v + dot(v, C.yyy));
+  vec3 x0 = v - i + dot(i, C.xxx);
+  vec3 g = step(x0.yzx, x0.xyz);
+  vec3 l = 1.0 - g;
+  vec3 i1 = min(g.xyz, l.zxy);
+  vec3 i2 = max(g.xyz, l.zxy);
+  vec3 x1 = x0 - i1 + C.xxx;
+  vec3 x2 = x0 - i2 + 2.0 * C.xxx;
+  vec3 x3 = x0 - 1.0 + 3.0 * C.xxx;
+  i = mod(i, 289.0);
+  vec4 p = permute(permute(permute(
+      i.z + vec4(0.0, i1.z, i2.z, 1.0))
+    + i.y + vec4(0.0, i1.y, i2.y, 1.0))
+    + i.x + vec4(0.0, i1.x, i2.x, 1.0));
+  float n_ = 1.0/7.0;
+  vec3 ns = n_ * D.wyz - D.xzx;
+  vec4 j = p - 49.0 * floor(p * ns.z * ns.z);
+  vec4 x_ = floor(j * ns.z);
+  vec4 y_ = floor(j - 7.0 * x_);
+  vec4 x = x_ * ns.x + ns.yyyy;
+  vec4 y = y_ * ns.x + ns.yyyy;
+  vec4 h = 1.0 - abs(x) - abs(y);
+  vec4 b0 = vec4(x.xy, y.xy);
+  vec4 b1 = vec4(x.zw, y.zw);
+  vec4 s0 = floor(b0) * 2.0 + 1.0;
+  vec4 s1 = floor(b1) * 2.0 + 1.0;
+  vec4 sh = -step(h, vec4(0.0));
+  vec4 a0 = b0.xzyw + s0.xzyw * sh.xxyy;
+  vec4 a1 = b1.xzyw + s1.xzyw * sh.zzww;
+  vec3 p0 = vec3(a0.xy, h.x);
+  vec3 p1 = vec3(a0.zw, h.y);
+  vec3 p2 = vec3(a1.xy, h.z);
+  vec3 p3 = vec3(a1.zw, h.w);
+  vec4 norm = taylorInvSqrt(vec4(dot(p0,p0), dot(p1,p1), dot(p2,p2), dot(p3,p3)));
+  p0 *= norm.x; p1 *= norm.y; p2 *= norm.z; p3 *= norm.w;
+  vec4 m = max(0.6 - vec4(dot(x0,x0), dot(x1,x1), dot(x2,x2), dot(x3,x3)), 0.0);
+  m = m * m;
+  return 42.0 * dot(m*m, vec4(dot(p0,x0), dot(p1,x1), dot(p2,x2), dot(p3,x3)));
+}
+
+// --- value noise + fbm (4 octaves, rotated) ---
+float rnd(vec2 st){ return fract(sin(dot(st, vec2(12.9898, 78.233))) * 43758.5453123); }
+float vnoise(vec2 st){
+  vec2 i = floor(st), fr = fract(st);
+  float a = rnd(i), b = rnd(i + vec2(1., 0.)), c = rnd(i + vec2(0., 1.)), d = rnd(i + vec2(1., 1.));
+  vec2 u = fr * fr * (3.0 - 2.0 * fr);
+  return mix(a, b, u.x) + (c - a) * u.y * (1.0 - u.x) + (d - b) * u.x * u.y;
+}
+float fbm(vec2 st){
+  float v = 0.0, a = 0.5;
+  mat2 rot = mat2(cos(0.5), sin(0.5), -sin(0.5), cos(0.5));
+  for (int i = 0; i < 4; i++){ v += a * vnoise(st); st = rot * st * 2.0 + vec2(100.0); a *= 0.5; }
+  return v;
+}
+
+void main(){
+  vec2 uv = vec2(1.0 - vUv.x, vUv.y);
+
+  // sphere: bulge the texture coordinates toward the middle
+  vec2 p = (uv - 0.5) * 2.0 * mix(1.0, 0.72, uFill);
+  float d = pow(sqrt(1.0 - clamp(dot(p, p), 0.0, 1.0)), ${f(CFG.spherePower)});
+  vec3 normal = vec3(p, d);
+  uv = (p * ${f(CFG.sphereScale)} / (d + 1.0) + 1.0) * 0.5;
+
+  // liquid: domain-warped fbm; the voice speeds up its clock
+  vec2 fuv = uv * ${f(CFG.fbmScale)};
+  float tw = uTime * ${f(CFG.fbmSpeed)} * 0.5 + uCum.x * 0.25;
+  vec2 q = vec2(fbm(fuv), fbm(fuv + vec2(1.0)));
+  vec2 r = vec2(fbm(fuv + q + vec2(91.3, 0.55) + 0.15 * tw),
+                fbm(fuv + q - vec2(45.33, 1.2) + 0.126 * tw));
+  float fv = fbm(fuv + r);
+  float ff = mix(0.8, 0.66, clamp(fv * fv * ${f(CFG.fbmPower)}, 0.0, 1.0));
+  ff = mix(ff, 0.0, clamp(length(q), 0.0, 1.0));
+  ff = mix(ff, 1.0, clamp(abs(r.x), 0.0, 1.0));
+
+  // simplex drift; high frequencies shake it harder
+  float n1 = uTime * ${f(CFG.noiseSpeed)} * 0.5 + uCum.z * 0.1;
+  vec2 disp = vec2(snoise(vec3(vUv * ${f(CFG.noiseScale)}, n1)),
+                   snoise(vec3(vUv * ${f(CFG.noiseScale)} + vec2(54.0), uTime * ${f(CFG.noiseSpeed)})));
+  disp *= 1.0 + uAudio.z * ${f(CFG.voiceShake)};
+
+  // the louder the voice, the more the liquid is stirred
+  float drive = clamp(uAudio.w * 3.0, 0.0, 1.5);
+  uv += normal.xy * (ff - 0.5) * ${f(CFG.fbmAmplitude)} * (1.0 + drive * ${f(CFG.voiceWarp)});
+  uv += disp * ${f(CFG.noiseAmplitude)};
+  vec3 color = texture(uTexture, uv).rgb;
+
+  // ring of light: only shows while there is sound
+  vec2 ru = (vUv - 0.5) * 2.0 * 0.75;
+  float ang = atan(ru.y, ru.x);
+  float len = length(ru);
+  float rt = -uTime * 0.5 - uCum.w * 0.2;
+  ru.x += 1.0 + uAudio.y * 1.5;
+  float n0 = snoise(vec3(ru * (0.65 + uAudio.x * 0.4), rt * 0.5)) * 0.5 + 0.5;
+  float cl = cos(ang + rt * 2.0) * 0.5 + 0.5;
+  cl *= (1.0 - smoothstep(mix(0.25, 1.0, n0 * 0.5), 1.0, len));
+  cl *= pow(smoothstep(0.25, mix(0.25, 1.0, n0 * 0.75), len), 2.0);
+  cl = clamp(pow(cl * min(uAudio.w * 4.0, 1.0), 3.0), 0.0, 1.0);
+  color += vec3(cl) * ${f(CFG.ringOpacity)};
+
+  // round mask, antialiased
+  float dist = length(vUv - 0.5) * 2.0;
+  float aa = max(fwidth(dist), 1e-4);
+  float a = mix(1.0 - smoothstep(1.0, 1.0 + aa, dist), 1.0, uFill);
+
+  // light grain: static noise per pixel, centered on zero so it neither darkens nor lightens
+  float grain = fract(sin(dot(gl_FragCoord.xy, vec2(12.9898, 78.233))) * 43758.5453);
+  color = color * (1.0 + uExposure) + (grain - 0.5) * uGrain;
+  color = clamp(color, 0.0, 1.0);
+  outColor = vec4(color * a, a);
+}`;
+
+  /* --- tiny seeded random: the palette texture is the same on every render --- */
+  function mulberry32(a) {
+    return function () {
+      a |= 0;
+      a = (a + 0x6d2b79f5) | 0;
+      let t = Math.imul(a ^ (a >>> 15), 1 | a);
+      t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+      return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+  }
+
+  function withAlpha(css, a) {
+    const c = document.createElement("canvas").getContext("2d");
+    c.fillStyle = css;
+    const m = c.fillStyle.match(/^#(..)(..)(..)$/);
+    return m ? `rgba(${parseInt(m[1], 16)},${parseInt(m[2], 16)},${parseInt(m[3], 16)},${a})` : css;
+  }
+
+  /* The orb's gradient: a diagonal wash of the three colors plus soft blobs of each of them. */
+  function paintTexture(palette, seed) {
+    const S = 512;
+    const c = document.createElement("canvas");
+    c.width = c.height = S;
+    const g = c.getContext("2d");
+    const rnd = mulberry32(seed);
+    const base = g.createLinearGradient(0, 0, S, S);
+    palette.forEach((col, i) => base.addColorStop(i / (palette.length - 1), col));
+    g.fillStyle = base;
+    g.fillRect(0, 0, S, S);
+    for (let i = 0; i < palette.length * 4; i++) {
+      const x = rnd() * S;
+      const y = rnd() * S;
+      const r = S * (0.22 + rnd() * 0.28);
+      const col = palette[i % palette.length]; /* each color gets the same number of blobs */
+      const rg = g.createRadialGradient(x, y, 0, x, y, r);
+      rg.addColorStop(0, col);
+      rg.addColorStop(1, withAlpha(col, 0)); /* same hue, not transparent black: no dark fringe */
+      g.globalAlpha = 0.9;
+      g.fillStyle = rg;
+      g.fillRect(0, 0, S, S);
+    }
+    g.globalAlpha = 1;
+    return c;
+  }
+
+  /* Per-frame audio state, precomputed once so a seek is a lookup: the lerps
+     of the live orb are IIR filters, which would make the frame depend on the
+     order of the calls. Index i = frame i of the envelope at envFps. */
+  function precompute(env) {
+    const n = (env && env.all ? env.all.length : 0) + CFG.envFps * 2; /* 2 s of tail: it settles */
+    const avg = new Float32Array(n * 4);
+    const cum = new Float32Array(n * 4);
+    const a = [0, 0, 0, 0];
+    const c = [0, 0, 0, 0];
+    const bands = env ? [env.low, env.mid, env.high, env.all] : [];
+    for (let i = 0; i < n; i++) {
+      for (let k = 0; k < 4; k++) {
+        const raw = (bands[k] && bands[k][i]) || 0;
+        a[k] += CFG.avgLerp * (raw * CFG.overallSound - a[k]);
+        c[k] += CFG.cumLerp * raw * CFG.overallSound * CFG.timeScale; /* one 1/60 s step */
+        avg[i * 4 + k] = a[k];
+        cum[i * 4 + k] = c[k];
+      }
+    }
+    return { n, avg, cum };
+  }
+
+  /* The GL side, apart from any canvas: compiles the program once on `gl` and draws
+     one orb per call into a viewport. The studio shares one context among many
+     avatars through this; a scene's `mount` below owns a context of its own. */
+  function createPainter(gl) {
+    const sh = (type, src) => {
+      const s = gl.createShader(type);
+      gl.shaderSource(s, src);
+      gl.compileShader(s);
+      if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) throw new Error("VoiceAvatar shader: " + gl.getShaderInfoLog(s));
+      return s;
+    };
+    const prog = gl.createProgram();
+    gl.attachShader(prog, sh(gl.VERTEX_SHADER, VERT));
+    gl.attachShader(prog, sh(gl.FRAGMENT_SHADER, FRAG));
+    gl.linkProgram(prog);
+    if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) throw new Error("VoiceAvatar link: " + gl.getProgramInfoLog(prog));
+    gl.useProgram(prog);
+
+    const buf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+    gl.bufferData(gl.ARRAY_BUFFER, new Float32Array([-1, -1, 3, -1, -1, 3]), gl.STATIC_DRAW);
+    const loc = gl.getAttribLocation(prog, "aPos");
+    gl.enableVertexAttribArray(loc);
+    gl.vertexAttribPointer(loc, 2, gl.FLOAT, false, 0, 0);
+
+    const U = n => gl.getUniformLocation(prog, n);
+    const uTime = U("uTime");
+    const uAudio = U("uAudio");
+    const uCum = U("uCum");
+    const uExposure = U("uExposure");
+    const uFill = U("uFill");
+    const uGrain = U("uGrain");
+    gl.uniform1i(U("uTexture"), 0);
+    gl.enable(gl.SCISSOR_TEST);
+
+    return {
+      /* the orb's gradient, uploaded as a texture; free it with deleteTexture */
+      texture(palette, seed) {
+        const tex = gl.createTexture();
+        gl.bindTexture(gl.TEXTURE_2D, tex);
+        gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
+        gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, paintTexture(palette, seed));
+        /* no mipmaps: the warped coordinates jump between neighbour pixels, and the
+           derivative-picked mip level draws a fine hatch */
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
+        gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+        return tex;
+      },
+      deleteTexture(tex) {
+        gl.deleteTexture(tex);
+      },
+      /* o: { texture, time (s), audio [4], cum [4], width, height, x?, y?, fill?, exposure?, grain? } */
+      draw(o) {
+        const x = o.x || 0;
+        const y = o.y || 0;
+        gl.useProgram(prog);
+        gl.activeTexture(gl.TEXTURE0);
+        gl.bindTexture(gl.TEXTURE_2D, o.texture);
+        gl.viewport(x, y, o.width, o.height);
+        gl.scissor(x, y, o.width, o.height);
+        gl.uniform1f(uTime, o.time * CFG.timeScale);
+        gl.uniform4fv(uAudio, o.audio);
+        gl.uniform4fv(uCum, o.cum);
+        gl.uniform1f(uExposure, o.exposure == null ? 0.15 : o.exposure);
+        gl.uniform1f(uFill, o.fill ? 1 : 0);
+        gl.uniform1f(uGrain, o.grain == null ? CFG.grain : o.grain);
+        gl.clearColor(0, 0, 0, 0);
+        gl.clear(gl.COLOR_BUFFER_BIT);
+        gl.drawArrays(gl.TRIANGLES, 0, 3);
+      },
+    };
+  }
+
+  function mount(el, opts) {
+    opts = opts || {};
+    const palette = opts.palette && opts.palette.length > 1 ? opts.palette : ["#ff5a1f", "#ffa04d", "#c8240f"];
+    const side = opts.size || el.clientWidth || 256;
+    const audioStart = opts.audioStart || 0;
+    const timeOffset = opts.timeOffset || 0;
+    const state = precompute(opts.envelope);
+    const fps = (opts.envelope && opts.envelope.fps) || CFG.envFps;
+
+    el.classList.add("voiceavatar");
+    if (opts.size) {
+      el.style.width = el.style.height = side + "px";
+    }
+    const cv = document.createElement("canvas");
+    cv.width = cv.height = Math.round(side * (opts.dpr || 1));
+    cv.style.cssText = "position:absolute;inset:0;width:100%;height:100%;display:block";
+    el.appendChild(cv);
+
+    const gl = cv.getContext("webgl2", { alpha: true, premultipliedAlpha: true, antialias: false, preserveDrawingBuffer: true });
+    if (!gl) throw new Error("VoiceAvatar: WebGL2 indisponível");
+    const painter = createPainter(gl);
+    const texture = painter.texture(palette, opts.seed == null ? 7 : opts.seed);
+
+    /* audio state at scene second t: linear between the two frames around it */
+    function audioAt(t) {
+      const x = (t - audioStart) * fps;
+      if (x <= 0) return { avg: [0, 0, 0, 0], cum: [0, 0, 0, 0] };
+      const i0 = Math.min(Math.floor(x), state.n - 1);
+      const i1 = Math.min(i0 + 1, state.n - 1);
+      const w = x - Math.floor(x);
+      const avg = [];
+      const cum = [];
+      for (let k = 0; k < 4; k++) {
+        avg.push(state.avg[i0 * 4 + k] * (1 - w) + state.avg[i1 * 4 + k] * w);
+        cum.push(state.cum[i0 * 4 + k] * (1 - w) + state.cum[i1 * 4 + k] * w);
+      }
+      return { avg, cum };
+    }
+
+    function seek(t) {
+      const s = audioAt(t);
+      painter.draw({
+        texture,
+        time: t + timeOffset,
+        audio: s.avg,
+        cum: s.cum,
+        width: cv.width,
+        height: cv.height,
+        exposure: opts.exposure,
+        fill: opts.fill,
+        grain: opts.grain,
+      });
+    }
+
+    const readT = () => parseFloat(document.documentElement.style.getPropertyValue("--t")) || 0;
+    if (opts.autoSeek !== false) {
+      new MutationObserver(() => seek(readT())).observe(document.documentElement, { attributes: true, attributeFilter: ["style"] });
+    }
+    seek(readT());
+    return { seek, canvas: cv, audioAt };
+  }
+
+  /* a scene loads this as a plain script and finds `VoiceAvatar` on window; a bundler (the studio)
+     gets it as a module, and must not touch the global: a bundle's own top-level `VoiceAvatar`
+     (the React component) would be overwritten by it */
+  const api = { mount, createPainter, config: CFG };
+  if (typeof module === "object" && module && module.exports) module.exports = api;
+  else root.VoiceAvatar = api;
+})(typeof window !== "undefined" ? window : globalThis);

package/templates/motion.md

@@ -0,0 +1,80 @@
+# Roteiro de motion · <título>
+
+Formato: 9:16, 1080×1920, 30 fps.
+Momento "wow": cena `cNN`, <o que acontece>.
+
+## Estilo visual
+
+Um estilo visual da biblioteca, `referencias/<pasta>` (veja `node tools/reference.mjs list`).
+Um, no máximo dois. O que vem dele é princípio, não asset.
+
+| | |
+|---|---|
+| por que este | o que ele tem que este vídeo precisa |
+| vale levar | os itens do "Vale levar" do guia que entram aqui, cada um como regra |
+| primitivas | as do guia que este vídeo usa, e se vêm do código da `proof/proof.html` |
+| traduzido | o que da peça o código não reproduz (Tipo do guia) e o que entra no lugar; "nada" se o Tipo é reproduzível inteiro |
+| ritmo | do `measurements.json`: quanto dura um beat, quanto a tela segura depois |
+| não copiar | marca, dados, layout literal |
+
+## Estilo do vídeo
+
+Vale para todas as cenas e sai do estilo visual: medido, não inventado.
+
+| | escolha |
+|---|---|
+| fundo | cor ou textura; se anda, vai em `motion/src/_common.html`, no tempo do vídeo |
+| paleta | 2 a 3 cores, com papel de cada uma |
+| tipografia | Schibsted Grotesk, a sans padrão (`av-motion`); do estilo visual, corpos, pesos e tracking |
+| curva de entrada | ex.: `cubic-bezier(0.22, 1, 0.36, 1)`, sem overshoot |
+| entrada padrão | ex.: opacidade + 12 px de subida + desfoque de 3 px, 600 ms |
+| som | a família de efeitos (ex.: cliques secos e um whoosh curto), quantos no vídeo e o termo de busca na Epidemic de cada um |
+
+## Cenas
+
+| cena | bloco | herói | o que está na tela |
+|---|---|---|---|
+| c01 | B1 | | |
+| c02 | B2 | | |
+
+---
+
+## c01 · <título>
+
+**Objetivo:** o que a cena comunica.
+**Herói:** o único elemento em destaque total.
+**Apoio:** o que entra e cede o palco.
+
+<!-- Up to here, the motion script (stage 2), one block per scene. The
+     scenes' composition notes (composição, beats table, passagem) go to the
+     "Composição por cena" section, which tools/compose.mjs apply writes during
+     composition (stage 3); the Passagens section is written by the close call. -->
+
+---
+
+## Base da composição
+
+<!-- Stage 3, written by the `base da composição` call before the scenes: what
+     motion/src/_common.html offers and the rules every scene fork follows. -->
+
+| peça | o que é | como usar |
+|---|---|---|
+| `--ink`, `--accent`… | paleta por papel | `color: var(--accent)` só no herói |
+| `--ease-in`, `--dur-in` | a curva e a duração medidas no guia | toda entrada |
+| `.card` | o cartão que se repete | `<div class="card">` |
+| fundo | grão e gradiente no tempo do vídeo | já está em toda cena |
+
+Regras: entradas em `--dur-in` com `--ease-in`, nada some para opacidade 0 no
+meio da cena, a tela fica parada ≥ 600 ms antes do corte.
+
+---
+
+## Passagens
+
+Como cada cena entra a partir da anterior. Corte seco é escolha, não
+esquecimento; o que continua leva `data-continues` nas duas cenas.
+
+| corte | tipo | o que continua | como |
+|---|---|---|---|
+| c01 → c02 | continua | `fundo`, `card` | o card termina a c01 onde a c02 começa |
+| c02 → c03 | corte | — | troca de assunto |

package/templates/playbook.md

@@ -0,0 +1,43 @@
+# Playbook do canal
+
+O que o canal promete, os pilares e o que os números já mostraram. O
+`av-script` lê antes de escrever; a análise de cada vídeo publicado atualiza.
+Cada aprendizado diz quantos vídeos o sustentam: com menos de 5, é hipótese.
+Números de `node tools/metrics.mjs show`.
+
+## Promessa
+
+Uma frase: o que quem segue ganha, vídeo após vídeo.
+
+## Pilares
+
+| pilar | o que é | objetivo mais comum |
+|---|---|---|
+| | | |
+
+## O que cada métrica julga
+
+| métrica | julga | pergunta que ela responde |
+|---|---|---|
+| pulo em 3 s | gancho: quadro 0 + primeira frase | parei de rolar? |
+| % assistido | o miolo | valeu ficar? |
+| compartilhamentos | o tema | mando isso para alguém? |
+| salvos | a utilidade | vou querer rever? |
+| comentários | o CTA | tenho motivo para falar? |
+| visitas ao perfil e seguidores | a promessa do canal | quero mais disso? |
+
+## Linha de base
+
+As medianas do canal, para dizer se um vídeo foi acima ou abaixo. Compare
+vídeos na mesma idade (marcos 24 h e 72 h do `metrics.json`).
+
+| métrica | mediana | vídeos | de quando |
+|---|---|---|---|
+| pulo em 3 s | | | |
+| % assistido | | | |
+
+## Aprendizados
+
+| # | hipótese | evidência | n | confiança | desde |
+|---|---|---|---|---|---|
+| | | | | baixa · média · alta | |