xevol 0.15.0 → 0.17.0

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

@@ -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

@@ -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()