diff --git a/README.md b/README.md index a2da879..b84a181 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ opendubstage qc mix.wav --md qc.md # loudness, true peak, LRA, dead ai | Spectral repair | Fill coughs, thumps and handling noise with the recording's own room tone; attenuate events under speech | `opendubstage specrepair` | | De-rumble | Take car rumble and room boom out of a voice memo without touching the voice above 400 Hz | `opendubstage memofix` | | Dialogue EQ match | Match one voice's long-term spectrum to another's with a gain-limited EQ, emitted as an `ffmpeg` filter chain | `opendubstage ltasmatch` | +| Dialogue leveller | Ride whole phrases from word timings, with pause-only ramps and explicit breath policy | `opendubstage leveller` | | Music carve | Dip the music's 1–4 kHz band while someone speaks; bring music up in the gaps (posts); end cues on a phrase | `opendubstage carve` | | Transitions | J-cuts, L-cuts and equal-power crossfades at chapter boundaries, on a cue sheet, without moving sync | `opendubstage transitions` | | Mix QC | BS.1770-4 integrated loudness, true peak, LRA, dead air, clicks at edits, voice level jumps, music masking speech | `opendubstage qc` | @@ -55,8 +56,7 @@ opendubstage qc mix.wav --md qc.md # loudness, true peak, LRA, dead ai diff the result. It is not a replacement for RX on a difficult track. It is the batchable, checkable version of the routine pass. - **Auphonic** is a hosted service that levels, normalises loudness and reduces noise in one upload. OpenDubStage runs - offline, uploads nothing, and splits the work into separate steps with their parameters exposed. It has no dialogue - leveller yet; that is first on the [roadmap](ROADMAP.md). + offline, uploads nothing, and splits the work into separate steps with their parameters exposed. Its experimental [dialogue leveller](docs/leveller.md) uses explicit word timings; it does not infer speech or replace listening review. - **pyloudnorm** is a BS.1770 loudness meter and normaliser library. `qc` measures gated integrated loudness and true peak the same way, then adds what a broadcast QC pass asks for on top: LRA, dead air, clicks at cue edges, level jumps between voices and masking of speech in the presence band, with blocking and advisory checks kept separate. @@ -72,12 +72,13 @@ opendubstage qc mix.wav --md qc.md # loudness, true peak, LRA, dead ai | | `memofix` | Removes rumble from a voice memo recorded in a car (or a boomy room). It learns a noise profile from the gaps between words, subtracts below 400 Hz only, then applies a gentle, clamped EQ toward the international long-term average speech spectrum. Nothing is resynthesised. | | `opendubstage.match` | `ltasmatch` | Dialogue EQ match. It compares long-term average spectra on speech frames, then fits a smoothed, gain-limited set of peaking bands. The output is a plain `ffmpeg` `equalizer` chain, plus an early-reflections helper for putting a dry voice in a small room. | | `opendubstage.mix` | `carve` | Speech-keyed dynamic EQ: the music's 1–4 kHz band dips while dialogue is active. It also provides *posts*, where music comes up in the gaps between lines and dips just before the next word, and *phrase-safe* music outs on a section, phrase or downbeat. | +| | `leveller` | Experimental phrase-constant gain rides, linked across channels, with sample-peak headroom caps and JSON audit report. See [method and timing schema](docs/leveller.md). | | | `transitions` | A cue-sheet pass at chapter boundaries. It adds ambience pre-laps (J-cuts), tails (L-cuts) and equal-power music crossfades, and puts a short ambience gap between two foreground songs. It never moves a sync point, touches dialogue or extends a cue past its source. | | `opendubstage.qc` | `qc` | Public-radio-style mix QC: integrated loudness (BS.1770-4 gating), true peak, LRA, dead air, clicks at cue edges, level jumps between voices, music/ambience masking of speech in the presence band, hard stops and tonal balance per voice class. Blocking and advisory checks are kept separate. | | `opendubstage.foley` | `foley` | Sound for stills and archival footage. It analyses each picture, proposes sounds, then applies documentary placement rules (levels relative to dialogue, density caps, never on the cut, key-line protection, no-sound classes). The output is an auditable cue sheet. Library and local-model backends are pluggable. See [docs/foley.md](docs/foley.md). | | `skills/` | | Agent skills for documentary sound design; see [skills/README.md](skills/README.md). | -The planned tools (dialogue leveller, room-tone synthesis, de-reverb, a true-peak limiter helper and an MLX VoxCPM LoRA +The planned tools (room-tone synthesis, de-reverb, a true-peak limiter helper and an MLX VoxCPM LoRA training port) are listed in [ROADMAP.md](ROADMAP.md). ## Install diff --git a/ROADMAP.md b/ROADMAP.md index 31858ea..2246f43 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -18,7 +18,14 @@ plus objective checks, never by a metric alone. ## 0.2: planned tools -### Dialogue leveller +### Dialogue leveller (experimental word-timing implementation) + +Implemented as `opendubstage leveller`; see [method, defaults and limitations](docs/leveller.md). +Synthetic invariants cover convergence when limits allow, word-safe gains and exact untouched samples. +VAD input, real-world listening validation and a release remain pending. +The current phrase meter is ungated K-weighted mean square, not standardized three-second short-term loudness. + +Original goal: A sentence-level leveller in the spirit of a dialogue-leveller plug-in, as opposed to a compressor: - Measure short-term loudness per phrase (from word timings or a VAD) and ride each phrase toward a target with slow, phrase-aligned gain moves. Gain changes happen in pauses, never mid-word. diff --git a/docs/leveller.md b/docs/leveller.md new file mode 100644 index 0000000..7940c82 --- /dev/null +++ b/docs/leveller.md @@ -0,0 +1,74 @@ +# Experimental dialogue leveller + +`opendubstage leveller input.wav output.wav --timings words.json --report report.json` + +This offline gain rider takes explicit word timings. It does not detect speech, transcribe, +compress, denoise, or send audio anywhere. Input and output are mono/stereo PCM or floating-point +WAV files, with the input sample rate and subtype preserved. The full recording is held in RAM. + +## Timing schema + +```json +{ + "words": [{"start": 0.5, "end": 1.0}, {"start": 1.1, "end": 1.8}], + "breaths": [{"start": 2.0, "end": 2.2}] +} +``` + +Times are seconds relative to sample zero. Each list must be ordered and non-overlapping, +within the recording, and have positive durations. Breaths must not intersect words. +Fractional sample edges round outward to protect words. Extra fields such as transcript +text are ignored and not copied into the report. Empty word lists are valid. + +## Method and defaults + +Words separated by at most `--phrase-gap 0.3` seconds form one phrase. An explicit breath +splits a phrase even when the gap is short. All channels receive the same gain, held constant +from the first word's start to the last word's end, including internal gaps. The meter resets +at each phrase and measures ungated K-weighted mean-square energy with mono/stereo channel +summing. This is a useful phrase descriptor, **not** EBU standardized 3-second short-term, +gated integrated loudness, or a claim of delivery compliance. + +- `--target -24`: phrase target, inspired by A/85 dialogue level as a starting point. +- `--min-gain -12`, `--max-gain 6`: conservative gain bounds, in dB. +- `--tolerance 0.5`: leave phrases already this close to target untouched. +- `--floor -60`: do not boost near-silent phrases. Digital silence remains unchanged. +- `--ramp 0.15`: raised-cosine ramps in dB before/after each event, entirely outside words + and breaths. Each ramp requires the configured duration (rounded up, at least two samples), + using at most half the available gap. If a full ramp cannot fit at either internal + boundary, the entire event stays unchanged, with `insufficient_pause` recorded. + Thus a 150 ms ramp requires at least 300 ms of gap on that side. Farther gaps stay + untouched; recording start/end need no outside ramp. Choose shorter ramps explicitly + only after listening; the algorithm never silently substitutes a sharp transition. +- `--peak-ceiling -1`: cap positive gain against the maximum sample peak across the whole + affected phrase and ramp support. Existing over-ceiling material is not globally repaired. + This is a sample-peak guard, **not** a true-peak limiter; use `opendubstage qc` on the result. +- `--breath-policy keep`: keep explicitly marked breath samples bit-exact (the default). + `--breath-policy attenuate --breath-db -6` instead applies fixed attenuation, with the same + pause-only ramp protection. Unmarked breaths inside phrases receive that phrase's gain. + +Other than the target's broadcast inspiration, these defaults are engineering starting +points chosen for restraint, not perceptually validated universal settings. In particular, +phrase boundaries and breath timings need review. When gain/headroom limits bind, the target +is deliberately not reached. The synthetic tests establish signal properties, not perceived +improvement; blind listening review is still needed before use on productions. + +## Report and exactness + +The JSON report uses schema `opendubstage.leveller/0.1`. It includes parameters, per-event +sample bounds and ramp supports, requested/applied gains, gain/headroom-limit flags, +before/after phrase loudness, and input/output sample peaks. Digital silence is represented +by `null`, never non-standard JSON infinity. All sample ranges are half-open `[start, end)`. +`changed_ranges` describes non-unity gain; `untouched_ranges` its complement. A changed range +can contain zero samples that numerically remain zero. + +Measurements are made before WAV encoding. Unchanged decoded PCM/float samples are preserved, +not the entire WAV container or metadata. Changed PCM samples are quantized to the original +subtype. No-op does not mean "normalize the whole file." The API returns a new array and never +modifies the source. The CLI requires distinct input, output, timings and report paths; like +other tools it can overwrite existing output destinations, so choose fresh filenames. + +```python +from opendubstage.mix.leveller import level +processed, report = level(audio_float_array, sample_rate, timings_dict) +``` diff --git a/opendubstage/cli.py b/opendubstage/cli.py index 735c847..ef68453 100644 --- a/opendubstage/cli.py +++ b/opendubstage/cli.py @@ -11,6 +11,7 @@ # tool -> (module, one-line help). Modules are imported lazily so `--help` stays fast and light. TOOLS = { + "leveller": ("opendubstage.mix.leveller", "phrase-safe dialogue gain rides from word timings"), "specrepair": ("opendubstage.restore.specrepair", "spectral repair: room-tone replace, attenuate, LF thumps"), "memofix": ("opendubstage.restore.memofix", "remove car/room rumble learned from word gaps, LTASS matching EQ"), "ltasmatch": ("opendubstage.match.ltasmatch", "dialogue EQ match: fit an ffmpeg equalizer chain from LTAS"), diff --git a/opendubstage/foley/rules.py b/opendubstage/foley/rules.py index f9a4ed6..688535d 100644 --- a/opendubstage/foley/rules.py +++ b/opendubstage/foley/rules.py @@ -176,10 +176,13 @@ def room_of(s: Still, a: SceneAnalysis) -> str | None: xf = r.bed_crossfade_s if i > 0 else 0.0 span = Interval(max(0.0, run[0].start - xf), run[-1].end) for part in _subtract(span, list(seq.silences)): - sheet.cues.append(Cue(nid("b"), Layer.BED, bed, part.start, part.dur, + dur = part.dur + while part.start + dur > part.end: # preserve silence boundaries after float subtraction/addition + dur = math.nextafter(dur, 0.0) + sheet.cues.append(Cue(nid("b"), Layer.BED, bed, part.start, dur, target_lufs(Layer.BED, seq.dialogue_lufs), - fade_in=min(r.bed_crossfade_s, part.dur / 2), - fade_out=min(r.bed_crossfade_s if i < len(runs) - 1 else 2.0, part.dur / 2), + fade_in=min(r.bed_crossfade_s, dur / 2), + fade_out=min(r.bed_crossfade_s if i < len(runs) - 1 else 2.0, dur / 2), prompt=bed_prompt(bed, tod), room=ROOM_FOR_BED.get(bed))) # 2. transitions: hand-requested only, <= N per chapter run, straddling the cut diff --git a/opendubstage/mix/leveller.py b/opendubstage/mix/leveller.py new file mode 100644 index 0000000..15f3fb5 --- /dev/null +++ b/opendubstage/mix/leveller.py @@ -0,0 +1,204 @@ +"""Conservative offline phrase levelling from explicit word timings (no VAD or compressor). + +Timing JSON: {"words": [{"start": 0.2, "end": 1.0}, ...], + "breaths": [{"start": 1.2, "end": 1.4}, ...]}. +Times are seconds, ordered, non-overlapping and inside the recording. Breaths must not +intersect words. Unknown fields (e.g. transcript text) are ignored, never copied to reports. + +Measurement is ungated K-weighted mean-square loudness over each phrase, using the +BS.1770 filter and mono/stereo channel sum. It is NOT standardized 3-second short-term +or gated programme loudness. The target -24 is a starting point inspired by A/85, +not a delivery compliance claim. Other defaults are conservative engineering choices: +300 ms phrase gap, 150 ms raised-cosine ramps in pauses, -12/+6 dB gain limits, +0.5 LU no-op tolerance, -60 loudness floor (do not boost near-silence), -1 dBFS +sample-peak ceiling, and breaths kept unchanged unless explicitly attenuated by 6 dB. +Ramps require the configured duration at internal boundaries, using at most half each +available gap. If a full ramp does not fit, the entire event is left unchanged and +reported as insufficient_pause. Phrase gains never change mid-word. Clipping prevention caps +positive gain using the entire affected support. This is not +an inter-sample true-peak limiter; already-hot untouched input is reported, not repaired. + +API: level(audio, sr, timings, **options) -> (audio_copy, report). Mono/stereo float +arrays only. Report schema opendubstage.leveller/0.1 contains parameters, event sample +bounds, gains, before/after phrase measurements, headroom constraints, actual changed +and untouched sample ranges, and sample peaks. Null loudness means digital silence. +CLI preserves the input WAV subtype; bit-exact means decoded samples in untouched +regions, not byte-identical WAV containers. Report measurements precede output encoding. +""" +from __future__ import annotations + +import argparse +import json +import math +from pathlib import Path + +import numpy as np +import soundfile as sf +from scipy.signal import sosfilt + +from opendubstage.qc.mixqc import kweight_sos + + +def phrase_loudness(audio, sr): + """Ungated K-weighted phrase loudness; null for digital silence.""" + x = np.asarray(audio, dtype=np.float64) + if x.ndim == 1: + x = x[:, None] + z = sosfilt(kweight_sos(sr), x, axis=0) + power = float(np.mean(np.sum(z * z, axis=1))) + return -0.691 + 10 * math.log10(power) if power > 0 else None + + +def _intervals(items, sr, n, name): + if not isinstance(items, list): + raise ValueError(f'{name} must be a list') + result = [] + previous = 0.0 + for item in items: + if not isinstance(item, dict): + raise ValueError(f'{name} entries must have start/end seconds') + try: + a, b = float(item['start']), float(item['end']) + except (KeyError, TypeError, ValueError) as exc: + raise ValueError(f'{name} entries must have numeric start/end') from exc + if not (math.isfinite(a) and math.isfinite(b) and previous <= a < b <= n / sr): + raise ValueError(f'{name} must be ordered, non-overlapping and within audio') + # Protect every sample touched by a word, including fractional-sample edges. + lo, hi = int(math.floor(a * sr)), min(n, int(math.ceil(b * sr))) + if result and lo < result[-1][1]: + raise ValueError(f'{name} overlap at sample resolution') + result.append((lo, hi)) + previous = b + return result + + +def _ranges(mask): + edges = np.flatnonzero(np.diff(np.r_[False, mask, False])) + return [[int(a), int(b)] for a, b in edges.reshape(-1, 2)] + + +def _peak(x): + p = float(np.max(np.abs(x))) if x.size else 0.0 + return 20 * math.log10(p) if p else None + + +def level(audio, sr, timings, *, target=-24.0, phrase_gap=0.3, ramp=0.15, + min_gain=-12.0, max_gain=6.0, tolerance=0.5, floor=-60.0, + peak_ceiling=-1.0, breath_policy='keep', breath_db=-6.0): + """Return a new float array and JSON-safe report; never modify the input.""" + x = np.asarray(audio) + if x.dtype.kind != 'f' or x.ndim not in (1, 2) or (x.ndim == 2 and x.shape[1] not in (1, 2)): + raise ValueError('audio must be a mono/stereo floating-point array') + if not np.all(np.isfinite(x)) or not isinstance(sr, (int, np.integer)) or sr < 8000: + raise ValueError('audio must be finite and sample rate an integer >= 8000') + params = dict(target=target, phrase_gap=phrase_gap, ramp=ramp, min_gain=min_gain, + max_gain=max_gain, tolerance=tolerance, floor=floor, + peak_ceiling=peak_ceiling, breath_policy=breath_policy, breath_db=breath_db) + if not all(isinstance(v, (int, float)) and math.isfinite(v) for k, v in params.items() if k != 'breath_policy'): + raise ValueError('parameters must be finite numbers') + if not (0 <= phrase_gap and 0 < ramp and min_gain <= 0 <= max_gain <= 60 and + min_gain >= -120 and tolerance >= 0 and floor < target <= 0 and + peak_ceiling <= 0 and -120 <= breath_db <= 0 and breath_policy in ('keep', 'attenuate')): + raise ValueError('invalid leveller parameters') + if not isinstance(timings, dict) or 'words' not in timings: + raise ValueError('timings must contain a words list') + n = len(x) + words = _intervals(timings['words'], sr, n, 'words') + breaths = _intervals(timings.get('breaths', []), sr, n, 'breaths') + if any(a < d and c < b for a, b in words for c, d in breaths): + raise ValueError('breaths must not overlap words') + phrases = [] + for a, b in words: + if (phrases and a - phrases[-1][1] <= phrase_gap * sr and + not any(c < a and d > phrases[-1][1] for c, d in breaths)): + phrases[-1][1] = b + else: + phrases.append([a, b]) + ramp_samples = max(2, int(math.ceil(ramp * sr))) + events = sorted([(a, b, 'phrase') for a, b in phrases] + [(a, b, 'breath') for a, b in breaths]) + envelope = np.ones(n, dtype=np.float64) + report_events = [] + for i, (a, b, kind) in enumerate(events): + left = events[i - 1][1] if i else 0 + right = events[i + 1][0] if i + 1 < len(events) else n + pre = min(ramp_samples, (a - left) // 2) + post = min(ramp_samples, (right - b) // 2) + lo, hi = a - pre, b + post + before = phrase_loudness(x[a:b], sr) + requested = 0.0 + reason = 'breath_kept' if kind == 'breath' else 'within_tolerance' + if kind == 'breath' and breath_policy == 'attenuate': + requested, reason = breath_db, 'breath_attenuated' + elif kind == 'phrase': + if before is None or before < floor: + reason = 'below_floor' + elif abs(target - before) > tolerance: + requested, reason = target - before, 'levelled' + gain = float(np.clip(requested, min_gain, max_gain)) if kind == 'phrase' else requested + peak = _peak(x[lo:hi]) + headroom_limited = gain > 0 and peak is not None and gain > max(0.0, peak_ceiling - peak) + if headroom_limited: + gain = max(0.0, peak_ceiling - peak) + insufficient_pause = gain != 0 and ((a > 0 and pre < ramp_samples) or (b < n and post < ramp_samples)) + if insufficient_pause: + gain, reason = 0.0, 'insufficient_pause' + if gain != 0: + envelope[a:b] = 10 ** (gain / 20) + if pre: + t = np.arange(pre) / pre + envelope[lo:a] = 10 ** (gain * (0.5 - 0.5 * np.cos(np.pi * t)) / 20) + if post: + t = np.arange(1, post + 1) / post + envelope[b:hi] = 10 ** (gain * (0.5 + 0.5 * np.cos(np.pi * t)) / 20) + report_events.append(dict(kind=kind, start_sample=a, end_sample=b, + support=[lo, hi], before_loudness=before, + requested_gain_db=requested, gain_db=gain, reason=reason, + gain_limited=not math.isclose(gain, requested), + headroom_limited=bool(headroom_limited), + insufficient_pause=bool(insufficient_pause))) + y = x.copy() + changed = envelope != 1.0 + y[changed] = x[changed] * (envelope[changed, None] if x.ndim == 2 else envelope[changed]) + for event in report_events: + event['after_loudness'] = phrase_loudness(y[event['start_sample']:event['end_sample']], sr) + report = dict(schema='opendubstage.leveller/0.1', sample_rate=int(sr), samples=n, + measurement='ungated K-weighted phrase mean-square (not EBU short-term)', + parameters=params, events=report_events, changed_ranges=_ranges(changed), + untouched_ranges=_ranges(~changed), input_sample_peak_dbfs=_peak(x), + output_sample_peak_dbfs=_peak(y), peak_ceiling_is_true_peak=False) + return y, report + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument('input', type=Path) + parser.add_argument('output', type=Path) + parser.add_argument('--timings', type=Path, required=True) + parser.add_argument('--report', type=Path, required=True) + for name, default in [('target', -24.), ('phrase-gap', .3), ('ramp', .15), + ('min-gain', -12.), ('max-gain', 6.), ('tolerance', .5), + ('floor', -60.), ('peak-ceiling', -1.), ('breath-db', -6.)]: + parser.add_argument('--' + name, type=float, default=default) + parser.add_argument('--breath-policy', choices=['keep', 'attenuate'], default='keep') + args = vars(parser.parse_args(argv)) + src, dst, timing_path, report_path = [args.pop(k) for k in ('input', 'output', 'timings', 'report')] + if len({p.resolve() for p in (src, dst, timing_path, report_path)}) != 4: + parser.error('input, output, timings and report must be distinct paths') + try: + info = sf.info(src) + if info.format not in ('WAV', 'WAVEX') or dst.suffix.lower() != '.wav': + raise ValueError('input and output must be WAV files') + if info.subtype not in ('PCM_U8', 'PCM_16', 'PCM_24', 'PCM_32', 'FLOAT', 'DOUBLE'): + raise ValueError('WAV must use lossless PCM or floating-point samples') + x, sr = sf.read(src, dtype='float64') + y, report = level(x, sr, json.loads(timing_path.read_text()), **args) + encoded_report = json.dumps(report, indent=2, allow_nan=False) + '\n' + sf.write(dst, y, sr, subtype=info.subtype) + report_path.write_text(encoded_report) + except (ValueError, OSError, RuntimeError) as exc: + parser.error(str(exc)) + return 0 + + +if __name__ == '__main__': + raise SystemExit(main()) diff --git a/tests/foley/test_rules.py b/tests/foley/test_rules.py index a106e9a..7831df1 100644 --- a/tests/foley/test_rules.py +++ b/tests/foley/test_rules.py @@ -193,3 +193,20 @@ def test_texture_end_never_rounds_past_a_block(): tex = sheet.by_layer(Layer.TEXTURE) assert tex and tex[0].end <= b assert check(sheet, seq) == [] + + +def test_bed_duration_rounding_never_crosses_designed_silence(): + from opendubstage.foley.analysis import KeywordAnalyzer + from opendubstage.foley.model import Interval, Layer, Sequence, Still + + boundary = 33.576484481558374 + seq = Sequence(stills=[ + Still(id='a', start=0, dur=6.140261126968152, chapter='a', caption='cars on a highway'), + Still(id='b', start=6.140261126968152, dur=28, chapter='b', caption='cars on a highway'), + ], silences=[Interval(boundary, boundary + 1)]) + analyzer = KeywordAnalyzer() + sheet = plan(seq, {s.id: analyzer.analyze(s) for s in seq.stills}) + beds = [c for c in sheet.cues if c.layer is Layer.BED] + assert len(beds) == 2 + assert all(c.end <= boundary for c in beds) + assert check(sheet, seq) == [] diff --git a/tests/test_leveller.py b/tests/test_leveller.py new file mode 100644 index 0000000..7ffd9b4 --- /dev/null +++ b/tests/test_leveller.py @@ -0,0 +1,152 @@ +"""Synthetic invariants for phrase-safe levelling, no recordings or models.""" +import json + +import numpy as np +import pytest +import soundfile as sf + +from opendubstage.cli import main +from opendubstage.mix.leveller import level, phrase_loudness + +SR = 16000 + + +def tone(seconds=4, amplitude=.03): + t = np.arange(int(seconds * SR)) / SR + return amplitude * np.sin(2 * np.pi * 440 * t) + + +def test_converges_and_never_moves_inside_words(): + x = tone() + x[2 * SR:3 * SR] *= 4 + timings = {'words': [{'start': .5, 'end': 1}, {'start': 1.1, 'end': 1.5}, + {'start': 2, 'end': 3}]} + y, rep = level(x, SR, timings, min_gain=-24, max_gain=24) + for e in rep['events']: + assert abs(e['after_loudness'] + 24) < 1 + a, b = e['start_sample'], e['end_sample'] + np.testing.assert_allclose(y[a:b], x[a:b] * 10 ** (e['gain_db'] / 20), rtol=1e-14) + for a, b in rep['untouched_ranges']: + assert np.array_equal(y[a:b], x[a:b]) + assert np.array_equal(y[:int(.3 * SR)], x[:int(.3 * SR)]) + + +def test_noop_bit_exact_input_not_mutated(): + x = tone() + original = x.copy() + target = phrase_loudness(x[SR:2 * SR], SR) + y, rep = level(x, SR, {'words': [{'start': 1, 'end': 2}]}, target=target) + assert np.array_equal(x, original) and np.array_equal(y, original) + assert rep['changed_ranges'] == [] + assert rep['untouched_ranges'] == [[0, len(x)]] + + +def test_silence_empty_timings_and_empty_audio(): + for x, words in [(np.zeros(SR), [{'start': 0, 'end': 1}]), (tone(), []), (np.zeros(0), [])]: + y, rep = level(x, SR, {'words': words}) + assert np.array_equal(x, y) + json.dumps(rep, allow_nan=False) + + +def test_stereo_linked_and_limits(): + x = np.stack([tone(), tone() * .5], axis=1) + y, rep = level(x, SR, {'words': [{'start': 1, 'end': 2}]}, target=-10, max_gain=2) + assert rep['events'][0]['gain_db'] == 2 + np.testing.assert_allclose(y[:, 0], y[:, 1] * 2) + assert rep['events'][0]['gain_limited'] + + +def test_peak_limit_checks_ramp_support(): + x = tone(amplitude=.01) + x[int(.9 * SR)] = .88 # in the fade, not in the phrase + y, rep = level(x, SR, {'words': [{'start': 1, 'end': 2}]}, max_gain=30) + assert rep['events'][0]['headroom_limited'] + assert np.max(np.abs(y)) <= 10 ** (-1 / 20) + 1e-12 + + +def test_breath_keep_splits_close_phrases_and_is_exact(): + x = tone() + timing = {'words': [{'start': .5, 'end': 1}, {'start': 1.2, 'end': 2}], + 'breaths': [{'start': 1.05, 'end': 1.15}]} + y, rep = level(x, SR, timing, ramp=.01) + assert len(rep['events']) == 3 + assert np.array_equal(y[int(1.05 * SR):int(1.15 * SR)], x[int(1.05 * SR):int(1.15 * SR)]) + z, rep = level(x, SR, timing, breath_policy='attenuate', ramp=.01) + a, b = int(1.05 * SR), int(1.15 * SR) + np.testing.assert_allclose(z[a:b], x[a:b] * 10 ** (-6 / 20)) + + +@pytest.mark.parametrize('words,breaths', [ + ([{'start': -1, 'end': 1}], []), ([{'start': 1, 'end': 5}], []), + ([{'start': 1, 'end': 2}, {'start': 1.5, 'end': 3}], []), + ([{'start': float('nan'), 'end': 2}], []), + ([{'start': 1, 'end': 2}], [{'start': 1.9, 'end': 2.2}]), + ([{'start': 1, 'end': 1}], []), +]) +def test_invalid_intervals_rejected(words, breaths): + with pytest.raises(ValueError): + level(tone(), SR, {'words': words, 'breaths': breaths}) + + +@pytest.mark.parametrize('options', [{'ramp': 0}, {'max_gain': -1}, {'target': float('inf')}, + {'breath_db': 2}, {'breath_policy': 'delete'}, {'tolerance': -1}]) +def test_invalid_options(options): + with pytest.raises(ValueError): + level(tone(), SR, {'words': []}, **options) + + +def test_touching_words_share_gain_and_fractional_edges_protected(): + x = tone() + y, rep = level(x, SR, {'words': [{'start': .5 + .2 / SR, 'end': 1}, + {'start': 1, 'end': 2}]}) + assert len(rep['events']) == 1 + a, b = rep['events'][0]['start_sample'], rep['events'][0]['end_sample'] + np.testing.assert_allclose(y[a:b], x[a:b] * 10 ** (rep['events'][0]['gain_db'] / 20)) + + +def test_cli_roundtrip_preserves_unmodified_pcm_and_report(tmp_path): + src, dst, timings, report = [tmp_path / s for s in ('in.wav', 'out.wav', 'words.json', 'report.json')] + sf.write(src, tone(), SR, subtype='PCM_24') + timings.write_text(json.dumps({'words': [{'start': 1, 'end': 2}]})) + assert main(['leveller', str(src), str(dst), '--timings', str(timings), '--report', str(report)]) == 0 + x, sr = sf.read(src, dtype='int32') + y, _ = sf.read(dst, dtype='int32') + rep = json.loads(report.read_text()) + assert sr == SR and sf.info(dst).subtype == 'PCM_24' + for a, b in rep['untouched_ranges']: + assert np.array_equal(y[a:b], x[a:b]) + assert rep['schema'] == 'opendubstage.leveller/0.1' + with pytest.raises(SystemExit): + main(['leveller', str(src), str(src), '--timings', str(timings), '--report', str(report)]) + + +def test_touching_breath_boundaries_skip_rides_without_pause(): + x = np.full(3 * SR, .03) + timings = {'words': [{'start': .5, 'end': 1}, {'start': 1.1, 'end': 2}], + 'breaths': [{'start': 1, 'end': 1.1}]} + for policy in ('keep', 'attenuate'): + y, report = level(x, SR, timings, breath_policy=policy) + assert np.array_equal(x, y) + for event in report['events']: + if event['requested_gain_db'] != 0: + assert event['insufficient_pause'] + assert event['reason'] == 'insufficient_pause' + assert event['gain_db'] == 0 + + +def test_recording_edges_do_not_require_external_ramps(): + x = tone(1) + y, report = level(x, SR, {'words': [{'start': 0, 'end': 1}]}) + event = report['events'][0] + assert event['gain_db'] != 0 and not event['insufficient_pause'] + np.testing.assert_allclose(y, x * 10 ** (event['gain_db'] / 20)) + + +def test_short_nonzero_pause_does_not_substitute_one_sample_ramp(): + x = tone(3) + timings = {'words': [{'start': .5, 'end': 1}, {'start': 1.1 + 4 / SR, 'end': 2}], + 'breaths': [{'start': 1 + 2 / SR, 'end': 1.1 + 2 / SR}]} + y, report = level(x, SR, timings, breath_policy='attenuate') + assert np.array_equal(x, y) + assert all(e['insufficient_pause'] for e in report['events']) + assert all(e['gain_db'] == 0 for e in report['events'])