@amg555/frameforge-mcp 2.7.3 → 2.7.7

package/plugins/faceless-shorts/styles/stick-story/example/src/sheet.js

@@ -0,0 +1,64 @@
+// The Stick Story style sheet, drawn with the style's own kit.
+import { ctx } from './core/lib.js';
+import { startBoard, panel, frame, cell, small, swatches, rules } from './core/board.js';
+import * as K from './core/kit.js';
+const { P } = K;
+
+const cv = document.getElementById('cv');
+await document.fonts.load('900 40px Inter'); await document.fonts.load('800 40px Inter');
+startBoard(cv, { title: 'STICK STORY: VIDEO STYLE SHEET', accent: P.gold });
+
+// 1 · hero frame
+let b = panel(20, 80, 560, 520, 1, 'HERO FRAME');
+frame(b.x + 6, b.y, 240, () => {
+  K.livingRoom({ night: true, lampOn: false });
+  K.person({ x: 520, y: K.GROUND, h: 720, dir: 1, mood: 'worried', look: [1, -0.2], arms: { L: [-10, 20], R: [70, 20] }, hold: (x, y) => K.flashlight(x + 10, y, 1.3, true, -0.15) });
+  K.counterPill('9:12 P.M.', 540, 230, 1.1);
+  K.captionBar([{ txt: 'The power' }, { txt: 'goes' }, { txt: 'out.', hi: 1 }], 540, K.CAPLOOK.y, 1.05);
+});
+small('A STICK HERO WITH\nEYES THAT ACT', b.x + 270, b.y + 40, 'left', 17);
+small('FLAT ROOMS,\nDAY OR NIGHT', b.x + 270, b.y + 130, 'left', 17);
+small('ONE PICTURE\nPER CLAUSE', b.x + 270, b.y + 220, 'left', 17);
+small('GOLD = STEPS,\nRED = DANGER', b.x + 270, b.y + 310, 'left', 17);
+
+// 2 · palette
+b = panel(590, 80, 660, 520, 2, 'PALETTE');
+const yy = swatches(b, [['WALL', P.wall], ['FLOOR', P.floor], ['INK', P.ink], ['GOLD', P.gold], ['NAVY', P.navy], ['DANGER', P.red], ['SAFE', P.green], ['NIGHT', P.nWall]]);
+['PEOPLE ARE ALWAYS INK BLACK. COLOUR LIVES IN THE ROOM.', 'GOLD IS ONLY FOR STEP CARDS AND KEY WORDS.', 'NIGHT = THE SAME ROOM IN BLUE, LIT BY ONE LAMP.']
+  .forEach((t, i) => small(t, b.x + 4, yy + 20 + i * 40, 'left', 16, '#E6E7EA'));
+// expressions strip (the eyes are the style's signature)
+ctx.fillStyle = P.wall; ctx.beginPath(); ctx.roundRect(b.x, yy + 140, b.w, 150, 14); ctx.fill();
+['calm', 'happy', 'worried', 'scared', 'determined', 'sleepy'].forEach((m, i) => cell(b.x + 55 + i * 104, yy + 195, 0.36, () => K.bigHead(0, 0, 100, { mood: m }), m.toUpperCase(), 72));
+
+// 3 · components
+b = panel(1260, 80, 640, 520, 3, 'COMPONENTS');
+ctx.fillStyle = P.wall; ctx.beginPath(); ctx.roundRect(b.x, b.y, b.w, b.h, 14); ctx.fill();
+const gx = (i) => b.x + 75 + i * 150, gy = (r) => b.y + 140 + r * 195;
+cell(gx(0), gy(0) + 80, 0.38, () => K.person({ x: 0, y: 0, h: 520, mood: 'happy', arms: { L: [-30, 40], R: [150, 20] } }), 'HERO', 30);
+cell(gx(1), gy(0) + 80, 0.38, () => K.person({ x: 0, y: 0, h: 520, mood: 'scared', walk: 1.2, dir: -1 }), 'WALKING', 30);
+cell(gx(2), gy(0), 0.55, () => K.bigHead(0, -20, 120, { mood: 'determined' }), 'CLOSE-UP', 90);
+cell(gx(3), gy(0), 0.5, () => K.thought(0, -40, 0.8, () => K.bottle(0, -20, 0.6), 60, 120), 'THOUGHT', 90);
+cell(gx(0), gy(1), 0.55, () => { K.bottle(-40, 60); K.can(50, 60); }, 'SUPPLIES', 70);
+cell(gx(1), gy(1), 0.5, () => K.phone(0, 0, 0.8, true), 'PHONE', 70);
+cell(gx(2), gy(1) - 10, 0.55, () => { K.check(-55, 0, 0.8); K.cross(55, 0, 0.8); }, 'YES / NO', 80);
+cell(gx(3), gy(1), 0.2, () => K.stepCard(1, 'FILL THE TUB', 0, 0), 'STEP CARD', 70);
+
+// 4 · scenes
+b = panel(20, 610, 760, 456, 4, 'SCENES');
+const sw = 200, sx = (i) => b.x + 20 + i * (sw + 45);
+frame(sx(0), b.y, sw, () => { K.livingRoom({}); K.person({ x: 420, y: K.GROUND, h: 700, mood: 'calm', dir: 1, look: [1, 0] }); });
+frame(sx(1), b.y, sw, () => { K.kitchen({}); K.person({ x: 650, y: K.GROUND, h: 700, mood: 'determined', dir: -1, hold: (x, y) => K.bottle(x, y + 40, 1) }); });
+frame(sx(2), b.y, sw, () => { K.hallway({ night: true, openB: 0.3 }); K.person({ x: 520, y: K.GROUND, h: 700, mood: 'scared', dir: 1, walk: 0.6 }); });
+['(A) LIVING ROOM', '(B) KITCHEN', '(C) HALLWAY · NIGHT'].forEach((t, i) => small(t, sx(i) + sw / 2, b.y + sw * 16 / 9 + 26, 'center', 15));
+
+// 5 · captions
+b = panel(790, 610, 520, 456, 5, 'CAPTIONS');
+ctx.fillStyle = P.wall; ctx.fillRect(b.x, b.y, b.w, b.h - 10);
+[[[{ txt: 'Lock' }, { txt: 'the' }, { txt: 'door.', hi: 1 }], 70], [[{ txt: 'Then' }, { txt: 'fill' }, { txt: 'the' }, { txt: 'tub.', hi: 1 }], 175], [[{ txt: 'Day' }, { txt: 'three.', hi: 1 }], 280]]
+  .forEach(([w, y]) => cell(b.x + b.w / 2, b.y + y, 0.42, () => K.captionBar(w, 0, 0), null));
+small('SENTENCE CASE · 2-4 WORDS · ONE GOLD WORD', b.x + b.w / 2, b.y + b.h - 26, 'center', 14, '#5A5560');
+
+// 6 · rules
+b = panel(1320, 610, 580, 456, 6, 'RULES');
+rules(b, ['ONE PICTURE PER CLAUSE: CUT EVERY 1-2 S.', 'EYES ACT FIRST: LOOK, THEN REACT.', 'EVERY STEP GETS A GOLD NUMBERED CARD.', 'SAME ROOMS ALL VIDEO: DAY, THEN NIGHT.', 'CINEMA BARS ONLY ON THE SCARY BEAT.', 'SOFT CARTOON SOUND: POP, WHOOSH, STEPS.', 'MOOD: TENSE, CLEVER, A LITTLE FUNNY.'], b.y + 26, 17, 52);
+window.SHEET_READY = true;

package/plugins/faceless-shorts/styles/stick-story/example/src/shots.js

@@ -0,0 +1,148 @@
+// WHAT IF THE POWER WENT OUT FOR 3 DAYS? : the shot list (Stick Story example).
+// One picture per clause. A shot: { id, at, cam: [cx, cy], zoom, note, draw(lt, d, t) }. cut(i) = just before line i,
+// Wd('word', i) = when the word is said. Sound: cue(t, type, { gain, dur }).
+import { ctx, W, H, clamp, lerp, seg, eo, eio, eob, rnd, rr, circle, ell, line } from './core/lib.js';
+import { L, Wd, T } from './core/timing.js';
+import * as K from './core/kit.js';
+const { P, GROUND } = K;
+
+// small set pieces for this story
+function tv(x, y, on) { rr(x - 170, y - 230, 340, 210, 16); ctx.fillStyle = P.ink; ctx.fill(); rr(x - 150, y - 212, 300, 174, 8); ctx.fillStyle = on ? '#7FB8E6' : '#2E3445'; ctx.fill(); rr(x - 120, y - 20, 240, 30, 8); ctx.fillStyle = '#6B4A34'; ctx.fill(); ctx.fillStyle = '#6B4A34'; ctx.fillRect(x - 110, y + 10, 20, 120); ctx.fillRect(x + 90, y + 10, 20, 120); }
+function plug(x, y, inWall) { line([[x - 300, y + 40], [x - 120, y + 60], [x - 10, y + 10]], P.ink, 10); rr(x - 20, y - 22, inWall ? 40 : 56, 44, 8); ctx.fillStyle = '#E8E3D8'; ctx.fill(); ctx.strokeStyle = P.ink; ctx.lineWidth = 5; ctx.stroke(); if (!inWall) { line([[x + 36, y - 10], [x + 56, y - 10]], '#B8A36A', 7); line([[x + 36, y + 10], [x + 56, y + 10]], '#B8A36A', 7); } }
+function socket(x, y) { rr(x - 50, y - 70, 100, 140, 14); ctx.fillStyle = '#F7F1E6'; ctx.fill(); ctx.strokeStyle = '#C9BFA9'; ctx.lineWidth = 5; ctx.stroke(); for (const dy of [-28, 28]) { circle(x, dy + y, 20, '#C9BFA9'); ctx.fillStyle = P.ink; ctx.fillRect(x - 8, y + dy - 8, 5, 14); ctx.fillRect(x + 3, y + dy - 8, 5, 14); } }
+function candle(x, y, s, t) { ctx.save(); ctx.translate(x, y); ctx.scale(s, s); rr(-26, -140, 52, 150, 10); ctx.fillStyle = '#F4EEDC'; ctx.fill(); line([[0, -140], [0, -158]], P.ink, 5); const f = 1 + Math.sin(t * 20) * 0.08; ell(0, -190, 20 * f, 38 * f, '#F2B23E'); ell(0, -182, 10, 20, '#FFF3C4'); ctx.restore(); }
+function curtain(x, y, h, wave) { ctx.beginPath(); ctx.moveTo(x, y); for (let k = 0; k <= 10; k++) ctx.lineTo(x + 200 + Math.sin(k + wave) * 18, y + h * k / 10); ctx.lineTo(x, y + h); ctx.closePath(); ctx.fillStyle = '#C96B5B'; ctx.fill(); }
+function bolt(x, y, s) { ctx.save(); ctx.translate(x, y); ctx.scale(s, s); ctx.beginPath(); ctx.moveTo(10, -120); ctx.lineTo(-50, 10); ctx.lineTo(0, 10); ctx.lineTo(-20, 120); ctx.lineTo(60, -20); ctx.lineTo(10, -20); ctx.closePath(); ctx.fillStyle = '#FFD43B'; ctx.fill(); ctx.lineWidth = 8; ctx.strokeStyle = P.ink; ctx.stroke(); ctx.restore(); }
+
+export function buildShots() {
+  const S = [], CUES = [], add = (o) => (S.push(o), o), cue = (t, type, o = {}) => CUES.push({ t: +t.toFixed(3), type, ...o });
+  const cut = (i) => (i === 0 ? 0 : L(i) - 0.08);
+  const blink = (t) => ((t % 3.1) < 0.12 ? 1 : 0);
+
+  // 1 · a normal evening, phone in hand
+  add({ id: 'S01', at: 0, cam: [540, 1100], note: 'evening, hero scrolls phone, looks up', draw(lt, d, t) {
+    K.livingRoom({ night: true, lampOn: true });
+    const up = lt > d * 0.6;
+    K.person({ glow: true, x: 520, y: GROUND, h: 840, mood: up ? 'worried' : 'calm', look: up ? [0.2, -1] : [0.6, 0.6], blink: blink(t), arms: { L: [-6, 14], R: [60, 60] }, hold: (x, y) => K.phone(x + 12, y - 40, 0.55, true) });
+    if (up) K.thought(800, 560, 0.9 * eob(seg(lt, d * 0.6, d * 0.6 + 0.25)), () => bolt(800, 545, 0.75), 640, 760);
+  } });
+  cue(0.2, 'pop', { gain: 0.5 });
+
+  // 2 · nine at night … everything goes dark
+  { const st = cut(1), dark = Wd('dark', 1) - st;
+    add({ id: 'S02', at: st, cam: [540, 1000], zoom: 0.1, note: 'lamp on, then BLACKOUT on "dark"', draw(lt, d, t) {
+      const off = lt > dark;
+      K.livingRoom({ night: true, lampOn: !off });
+      if (off) { ctx.fillStyle = 'rgba(5,8,18,0.62)'; ctx.fillRect(-300, -300, W + 600, H + 600); }
+      K.person({ glow: true, x: 520, y: GROUND, h: 840, mood: off ? 'scared' : 'calm', look: off ? [Math.sin(lt * 4), -0.3] : [0.5, 0], blink: off ? 0 : blink(t), arms: off ? { L: [-30, 40], R: [-30, 40] } : undefined });
+      K.counterPill('9:00 P.M.', 540, 300, eob(seg(lt, 0, 0.25)));
+      K.cinemaBars(off ? eo(seg(lt, dark, dark + 0.3)) : 0);
+    } });
+    cue(st, 'whoosh'); cue(st + dark, 'thud'); cue(st + dark + 0.05, 'whoosh', { gain: 0.6 }); }
+
+  // 3 · step one: don't touch the fridge
+  { const st = cut(2), fr = Wd('fridge', 2) - st;
+    add({ id: 'S03', at: st, cam: [400, 1100], note: 'kitchen, hand stops before the fridge', draw(lt, d, t) {
+      K.kitchen({ night: true }); ctx.fillStyle = 'rgba(5,8,18,0.35)'; ctx.fillRect(-300, -300, W + 600, H + 600);
+      const reach = eio(seg(lt, 0.1, fr)), stop = lt > fr;
+      K.person({ glow: true, x: 560, y: GROUND, h: 840, dir: -1, mood: stop ? 'determined' : 'calm', look: [-1, 0], arms: { L: [-6, 12], R: [lerp(10, stop ? 40 : 75, reach), 10] }, blink: blink(t) });
+      if (stop) K.cross(260, 760, eob(seg(lt, fr, fr + 0.25)));
+      K.stepCard(1, "DON'T OPEN IT", 540, 300, eob(seg(lt, 0.05, 0.3)));
+    } });
+    cue(st, 'whoosh'); cue(st + 0.05, 'pop'); cue(st + fr, 'boing', { gain: 0.5 }); }
+
+  // 4 · closed fridge = 4 hours, full freezer = 2 days
+  { const st = cut(3), h4 = Wd('four', 3) - st, fz = Wd('freezer', 3) - st;
+    add({ id: 'S04', at: st, cam: [300, 1050], zoom: 0.08, note: 'fridge with 4 HOURS and 2 DAYS timers', draw(lt, d, t) {
+      K.kitchen({ night: true }); ctx.fillStyle = 'rgba(5,8,18,0.35)'; ctx.fillRect(-300, -300, W + 600, H + 600);
+      K.person({ glow: true, x: 640, y: GROUND, h: 840, dir: -1, mood: lt > fz ? 'happy' : 'calm', look: [-1, -0.5], blink: blink(t) });
+      K.counterPill('FRIDGE: 4 HOURS', 330, 560, lt > h4 ? eob(seg(lt, h4, h4 + 0.25)) : 0);
+      K.counterPill('FREEZER: 2 DAYS', 330, 430, lt > fz ? eob(seg(lt, fz, fz + 0.25)) : 0);
+      if (lt > fz + 0.5) K.check(170, 900, eob(seg(lt, fz + 0.5, fz + 0.75)));
+    } });
+    cue(st, 'whoosh'); cue(st + h4, 'pop'); cue(st + fz, 'pop'); cue(st + fz + 0.5, 'sparkle', { dur: 0.6 }); }
+
+  // 5 · step two: flashlight, not a candle
+  { const st = cut(4), fl = Wd('flashlight', 4) - st, ca = Wd('candle', 4) - st;
+    add({ id: 'S05', at: st, cam: [540, 1100], note: 'flashlight beam on; candle gets a red X', draw(lt, d, t) {
+      K.livingRoom({ night: true, lampOn: false }); ctx.fillStyle = 'rgba(5,8,18,0.5)'; ctx.fillRect(-300, -300, W + 600, H + 600);
+      const on = lt > fl;
+      K.person({ glow: true, x: 420, y: GROUND, h: 840, mood: 'determined', look: [1, 0], arms: { L: [-6, 14], R: [80, 10] }, hold: (x, y) => K.flashlight(x + 10, y, 1.2, on, -0.05) });
+      K.stepCard(2, 'FLASHLIGHT', 540, 300, eob(seg(lt, 0.05, 0.3)));
+      if (lt > ca) { candle(860, 1250, 1, t); K.cross(860, 1020, eob(seg(lt, ca, ca + 0.25)) * 0.9); }
+    } });
+    cue(st, 'whoosh'); cue(st + 0.05, 'pop'); cue(st + fl, 'tock'); cue(st + ca, 'boing', { gain: 0.5 }); }
+
+  // 6 · candles are a real fire risk (close-up: candle by a curtain)
+  { const st = cut(5);
+    add({ id: 'S06', at: st, cam: [540, 1000], zoom: 0.14, note: 'candle flame licks toward the curtain', draw(lt, d, t) {
+      ctx.fillStyle = P.nWall; ctx.fillRect(-300, -300, W + 600, H + 600); curtain(380, 200, 1150, t * 2);
+      ctx.fillStyle = '#5C4636'; ctx.fillRect(-300, 1380, W + 600, 700);
+      candle(560, 1380, 1.6, t); const glow = ctx.createRadialGradient(560, 1070, 10, 560, 1070, 420); glow.addColorStop(0, 'rgba(242,178,62,0.35)'); glow.addColorStop(1, 'rgba(242,178,62,0)'); ctx.fillStyle = glow; ctx.fillRect(0, 600, W, 900);
+      K.counterPill('FIRE RISK', 540, 330, eob(seg(lt, 0.2, 0.45)));
+    } });
+    cue(st, 'whoosh'); cue(st + 0.2, 'alarm', { dur: 1.2, gain: 0.6 }); }
+
+  // 7 · step three: fill bottles with water
+  { const st = cut(6), wt = Wd('water', 6) - st;
+    add({ id: 'S07', at: st, cam: [540, 1100], note: 'bottles pop onto the counter one by one', draw(lt, d, t) {
+      K.kitchen({ night: true }); ctx.fillStyle = 'rgba(5,8,18,0.3)'; ctx.fillRect(-300, -300, W + 600, H + 600);
+      K.person({ glow: true, x: 230, y: GROUND, h: 840, mood: 'happy', look: [1, 0], blink: blink(t) });
+      for (let i = 0; i < 6; i++) { const p = seg(lt, 0.3 + i * 0.22, 0.5 + i * 0.22); if (p > 0) K.bottle(470 + i * 95, 1060, eob(p) * 1.05); }
+      K.stepCard(3, 'STORE WATER', 540, 300, eob(seg(lt, 0.05, 0.3)));
+    } });
+    cue(st, 'whoosh'); cue(st + 0.05, 'pop'); for (let i = 0; i < 6; i++) cue(st + 0.32 + i * 0.22, 'plop', { gain: 0.45 }); }
+
+  // 8 · a gallon per person, per day
+  { const st = cut(7);
+    add({ id: 'S08', at: st, cam: [540, 1000], zoom: 0.1, note: 'big rule card: 1 gallon / person / day', draw(lt, d, t) {
+      ctx.fillStyle = P.wall; ctx.fillRect(-300, -300, W + 600, H + 600);
+      K.counterPill('1 GALLON', 540, 520, eob(seg(lt, 0.1, 0.35)) * 1.5);
+      K.counterPill('PER PERSON', 540, 720, eob(seg(lt, 0.5, 0.75)) * 1.2);
+      K.counterPill('EVERY DAY', 540, 890, eob(seg(lt, 0.9, 1.15)) * 1.2);
+      K.person({ x: 280, y: 1560, h: 660, mood: 'happy', look: [1, -0.5] }); K.person({ x: 800, y: 1560, h: 600, mood: 'happy', dir: -1, look: [-1, -0.5], cap: '#E2574C' });
+      for (let i = 0; i < 2; i++) K.bottle(450 + i * 180, 1550, 1.3);
+    } });
+    cue(st + 0.1, 'pop'); cue(st + 0.5, 'pop'); cue(st + 0.9, 'pop'); }
+
+  // 9 · step four: unplug your electronics
+  { const st = cut(8), un = Wd('unplug', 8) - st;
+    add({ id: 'S09', at: st, cam: [600, 1200], note: 'hero pulls the TV plug from the socket', draw(lt, d, t) {
+      K.livingRoom({ night: true, lampOn: false }); ctx.fillStyle = 'rgba(5,8,18,0.4)'; ctx.fillRect(-300, -300, W + 600, H + 600);
+      tv(800, 1250, false); socket(560, 1380);
+      const pulled = eio(seg(lt, un, un + 0.4));
+      plug(560 - pulled * 90, 1380, pulled < 0.1);
+      K.person({ glow: true, x: 330, y: GROUND, h: 840, mood: 'determined', look: [1, 0.8], lean: 18, arms: { L: [-6, 14], R: [lerp(60, 50, pulled), 0] } });
+      K.stepCard(4, 'UNPLUG IT', 540, 300, eob(seg(lt, 0.05, 0.3)));
+    } });
+    cue(st, 'whoosh'); cue(st + 0.05, 'pop'); cue(st + un + 0.1, 'pop', { gain: 0.7 }); }
+
+  // 10 · a surge can fry them
+  { const st = cut(9), sg = Wd('surge', 9) - st;
+    add({ id: 'S10', at: st, cam: [540, 1100], zoom: 0.12, note: 'power returns: zap on the TV', draw(lt, d, t) {
+      K.livingRoom({ night: true, lampOn: lt > sg }); ctx.fillStyle = 'rgba(5,8,18,0.35)'; ctx.fillRect(-300, -300, W + 600, H + 600);
+      tv(560, 1350, false); socket(880, 1380); plug(880, 1380, true);
+      if (lt > sg) { const p = seg(lt, sg, sg + 0.6); bolt(560, 1050, eob(clamp(p * 2)) * 1.3); if (Math.floor(lt * 14) % 2 === 0) { ctx.fillStyle = 'rgba(255,240,180,0.25)'; ctx.fillRect(0, 0, W, H); } K.cross(800, 860, eob(seg(lt, sg + 0.3, sg + 0.55)) * 0.8); }
+    } });
+    cue(st, 'whoosh'); cue(st + sg, 'zip'); cue(st + sg + 0.05, 'slam', { gain: 0.6 }); }
+
+  // 11 · day three: lights flicker back on
+  { const st = cut(10), on = Wd('flicker', 10) - st;
+    add({ id: 'S11', at: st, cam: [540, 1050], note: 'DAY 3 card, lamp flickers back on', draw(lt, d, t) {
+      const flick = lt > on && (lt > on + 0.8 || Math.floor(lt * 12) % 2 === 0);
+      K.livingRoom({ night: true, lampOn: flick }); if (!flick) { ctx.fillStyle = 'rgba(5,8,18,0.55)'; ctx.fillRect(-300, -300, W + 600, H + 600); }
+      K.person({ glow: true, x: 520, y: GROUND, h: 840, mood: flick ? 'happy' : 'sleepy', look: [-0.6, -0.8], blink: 0, arms: flick ? { L: [150, 10], R: [150, 10] } : undefined });
+      K.counterPill('DAY 3', 540, 300, eob(seg(lt, 0, 0.25)));
+    } });
+    cue(st, 'whoosh'); cue(st + on, 'tock'); cue(st + on + 0.2, 'tock'); cue(st + on + 0.8, 'sparkle', { dur: 0.8 }); }
+
+  // 12 · because you were ready, you're totally fine
+  { const st = cut(11), fine = Wd('fine', 11) - st;
+    add({ id: 'S12', at: st, cam: [540, 1000], zoom: 0.1, note: 'daylight, hero relaxed, big check', draw(lt, d, t) {
+      K.livingRoom({}); K.person({ x: 480, y: GROUND, h: 860, mood: 'happy', look: [0, 0], blink: blink(t), arms: { L: [-20, 30], R: [130, 60] } });
+      K.check(820, 700, lt > fine - 0.3 ? eob(seg(lt, fine - 0.3, fine)) * 1.3 : 0);
+    } });
+    cue(st, 'whoosh'); cue(st + fine - 0.3, 'sparkle', { dur: 1 }); }
+
+  return { shots: S, cues: CUES };
+}

package/plugins/faceless-shorts/styles/stick-story/example/tools/capture.mjs

@@ -0,0 +1,122 @@
+// Frame-exact capture through headless Chrome. No npm packages (Node 22+). Run from the project folder.
+//   node tools/capture.mjs check                         boot, list shots + captions, report errors
+//   node tools/capture.mjs cues                          write data/cues.json (the sound cues, for tools/mix.py)
+//   node tools/capture.mjs sheet review/all.jpg [step=0.5] [cols=9]   contact sheet, a frame every `step` s, time-stamped
+//   node tools/capture.mjs frames review/full "1.2,8.4"  full-size JPEGs of those times
+//   node tools/capture.mjs video renders/out.mp4 [start end] [--draft]   the film (30 fps) with data/mix.wav if it exists
+//   node tools/capture.mjs preview                       serve the project and print a URL to watch it in a browser
+// CHROME=/path/to/chrome overrides the browser.
+import { spawn, spawnSync } from 'node:child_process';
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FPS = +(process.env.FPS || 30);
+const CHROME = [process.env.CHROME, '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome', '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge', '/usr/bin/google-chrome', '/usr/bin/google-chrome-stable', '/usr/bin/chromium',
+  '/usr/bin/chromium-browser', '/snap/bin/chromium', 'C:/Program Files/Google/Chrome/Application/chrome.exe',
+  'C:/Program Files (x86)/Google/Chrome/Application/chrome.exe'].find((p) => p && fs.existsSync(p));
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const args = process.argv.slice(2), flags = new Set(args.filter((a) => a.startsWith('--')));
+const [mode, ...rest] = args.filter((a) => !a.startsWith('--'));
+
+const MIME = { '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.json': 'application/json', '.otf': 'font/otf',
+  '.ttf': 'font/ttf', '.woff2': 'font/woff2', '.wav': 'audio/wav', '.mp3': 'audio/mpeg', '.png': 'image/png', '.jpg': 'image/jpeg' };
+function serve(port = 0) {
+  return new Promise((res) => {
+    const srv = http.createServer((req, r) => {
+      const u = decodeURIComponent(req.url.split('?')[0]), f = path.join(ROOT, u === '/' ? 'index.html' : u);
+      if (!f.startsWith(ROOT) || !fs.existsSync(f) || fs.statSync(f).isDirectory()) { r.writeHead(404); r.end(); return; }
+      r.writeHead(200, { 'Content-Type': MIME[path.extname(f)] || 'application/octet-stream', 'Cache-Control': 'no-store' });
+      fs.createReadStream(f).pipe(r);
+    });
+    srv.listen(port, '127.0.0.1', () => res(srv));
+  });
+}
+
+async function openPage(port) {
+  if (!CHROME) throw new Error('Chrome not found: install Google Chrome or set CHROME=/path/to/chrome');
+  const prof = fs.mkdtempSync(path.join(os.tmpdir(), 'fs-chrome-'));
+  const chrome = spawn(CHROME, ['--headless=new', '--remote-debugging-port=0', `--user-data-dir=${prof}`, '--no-first-run', '--no-default-browser-check',
+    '--hide-scrollbars', '--window-size=1080,1920', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', ...(process.env.SOFTWARE_GL ? ['--use-angle=swiftshader'] : []), ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []), '--disable-background-timer-throttling', '--disable-renderer-backgrounding', 'about:blank'], { stdio: 'ignore' });
+  let dbg;
+  for (let i = 0; i < 200 && !dbg; i++) { try { dbg = fs.readFileSync(path.join(prof, 'DevToolsActivePort'), 'utf8').split('\n')[0].trim(); } catch { await sleep(100); } }
+  if (!dbg) throw new Error('Chrome did not start');
+  const r = await fetch(`http://127.0.0.1:${dbg}/json/new?${encodeURIComponent(`http://127.0.0.1:${port}/index.html?capture=1${process.env.QS || ''}`)}`, { method: 'PUT' });
+  const target = await r.json();
+  const ws = new WebSocket(target.webSocketDebuggerUrl);
+  await new Promise((res, rej) => { ws.onopen = res; ws.onerror = rej; });
+  let id = 0; const pend = new Map(), logs = [];
+  ws.onmessage = (e) => {
+    const m = JSON.parse(e.data);
+    if (m.id && pend.has(m.id)) { const p = pend.get(m.id); pend.delete(m.id); m.error ? p.rej(new Error(m.error.message)) : p.res(m.result); }
+    else if (m.method === 'Runtime.exceptionThrown') logs.push('EXCEPTION ' + (m.params.exceptionDetails.exception?.description || m.params.exceptionDetails.text));
+    else if (m.method === 'Runtime.consoleAPICalled' && m.params.type === 'error') logs.push('ERROR ' + m.params.args.map((a) => a.value ?? a.description).join(' '));
+  };
+  const send = (method, params = {}) => new Promise((res, rej) => { const i = ++id; pend.set(i, { res, rej }); ws.send(JSON.stringify({ id: i, method, params })); });
+  const ev = async (expr) => { const x = await send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true }); if (x.exceptionDetails) throw new Error(x.exceptionDetails.exception?.description || x.exceptionDetails.text); return x.result.value; };
+  await send('Runtime.enable');
+  for (let i = 0; ; i++) {
+    const st = await ev('window.OP ? (OP.bootError ? "ERR:" + OP.bootError : OP.ready) : false').catch(() => false);
+    if (st === true) break;
+    if (typeof st === 'string') throw new Error('boot failed: ' + st + '\n' + logs.join('\n'));
+    if (i > 1200) throw new Error('boot timeout\n' + logs.join('\n'));
+    await sleep(100);
+  }
+  const close = () => { try { ws.close(); } catch {} chrome.kill('SIGKILL'); setTimeout(() => { try { fs.rmSync(prof, { recursive: true, force: true }); } catch {} }, 300); };
+  return { ev, logs, close };
+}
+const jpg = (d) => Buffer.from(d.slice(d.indexOf(',') + 1), 'base64');
+const FRAME = (t, q, label) => `(() => { const d = OP.frame(${t}, ${q}); ${label ? `const cv = document.getElementById('cv'), c = cv.getContext('2d'); c.setTransform(1,0,0,1,0,0); c.fillStyle = '#000'; c.fillRect(0, 0, 250, 86); c.fillStyle = '#fff'; c.font = '700 60px sans-serif'; c.textAlign = 'left'; c.textBaseline = 'alphabetic'; c.fillText('${(+t).toFixed(2)}', 14, 64); return cv.toDataURL('image/jpeg', ${q});` : 'return d;'} })()`;
+
+const srv = await serve(mode === 'preview' ? 8765 : 0), port = srv.address().port;
+if (mode === 'preview') { console.log(`open http://127.0.0.1:${port}/  (Ctrl+C to stop)`); }
+else {
+  const P = await openPage(port);
+  try {
+    const dur = await P.ev('OP.duration()');
+    if (mode === 'check') {
+      console.log(`duration ${dur.toFixed(2)} s`);
+      for (const s of await P.ev('OP.shots()')) console.log(`${s.id.padEnd(5)} ${s.at.toFixed(2).padStart(6)} → ${s.end.toFixed(2).padStart(6)}  (${(s.end - s.at).toFixed(2)} s)  ${s.note}`);
+      console.log('captions:'); for (const c of await P.ev('OP.captions()')) console.log(`  ${c.s.toFixed(2).padStart(6)}–${c.e.toFixed(2).padEnd(6)} ${c.text}`);
+      let bad = 0; for (let t = 0; t < dur; t += 0.25) { try { await P.ev(`OP.draw(${t})`); } catch (e) { bad++; console.log(`ERROR at ${t.toFixed(2)}: ${e.message.split('\n')[0]}`); } }
+      if (P.logs.length) console.log(P.logs.join('\n'));
+      console.log(bad || P.logs.length ? 'CHECK FAILED' : 'CHECK OK');
+    } else if (mode === 'cues') {
+      const cues = await P.ev('OP.cues()');
+      fs.mkdirSync(path.join(ROOT, 'data'), { recursive: true });
+      fs.writeFileSync(path.join(ROOT, 'data/cues.json'), JSON.stringify({ duration: dur, cues }, null, 1));
+      console.log(`data/cues.json: ${cues.length} cues, ${dur.toFixed(2)} s`);
+    } else if (mode === 'frames') {
+      const dir = path.resolve(ROOT, rest[0] || 'review/frames'); fs.mkdirSync(dir, { recursive: true });
+      for (const t of (rest[1] || '0').split(',').map(Number)) { fs.writeFileSync(path.join(dir, `t${t.toFixed(2)}.jpg`), jpg(await P.ev(FRAME(t, 0.92)))); }
+      console.log(dir);
+    } else if (mode === 'sheet') {
+      const out = path.resolve(ROOT, rest[0] || 'review/all.jpg'), step = +(rest[1] || 0.5), cols = +(rest[2] || 9);
+      const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'fs-sheet-')); let n = 0;
+      for (let t = step / 2; t < dur; t += step) fs.writeFileSync(path.join(tmp, `f${String(n++).padStart(4, '0')}.jpg`), jpg(await P.ev(FRAME(t, 0.8, true))));
+      const rows = Math.ceil(n / cols); fs.mkdirSync(path.dirname(out), { recursive: true });
+      const r = spawnSync('ffmpeg', ['-v', 'error', '-y', '-framerate', '1', '-i', path.join(tmp, 'f%04d.jpg'), '-vf', `scale=216:384,tile=${cols}x${rows}:padding=4:color=black`, '-frames:v', '1', '-q:v', '3', out]);
+      fs.rmSync(tmp, { recursive: true, force: true });
+      if (r.status) throw new Error('ffmpeg: ' + r.stderr); console.log(`${out} (${n} frames, every ${step} s)`);
+    } else if (mode === 'video') {
+      const out = path.resolve(ROOT, rest[0] || 'renders/video.mp4'); fs.mkdirSync(path.dirname(out), { recursive: true });
+      const mix = path.join(ROOT, 'data/mix.wav'), hasMix = fs.existsSync(mix), a0 = rest[1] ? +rest[1] : 0, a1 = rest[2] ? Math.min(+rest[2], dur) : dur, n = Math.round((a1 - a0) * FPS);
+      const ff = spawn('ffmpeg', ['-v', 'error', '-y', '-f', 'image2pipe', '-framerate', String(FPS), '-i', '-',
+        ...(hasMix ? ['-ss', String(a0), '-t', String(a1 - a0), '-i', mix] : ['-f', 'lavfi', '-i', 'anullsrc=r=48000:cl=stereo']), '-map', '0:v', '-map', '1:a',
+        '-c:v', 'libx264', '-preset', flags.has('--draft') ? 'ultrafast' : 'veryfast', '-crf', flags.has('--draft') ? '28' : '18', '-pix_fmt', 'yuv420p',
+        '-c:a', 'aac', '-b:a', '192k', '-shortest', '-movflags', '+faststart', out], { stdio: ['pipe', 'inherit', 'inherit'] });
+      const t0 = Date.now();
+      for (let i = 0; i < n; i++) {
+        const b = jpg(await P.ev(FRAME(a0 + i / FPS, flags.has('--draft') ? 0.8 : 0.93)));
+        if (!ff.stdin.write(b)) await new Promise((r) => ff.stdin.once('drain', r));
+        if (i % 150 === 0) process.stdout.write(`\r${i}/${n} frames`);
+      }
+      ff.stdin.end(); await new Promise((r) => ff.on('close', r));
+      console.log(`\r${out} (${n} frames, ${hasMix ? 'with data/mix.wav' : 'SILENT: no data/mix.wav'}, ${((Date.now() - t0) / 1000).toFixed(0)} s)`);
+    } else console.log('modes: check · cues · sheet · frames · video · preview');
+  } finally { P.close(); srv.close(); }
+}

package/plugins/faceless-shorts/styles/stick-story/example/tools/mix.py

@@ -0,0 +1,172 @@
+"""Inside Out soundtrack: narration + soft procedural sound effects + a quiet music bed, all made here with numpy.
+No samples, no AI audio, no downloads.
+
+  python3 tools/mix.py [project=.]          → data/mix.wav (48 kHz stereo)
+
+Reads data/cues.json (node tools/capture.mjs cues), data/narration.wav if it exists (voice.py or words.py --audio),
+and script.json "music": "bed" (the procedural score, default) · "none" · "audio/your-track.mp3" (your own royalty-free
+track, any format ffmpeg reads). The music ducks under the voice.
+
+Sound rules (STYLE.md): every effect is soft and rounded, nothing above ~5 kHz, no ticks / hats / glitches / beeps.
+Cue types: whoosh slide pop plop gulp boing bubbles sizzle sparkle thud slam tock zip alarm  (+ gain, dur)
+"""
+import json, subprocess, sys
+from pathlib import Path
+import numpy as np
+from scipy import signal
+from scipy.io import wavfile
+
+P = Path(sys.argv[1] if len(sys.argv) > 1 else '.')
+SR = 48000
+rng = np.random.default_rng(11)
+cj = json.loads((P / 'data/cues.json').read_text())
+script = json.loads((P / 'script.json').read_text())
+DUR = float(cj['duration'])
+N = int(DUR * SR) + SR // 10
+
+
+def lp(x, f, o=2): b, a = signal.butter(o, min(f, SR / 2 - 100) / (SR / 2), 'low'); return signal.lfilter(b, a, x)
+def hp(x, f, o=2): b, a = signal.butter(o, f / (SR / 2), 'high'); return signal.lfilter(b, a, x)
+def bp(x, f0, f1, o=2): b, a = signal.butter(o, [f0 / (SR / 2), f1 / (SR / 2)], 'band'); return signal.lfilter(b, a, x)
+def db(x): return 10 ** (x / 20)
+def tt(d): return np.arange(int(d * SR)) / SR
+def env(n, a=0.005, r=None):
+    """attack a seconds then exponential release over the rest"""
+    e = np.ones(n); na = max(1, int(a * SR)); e[:na] = np.linspace(0, 1, na)
+    rest = n - na; e[na:] = np.exp(-np.linspace(0, r or 5, rest)) if rest > 0 else 1; return e
+def sweep(f0, f1, d, shape='exp'):
+    t = tt(d); f = f0 * (f1 / f0) ** (t / d) if shape == 'exp' else f0 + (f1 - f0) * t / d
+    return np.sin(2 * np.pi * np.cumsum(f) / SR)
+def noise(d): return rng.standard_normal(int(d * SR))
+
+
+# ---------- the effects ----------
+def whoosh(d=0.38, **_):
+    n = noise(d); lo, hi = lp(n, 500), lp(n, 2200)
+    k = np.sin(np.pi * np.linspace(0, 1, len(n))); x = (lo * (1 - k) + hi * k) * k ** 1.5
+    return x / (np.abs(x).max() + 1e-9) * 0.5
+def slide(d=1.0, **_):
+    n = lp(noise(d), 700); e = np.sin(np.pi * np.linspace(0, 1, len(n))) ** 2
+    return n / (np.abs(n).max() + 1e-9) * e * 0.35 + sweep(260, 120, d) * e * 0.08
+def pop(**_): x = sweep(560, 240, 0.11) * env(int(0.11 * SR), 0.002, 6); return lp(x, 3000) * 0.7
+def plop(**_): x = sweep(700, 180, 0.14) * env(int(0.14 * SR), 0.002, 5); return lp(x, 2500) * 0.6
+def gulp(**_):
+    a = sweep(320, 140, 0.16) * env(int(0.16 * SR), 0.01, 4); b = sweep(240, 90, 0.2) * env(int(0.2 * SR), 0.01, 4)
+    x = np.concatenate([a, np.zeros(int(0.04 * SR)), b]); return lp(x, 1800) * 0.8
+def boing(**_):
+    d = 0.42; t = tt(d); f = 200 * (1 + 0.6 * t / d) * (1 + 0.08 * np.sin(2 * np.pi * 18 * t))
+    return lp(np.sin(2 * np.pi * np.cumsum(f) / SR) * env(len(t), 0.004, 4), 2000) * 0.55
+def bubbles(d=2.0, **_):
+    x = np.zeros(int(d * SR))
+    for _ in range(int(d * 7)):
+        st = rng.integers(0, max(1, len(x) - int(0.08 * SR))); f = rng.uniform(380, 900); b = sweep(f, f * 1.6, 0.06) * env(int(0.06 * SR), 0.003, 5)
+        x[st:st + len(b)] += b * rng.uniform(0.2, 0.5)
+    return lp(x, 2500) * 0.5
+def sizzle(d=1.0, **_):
+    n = bp(noise(d), 1800, 4500); crack = (rng.random(len(n)) < 0.002).astype(float); crack = lp(crack, 300) * 40
+    e = np.minimum(1, np.linspace(0, 6, len(n))) * np.linspace(1, 0.2, len(n)); return n * (0.4 + crack) * e * 0.12
+def sparkle(d=1.2, **_):
+    notes = [784, 880, 1047, 1175, 1319, 1568]; x = np.zeros(int(d * SR) + SR // 2)
+    for k, f in enumerate(notes):
+        st = int(k * d / len(notes) * SR); n = int(0.4 * SR); t = tt(0.4)
+        x[st:st + n] += (np.sin(2 * np.pi * f * t) + 0.3 * np.sin(4 * np.pi * f * t)) * env(n, 0.004, 6) * 0.22
+    return lp(x, 4500)
+def thud(**_):
+    d = 0.35; t = tt(d); x = np.sin(2 * np.pi * (70 + 40 * np.exp(-t * 30)) * t) * env(len(t), 0.002, 7)
+    return x * 0.9 + lp(noise(d), 220) * env(len(t), 0.001, 12) * 0.3
+def slam(**_):
+    d = 0.5; t = tt(d); x = np.sin(2 * np.pi * (60 + 60 * np.exp(-t * 25)) * t) * env(len(t), 0.002, 6)
+    return np.tanh(1.6 * (x + lp(noise(d), 1200) * env(len(t), 0.001, 10) * 0.6)) * 0.9
+def tock(**_): d = 0.09; t = tt(d); return (np.sin(2 * np.pi * 420 * t) + 0.3 * np.sin(2 * np.pi * 840 * t)) * env(len(t), 0.001, 9) * 0.35
+def zip_(**_):
+    d = 0.32; n = bp(noise(d), 400, 3000); k = np.linspace(0, 1, len(n))
+    return (n / (np.abs(n).max() + 1e-9) * 0.35 + sweep(300, 1100, d) * 0.12) * np.sin(np.pi * k) ** 1.2
+def alarm(d=2.0, **_):
+    x = np.zeros(int(d * SR)); one = np.sin(2 * np.pi * 150 * tt(0.22)) * env(int(0.22 * SR), 0.02, 5)
+    for st in np.arange(0, d - 0.25, 0.5): i = int(st * SR); x[i:i + len(one)] += one
+    return lp(x, 900) * 0.55
+
+def inhale(d=1.0, **_):
+    n = bp(noise(d), 300, 2600); k = np.linspace(0, 1, len(n)); e = np.sin(np.pi * np.minimum(1, k * 1.15)) ** 1.5 * (0.6 + 0.4 * k)
+    return n / (np.abs(n).max() + 1e-9) * e * 0.5
+def heartbeat(**_):
+    one = lambda d, f: np.sin(2 * np.pi * f * tt(d)) * env(int(d * SR), 0.004, 7)
+    x = np.concatenate([one(0.16, 58), np.zeros(int(0.09 * SR)), one(0.2, 52) * 0.75]); return lp(x, 300) * 1.0
+
+FX = dict(inhale=inhale, heartbeat=heartbeat, whoosh=whoosh, slide=slide, pop=pop, plop=plop, gulp=gulp, boing=boing, bubbles=bubbles, sizzle=sizzle,
+          sparkle=sparkle, thud=thud, slam=slam, tock=tock, zip=zip_, alarm=alarm)
+LEVEL = dict(inhale=-15, heartbeat=-8, whoosh=-17, slide=-19, pop=-14, plop=-15, gulp=-11, boing=-15, bubbles=-21, sizzle=-18, sparkle=-17,
+             thud=-11, slam=-9, tock=-18, zip=-14, alarm=-17)
+
+
+# ---------- the music bed: soft pad + plucked arpeggio, 100 BPM, I–vi–IV–V ----------
+def music_bed():
+    bpm = 100; beat = 60 / bpm; bar = beat * 4
+    chords = [[261.6, 329.6, 392.0], [220.0, 261.6, 329.6], [174.6, 220.0, 261.6], [196.0, 246.9, 293.7]]
+    x = np.zeros(N)
+    nb = int(np.ceil(DUR / bar)) + 1
+    for b in range(nb):
+        ch = chords[b % 4]; st = int(b * bar * SR); n = int(bar * SR)
+        if st >= N: break
+        t = tt(bar); e = np.minimum(1, t / 0.4) * np.minimum(1, (bar - t) / 0.4)
+        pad = sum(np.sin(2 * np.pi * f / 2 * t) + 0.25 * np.sin(2 * np.pi * f * t) for f in ch) * e * 0.10
+        x[st:st + n] += pad[:max(0, min(n, N - st))]
+        for k in range(8):                                                       # eighth-note pluck arpeggio
+            f = ch[[0, 1, 2, 1, 2, 0, 1, 2][k]] * (2 if k % 4 == 2 else 1); ps = st + int(k * beat / 2 * SR); pn = int(0.5 * SR)
+            if ps + pn >= N: continue
+            pt = tt(0.5); pl = (np.sin(2 * np.pi * f * pt) + 0.35 * np.sin(4 * np.pi * f * pt)) * env(pn, 0.003, 7) * 0.12
+            x[ps:ps + pn] += pl
+    x = lp(x, 3200)
+    fade = np.ones(N); fo = int(1.2 * SR); fade[-fo:] = np.linspace(1, 0, fo)
+    return x / (np.abs(x).max() + 1e-9) * fade
+
+def music_tension():
+    """low drone + slow minor pulse, for mysterious / tense explainers (script.json "music": "tension")"""
+    t = np.arange(N) / SR; x = np.zeros(N)
+    for f, g in [(55, 0.5), (82.4, 0.3), (110, 0.2), (130.8, 0.12)]: x += np.sin(2 * np.pi * f * t + np.sin(t * 0.3) * 0.5) * g
+    x *= 0.55 + 0.45 * np.sin(2 * np.pi * t / 8) ** 2
+    beat = 60 / 84; ping = lambda f: (np.sin(2 * np.pi * f * tt(1.2)) + 0.3 * np.sin(4 * np.pi * f * tt(1.2))) * env(int(1.2 * SR), 0.01, 5)
+    seq = [220.0, 261.6, 196.0, 174.6]
+    for k in range(int(DUR / (beat * 2))):
+        i = int(k * beat * 2 * SR); pg = ping(seq[(k // 2) % 4]) * 0.35
+        if i + len(pg) < N: x[i:i + len(pg)] += pg
+    x = lp(x, 2200); fade = np.ones(N); fo = int(1.5 * SR); fade[-fo:] = np.linspace(1, 0, fo); fi = int(0.8 * SR); fade[:fi] *= np.linspace(0, 1, fi)
+    return x / (np.abs(x).max() + 1e-9) * fade
+
+def load_audio(f):
+    out = subprocess.run(['ffmpeg', '-v', 'error', '-i', str(f), '-f', 'f32le', '-ac', '2', '-ar', str(SR), '-'], capture_output=True, check=True).stdout
+    a = np.frombuffer(out, dtype=np.float32).reshape(-1, 2).astype(np.float64); return a
+
+
+mix = np.zeros((N, 2))
+# voice
+vf = P / 'data/narration.wav'
+voice = None
+if vf.exists():
+    v = load_audio(vf)[:N]; voice = np.zeros((N, 2)); voice[:len(v)] = v
+    rms = np.sqrt(np.mean(voice ** 2) + 1e-12); voice *= db(-19) / rms
+    mix += voice
+# music
+mus = script.get('music', 'bed')
+if mus and mus != 'none':
+    m = music_bed() if mus == 'bed' else music_tension() if mus == 'tension' else None
+    if m is None:
+        a = load_audio(P / mus)[:N]; m = np.zeros(N); m[:len(a)] = a.mean(1); m /= np.abs(m).max() + 1e-9
+    m = np.stack([m, m], 1) * db(-24 if voice is not None else -20)
+    if voice is not None:                                                        # duck under the voice
+        lev = np.abs(voice.mean(1)); lev = signal.lfilter([1 - 0.9995], [1, -0.9995], lev); lev /= lev.max() + 1e-9
+        m *= (1 - 0.55 * np.clip(lev * 3, 0, 1))[:, None]
+    mix += m
+# effects
+for c in cj['cues']:
+    fn = FX.get(c['type'])
+    if not fn: print('unknown cue type, skipped:', c['type']); continue
+    x = fn(**({'d': c['dur']} if c.get('dur') else {}))
+    x = lp(x, 5000) * db(LEVEL[c['type']]) * c.get('gain', 1.0) / (np.abs(x).max() + 1e-9) * 0.9
+    i = int(c['t'] * SR); n = min(len(x), N - i)
+    if n > 0 and i >= 0: pan = c.get('pan', 0.0); mix[i:i + n, 0] += x[:n] * (1 - max(0, pan)); mix[i:i + n, 1] += x[:n] * (1 + min(0, pan))
+# master: gentle soft-clip, peak -1 dBFS
+mix = np.tanh(mix * 1.2) / 1.2
+mix *= db(-1) / (np.abs(mix).max() + 1e-9)
+wavfile.write(P / 'data/mix.wav', SR, (mix * 32767).astype(np.int16))
+print(f"data/mix.wav: {DUR:.2f} s · voice: {'yes' if voice is not None else 'NO (captions-only)'} · music: {mus} · {len(cj['cues'])} cues")

package/plugins/faceless-shorts/styles/tall-tale/STYLE.md

@@ -0,0 +1,51 @@
+# Tall Tale 3D: funny true stories, 9:16
+
+Playful, clever, a little cheeky. Flat 2D cartoon people (thick ink outlines, big round white heads, bean bodies, stick
+limbs) acting inside a sunny, saturated 3D world: small-town streets, wallpapered shops, meadows, trains. The camera moves
+in every shot, faces react on every beat, captions come one word at a time.
+Example: `example/` = **THE GIRL WHO WAS MAILED TO GRANDMA** (1914; 52 s, 21 shots). Sheet: `style-sheet.png`.
+
+## 1. Rules
+- **People are 2D, the world is 3D.** Every person is a `Toon` cut-out that turns to face the camera and casts a real
+  shadow. Never build people in 3D; never draw sets flat.
+- **Faces do the acting.** Change the mood on the beat: `smug` when someone's clever, `shock` on the reveal, `laugh` /
+  `happy` for the payoff, `worried` + `sweat` for trouble. Blink with `blink(t)`, talk with `talk(t)`.
+- One hat + one neck thing per character; same look all video. Kids: `kid: true` (short legs) and `height: 1.4`.
+- Camera always moving: push-ins, pans, crane-downs, a punch-in on the reveal word. New shot every 1.5-3 s.
+- Bright midday sun outside, warm bulbs inside, pink sunset for endings or flashbacks.
+- Captions: one word at a time (short words pair up: "a single"), white Inter Black with a black edge and soft shadow,
+  centre screen (y 1340). No colour highlight. Words keep their punctuation.
+- Story shape: open on the most surprising fact ("they mailed their daughter"), then "See, ..." rewind and explain the
+  trick step by step, one picture per clause, short reaction beats, end on a punchline that flips the start.
+- Narration: upbeat storyteller, `am_michael` x1.05. Music `"bounce"` (light comedy). Lots of small sounds: `pop`,
+  `plop`, `boing`, `stamp`, `ding`, `chirp`, `chug`, `whoosh` on cuts.
+- True stories only, checked against good sources (museums, encyclopaedias, major outlets) and listed in `script.json`
+  "sources". If sources disagree on a number, use the one most of them give and keep the wording simple.
+
+## 2. Engine map (`example/src/`)
+| file | gives you |
+|---|---|
+| `core/engine.js` | `makeEngine` (neutral tone curve, soft shadows, bloom, depth of field, saturation grade), `camera(fov)` |
+| `core/toon.js` | `drawToon(g, look, st)` (2D drawing), `new Toon(look, { height, res })` (3D cut-out: `.at(x,y,z)`, `.set(st)`, `.face(cam)`, `.tint(col)`, `.restyle(patch)`), `PROPS` held in hands |
+| `core/world.js` | sets: `mainStreet(E, { shops, dusk })` (returns `buildings` with each shop's position), `interior(E, { wall, motif, floor, ceiling, view, signText, counterOn })`, `meadow(E, { sunset, fenceOn })`; pieces: `sky, clouds, sunlight, hills, tree, pole, wire, lamp, barrel, crate, car, fence, bunting, signBoard, facade, extras`; painted textures `T.planks/wallpaper/brick/siding/dirt/grass/felt`; `snapshot(E, scene, cam)` renders a set into a texture (window views) |
+| `core/props.js` | `house()` (`.door` opens), `signpost`, `platformScale()` (`.set(lbs)`), `train()` (`.update(t)`), `rails`, `cubbies`, `mailSack`, `parcel`, `desk`, `poster(lines)`, `chickCrate()` |
+| `core/captions.js` | one-word captions, `captionText(text, x, y)` |
+
+**Toon look**: `{ body, pattern: plain│check│stripes│overalls│vest│apron│stamps, patCol, hat: none│cap│bowler│boater│beanie│visor│tophat│bun│flower│bow│mailcap, hatCol, band, neck: none│bowtie│tie│scarf│collar, neckCol, dots, extra: [mustache, glasses, freckles, blush, pencil, monocle], kid, stamps }`.
+**Toon state**: `{ mood: neutral│smug│happy│laugh│shock│worried│angry│sad│sly│proud│tired│dizzy, look: [dx, dy], blink, talk,
+sweat, tears, armL / armR: [shoulder°, elbow°] (0 = down, 150 = up), legs: stand│walk│run│sit│jump, phase, lean, bob,
+holdL / holdR: PROPS.x, flip }`. A prop made with arguments (`PROPS.book('RULES', 1)`) needs a `v: 'something'` in the
+state that changes when the prop changes, so the cut-out redraws.
+Positions: people stand at y 0 (boardwalks y 0.18, on a counter y 1.26). Interior counter: x 2.2..3.2, clerk at x 3.55.
+
+## 3. Shot anatomy (see `example/src/shots.js`)
+Build every set once at the top, give each set its own cut-outs, then per shot: place people, `set()` their state from
+`t`, `shoot(scene, people, camFrom, camTo, lookFrom, lookTo, k, LOOK)` (moves the camera, turns everyone to face it,
+renders with depth of field), `blit()`, then any 2D overlay (a RETURN TO SENDER stamp). Cues go on the word
+(`cue(Wd('banned', 17), 'stamp')`).
+
+## 4. QA pitfalls
+- A cut-out seen from the side becomes a sliver: keep the camera within ~60° of facing people (`.face(cam)` handles the rest).
+- People inside furniture: check feet heights (boardwalk 0.18, counter top 1.18 + scale 0.08).
+- Shadows only fall inside the sun's shadow box: move `sun.key.target` near the action when you build a new set.
+- Rendering speed: same as Deep Dive (`SOFTWARE_GL=1 QS='&res=0.6&aa=0&shadow=1024' FPS=24` without a GPU, ≈2-3 s/frame).