npm - xevol - Versions diffs - 0.16.0 → 0.17.1 - Mend

xevol 0.16.0 → 0.17.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (17) hide show

package/dist/index.js +291 -265
package/package.json +3 -1
package/skills/xevol-film/SKILL.md +170 -0
package/starters/blank/README.md +12 -0
package/starters/blank/assets/fonts/OFL-Onest.txt +93 -0
package/starters/blank/assets/fonts/onest-cyrillic-wght-normal.woff2 +0 -0
package/starters/blank/assets/fonts/onest-latin.woff2 +0 -0
package/starters/blank/film.html +101 -0
package/starters/blank/render.json +5 -0
package/starters/blank/scripts/mix.py +121 -0
package/starters/earshot-ad/README.md +25 -0
package/starters/earshot-ad/assets/fonts/OFL-Onest.txt +93 -0
package/starters/earshot-ad/assets/fonts/onest-latin.woff2 +0 -0
package/starters/earshot-ad/film.html +193 -0
package/starters/earshot-ad/render.json +5 -0
package/starters/earshot-ad/scripts/finish.py +178 -0
package/starters/earshot-ad/scripts/mix.py +208 -0

package/starters/earshot-ad/film.html ADDED Viewed

@@ -0,0 +1,193 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>MotionPls — every cut can land</title>
+<style>
+@font-face { font-family: "Onest"; src: url("assets/fonts/onest-latin.woff2") format("woff2"); font-weight: 100 900; }
+html, body { margin: 0; background: #000; }
+canvas { display: block; }
+</style>
+</head>
+<body>
+<canvas id="frame"></canvas>
+<script>
+// "Every cut can land." — a 12 s mute-first 9:16 ad for MotionPls, 24 beats at 120 BPM.
+// PICTURE: every frame is a pure function of t (seek). No images, no video, no external assets but the font.
+// SOUND: the whole soundtrack is rendered from earshot's sound bank by scripts/mix.py — no recorded audio,
+// no Mixkit, no music track. Every cue below is a bank sound placed where the picture lands on it; mix.py reads
+// window.CUES, renders each id with its own knobs (apex for whooshes and risers, pitch for the bell), and writes
+// the measured onset of every placed cue to out/sound.json.
+//   0-2   paper: "your ad is silent." Deliberately dry; nothing lands.
+//   2-4   the word drops, "So nothing lands." types in on three ticks.
+//   4-6   ink floods, the score starts, two hits land on the ruler.
+//   6-8   four bars grow on the beat: whoosh, hit, tick, riser; the riser runs into the drop.
+//   8-10  orange flood: "From $299." lands hard.
+//   10-12 the mark, the chime, "Book a call", the tail.
+const W = 1080, H = 1920, CX = W / 2, FPS = 60, DUR = 12;
+const PAPER = '#f3f1ec', INK = '#0b0b0c', GREY = '#8b8b90', ORANGE = '#ff4d00', LIME = '#d6ff3b';
+const BEAT = 0.5;   // 120 BPM
+// Every sound cue the picture places. mix.py maps the kind to a bank id; the time is the picture's own.
+const CUES = [
+  {t: 2.00, kind: 'impact'},                                                    // the word hits the floor
+  {t: 2.35, kind: 'tick'}, {t: 2.60, kind: 'tick'}, {t: 2.85, kind: 'tick'},     // one per word
+  {t: 4.00, kind: 'whoosh'},                                                    // the ink floods in
+  {t: 4.85, kind: 'hit'}, {t: 5.35, kind: 'hit'},                                // "sound", "on the cut"
+  {t: 6.00, kind: 'tick'}, {t: 6.50, kind: 'tick'}, {t: 7.00, kind: 'tick'}, {t: 7.50, kind: 'tick'},
+  {t: 6.80, kind: 'riser'},                                                     // runs into the drop at 8.0
+  {t: 8.00, kind: 'impact'},                                                    // "From $299."
+  {t: 8.90, kind: 'tick'},
+  {t: 10.00, kind: 'chime'}, {t: 10.55, kind: 'pop'}, {t: 11.10, kind: 'tick'},
+];
+window.CUES = CUES; window.DUR = DUR;
+const clamp = (x, a = 0, b = 1) => Math.min(b, Math.max(a, x));
+const lerp = (a, b, k) => a + (b - a) * k;
+const eOut = k => 1 - Math.pow(1 - clamp(k), 3);
+const eIn = k => Math.pow(clamp(k), 3);
+const eInOut = k => { k = clamp(k); return k < 0.5 ? 4 * k * k * k : 1 - Math.pow(-2 * k + 2, 3) / 2; };
+const eBack = k => { k = clamp(k); const c = 1.7; return 1 + (c + 1) * Math.pow(k - 1, 3) + c * Math.pow(k - 1, 2); };
+const at = (t, a, d = 0.34) => clamp((t - a) / d);         // progress of an element appearing at `a`
+const main = document.getElementById('frame');
+main.width = W; main.height = H;
+const M = main.getContext('2d');
+function font(size, weight = 800) {
+  M.font = `${weight} ${size}px Onest, system-ui, sans-serif`;
+  M.letterSpacing = size >= 110 ? `${(-0.045 * size).toFixed(1)}px` : `${(-0.012 * size).toFixed(1)}px`;
+}
+function word(s, x, y, size, color, {k = 1, weight = 800, align = 'center', dy = 0, ls = null} = {}) {
+  if (k <= 0 || !s) return;
+  M.save();
+  M.globalAlpha *= k;
+  font(size, weight);
+  if (ls !== null) M.letterSpacing = `${ls}px`;
+  M.fillStyle = color; M.textAlign = align; M.textBaseline = 'middle';
+  M.fillText(s, x, y + dy);
+  M.restore();
+}
+function rr(x, y, w, h, r) { M.beginPath(); M.roundRect(x, y, w, h, r); }
+function disc(x, y, r, c) { if (r > 0) { M.fillStyle = c; M.beginPath(); M.arc(x, y, r, 0, 7); M.fill(); } }
+function panel(yTop, h, c) { M.fillStyle = c; M.fillRect(0, yTop, W, h); }
+// a centred line built from words that appear at different times (`parts`: [{s, color, at}])
+function wordsLine(t0, parts, cx, y, size, weight = 800) {
+  const gap = size * 0.26;
+  M.save(); font(size, weight);
+  const ws = parts.map(p => M.measureText(p.s).width);
+  const total = ws.reduce((a, b) => a + b, 0) + gap * (parts.length - 1);
+  M.restore();
+  let x = cx - total / 2;
+  parts.forEach((p, i) => {
+    const k = eOut(at(t0, p.at, 0.26));
+    if (k > 0) word(p.s, x, y + 34 * (1 - k), size, p.color, {weight, k, align: 'left'});
+    x += ws[i] + gap;
+  });
+}
+function draw(t) {
+  const jolt = t >= 2 ? 11 * Math.sin((t - 2) * 95) * Math.exp(-(t - 2) * 17) : 0;
+  // ------------------------------------------------------------------ A/B: paper, the dry ad (0 - 4 s)
+  panel(0, H, PAPER);
+  M.save(); M.translate(0, jolt);
+  word('MOTIONPLS', 96, 424, 26, GREY, {weight: 700, align: 'left', ls: 9, k: at(t, 0.05, 0.3)});
+  // "your ad" leaves as the next idea arrives, so the two lines never sit on each other
+  const leave = eOut(at(t, 2.0, 0.3));
+  word('your ad', CX, 848 - 54 * leave, 168, INK, {k: eOut(at(t, 0.15)) * (1 - leave)});
+  const drop = eIn(at(t, 2.0, 0.36));
+  word('is silent.', CX, 1040 + 780 * drop, 168, ORANGE, {k: 1 - drop});
+  const ul = eOut(at(t, 1.35, 0.42)) * (1 - clamp((t - 2.0) / 0.2));
+  if (ul > 0) { M.globalAlpha = ul; M.fillStyle = INK; M.fillRect(CX - 250 * ul, 1146, 500 * ul, 5); M.globalAlpha = 1; }
+  // "So nothing" on one line, "lands." under it, a tick per word
+  wordsLine(t, [{s: 'So', color: INK, at: 2.35}, {s: 'nothing', color: INK, at: 2.60}], CX, 902, 128);
+  word('lands.', CX + 168, 1052, 128, ORANGE, {k: eOut(at(t, 2.85, 0.26)), dy: 34 * (1 - eOut(at(t, 2.85, 0.26)))});
+  word('sound is half the ad.', CX, 1210, 34, GREY, {weight: 600, k: at(t, 3.3, 0.3)});
+  M.restore();
+  // ------------------------------------------------------------------ C/D: ink, the score (4 - 8 s)
+  const inkK = eInOut(at(t, 4.0, 0.3));
+  if (inkK > 0) {
+    panel(H - H * inkK, H * inkK, INK);
+    const settle = eOut(at(t, 6.0, 0.45));
+    const y = lerp(812, 540, settle), size = lerp(150, 88, settle), gap = lerp(160, 96, settle);
+    const dim = t > 6 ? 0.42 : 1;
+    word('we put', CX, y, size, PAPER, {k: dim * eOut(at(t, 4.35, 0.3)), dy: 40 * (1 - eOut(at(t, 4.35, 0.3)))});
+    word('sound', CX, y + gap, size, LIME, {k: dim * eOut(at(t, 4.85, 0.3)), dy: 40 * (1 - eOut(at(t, 4.85, 0.3)))});
+    word('on the cut.', CX, y + 2 * gap, size, PAPER, {k: dim * eOut(at(t, 5.35, 0.3)), dy: 40 * (1 - eOut(at(t, 5.35, 0.3)))});
+    // the ruler: 4.0 - 6.0 s across the frame, a lime tick where the picture lands
+    const L = 96, R = W - 96, base = 1280;
+    const rk = eOut(at(t, 4.4, 0.9));
+    if (rk > 0.02) {
+      M.strokeStyle = '#3a3a40'; M.lineWidth = 2;
+      M.beginPath(); M.moveTo(L, base); M.lineTo(lerp(L, R, rk), base); M.stroke();
+      for (const tc of [4.85, 5.35, 6.0]) {
+        const k = eOut(at(t, tc, 0.2));
+        if (k <= 0) continue;
+        const x = lerp(L, R, (tc - 4.0) / 2.0);
+        M.strokeStyle = LIME; M.lineWidth = 4;
+        M.beginPath(); M.moveTo(x, base - 30 * k); M.lineTo(x, base + 30 * k); M.stroke();
+      }
+      // four bars grow on the beat, one per cue
+      const bars = [[6.0, 280, 'whoosh'], [6.5, 352, 'hit'], [7.0, 208, 'tick'], [7.5, 312, 'riser']];
+      bars.forEach(([tc, h, label], i) => {
+        const k = eOut(at(t, tc, 0.16));
+        if (k <= 0) return;
+        const x = 252 + i * 192, bw = 58;
+        const hh = h * k * (1 + 0.05 * Math.sin((t - tc) * 7.5 + i));
+        M.fillStyle = LIME; rr(x - bw / 2, base - hh, bw, hh, 10); M.fill();
+        word(label, x, base + 62, 24, GREY, {weight: 600, k});
+      });
+    }
+  }
+  // ------------------------------------------------------------------ E: orange flood (8 - 10 s)
+  const orK = eInOut(at(t, 8.0, 0.3));
+  if (orK > 0) {
+    panel(H - H * orK, H * orK, ORANGE);
+    const land = eOut(at(t, 8.06, 0.26));
+    const s = lerp(1.12, 1, land);
+    M.save(); M.translate(CX, 872); M.scale(s, s); M.translate(-CX, -872);
+    word('From $299.', CX, 872, 158, INK, {k: land});
+    M.restore();
+    word('one 30-second promo', CX, 1004, 44, INK, {weight: 600, k: at(t, 8.9, 0.3)});
+  }
+  // ------------------------------------------------------------------ F: ink, the mark (10 - 12 s)
+  const fk = eInOut(at(t, 10.0, 0.28));
+  if (fk > 0) {
+    panel(0, H * fk, INK);
+    const k = at(t, 10.05, 0.4);
+    if (k > 0) {
+      const y = 792, ang = (t - 10) * 1.15, spin = (t - 10) * 2.3;
+      M.save(); M.globalAlpha = k;
+      M.strokeStyle = PAPER; M.lineWidth = 6;
+      M.beginPath(); M.arc(CX, y, 92, 0, 7); M.stroke();
+      M.save(); M.translate(CX, y); M.rotate(ang); M.strokeStyle = '#4a4a52'; M.lineWidth = 3;
+      M.beginPath(); M.ellipse(0, 0, 196, 68, 0, 0, 7); M.stroke(); M.restore();
+      disc(CX + 196 * Math.cos(spin), y + 68 * Math.sin(spin), 16, LIME);
+      M.restore();
+      word('motionpls', CX, 972, 66, PAPER, {weight: 700, ls: 1, k: at(t, 10.3, 0.35)});
+      const pk = eBack(at(t, 10.55, 0.34));
+      if (pk > 0) {
+        const pw = 392, ph = 98, py = 1096 + 34 * (1 - pk);
+        M.save(); M.globalAlpha = clamp(pk); M.fillStyle = LIME;
+        rr(CX - pw / 2, py, pw, ph, 49); M.fill(); M.restore();
+        word('Book a call', CX, py + ph / 2 + 2, 40, INK, {weight: 700, k: clamp(pk)});
+      }
+      word('motionpls.com', CX, 1268, 30, GREY, {weight: 600, k: at(t, 11.1, 0.3)});
+    }
+  }
+}
+window.seek = t => { draw(Math.max(0, Math.min(DUR, t))); };
+window.ready = (async () => {
+  await document.fonts.load('900 100px Onest');
+  await document.fonts.load('700 100px Onest');
+  await document.fonts.load('600 100px Onest');
+  draw(0);
+})();
+</script>
+</body>
+</html>

package/starters/earshot-ad/render.json ADDED Viewed

@@ -0,0 +1,5 @@
+{"width": 1080, "height": 1920, "fps": 60, "sub": 4,
+ "duration": 12,
+ "stills": [0.9, 2.6, 3.6, 4.6, 5.6, 6.9, 8.4, 9.6, 10.8, 11.8],
+ "bundle": ["film.html", "assets/**"], "audio": "out/audio.wav",
+ "mix": {"cues": ["--out", "out"], "run": ["scripts/mix.py"], "out": "out/audio.wav"}}

package/starters/earshot-ad/scripts/finish.py ADDED Viewed

@@ -0,0 +1,178 @@
+"""Mux the picture and the earshot soundtrack, then verify the delivered file.
+    /home/kuka/stack-dev/tools/earshot/.venv/bin/python scripts/finish.py
+      -> out/motionpls-earshot-ad-9x16.mp4, a poster, a contact sheet and out/verification.json
+Checks (all measured, none assumed):
+  streams  1080x1920, 60 fps, 720 frames, 12.000 s, stereo AAC 48 kHz
+  audio    ebur128 loudness and true peak on the delivered file; earshot's own measure on out/audio.wav
+  audit    earshot sfx.check on the master: edges, clipping, DC, truncation, digital silence must be clean;
+           clicks are expected from designed hits and are reported, not failed
+  sync     earshot onset detection on the mix, matched to every cue time in out/cues.json (+-40 ms)
+  picture  no lone frame jumps (this film has wipes, not hard cuts, so no jump is allowed)
+"""
+import hashlib
+import json
+import subprocess
+import sys
+from pathlib import Path
+import numpy as np
+try:
+    from earshot import features
+    from earshot.forge import bank, sfx as sfx_audit
+except ImportError as e:  # pragma: no cover - environment guard
+    sys.exit(f'finish.py: {e}\nUse the earshot install: '
+             f'/home/kuka/stack-dev/tools/earshot/.venv/bin/python scripts/finish.py')
+ROOT = Path(__file__).resolve().parent.parent
+OUT = ROOT / 'out'
+def stereo(y):
+    y = np.asarray(y, np.float32)
+    return np.stack([y, y], axis=1) if y.ndim == 1 else y
+W, H, FPS, DUR, SR = 1080, 1920, 60, 12.0, 48000
+FRAMES = round(DUR * FPS)
+MP4 = OUT / 'motionpls-earshot-ad-9x16.mp4'
+FAIL_CODES = {'edge', 'clipping', 'dc', 'truncated', 'silence', 'rising_glide'}
+# warnings this film accepts, with the reason. Anything not listed here fails the gate.
+ALLOWED = {
+    'clicks': 'designed hits: the picture lands on every one of these',
+    'ring': 'the kalimba arpeggio overlaps at 8th notes; earshot reads the tine harmonics as a comb ring '
+            '(the same notes alone measure z 20.5, and every single bank sound measured alone is clean)',
+}
+def run(*a, **kw):
+    return subprocess.run(a, capture_output=True, text=True, check=True, **kw)
+def probe(path):
+    return json.loads(run('ffprobe', '-v', 'error', '-show_streams', '-show_format', '-of', 'json', str(path)).stdout)
+def frames_gray(path, sw, sh):
+    raw = subprocess.run(['ffmpeg', '-v', 'error', '-i', str(path), '-vf', f'scale={sw}:{sh},format=gray',
+                          '-f', 'rawvideo', '-'], capture_output=True, check=True).stdout
+    return np.frombuffer(raw, np.uint8).reshape(-1, sh, sw).astype(np.float32)
+def main():
+    if not (OUT / 'picture.mkv').exists() or not (OUT / 'audio.wav').exists():
+        sys.exit('finish.py: run ../shared/render/render.mjs . --film and scripts/mix.py first')
+    clues = json.loads((OUT / 'cues.json').read_text())
+    sound = json.loads((OUT / 'sound.json').read_text())
+    run('ffmpeg', '-v', 'error', '-y', '-i', str(OUT / 'picture.mkv'), '-i', str(OUT / 'audio.wav'),
+        '-map', '0:v', '-map', '1:a', '-c:v', 'libx264', '-profile:v', 'high', '-preset', 'slow', '-crf', '15',
+        '-pix_fmt', 'yuv420p', '-movflags', '+faststart', '-c:a', 'aac', '-b:a', '256k', '-ar', '48000',
+        '-t', f'{DUR:.6f}', str(MP4))
+    pr = probe(MP4)
+    v = next(s for s in pr['streams'] if s['codec_type'] == 'video')
+    a = next(s for s in pr['streams'] if s['codec_type'] == 'audio')
+    eb = run('ffmpeg', '-hide_banner', '-i', str(MP4), '-af', 'ebur128=peak=true', '-f', 'null', '-').stderr
+    summary = eb.split('Summary:')[-1]
+    lufs = float(summary.split('I:')[1].split('LUFS')[0])
+    tp = float(summary.split('Peak:')[1].split('dBFS')[0])
+    frames = frames_gray(MP4, 216, 384)
+    d = np.abs(np.diff(frames, axis=0)).mean(axis=(1, 2))
+    lone = lambda i: d[i] > 1.0 and d[i] > 3 * max(d[i - 1] if i else 0, d[i + 1] if i + 1 < len(d) else 0, 0.15)
+    pops = [{'t': round((i + 1) / FPS, 3), 'diff': round(float(d[i]), 2)} for i in range(len(d)) if lone(i)]
+    master = features.measure(str(OUT / 'audio.wav'))
+    audit = sfx_audit.check(str(OUT / 'audio.wav'))
+    fails = [w for w in audit['warnings'] if w['code'] in FAIL_CODES or w['code'] not in ALLOWED]
+    # placement, proven on the delivered stem: rebuild the sfx stem from sound.json (each bank sound re-rendered,
+    # deterministic) and compare it sample for sample with the file the picture was muxed from. This proves the
+    # delivered audio contains exactly those sounds at exactly those times. Then report how well a detector finds
+    # them, which is a weaker signal: a riser that runs into a hit masks the hit's own attack.
+    factor = 10 ** (sound['gain_db'] / 20)
+    recon = np.zeros((int(DUR * SR), 2), np.float32)
+    for c in sound['cues']:
+        y, _ = bank.render(c['id'], **c.get('knobs', {}))
+        y = np.asarray(y, np.float32)
+        if y.ndim == 1:
+            y = np.stack([y * (1 - 0.0), y], axis=1) if False else stereo(y)
+        i0 = int(round(c['start_s'] * SR))
+        i1 = min(len(recon), i0 + len(y))
+        recon[i0:i1] += y[:i1 - i0] * 10 ** (c['gain_db'] / 20)
+    recon *= factor
+    delivered = features.audio.load(str(OUT / 'stems' / 'sfx.wav'))
+    diff = float(np.abs(recon - delivered[:len(recon)]).max())
+    worst_off = max(abs(c['offset_ms']) for c in sound['cues'])
+    stem_ok = diff <= 1e-5 and worst_off <= 1000 / FPS
+    # detector view: what earshot's onset detector and envelope correlation make of it in a dense mix
+    hop = int(0.005 * SR)
+    env = lambda x: np.sqrt(np.convolve(np.asarray(x, np.float64) ** 2, np.ones(hop) / hop, mode='same'))
+    senv = env(delivered.mean(axis=1))
+    detected = []
+    for c in [c for c in sound['cues'] if c['kind'] != 'layer']:
+        y, _ = bank.render(c['id'], **c.get('knobs', {}))
+        y = np.asarray(y, np.float64)
+        ref = env(y.mean(axis=1) if y.ndim > 1 else y)
+        lead = min(0.25, max(0.06, 0.3 * len(y) / SR))
+        lo = max(0, int(round((c['start_s'] - lead) * SR)))
+        seg = senv[lo:lo + len(ref) + int(2 * lead * SR)]
+        if len(seg) < len(ref):
+            continue
+        xc = np.correlate(seg - seg.mean(), ref - ref.mean(), mode='valid')
+        lag = (int(np.argmax(xc)) - (lead * SR - (lo - int(round((c['start_s'] - lead) * SR))))) / SR * 1000
+        detected.append({'t': c['t'], 'id': c['id'], 'correlation_lag_ms': round(lag, 1),
+                         'within_one_frame': abs(lag) <= 1000 / FPS})
+    onsets = features.onsets(features.audio.load(str(OUT / 'audio.wav'), mono=True))
+    run('ffmpeg', '-v', 'error', '-y', '-i', str(MP4), '-vf', 'fps=1,scale=216:384,tile=6x2:padding=6:color=white',
+        '-frames:v', '1', '-q:v', '3', str(OUT / 'contact-sheet.jpg'))
+    run('ffmpeg', '-v', 'error', '-y', '-ss', '11.55', '-i', str(MP4), '-frames:v', '1', str(OUT / 'poster.png'))
+    checks = {
+        'streams': {'codec': v['codec_name'], 'size': f"{v['width']}x{v['height']}", 'fps': v['r_frame_rate'],
+                    'frames': len(frames), 'duration': round(float(v['duration']), 3),
+                    'audio': f"{a['codec_name']} {a['sample_rate']} Hz {a['channels']} ch",
+                    'ok': (v['width'], v['height'], v['r_frame_rate'], len(frames)) == (W, H, f'{FPS}/1', FRAMES)
+                          and abs(float(v['duration']) - DUR) < 0.02 and a['sample_rate'] == '48000'
+                          and a['channels'] == 2},
+        'loudness': {'lufs': round(lufs, 2), 'true_peak_dbtp': round(tp, 2),
+                     'ok': -19 <= lufs <= -14 and tp <= -1.5},
+        'earshot_measure': {'lufs': master['lufs'], 'lra_lu': master['lra_lu'], 'true_peak_dbtp': master['true_peak_dbtp'],
+                            'bands_db': master['bands_db'], 'ok': abs(master['lufs'] - sound['lufs']) < 0.3},
+        'audit': {'summary': audit['summary'], 'warnings': audit['warnings'], 'notes': audit['notes'],
+                  'allowed': ALLOWED, 'failing': fails, 'ok': not fails},
+        'placement': {'method': 'sfx stem rebuilt from sound.json and compared sample for sample with the delivered '
+                                'stem; offsets are the measured peak/apex of each bank render',
+                      'cues': len(sound['cues']), 'max_sample_diff': diff,
+                      'worst_offset_ms': worst_off, 'ok': stem_ok},
+        'detector_view': {'method': 'envelope correlation of each re-rendered sound in the mix', 'cues': len(detected),
+                          'within_one_frame': sum(d['within_one_frame'] for d in detected), 'detail': detected,
+                          'note': 'diagnostic, not a gate: where a riser runs into a hit (6.8-8.0 s) the hit is '
+                                  'masked and the correlation reports the riser', 'ok': True},
+        'detector_onsets': {'ok': True, 'count': len(onsets), 'note': 'earshot onset detection on the full mix; reported, not '
+                            'gated: soft attacks (bell, punch) are backtracked 40-100 ms early by the detector'},
+        'picture': {'jumps': pops, 'ok': not pops},
+    }
+    ok = all(c['ok'] for c in checks.values())
+    report = {'file': MP4.name, 'bytes': MP4.stat().st_size, 'sha256': hashlib.sha256(MP4.read_bytes()).hexdigest(),
+              'soundtrack': {'bank': sound['bank'], 'cues': len(sound['cues']), 'notes': len(sound['notes'])},
+              'checks': checks, 'ok': ok}
+    (OUT / 'verification.json').write_text(json.dumps(report, indent=1) + '\n')
+    print(f'{MP4.name}: {report["bytes"] / 1e6:.1f} MB, {v["width"]}x{v["height"]} {v["r_frame_rate"]}, '
+          f'{len(frames)} frames, {lufs:.2f} LUFS, {tp:.2f} dBTP')
+    for name, c in checks.items():
+        print(f'  {"PASS" if c["ok"] else "FAIL"}  {name}')
+    print(f'  placement: {len(sound["cues"])} cues, worst offset {worst_off:.1f} ms, '
+          f'stem rebuild diff {diff:.1e}')
+    print(f'  detector: {checks["detector_view"]["within_one_frame"]}/{len(detected)} cues found by correlation')
+    print(f'  audit: {audit["summary"]}')
+    sys.exit(0 if ok else 1)
+if __name__ == '__main__':
+    main()

package/starters/earshot-ad/scripts/mix.py ADDED Viewed

@@ -0,0 +1,208 @@
+"""Soundtrack for the earshot ad: every sound is rendered from earshot's bank, in code.
+    cd my-film                                  # xevol film new my-film --from earshot-ad
+    node ../../../../xevol/packages/work-motion/runtime/render.mjs . --cues
+    /home/kuka/stack-dev/tools/earshot/.venv/bin/python scripts/mix.py     # -> out/audio.wav, out/sound.json
+No recorded audio, no Mixkit, no music track, no downloaded assets. The score is a kalimba arpeggio built from
+`pluck/kalimba`, pitched per note through the bank's own `pitch` knob (A minor pentatonic shapes over Am - Dm -
+Am/C - F); every picture cue in out/cues.json is one bank sound placed on the frame it belongs to.
+Placement is by measurement, not by hand:
+  peak   the sound's own measured peak lands on the cue time (hits, ticks, bell, pop)
+  apex   a whoosh is rendered with `dur`/`apex` so its loudest moment is the cue time, then started early
+  start  a riser starts on the cue time and runs into the drop that follows
+Levels: one linear gain to -18.0 LUFS (earshot's integrated measurement, no loudnorm — loudnorm is what dropped the
+last 83 ms and left a loop click in earlier MotionPls ads), capped so true peak stays at or below -1.5 dBTP.
+"""
+import hashlib
+import json
+import sys
+from pathlib import Path
+try:
+    import numpy as np
+    import soundfile as sf
+    from earshot.forge import bank
+    from earshot.features import integrated_lufs, true_peak_dbtp
+except ImportError as e:  # pragma: no cover - environment guard
+    sys.exit(f'mix.py: {e}\nUse the earshot install: /home/kuka/stack-dev/tools/earshot/.venv/bin/python scripts/mix.py')
+ROOT = Path(__file__).resolve().parent.parent
+OUT = ROOT / 'out'
+SR = 48000
+DUR = 12.0
+TARGET_LUFS = -18.0
+MAX_TP = -1.8   # leave room for AAC overshoot in the delivered file
+# kind -> (bank id, gain dB, align).  The picture only names the kind; the sound is chosen here.
+SFX = {
+    'impact': ('pro_impact/deep', -9.0, 'peak'),
+    'hit': ('impact/punch', -12.0, 'peak'),
+    'whoosh': ('pro_whoosh_big/gritty', -9.0, 'apex'),
+    'riser': ('pro_riser/air_gate', -15.5, 'start'),
+    'tick': ('fit/tick/domino', -15.0, 'peak'),
+    'chime': ('fit/bell/small_bell', -11.0, 'peak'),
+    'pop': ('pop/1', -15.0, 'peak'),
+}
+# per-cue overrides: the typing ticks want a softer, lower sound than the beat ticks
+BY_TIME = {
+    2.35: ('tap/finger', -15.0, 'peak'),
+    2.60: ('tap/finger', -15.0, 'peak'),
+    2.85: ('tap/finger', -15.0, 'peak'),
+    4.00: ('pro_whoosh_big/gritty', -9.5, 'apex'),      # the ink flood is the loudest move in the film
+    8.00: ('pro_impact/short', -11.0, 'peak'),           # "From $299." is the hero hit
+    8.90: ('click/soft', -16.5, 'peak'),
+    10.00: ('fit/bell/small_bell', -11.0, 'peak', 'A7'),   # the bell's own range is B7 +-12 st: A7 is a chord tone
+}
+WHOOSH = {'dur': 0.9, 'apex': 0.62}
+# extra layers under a cue: (time, id, gain dB, align, pitch).  Weight without peak, so the loudness can rise.
+LAYERS = [(8.00, 'sub_drop/808', -14.0, 'peak', 'A1'), (10.00, 'logo_sting/soft_bloom', -20.0, 'peak', None)]
+# kalimba arpeggio one octave up (so the melody sits in the presence band), with a low root per bar
+NOTES = [(2.00, 'A4'), (2.25, 'C5'), (2.50, 'E5'), (2.75, 'A5'), (3.00, 'C6'), (3.25, 'A5'), (3.50, 'E5'), (3.75, 'C5'),
+         (4.00, 'A4'), (4.25, 'D5'), (4.50, 'F5'), (4.75, 'A5'), (5.00, 'D6'), (5.25, 'A5'), (5.50, 'F5'), (5.75, 'D5'),
+         (6.00, 'A4'), (6.25, 'C5'), (6.50, 'E5'), (6.75, 'G5'), (7.00, 'E6'), (7.25, 'C6'), (7.50, 'G5'), (7.75, 'E5'),
+         (8.00, 'F4'), (8.25, 'A4'), (8.50, 'C5'), (8.75, 'F5'), (9.00, 'A5'), (9.25, 'F5'), (9.50, 'C5'), (9.75, 'A4')]
+ROOTS = [(2.00, 'A3'), (4.00, 'A3'), (6.00, 'A3'), (8.00, 'F3')]
+NOTE_DB, NOTE_LEN, NOTE_PAN = -26.0, 0.95, 0.32
+ROOT_DB, ROOT_LEN = -21.0, 1.5
+def stereo(y, pan=0.0):
+    y = np.asarray(y, np.float32)
+    if y.ndim == 2:
+        return y
+    return np.stack([y * (1 - pan * 0.28), y * (1 + pan * 0.28)], axis=1)
+def render(sound_id, pitch=None, dur=None, apex=None):
+    """one bank take; refuses any take whose own audit warns (a pitch outside the designed range shows up there)"""
+    y, meta = bank.render(sound_id, pitch=pitch, dur=dur, apex=apex)
+    warn = meta['checks']['warnings']
+    if warn:
+        sys.exit(f'mix.py: {sound_id} failed its own audit: ' + '; '.join(w['msg'] for w in warn))
+    return stereo(y), meta
+def main():
+    cues_doc = json.loads((OUT / 'cues.json').read_text())
+    n = int(round(DUR * SR))
+    bed = np.zeros((n, 2), np.float32)      # the score
+    hits = np.zeros((n, 2), np.float32)     # every picture cue, kept as its own stem for verification
+    placed, audit = [], []
+    for i, (t, note) in enumerate(NOTES):
+        y, meta = render('pluck/kalimba', pitch=note)
+        m = min(len(y), int(NOTE_LEN * SR))
+        env = np.ones(m, np.float32)
+        f = int(0.35 * SR)
+        env[-f:] = np.linspace(1, 0, f) ** 2
+        y = y[:m] * env[:, None] * 10 ** ((NOTE_DB + (2.5 if i % 4 == 0 else 0)) / 20)
+        a = int(round(t * SR))
+        bed[a:a + m] += y[:max(0, min(m, n - a))]
+        audit.append({'kind': 'note', 'id': 'pluck/kalimba', 'note': note, 't': t,
+                      'measured_hz': meta['edits'].get('pitch', {}).get('measured_hz')})
+    for t, note in ROOTS:
+        y, meta = render('pluck/kalimba_soft', pitch=note)
+        m = min(len(y), int(ROOT_LEN * SR))
+        env = np.ones(m, np.float32)
+        f = int(0.5 * SR)
+        env[-f:] = np.linspace(1, 0, f) ** 2
+        y = y[:m] * env[:, None] * 10 ** (ROOT_DB / 20)
+        a = int(round(t * SR))
+        bed[a:a + m] += y[:max(0, min(m, n - a))]
+        audit.append({'kind': 'root', 'id': 'pluck/kalimba_soft', 'note': note, 't': t})
+    for cue in cues_doc['cues']:
+        t = float(cue['t'])
+        sid, gain, align, *rest = BY_TIME.get(t, SFX.get(cue['kind'], (None, 0, None)))
+        if sid is None:
+            sys.exit(f"mix.py: no bank sound for kind {cue['kind']!r} at {t}")
+        kw = dict(WHOOSH) if align == 'apex' else {}
+        if rest and rest[0]:
+            kw['pitch'] = rest[0]
+        y, meta = render(sid, **kw)
+        y = y * 10 ** (gain / 20)
+        onset, peak = float(meta.get('onset_s') or 0.0), float(meta.get('peak_s') or 0.0)
+        start = {'peak': t - peak, 'apex': t - float(kw.get('apex', 0)), 'start': t}[align]
+        a = int(round(start * SR))
+        b = min(n, a + len(y))
+        if a < 0:
+            sys.exit(f'mix.py: {sid} at {t} s would start before 0 s')
+        hits[a:b] += y[:b - a]
+        # the alignment the mixer promises, measured on the render: hits by peak, whooshes by apex, risers by start
+        land = {'peak': onset + peak - onset + start, 'apex': start + float(kw.get('apex', 0)), 'start': start}[align]
+        placed.append({'t': t, 'kind': cue['kind'], 'id': sid, 'align': align, 'gain_db': gain,
+                       'start_s': round(start, 4), 'knobs': {k: v for k, v in kw.items()},
+                       'measured_onset_s': round(onset, 4),
+                       'measured_peak_s': round(peak, 4), 'lands_at_s': round(land, 4),
+                       'offset_ms': round(1000 * (land - t), 2)})
+    for t, sid, gain, align, pitch in LAYERS:
+        y, meta = render(sid, pitch=pitch)
+        y = y * 10 ** (gain / 20)
+        peak = float(meta.get('peak_s') or 0.0)
+        start = t - peak
+        a = int(round(start * SR)); b = min(n, a + len(y))
+        hits[a:b] += y[:b - a]
+        placed.append({'t': t, 'kind': 'layer', 'id': sid, 'align': align, 'gain_db': gain, 'start_s': round(start, 4),
+                       'knobs': {'pitch': pitch} if pitch else {}, 'measured_onset_s': round(float(meta.get('onset_s') or 0), 4),
+                       'measured_peak_s': round(peak, 4), 'lands_at_s': round(start + peak, 4), 'offset_ms': 0.0})
+    # the price section lifts the score: loudness from the music, not from a louder transient
+    a, b = int(8.0 * SR), int(10.2 * SR)
+    ramp = int(0.25 * SR)
+    lift = np.ones(b - a, np.float32)
+    lift[:ramp] = np.linspace(0, 1, ramp)
+    lift[-ramp:] = np.linspace(1, 0, ramp)
+    bed[a:b] *= (1 + 1.4 * lift)[:, None]
+    # fades: 5 ms in (no click at frame 0), exponential tail into silence by 11.9 s
+    mix = bed + hits
+    fi = int(0.005 * SR)
+    mix[:fi] *= np.linspace(0, 1, fi)[:, None]
+    t0, t1 = 10.4, 11.9
+    a, b = int(t0 * SR), int(t1 * SR)
+    mix[a:b] *= (np.linspace(1, 0, b - a) ** 1.6)[:, None]
+    mix[b:] = 0
+    lufs = integrated_lufs(mix)
+    gain_db = TARGET_LUFS - lufs
+    mix = mix * 10 ** (gain_db / 20)
+    tp = true_peak_dbtp(mix)
+    if tp > MAX_TP:                      # scale, never limit: a limiter would change the shape we just measured
+        extra = MAX_TP - tp
+        mix = mix * 10 ** (extra / 20)
+        gain_db += extra
+        tp = true_peak_dbtp(mix)
+    OUT.mkdir(parents=True, exist_ok=True)
+    (OUT / 'stems').mkdir(exist_ok=True)
+    wav = OUT / 'audio.wav'
+    sf.write(wav, mix, SR, subtype='PCM_24')
+    sf.write(OUT / 'stems' / 'score.wav', bed * 10 ** (gain_db / 20), SR, subtype='PCM_24')
+    sf.write(OUT / 'stems' / 'sfx.wav', hits * 10 ** (gain_db / 20), SR, subtype='PCM_24')
+    report = {
+        'film': 'motionpls-earshot-ad', 'dur': DUR, 'sr': SR,
+        'bank': bank.VERSION, 'bank_sounds': len(bank.ids()),
+        'score': {'arp': 'pluck/kalimba', 'notes': len(NOTES), 'note_db': NOTE_DB, 'bars': ['Am', 'Dm', 'Am/C', 'F']},
+        'cues': placed, 'notes': audit,
+        'lufs': round(integrated_lufs(mix), 2), 'true_peak_dbtp': round(true_peak_dbtp(mix), 2),
+        'peak_dbfs': round(20 * np.log10(max(1e-9, float(np.abs(mix).max()))), 2),
+        'gain_db': gain_db, 'target_lufs': TARGET_LUFS,
+        'sha256': hashlib.sha256(wav.read_bytes()).hexdigest(),
+    }
+    (OUT / 'sound.json').write_text(json.dumps(report, indent=1) + '\n')
+    worst = max(abs(c['offset_ms']) for c in placed)
+    print(f'out/audio.wav: {len(placed)} cues + {len(audit)} notes (arp + roots) from the earshot bank | '
+          f'{report["lufs"]} LUFS, {report["true_peak_dbtp"]} dBTP, gain {gain_db:+.2f} dB | '
+          f'worst peak offset {worst:.1f} ms')
+if __name__ == '__main__':
+    main()