Ears for coding agents: let AI hear, review and make sound. CPU-only, open source.
#!/usr/bin/env python
"""Objective QA of a real-sound mix: what the critic lenses measure, in one pass, tied to the placements that caused it.
python -I <skill>/scripts/qa.py [--root .] [--design audio/sounddesign.json] [--report out/qa/mix_report.json]
[--trace out/qa/adds.json] [--stems out/audio/stems] [--master out/audio/soundtrack.wav]
[--cues out/cues.json] [--only NAME] [--cache out/audio/cache] [--video out/film.mp4]
[--out out/qa/qa.json] [--layers] [--listen] [--realness] [--json]
Run it after `mix.py --trace out/qa/adds.json` (same design, same --only): the trace ties every click, masked hit and
harsh peak to the placement that caused it. With --only, the report / stems default to mix.py's solo outputs
(out/audio-review/solo/<only>_report.json, _stems) and there is no master (levels at stem scale). Without the trace
only clicks, loudness and coverage run. No models needed; --listen / --realness add earshot's ears when installed. Sections (status ok / warn / fail + a plain summary):
clicks > 14 kHz bursts concentrated in 1 ms (the av-audit detector) in the master and each stem, attributed to
the placements whose start / end / body they sit in
edges used samples that start mid-sound or are cut mid-decay (unfaded head / tail level vs their peak, and the
source just outside the trim), a second hit inside a sample, steps in a stem at a placement's start / end
(second-difference ratio), placements cut by the film's ends
audibility every cue event's effect (its layers summed, rebuilt from the trace) vs the bed (music + amb) and vs
everything else, in 1/3-octave bands over its loudest 60 ms and its first 20 ms: read >= 6 dB clear, 3-6 ok,
0-3 barely, < 0 masked (margins capped at +-60 dB); an effect peaking under -70 dBFS is SILENT (a trim
that missed the sound: fail); not judged when the render has no bed (a solo); --layers also lists single
layers that add nothing measurable
harshness each event's 2-6 kHz peak (5 ms RMS, master scale) vs the music's loudest 2-6 kHz 5 ms level
loudness integrated LUFS vs the design's target, true peak, LRA, loudest momentary (time, share of the runtime),
short-term curve, per-act medians when the cue file has acts, head and tail of the master
coverage cue events with no sound (unsounded or placed but silent); classes of action sounded only in part
sync impacts by attack / peak (-45..+75 ms), whooshes and peak-aligned swells by their apex (+-45 ms), risers
and end-aligned swells by their audible end vs the hit (-250..+30 ms); measured norms of professional
launch films. A deviation that exactly one layer's rule offset explains is listed apart as deliberate
density events per second, the most reused samples, "machine-gun" rules (one sample, no pitch or level change)
listen --listen: earshot timeline + sheet + critique of the master; --realness: earshot realness of every source
Thresholds and where they come from: references/process.md. Writes --out (JSON) and prints a digest. Exit code 1 when
a section fails (a click at a placement edge in the master, a silent effect, stems of pure digital silence, the
loudness gate), 2 on missing or mismatched inputs (one line says which flag to pass), else 0.
"""
import argparse, json, math, os, re, sys
import numpy as np
import soundfile as sf
from scipy import signal
sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
import master as M # noqa: E402
import mix # noqa: E402 (read-only: the design loader, the sample library, envelope helpers)
SR = mix.SR
LONG = ('whoosh', 'riser', 'swell', 'suck')
FC = 10 ** (np.arange(20, 42) / 10) # 1/3-octave centres 100 Hz .. 12.6 kHz
BLO, BHI = FC * 2 ** (-1 / 6), FC * 2 ** (1 / 6)
SILENT_DB = -70.0 # an event whose peak (master scale) is below this makes no sound: a trim that missed the recording
CAP_DB = 60.0 # margins against a (near-)silent bed are reported as at most +60 dB
class InputError(Exception):
pass
def db(v):
return 20 * math.log10(max(float(v), 1e-12))
def pdb(p):
return 10 * math.log10(max(float(p), 1e-20))
def fmt_t(t):
m = int(t // 60)
return f'{m}:{t - 60 * m:05.2f}'
def say(s):
print(str(s).encode('ascii', 'replace').decode())
def lufs(x):
"""integrated LUFS, or None for audio shorter than one 400 ms block or with no gated signal (silence)"""
if x is None or len(x) < int(0.4 * SR):
return None
v = M.integrated(x)
return v if math.isfinite(v) else None
def clean(o):
"""JSON-safe: numpy scalars to Python, NaN / inf to None"""
if isinstance(o, dict):
return {k: clean(v) for k, v in o.items()}
if isinstance(o, (list, tuple)):
return [clean(v) for v in o]
if isinstance(o, np.integer):
return int(o)
if isinstance(o, (float, np.floating)):
return float(o) if math.isfinite(o) else None
return o
# ------------------------------------------------------------------ context
class Ctx:
def __init__(self, a):
self.root = os.path.abspath(a.root)
mix.ROOT = self.root
mix.CACHE = os.path.join(self.root, a.cache) if a.cache else os.path.join(self.root, 'out', 'audio', 'cache')
R = self.R = lambda p: os.path.normpath(p if os.path.isabs(p) else os.path.join(self.root, p))
def need(path, what, flag):
if not os.path.exists(R(path)):
raise InputError(f'{what} not found: {R(path)} ({flag})')
return R(path)
need(a.design, 'design file', 'pass --design')
self.design = mix.load_design(a.design, a.only)
self.report = json.load(open(need(a.report, 'mix report', 'run mix.py first or pass --report'), encoding='utf-8'))
self.trace = json.load(open(R(a.trace))) if a.trace and os.path.exists(R(a.trace)) else None
self.stems = {}
for k in ('sfx', 'amb', 'music'):
p = need(os.path.join(a.stems, k + '.wav'), f'stem {k}.wav', 'pass the --stems folder mix.py wrote')
self.stems[k] = sf.read(p, dtype='float32', always_2d=True)[0]
self.N = len(self.stems['sfx'])
if {len(v) for v in self.stems.values()} != {self.N}:
raise InputError(f'the stems in {R(a.stems)} have different lengths: re-render them with one mix.py run')
if a.master and getattr(a, 'master_given', False):
need(a.master, 'master', 'pass --master none to skip it')
self.master = (sf.read(R(a.master), dtype='float64', always_2d=True)[0]
if a.master and os.path.exists(R(a.master)) else None)
if self.master is not None and abs(len(self.master) - self.N) > 1:
raise InputError(f'the master {R(a.master)} ({len(self.master) / SR:.3f} s) does not match the stems '
f'({self.N / SR:.3f} s): pass the --master rendered with these stems, or --master none')
cp = a.cues or self.design.get('cues') or 'out/cues.json'
c = json.load(open(R(cp))) if os.path.exists(R(cp)) else {'fps': 60, 'events': []}
self.cues = c[0] if isinstance(c, list) else c
self.fps = self.cues.get('fps', 60)
m = self.design.get('master') or {}
self.target = m.get('lufs', -14)
pre = sum(self.stems[k].astype(np.float64) for k in self.stems)
self.pre_lufs = lufs(pre)
self.master_lufs = lufs(self.master)
both = self.master_lufs is not None and self.pre_lufs is not None
self.G = self.master_lufs - self.pre_lufs if both else 0.0 # no master (or silence): stem scale
self.scale = ('master' if both else 'stem') if self.master is not None else 'stem'
self.no_bed = not (np.any(self.stems['music']) or np.any(self.stems['amb']))
self.lib = None
self.only = a.only
def bus_curve(design, bus, n):
b = (design.get('buses') or {}).get(bus) or {}
c = mix.auto_curve(b.get('auto'), n)
return (np.ones(n) if c is None else c.astype(np.float64)) * mix.db2a(b.get('gain_db', 0.0))
def build_layers(ctx):
"""every sfx-bus placement rebuilt as it sits in the stem (sample, pitch, gain, pan, bus ride), grouped into events"""
recs = [a for a in ctx.trace if 'sample' in a]
pl = ctx.report.get('placements', [])
if len(recs) != len(pl):
return None, f'trace ({len(recs)} placements) and report ({len(pl)}) disagree: re-run mix.py with --trace'
ctx.lib = ctx.lib or mix.Lib(ctx.design)
places = iter(ctx.design.get('place') or [])
rules = {str(r.get('name', i)): r for i, r in enumerate(ctx.design.get('rules') or [])}
curve = bus_curve(ctx.design, 'sfx', ctx.N)
out, bad = [], 0
for a, p in zip(recs, pl):
if p['kind'] == 'place':
pp = next(places)
pitch, off, align, cue, rule = pp.get('pitch', 0.0), pp.get('offset', 0.0), pp.get('align', 'attack'), pp['at'], 'place'
ok = pp.get('qa_ok')
else:
r = rules.get(str(p.get('rule')), {})
pitch, off, align, rule = p.get('pitch', 0.0), r.get('offset', 0.0), p.get('align', 'attack'), str(p.get('rule'))
cue, ok = p['t'] - off, r.get('qa_ok')
x = ctx.lib.get(a['sample'], pitch)
if len(x) != a['n']:
bad += 1
continue
if a['bus'] != 'sfx':
continue
s0, s1 = max(0, a['start']), min(ctx.N, a['start'] + a['n'])
if s1 <= s0:
continue
seg = x[s0 - a['start']: s1 - a['start']].astype(np.float64) * a['gain']
if a['pan']:
seg = seg * np.array(mix.pan_gains(a['pan']))
seg = seg * curve[s0:s1, None]
out.append({'sample': a['sample'], 'rule': rule, 'kind': p['kind'], 'event': p.get('event'), 'cue': cue,
'offset': off, 'align': align, 'start': a['start'], 'n': a['n'], 'a': s0, 'b': s1, 'sig': seg, 'qa_ok': ok,
'att': a['start'] + mix.env_index(x, 'attack'), 'peak_db': db(np.abs(seg).max())})
ctx.layers = out
groups, by_cue = [], {}
for L in sorted(out, key=lambda L: L['att']):
if L['kind'] != 'place': # layers of one cue event share its exact cue time
k = (L['event'], round(L['cue'], 4))
if k in by_cue:
by_cue[k]['layers'].append(L)
else:
by_cue[k] = {'att0': L['att'], 'layers': [L]}
groups.append(by_cue[k])
continue
for g in groups[::-1][:12]: # free placements: layers whose attacks sit within 140 ms
if g.get('place') and abs(L['att'] - g['att0']) < 0.14 * SR:
g['layers'].append(L)
break
else:
groups.append({'place': True, 'att0': L['att'], 'layers': [L]})
for g in groups:
ls = g['layers']
g['a'], g['b'] = min(L['a'] for L in ls), max(L['b'] for L in ls)
g['sig'] = np.zeros((g['b'] - g['a'], 2))
for L in ls:
g['sig'][L['a'] - g['a']: L['b'] - g['a']] += L['sig']
g['cue'] = min(L['cue'] for L in ls)
g['loud'] = max(ls, key=lambda L: L['peak_db'])
g['kind'] = g['loud']['kind']
g['label'] = (ls[0]['event'] or 'place:' + ls[0]['sample'])
g['long'] = any(L['kind'] in LONG or L['align'] == 'peak' for L in ls)
g['builds'] = any(L['kind'] in ('riser', 'swell') for L in ls)
g['qa_ok'] = next((L['qa_ok'] for L in ls if L['qa_ok']), None)
g['peak_db'] = db(np.abs(g['sig']).max()) + ctx.G
g['silent'] = g['peak_db'] < SILENT_DB
note = f'{bad} placement(s) could not be rebuilt (sample length differs from the trace)' if bad else None
return groups, note
# ------------------------------------------------------------------ clicks
HP14 = signal.butter(4, 14000, 'high', fs=SR, output='sos')
def detect_clicks(x):
"""> 14 kHz samples > 9x the RMS of their 20 ms and > 6x their 4 ms neighbourhood; conc >= 0.8 of the burst's
> 14 kHz energy inside 1 ms = a click (a cut), else a designed attack"""
out = []
for ch in range(x.shape[1]):
hp = signal.sosfilt(HP14, x[:, ch].astype(np.float64))
e, e2 = np.abs(hp), hp ** 2
loc = np.sqrt(signal.fftconvolve(e2, np.ones(960) / 960, mode='same').clip(0)) + 1e-5
near = np.sqrt(signal.fftconvolve(e2, np.ones(192) / 192, mode='same').clip(0)) + 1e-5
last = -10 ** 9
for i in np.nonzero((e / loc > 9) & (e / near > 6) & (e > 0.01))[0]:
if i - last > SR * 0.01:
conc = float(e2[max(0, i - 24):i + 24].sum() / (e2[max(0, i - 240):i + 240].sum() + 1e-15))
out.append({'t': round(i / SR, 4), 'i': int(i), 'ch': ch, 'level_db': round(db(e[i]), 1),
'conc': round(conc, 2), 'kind': 'click' if conc >= 0.8 else 'attack'})
last = i
out.sort(key=lambda c: (c['t'], c['ch']))
return [c for k, c in enumerate(out) if k == 0 or c['t'] - out[k - 1]['t'] > 0.001]
def owners(trace, i, bus=None, win=960):
"""trace records around sample i, edge-near (within 2 ms of a start / end) first"""
res = []
for a in trace or []:
if bus and a['bus'] != bus:
continue
s, e = a['start'], a['start'] + a['n']
if s - win <= i <= e + win:
d = min(abs(i - s), abs(i - e))
where = 'start' if abs(i - s) <= 96 else 'end' if abs(i - e) <= 96 else 'body'
what = a.get('sample') or a.get('name') or a.get('label') or f"{a.get('kind', a['bus'])} at {s / SR:.3f} s"
res.append((where == 'body', d, {'bus': a['bus'], 'what': what,
'rule': a.get('rule', a.get('kind')), 'where': where,
'from_start_ms': round((i - s) / SR * 1000, 1),
'from_end_ms': round((i - e) / SR * 1000, 1)}))
return [r for _, _, r in sorted(res, key=lambda r: (r[0], r[1]))[:3]]
def hf_owner(ctx, i, ch):
"""the rebuilt sfx layer carrying the > 14 kHz burst at sample i (its level in the stem, where in the layer)"""
best = None
for L in getattr(ctx, 'layers', None) or []:
if not L['a'] - 480 <= i < L['b'] + 480:
continue
j = i - L['a']
lo, hi = max(0, j - 480), min(len(L['sig']), j + 480)
if hi - lo < 64:
continue
hp = signal.sosfilt(HP14, L['sig'][lo:hi, ch])
c = j - lo
v = float(np.abs(hp[max(0, c - 24):c + 24]).max()) if 0 <= c < len(hp) else 0.0
if best is None or v > best[0]:
off = i - L['start']
where = 'start' if abs(off) <= 96 else 'end' if abs(i - L['start'] - L['n']) <= 96 else 'body'
best = (v, {'bus': 'sfx', 'what': L['sample'], 'rule': L['rule'], 'where': where,
'from_start_ms': round(off / SR * 1000, 1), 'level_db': round(db(v), 1)})
return best
def check_clicks(ctx):
sets = [('master', ctx.master)] if ctx.master is not None else []
sets += [(k, ctx.stems[k]) for k in ('sfx', 'amb', 'music')]
items, counts = [], {}
for name, x in sets:
found = detect_clicks(x)
counts[name] = {'clicks': sum(c['kind'] == 'click' for c in found), 'attacks': sum(c['kind'] == 'attack' for c in found)}
for c in found:
if c['kind'] != 'click':
continue
own = hf_owner(ctx, c['i'], c['ch']) if name in ('master', 'sfx') else None
scale = 10 ** (-ctx.G / 20) if name == 'master' else 1.0 # master level back to stem scale
if own and own[0] >= 0.3 * 10 ** (c['level_db'] / 20) * scale:
ow = [own[1]]
else:
ow = owners(ctx.trace, c['i'], None if name == 'master' else name)
items.append({'in': name, **{k: v for k, v in c.items() if k != 'i'}, 'owners': ow,
'at_edge': bool(ow) and ow[0]['where'] in ('start', 'end')})
mc = [c for c in items if c['in'] == 'master']
edge = [c for c in items if c['at_edge']]
sc = len(items) - len(mc)
status = 'fail' if any(c['in'] == 'master' for c in edge) else 'warn' if items else 'ok'
summ = (f'{len(mc)} click(s) in the master, {sc} in the stems; {len(edge)} at a placement edge (a cut: fix the trim / '
'fade)' + (', the rest inside a recording (its own crisp transient or a defect in the source)' if items else '')
+ ('' if items else ' (designed attacks: ' + ', '.join(f"{k} {v['attacks']}" for k, v in counts.items()) + ')'))
return {'status': status, 'summary': summ, 'counts': counts, 'items': items}
# ------------------------------------------------------------------ edges
def rms(z):
return float(np.sqrt((np.asarray(z, np.float64) ** 2).mean())) if len(z) else 0.0
def sample_edges(x, raw_pre, raw_post, rawpk):
"""unfaded head / tail 1 ms RMS vs the sample's peak, the source 20 ms outside the trim vs the trim's peak, and a
second hit (a 5 ms envelope jump > 12 dB to within 18 dB of the peak) in the last 40 %"""
m = np.abs(x).max(axis=1)
pk = float(m.max()) or 1e-9
w = 240
n = len(m) // w
e = m[:n * w].reshape(n, w).max(axis=1) if n else np.zeros(1)
late = None
for k in range(max(1, int(n * 0.6)), n):
if e[k] > pk * 0.12 and e[k] > 4 * e[k - 1]:
late = round(k * w / SR, 3)
break
return {'head_db': round(db(rms(x[:48]) / pk), 1), 'tail_db': round(db(rms(x[-48:]) / pk), 1),
'pre20_db': round(db(rms(raw_pre) / rawpk), 1), 'post20_db': round(db(rms(raw_post) / rawpk), 1),
'attack_ms': round(mix.env_index(x, 'attack') / SR * 1000, 1), 'late_onset': late}
def judge_edges(r, fi, fo, trimmed_start):
"""(defects, notes): a defect is audible as a click or a chop; a note is a craft suggestion"""
bad, notes = [], []
if trimmed_start and r['pre20_db'] > -20:
msg = f"the trim cuts into a sound already playing (source 20 ms before at {r['pre20_db']} dB re peak)"
if fi < 0.005 and (r['attack_ms'] > 10 or r['pre20_db'] > -10): # exposed: no attack right after to cover it
bad.append(msg + f', fade_in only {fi * 1000:.0f} ms')
else:
notes.append(msg + ', softened by the fade-in')
elif r['head_db'] > -30:
notes.append(f"the attack starts in the first ms (head {r['head_db']} dB): the {fi * 1000:.0f} ms fade-in dulls it; "
'start the trim 3-5 ms earlier')
if r['tail_db'] > -35 and r['post20_db'] > -35:
msg = f"the sound continues after the trim (tail {r['tail_db']} dB, source after {r['post20_db']} dB)"
if fo < 0.03:
bad.append(msg + f': chopped with a {fo * 1000:.0f} ms fade')
else:
notes.append(msg + ': decay faded early')
if r['late_onset'] is not None:
notes.append(f"a second hit inside the sample at {r['late_onset']} s (fine for a rattle, wrong for a single hit)")
return bad, notes
def check_splices(ctx):
"""music segment boundaries: a segment end that chops a note still sounding into quieter material, holes and overlaps
between segments, segments that begin inside a sustained sound"""
mu = ctx.design.get('music')
if not mu or not mu.get('segments'):
return []
ratio = mu.get('target_bpm', 120) / mu['src_bpm'] if mu.get('stretch', 'rubberband') != 'none' else 1.0
x = mix.stretched(mu['file'], ratio)
k = 1.0 / ratio
w = int(0.05 * SR)
def lv(i0):
return db(rms(x[max(0, i0):max(0, i0 + w)]))
segs = sorted(mu['segments'], key=lambda sg: sg['at'])
dur = ctx.N / SR
out = []
for n, sg in enumerate(segs):
s0, e0 = int(round(sg['src_from'] * k * SR)), int(round(sg['src_to'] * k * SR))
end_t = sg['at'] + (sg['src_to'] - sg['src_from']) * k
nxt = segs[n + 1] if n + 1 < len(segs) else None
out_l, cut_l = lv(e0 - w), lv(e0)
in_l = lv(int(round(nxt['src_from'] * k * SR))) if nxt else -120.0
item = {'segment': sg.get('label') or n, 'film_end': round(end_t, 3), 'out_db': round(out_l, 1),
'cut_off_db': round(cut_l, 1), 'next_in_db': round(in_l, 1) if nxt else None, 'issues': [], 'notes': []}
fo = sg.get('fade_out', 0.06)
if not sg.get('tail_fade') and fo < 0.1 and end_t < dur - 0.05 and cut_l > out_l - 6 and cut_l > in_l + 6:
msg = (f'chops the music at {end_t:.3f} s: the source keeps sounding at {cut_l:.0f} dBFS and the next '
f'material enters at {in_l:.0f} (fade_out {fo * 1000:.0f} ms)')
if sg.get('qa_ok'):
item['notes'].append(f"acknowledged ({sg['qa_ok']}): {msg}")
else:
item['issues'].append(msg)
if nxt:
gap = nxt['at'] - end_t
if gap > 0.02:
item['notes'].append(f'{gap * 1000:.0f} ms of no music before {nxt["at"]:.3f} s (deliberate silence?)')
elif gap < -0.1:
item['notes'].append(f'overlaps the next segment by {-gap * 1000:.0f} ms (two passages at once)')
if s0 > w and lv(s0 - w) > lv(s0) - 3:
item['notes'].append(f"begins inside a sustained sound (the source before {sg['src_from']} s is as loud): "
'no fresh attack on the splice')
if item['issues'] or item['notes']:
out.append(item)
return out
def check_edges(ctx):
items = []
used = {p.get('sample') for p in ctx.report.get('placements', [])}
lib = ctx.lib = ctx.lib or mix.Lib(ctx.design)
for name, s in (ctx.design.get('samples') or {}).items():
if name not in used:
continue
raw = mix.decode(s['file'])
a = int(s.get('start', 0) * SR)
b = int(s['end'] * SR) if s.get('end') is not None else len(raw)
fi, fo = s.get('fade_in', 0.002), s.get('fade_out', 0.012)
trim_pk = float(np.abs(raw[a:b]).max()) if b - a > 0 else 0.0
if db(trim_pk) < -60: # nothing to judge: the trim missed the sound
why = ('empty (start >= end or past the file end)' if b - a <= 0 else 'digital silence' if trim_pk == 0
else f'near-silent (peak {db(trim_pk):.0f} dBFS)')
items.append({'what': 'sample', 'name': name, 'file': os.path.basename(s['file']), 'start': s.get('start', 0),
'end': s.get('end'), 'trim_peak_dbfs': round(db(trim_pk), 1), 'fade_in': fi, 'fade_out': fo,
'issues': [f'the trim is {why}: it misses the sound (file length {len(raw) / SR:.3f} s)'],
'notes': []})
continue
x = lib._finish(raw[a:b], {**s, 'fade_in': 0, 'fade_out': 0})
r = sample_edges(x, raw[max(0, a - 960):a], raw[b:b + 960], trim_pk)
bad, notes = judge_edges(r, fi, fo, a > 0)
if bad and s.get('qa_ok'):
notes, bad = notes + [f'acknowledged ({s["qa_ok"]}): ' + b_ for b_ in bad], []
if bad or notes:
items.append({'what': 'sample', 'name': name, 'file': os.path.basename(s['file']), 'start': s.get('start', 0),
'end': s.get('end'), **r, 'fade_in': fi, 'fade_out': fo, 'issues': bad, 'notes': notes})
for name, s in (ctx.design.get('slices') or {}).items():
if not any(u and u.startswith(name + '#') for u in used):
continue
try:
sl = lib._slice({**s, 'fade_in': 0, 'fade_out': 0})
except Exception as e: # noqa: BLE001
items.append({'what': 'slices', 'name': name, 'issues': [f'cannot slice: {e}'], 'notes': []})
continue
fi, fo = s.get('fade_in', 0.002), s.get('fade_out', 0.02)
bad, notes = set(), set()
for x, _ in sl:
r = sample_edges(x, x[:0], x[:0], float(np.abs(x).max()) or 1e-9)
r['post20_db'] = r['tail_db'] # a slice ends where the next hit begins: its tail level is what is cut
b_, n_ = judge_edges(r, fi, fo, False)
bad |= {m.split(' (')[0] for m in b_}
notes |= {m.split(' (')[0] for m in n_}
if bad or notes:
items.append({'what': 'slices', 'name': name, 'n': len(sl), 'issues': sorted(bad), 'notes': sorted(notes)})
cut = []
for a in ctx.trace or []:
if a['bus'] != 'music' and (a['start'] < 0 or a['start'] + a['n'] > ctx.N):
cut.append({'bus': a['bus'], 'what': a.get('sample') or a.get('name') or a.get('label'),
'start': round(a['start'] / SR, 3), 'end': round((a['start'] + a['n']) / SR, 3)})
splices = check_splices(ctx)
n_bad = sum(1 for it in items + splices if it['issues'])
n_note = sum(1 for it in items + splices if it['notes'] and not it['issues'])
summ = (f'{n_bad} defect(s) (abrupt entries, chopped decays, chopped music), {n_note} with craft notes only (used '
f'samples, slices, music splices); {len(cut)} placement(s) run past the film ends')
return {'status': 'warn' if n_bad else 'ok', 'summary': summ,
'items': sorted(items, key=lambda it: (not it['issues'], it['name'])), 'splices': splices,
'cut_by_film_ends': cut}
# ------------------------------------------------------------------ audibility / harshness / sync
def bands(seg):
w = signal.windows.tukey(len(seg), 0.25)[:, None]
S = (np.abs(np.fft.rfft(seg * w, axis=0)) ** 2).sum(axis=1)
f = np.fft.rfftfreq(len(seg), 1 / SR)
c = np.concatenate([[0], np.cumsum(S)])
ia, ib = np.searchsorted(f, BLO), np.searchsorted(f, BHI)
return c[ib] - c[ia] + 1e-30
def window_at(arr, a0, s, w):
o = arr[max(0, s - a0): max(0, s - a0) + w]
return np.pad(o, ((0, w - len(o)), (0, 0))) if len(o) < w else o
def read_metrics(ctx, eff, a, b, att, long):
"""m60 vs bed, m60r / m20 vs everything else (best band within 30 dB of the effect's strongest)"""
bed = ctx.stems['music'][a:b].astype(np.float64) + ctx.stems['amb'][a:b]
rest = ctx.stems['sfx'][a:b] - eff + bed
e2 = (eff ** 2).sum(axis=1)
c = np.concatenate([[0], np.cumsum(e2)])
def best(w, s0, s1):
s0 = max(a, s0)
s1 = max(s0, min(b - w, s1))
cand = np.arange(s0, s1 + 1, 48)
en = [c[min(len(c) - 1, s - a + w)] - c[max(0, s - a)] for s in cand]
return int(cand[int(np.argmax(en))])
w60, w20 = int(0.06 * SR), int(0.02 * SR)
s60 = best(w60, att - 240, (b - w60) if long else att + int(0.3 * SR))
s20 = s60 if long else best(w20, att - 144, att + int(0.08 * SR))
E, B, Rr = (bands(window_at(z, a, s60, w60)) for z in (eff, bed, rest))
E20, R20 = bands(window_at(eff, a, s20, w20)), bands(window_at(rest, a, s20, w20))
def mb(Ep, Bp):
ok = Ep >= Ep.max() * 1e-3
v = np.where(ok, np.clip(10 * np.log10(Ep / Bp), -CAP_DB, CAP_DB), -99)
k = int(np.argmax(v))
return round(float(v[k]), 1), int(round(FC[k]))
m60, f60 = mb(E, B)
m60r, _ = mb(E, Rr)
m20, f20 = mb(E20, R20)
read = max(m60r, m20)
verdict = 'clear' if read >= 6 else 'ok' if read >= 3 else 'barely' if read >= 0 else 'masked'
return {'vs_bed_db': m60, 'vs_bed_hz': f60, 'vs_all_db': m60r, 'first20_db': m20, 'first20_hz': f20,
'read_db': read, 'verdict': verdict, 'covered_by': 'music/amb' if m60 < 3 else 'other effects'}
def check_audibility(ctx, groups, layers_too=False):
rows = []
for g in groups:
att = min(L['att'] for L in g['layers'])
r = {'t': round(att / SR, 3), 'label': g['label'], 'kind': g['kind'], 'n_layers': len(g['layers']),
'rules': sorted({L['rule'] for L in g['layers']}), 'peak_db': round(max(g['peak_db'], -120), 1)}
if g['silent']:
r.update({'read_db': None, 'verdict': 'silent',
'samples': sorted({L['sample'] for L in g['layers']})})
elif ctx.no_bed:
r['verdict'] = 'not judged'
else:
r.update(read_metrics(ctx, g['sig'], g['a'], g['b'], att, g['long']))
if g['qa_ok']:
r['qa_ok'] = g['qa_ok']
rows.append(r)
cnt = {}
for r in rows:
cnt[r['verdict']] = cnt.get(r['verdict'], 0) + 1
masked = [r for r in rows if r['verdict'] == 'masked' and not r.get('qa_ok')]
silent = [r for r in rows if r['verdict'] == 'silent' and not r.get('qa_ok')]
sil = (f'; {len(silent)} SILENT (peak under {SILENT_DB:.0f} dBFS: the trim missed the sound) at '
+ ', '.join(f"{r['t']:.2f} {r['label']} ({', '.join(r['samples'])})" for r in silent[:6]) if silent else '')
if ctx.no_bed:
return {'status': 'fail' if silent else 'skipped', 'counts': cnt, 'events': rows, 'items': silent,
'summary': f'{len(rows)} events, not judged against a bed: this render has no music or ambience (a '
'solo render); judge audibility on the full mix' + sil}
judged = sorted((r for r in rows if r['read_db'] is not None), key=lambda r: r['read_db'])
res = {'status': 'fail' if silent else 'warn' if masked else 'ok', 'counts': cnt,
'summary': f'{len(rows)} events: ' + ', '.join(f'{k} {cnt.get(k, 0)}' for k in ('clear', 'ok', 'barely', 'masked'))
+ sil + ('' if not masked else '; masked at ' + ', '.join(f"{r['t']:.2f} {r['label']} (by {r['covered_by']})"
for r in masked[:6])),
'items': (silent + judged)[:40], 'events': rows}
if layers_too:
dead = []
for g in groups:
if len(g['layers']) < 2 or g['silent']:
continue
for L in g['layers']:
if L['peak_db'] + ctx.G < SILENT_DB:
dead.append({'t': round(L['att'] / SR, 3), 'rule': L['rule'], 'sample': L['sample'], 'read_db': None,
'silent': True})
continue
r = read_metrics(ctx, L['sig'], L['a'], L['b'], L['att'], g['long'])
if r['read_db'] < 0:
dead.append({'t': round(L['att'] / SR, 3), 'rule': L['rule'], 'sample': L['sample'], 'read_db': r['read_db']})
res['dead_layers'] = dead
res['summary'] += f'; {len(dead)} layer(s) in multi-layer events add nothing measurable (read < 0 dB)'
return res
def centroid(x):
S = np.abs(np.fft.rfft(x * np.hanning(len(x)))) ** 2
f = np.fft.rfftfreq(len(x), 1 / SR)
return float((f * S).sum() / (S.sum() + 1e-30))
def check_harshness(ctx, groups):
sos = signal.butter(4, [2000, 6000], 'bandpass', fs=SR, output='sos')
sol = signal.butter(4, [80, 400], 'bandpass', fs=SR, output='sos')
mu = signal.sosfilt(sos, ctx.stems['music'].astype(np.float64).mean(axis=1))
e5 = np.convolve(mu ** 2, np.ones(240) / 240, 'same')
has_music = e5.max() > 1e-10 # a solo render without the music: presence is not judged
ref = pdb(e5.max()) + ctx.G if has_music else None
rows = []
for g in groups:
att = min(L['att'] for L in g['layers'])
x = g['sig'].mean(axis=1)
pres = signal.sosfilt(sos, np.r_[np.zeros(480), x])[480:]
lo = signal.sosfilt(sol, np.r_[np.zeros(480), x])[480:]
i0 = max(0, att - g['a'] - 480)
i1 = len(x) if g['long'] else min(len(x), att - g['a'] + int(0.08 * SR))
if i1 - i0 < 240:
continue
pk = pdb(np.convolve(pres[i0:i1] ** 2, np.ones(240) / 240, 'valid').max()) + ctx.G
lk = pdb(np.convolve(lo[i0:i1] ** 2, np.ones(240) / 240, 'valid').max()) + ctx.G
m0, m1 = max(0, att - SR // 4), min(len(mu), att + SR // 4)
r = {'t': round(att / SR, 3), 'label': g['label'], 'rules': sorted({L['rule'] for L in g['layers']}),
'pres_db': round(pk, 1), 'pres_minus_low_db': round(pk - lk, 1), 'centroid_hz': int(centroid(x[i0:i1])),
'music_pres_db': round(pdb((mu[m0:m1] ** 2).mean()) + ctx.G, 1),
'over_music_max_db': round(pk - ref, 1) if has_music else None}
r['issues'] = []
if has_music and r['over_music_max_db'] > 6:
r['issues'].append(f"2-6 kHz peak {r['pres_db']} dBFS, {r['over_music_max_db']:+.1f} dB over the music's loudest")
r['bright'] = r['centroid_hz'] > 6500
if g['qa_ok'] and r['issues']:
r['qa_ok'], r['issues'] = g['qa_ok'], []
rows.append(r)
rows.sort(key=lambda r: -r['pres_db'])
hot = [r for r in rows if r['issues']]
bright = [r for r in rows if r['bright']]
head = (f"{len(hot)} event(s) more than 6 dB over the music's loudest 2-6 kHz peak ({ref:.1f} dBFS)" if has_music else
'no music in this render: presence vs the music not judged')
return {'status': 'warn' if hot else 'ok', 'music_max_db': round(ref, 1) if has_music else None,
'summary': (head + ('' if not hot else ': ' + ', '.join(f"{r['t']:.2f} {r['label']}" for r in hot[:6]))
+ f"; note: {len(bright)} bright event(s) (centroid > 6.5 kHz, above launch-film effects)"),
'items': hot[:20] + [r for r in rows if not r['issues']][:max(0, 10 - len(hot))],
'bright': [{'t': r['t'], 'label': r['label'], 'centroid_hz': r['centroid_hz']} for r in bright]}
def sync_issue(test, r, s):
"""the sync verdict for a measured event shifted by s ms (a rule offset): None when it sits on its cue"""
if test == 'end': # a riser stops on (or 30-250 ms before) its hit
e = r['end_ms'] - s
return f"its audible end is {e:+d} ms from its hit (want -250..+30)" if not -300 <= e <= 60 else None
if test == 'apex':
e = r['apex_ms'] - s
return f"apex {e:+d} ms from the cue (want +-45)" if abs(e) > 45 else None
a, p = r['attack_ms'] - s, r['peak_ms'] - s
return (f"attack {a:+d} ms (sound before picture)" if a < -45 else f"peak {p:+d} ms (lands late)" if p > 75 else None)
def check_sync(ctx, groups):
"""impacts by attack / peak, whooshes and peak-aligned swells by their apex, risers (and swells placed by their
end or attack) by their audible end vs the hit; a deviation that one layer's rule offset explains is deliberate"""
rows, deliberate, n = [], [], 0
for g in groups:
x = np.abs(g['sig']).max(axis=1)
k = len(x) // 240
if not k:
continue
align = g['loud']['align']
test = (('apex' if align == 'peak' else 'end') if g['builds'] else None if align in ('start', 'end') else
'apex' if g['long'] else 'impact')
if test is None: # placed by its start / end on purpose (not a build): no hit to judge
continue
n += 1
pk = (int(np.argmax(x[:k * 240].reshape(k, 240).max(axis=1))) * 240 + 120 + g['a']) / SR
p = np.convolve((g['sig'] ** 2).sum(axis=1), np.ones(2400) / 2400, 'same')
apex = (int(np.argmax(p)) + g['a']) / SR
att = g['loud']['att'] / SR
r = {'t_cue': round(g['cue'], 3), 'label': g['label'], 'kind': g['kind'], 'test': test, 'align': align,
'attack_ms': round((att - g['cue']) * 1000), 'peak_ms': round((pk - g['cue']) * 1000),
'apex_ms': round((apex - g['cue']) * 1000), 'long': g['long']}
if test == 'end':
nz = np.nonzero(x > x.max() * 0.1)[0] # the audible body: above 10 % of the peak (-20 dB)
r['end_ms'] = round(((nz[-1] if len(nz) else 0) + g['a']) / SR * 1000 - g['cue'] * 1000)
r['issue'] = sync_issue(test, r, 0)
if not r['issue']:
continue
offs = sorted({(round(L['offset'] * 1000), L['rule']) for L in g['layers'] if abs(L['offset']) >= 0.03})
why = next(((o, rule) for o, rule in offs if not sync_issue(test, r, o)), None)
if why:
r.update({'offset_s': why[0] / 1000, 'offset_rule': why[1],
'explained': f"{re.sub(r' [(].*', '', r['issue'])} = rule {why[1]}'s offset {why[0] / 1000:+.3f} s"})
deliberate.append(r)
elif g['qa_ok']:
r['qa_ok'] = g['qa_ok']
deliberate.append(r)
else:
if offs:
r['offsets_tried_s'] = [o / 1000 for o, _ in offs]
rows.append(r)
return {'status': 'warn' if rows else 'ok', 'checked': n, 'items': rows, 'deliberate': deliberate,
'summary': f'{n} events checked, {len(rows)} off their cue'
+ (': ' + ', '.join(f"{r['t_cue']:.2f} {r['label']} {r['issue']}" for r in rows[:5]) if rows else '')
+ f'; {len(deliberate)} more sit off the cue by exactly a rule offset or carry a qa_ok note (check those on '
'the frames)'}
def check_density(ctx, groups):
per_s = {}
for g in groups:
s = int(min(L['att'] for L in g['layers']) / SR)
per_s[s] = per_s.get(s, 0) + 1
pl = [p for p in ctx.report.get('placements', []) if p.get('kind') != 'place']
use = {}
for p in ctx.report.get('placements', []):
use[p['sample']] = use.get(p['sample'], 0) + 1
by = {}
for p in pl:
by.setdefault(str(p['rule']), []).append(p)
rules, mg = [], []
for k, v in by.items():
if len(v) < 4:
continue
t = np.array(sorted(p['t'] for p in v))
ioi = np.diff(t)
g = np.array([p['gain_db'] for p in v])
pt = np.array([p.get('pitch', 0) for p in v])
r = {'rule': k, 'n': len(v), 'distinct_samples': len({p['sample'] for p in v}), 'ioi_s': round(float(ioi.mean()), 3),
'ioi_cv': round(float(ioi.std() / max(ioi.mean(), 1e-9)), 2), 'gain_sd_db': round(float(g.std()), 2),
'pitch_sd_st': round(float(pt.std()), 2)}
rules.append(r)
if r['distinct_samples'] == 1 and r['pitch_sd_st'] < 0.1 and r['gain_sd_db'] < 0.5:
mg.append(r)
n = ctx.N / SR
busiest = sorted(per_s.items(), key=lambda kv: -kv[1])[:5]
return {'status': 'warn' if mg else 'ok', 'events_per_s': [per_s.get(s, 0) for s in range(int(math.ceil(n)))],
'busiest_s': busiest, 'most_used_samples': sorted(use.items(), key=lambda kv: -kv[1])[:8], 'rules': rules,
'machine_gun': mg,
'summary': (f'{len(groups)} effect events in {n:.0f} s ({len(groups) / n * 10:.1f} per 10 s); busiest seconds '
+ ', '.join(f'{s}s:{c}' for s, c in busiest) + f'; {len(mg)} machine-gun rule(s)'
+ (': ' + ', '.join(r['rule'] for r in mg) if mg else ''))}
# ------------------------------------------------------------------ loudness / coverage
def check_loudness(ctx):
x = ctx.master
if x is None:
return {'status': 'skipped', 'summary': 'no master WAV (pass --master)'}
if len(x) < int(0.4 * SR):
return {'status': 'skipped', 'summary': f'the master is {len(x) / SR * 1000:.0f} ms long: loudness needs >= 400 ms'}
if not np.any(x):
return {'status': 'fail', 'lufs': None, 'summary': 'the master is digital silence (no gated loudness)'}
I, tp, lr = M.integrated(x), M.true_peak_db(x), M.lra(x)
tm, mom = M.blocks(x, 0.4, 0.1)
ts, st = M.blocks(x, 3.0, 1.0)
k = int(np.argmax(mom))
dur = len(x) / SR
head = db(np.abs(x[:240]).max())
tail_rms = db(np.sqrt((x[-2400:] ** 2).mean()))
tail_pk = db(np.abs(x[-480:]).max())
r = {'lufs': round(I, 2), 'target': ctx.target, 'true_peak_dbtp': round(tp, 2), 'lra_lu': round(lr, 1),
'premaster_lufs': round(ctx.pre_lufs, 2) if ctx.pre_lufs is not None else None, 'loudest_momentary': round(float(mom[k]), 1),
'loudest_at': round(float(tm[k]), 2), 'loudest_frac': round(float(tm[k]) / dur, 2),
'short_term_per_s': [round(float(v), 1) for v in st], 'head_5ms_peak_dbfs': round(head, 1),
'tail_50ms_rms_dbfs': round(tail_rms, 1), 'tail_10ms_peak_dbfs': round(tail_pk, 1)}
acts = ctx.cues.get('acts') or {}
if acts:
r['acts'] = {}
for name, v in acts.items():
t0, t1 = v['from'] / ctx.fps, (v['from'] + v['dur']) / ctx.fps
sel = (tm >= t0) & (tm < t1)
if sel.any():
r['acts'][name] = {'from': round(t0, 2), 'momentary_median': round(float(np.median(mom[sel])), 1),
'momentary_max': round(float(mom[sel].max()), 1)}
fails, warns = [], []
if abs(I - ctx.target) > 0.5:
fails.append(f'integrated {I:.1f} LUFS, target {ctx.target}')
if tp > -1.0:
fails.append(f'true peak {tp:.1f} dBTP (> -1.0: AAC will clip)')
if tail_rms > -45 or tail_pk > -60:
fails.append(f'the end is not silent (last 50 ms {tail_rms:.0f} dBFS RMS, last 10 ms peak {tail_pk:.0f})')
if head > -40:
warns.append(f'first 5 ms peak {head:.0f} dBFS: starts mid-sound or clicks on sample 0')
if lr < 4:
warns.append(f'LRA {lr:.1f} LU: flat (launch films with an arc sit at 5-9 LU)')
elif lr > 10:
warns.append(f'LRA {lr:.1f} LU: wider than launch films (5-9 LU); quiet passages may vanish on phones')
if r['loudest_frac'] > 0.85:
warns.append(f'the loudest moment is at {r["loudest_frac"]:.0%} of the runtime: peak at the drop, resolve at the end')
r['status'] = 'fail' if fails else 'warn' if warns else 'ok'
r['summary'] = (f'{I:.1f} LUFS (target {ctx.target}), true peak {tp:.1f} dBTP, LRA {lr:.1f} LU, loudest momentary '
f'{mom[k]:.1f} LUFS at {fmt_t(tm[k])} ({r["loudest_frac"]:.0%} of the runtime)'
+ ('; ' + '; '.join(fails + warns) if fails or warns else ''))
return r
def stem_id(i):
return re.sub(r'(:\d+)+$', '', str(i or ''))
def check_coverage(ctx, groups=None):
"""cue events with no sound: unsounded in the report, or placed but silent (every layer below SILENT_DB)"""
ev = ctx.cues.get('events') or []
uns = list(ctx.report.get('unsounded_events', []))
quiet = [{'t': round(g['cue'], 3), 'kind': g['kind'], 'id': g['layers'][0]['event']}
for g in groups or [] if g['silent'] and not g.get('place') and not g['qa_ok']]
uns += quiet
tot, miss = {}, {}
for e in ev:
k = (e['kind'], stem_id(e.get('id')))
tot[k] = tot.get(k, 0) + 1
for e in uns:
k = (e['kind'], stem_id(e.get('id')))
miss.setdefault(k, []).append(e['t'])
partial = [{'kind': k[0], 'id': k[1], 'unsounded': len(v), 'of': tot.get(k, len(v)), 'at': v[:12]}
for k, v in miss.items() if len(v) < tot.get(k, len(v))]
silent = [{'kind': k[0], 'id': k[1], 'n': len(v), 'at': v[:12]} for k, v in miss.items() if len(v) >= tot.get(k, len(v))]
return {'status': 'warn' if partial or quiet else 'ok', 'partial': partial, 'unsounded_classes': silent,
'placed_but_silent': quiet,
'summary': (('solo render (events of the other fragments are expected to have no sound): ' if ctx.only else '')
+ f'{len(uns)} of {len(ev)} cue events have no sound'
+ (f' ({len(quiet)} of them placed but silent: ' + ', '.join(f"{q['t']:.2f} {q['id']}" for q in quiet[:5])
+ ')' if quiet else '') + f'; {len(partial)} class(es) of action sounded '
f'only in part' + (': ' + ', '.join(f"{p['kind']} {p['id']} ({p['unsounded']}/{p['of']} silent)"
for p in partial[:5]) if partial else '')
+ (f'; classes never sounded: ' + ', '.join(f"{s['kind']} {s['id']} x{s['n']}" for s in silent[:8])
if silent else ''))}
# ------------------------------------------------------------------ earshot
def listen(ctx, a):
try:
from earshot import api
except Exception as e: # noqa: BLE001
return {'status': 'skipped', 'summary': f'earshot is not importable here ({e}): pip install -e <earshot repo>'}
out_dir = os.path.dirname(ctx.R(a.out))
os.makedirs(out_dir, exist_ok=True)
res, notes = {}, []
video = ctx.R(a.video) if a.video else None
if a.listen and ctx.master is not None:
mp = ctx.R(a.master)
cues_used = ctx.R(a.cues_sounded) if a.cues_sounded and os.path.exists(ctx.R(a.cues_sounded)) else None
tl = {}
steps = (('timeline', lambda: tl.setdefault('r', api.timeline(mp, video=video, cues=cues_used))),
('sheet', lambda: api.sheet(mp, os.path.join(out_dir, 'qa_sheet.png'), video=video, cues=cues_used,
tl=tl.get('r'))),
('critique', lambda: api.critique(mp, video=video, use_ast=False, use_realness=False)))
for name, call in steps: # the critique is the fast scorecard: realness of the sources is --realness's job
try:
r = call()
res[name] = {'summary': r.get('summary'), **({'png': r.get('png') or r.get('path')} if name == 'sheet' else {})}
if name == 'timeline' and r.get('text'):
p = os.path.join(out_dir, 'qa_timeline.txt')
open(p, 'w', encoding='utf-8').write(r['text'])
res[name]['text_file'] = p
if name == 'critique':
res[name].update({'verdict': r.get('verdict'), 'score': r.get('score'), 'actions': r.get('actions'),
'off_range': [i for i in r.get('metrics') or [] if isinstance(i, dict)
and i.get('status') in ('low', 'high')]})
except Exception as e: # noqa: BLE001
notes.append(f'{name}: {type(e).__name__}: {str(e)[:160]}')
if a.realness:
rows = []
for f in ctx.report.get('files_used', []):
try:
r = api.realness(ctx.R(f))
rows.append({'file': f, 'p_real': r.get('p_real'), 'verdict': r.get('verdict')})
except Exception as e: # noqa: BLE001
notes.append(f'realness {os.path.basename(f)}: {str(e)[:160]}')
rows.sort(key=lambda r: (r['p_real'] is None, r['p_real'] if r['p_real'] is not None else 1))
res['realness'] = {'files': rows, 'not_real': [r for r in rows if (r['p_real'] < 0.5 if r['p_real'] is not None
else 'synth' in str(r['verdict']).lower())]}
short = lambda k, v: (v['summary'][:360].rsplit(' ', 1)[0] + f" ... (all of it: {v['text_file']})"
if k == 'timeline' and len(v['summary']) > 400 and v.get('text_file') else v['summary'])
parts = [f"{k}: {short(k, v)}" for k, v in res.items() if k != 'realness' and v.get('summary')]
if 'realness' in res:
rr = res['realness']
parts.append(f"realness: {len(rr['not_real'])} of {len(rr['files'])} sources judged not real" if rr['files'] else
'realness: not available (' + (notes[0] if notes else 'no sources') + ')')
if notes:
parts.append(f'{len(notes)} earshot call(s) failed (see notes)')
bad = bool(res.get('realness', {}).get('not_real'))
return {'status': 'warn' if bad or notes else 'ok', 'summary': '; '.join(parts) or 'nothing ran', **res, 'notes': notes}
# ------------------------------------------------------------------ run
def run_qa(a):
ctx = Ctx(a)
groups, note = build_layers(ctx) if ctx.trace is not None else (None, None)
live = [g for g in groups if not g['silent']] if groups else groups
sec = {'clicks': check_clicks(ctx), 'loudness': check_loudness(ctx), 'coverage': check_coverage(ctx, groups)}
if ctx.trace is None:
msg = 'needs the trace: run mix.py with --trace out/qa/adds.json'
for k in ('edges', 'audibility', 'harshness', 'sync', 'density'):
sec[k] = {'status': 'skipped', 'summary': msg}
else:
sec['edges'] = check_edges(ctx)
if groups is None:
for k in ('audibility', 'harshness', 'sync', 'density'):
sec[k] = {'status': 'skipped', 'summary': note}
else:
sec['audibility'] = check_audibility(ctx, groups, a.layers)
sec['harshness'] = check_harshness(ctx, live)
sec['sync'] = check_sync(ctx, live)
sec['density'] = check_density(ctx, live)
if a.listen or a.realness:
sec['listen'] = listen(ctx, a)
if not any(np.any(v) for v in ctx.stems.values()):
sec['mix'] = {'status': 'fail', 'summary': 'every stem is digital silence: nothing was mixed (check the trims with '
'mix.py --dump, the gains and the cue matches)'}
order = {'fail': 0, 'warn': 1, 'ok': 2, 'skipped': 3}
worst = min((s['status'] for s in sec.values()), key=lambda s: order.get(s, 9))
bad = [k for k, s in sec.items() if s['status'] in ('fail', 'warn')]
skipped = [k for k, s in sec.items() if s['status'] == 'skipped']
summary = (f"QA {worst.upper()}: " + (', '.join(f"{k} {sec[k]['status']}" for k in bad) if bad else
'every check that ran passed' if skipped else 'every check passed')
+ (f" (not run: {', '.join(skipped)})" if skipped else '')
+ (f". Master gain over the stems {ctx.G:+.1f} dB (levels below are at master scale)." if ctx.scale == 'master'
else '. Master or premaster silent / too short: levels below are at stem scale.' if ctx.master is not None
else '. No master: levels below are at stem scale.'))
return {'summary': summary, 'status': worst, 'note': note, 'sections': sec,
'inputs': {'design': a.design, 'report': a.report, 'trace': a.trace, 'stems': a.stems, 'master': a.master,
'only': a.only}}
def digest(res):
lines = [res['summary']]
for k, s in res['sections'].items():
lines.append(f"[{s['status'].upper():7s}] {k}: {s['summary']}")
if k == 'clicks':
for c in s.get('items', [])[:6]:
o = c['owners'][0] if c['owners'] else {}
lines.append(f" {c['in']} {c['t']:.3f} ({fmt_t(c['t'])}) ch{c['ch']} conc {c['conc']}: "
f"{o.get('bus', '?')}:{o.get('what', '?')} [{o.get('rule', '')}] at its {o.get('where', '?')}")
elif k == 'edges':
for it in [i for i in s.get('items', []) + s.get('splices', []) if i['issues']][:8]:
lines.append(f" {it.get('what', 'music')} {it.get('name', it.get('segment'))}: {'; '.join(it['issues'])}")
elif k == 'audibility':
for r in s.get('items', [])[:6]:
if r['verdict'] == 'silent':
lines.append(f" {r['t']:.3f} ({fmt_t(r['t'])}) {r['label']}: SILENT, peak {r['peak_db']} dBFS "
f"[{', '.join(r['samples'])[:80]}]")
elif r['verdict'] in ('masked', 'barely'):
lines.append(f" {r['t']:.3f} ({fmt_t(r['t'])}) {r['label']}: read {r['read_db']} dB ({r['verdict']}), "
f"vs bed {r['vs_bed_db']} dB @ {r['vs_bed_hz']} Hz [{', '.join(r['rules'])[:80]}]")
elif k == 'harshness':
for r in [r for r in s.get('items', []) if r['issues']][:5]:
lines.append(f" {r['t']:.3f} ({fmt_t(r['t'])}) {r['label']}: {'; '.join(r['issues'])} [{', '.join(r['rules'])[:70]}]")
elif k == 'sync':
for r in s.get('items', [])[:6]:
lines.append(f" cue {r['t_cue']:.3f} ({fmt_t(r['t_cue'])}) {r['label']}: {r['issue']}")
for r in s.get('deliberate', [])[:6]:
lines.append(f" cue {r['t_cue']:.3f} ({fmt_t(r['t_cue'])}) {r['label']}: deliberate, "
+ (r.get('explained') or f"{r['issue']} (qa_ok: {r.get('qa_ok')})"))
return '\n'.join(lines)
def main(argv=None):
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument('--root', default='.', help='project root: relative paths resolve against it')
ap.add_argument('--design', default='audio/sounddesign.json')
ap.add_argument('--report', help='default out/qa/mix_report.json (--only: out/audio-review/solo/<only>_report.json)')
ap.add_argument('--trace', default='out/qa/adds.json', help='mix.py --trace output (attribution, layers)')
ap.add_argument('--stems', help='default out/audio/stems (--only: out/audio-review/solo/<only>_stems)')
ap.add_argument('--master', help='default out/audio/soundtrack.wav (--only: none); "none" skips it')
ap.add_argument('--cues', help='cue file (default: the design\'s "cues", else out/cues.json)')
ap.add_argument('--cues-sounded', default='out/qa/cues_sounded.json', help='for earshot timeline (--listen)')
ap.add_argument('--only', help='the same --only the mix was rendered with')
ap.add_argument('--cache', help='decode cache (default <root>/out/audio/cache, as mix.py)')
ap.add_argument('--video', help='the film, for earshot (--listen)')
ap.add_argument('--out', default='out/qa/qa.json')
ap.add_argument('--layers', action='store_true', help='also measure every layer of multi-layer events (dead layers)')
ap.add_argument('--listen', action='store_true', help='earshot timeline + sheet + critique of the master')
ap.add_argument('--realness', action='store_true', help='earshot realness of every source recording used')
ap.add_argument('--json', action='store_true', help='print the full result as JSON')
a = ap.parse_args(argv)
base = 'out/audio-review/solo/' + re.sub(r'[^A-Za-z0-9._-]+', '_', a.only) if a.only else None
a.report = a.report or (base + '_report.json' if base else 'out/qa/mix_report.json')
a.stems = a.stems or (base + '_stems' if base else 'out/audio/stems')
a.master_given = bool(a.master) and a.master.lower() != 'none'
a.master = None if (a.master or '').lower() == 'none' else a.master or (None if base else 'out/audio/soundtrack.wav')
out = os.path.normpath(a.out if os.path.isabs(a.out) else os.path.join(os.path.abspath(a.root), a.out))
os.makedirs(os.path.dirname(out), exist_ok=True)
try:
res = run_qa(a)
except InputError as e:
say(f'qa.py: {e}')
return 2
full = clean(res)
json.dump(full, open(out, 'w'), indent=1)
say(json.dumps(full, indent=1) if a.json else digest(res) + f'\nwrote {out}')
return 1 if res['status'] == 'fail' else 0
if __name__ == '__main__':
sys.exit(main())