foley.weave.master#

Mastering — loudness-normalize + true-peak-limit the finished mix (report 06 §5).

Normalises the whole program to a MasterProfile integrated-loudness target (ITU-R BS.1770-4 / EBU R128 via pyloudnorm) and holds an inter-sample true-peak ceiling. It reuses foley.audio.loudness_normalize() (the same BS.1770 meter Tier-0 QC uses) for the LUFS stage and foley.qc.true_peak_dbtp() (oversampled) for the ceiling — so pyloudnorm comes from the existing audio extra (no redundant dependency) and is imported function-locally, keeping import foley.weave dol-only.

The default engine='auto' masters fully in-process (portable, testable). engine='ffmpeg' runs the two-pass ffmpeg loudnorm “guarantee the numbers” master (report 06 §5.4) — measure, then apply a linear loudnorm to the measured values — and fails safe back to the in-process path when the ffmpeg binary is unavailable or errors, so weaving never depends on it. ffmpeg is a WEAVE system requirement (see foley.weave.requirements); everything is lazy so import foley.weave stays dol-only.

Functions

master(mix, sample_rate, profile, *[, engine])

Master mix to profile — LUFS-normalise then true-peak-limit (report 06 §5).

Classes

MasterReport(target_lufs, input_lufs, ...)

What the master stage did — a JSON-serialisable audit row for the run-artifact.
class foley.weave.master.MasterReport(target_lufs, input_lufs, output_lufs, true_peak_dbtp, true_peak_ceiling_db, gain_db, limited, engine)[source]#

Bases: object

What the master stage did — a JSON-serialisable audit row for the run-artifact.

to_dict()[source]#

Return the plain-dict form (for WeaveResult.master_report / obs).

Return type:

dict

foley.weave.master.master(mix, sample_rate, profile, *, engine='auto')[source]#

Master mix to profile — LUFS-normalise then true-peak-limit (report 06 §5).

Parameters:

  • mix (ndarray) – The summed working mix (stereo (frames, 2) float32).

  • sample_rate (int) – Sample rate in Hz.

  • profile (MasterProfile) – The MasterProfile (target LUFS / true-peak / LRA).

  • engine (str) – 'auto'/'inprocess' master in-process (default, portable). 'ffmpeg' uses the two-pass ffmpeg loudnorm “guarantee the numbers” master (report 06 §5.4) and fails safe back to in-process if ffmpeg is unavailable or errors.

Return type:

tuple[ndarray, MasterReport]

Returns:

(mastered_mix, MasterReport). Loudness is measured before and after so the report is a faithful audit; when a true-peak limit engages, output LUFS may sit slightly below target (peak-safety wins over exact loudness).