Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.
JavaScript agentagentsai-agentdeepagentsdesignhyperframeslanggraphmanaged-agentsmotion-graphicspaperslackvideo
#!/usr/bin/env node
// master.mjs: master a mix to a loudness target with two-pass ffmpeg loudnorm.
//
// node master.mjs <input audio|video> <output> [--target -14] [--true-peak -1] [--lra 11]
//
// Pass one measures the input (integrated loudness, true peak, loudness range, threshold); pass two
// applies loudnorm with those measurements, linear when the target allows it (one gain for the whole
// file, so the mix keeps its dynamics), dynamic otherwise. Dynamic mode converges slowly and lands
// short of the target on clips of a few seconds, so when the result misses by more than half a LU a
// trim pass applies the remaining static gain through a 4x-oversampled true-peak limiter. The output
// is measured with ebur128 and true peak, so the numbers printed are what the file is.
//
// Output by extension: .wav (24-bit PCM, 48 kHz), .mp3 (320 kbps), .m4a/.aac (AAC 256 kbps), or
// .mp4/.mov/.webm (the input's video stream copied, AAC audio). Lossy encoders add a few tenths of a
// dB of true peak, so master to a slightly lower --true-peak when the delivery is lossy.
//
// Prints one JSON line: {"ok","output","mode","target":{i,tp,lra},"input":{i,tp,lra},"result":{i,tp,lra}}.
// Exit 0 within ±1 LU of the target and at or under the true-peak ceiling · 1 written but off target
// (the JSON says by how much) · 2 bad arguments, a missing input or ffmpeg failed.
import { spawnSync } from "node:child_process";
import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { dirname, extname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
const FFMPEG = process.env.DESIGN_AGENT_FFMPEG || "ffmpeg";
export class MasterError extends Error {}
function ffmpeg(args) {
const run = spawnSync(FFMPEG, ["-hide_banner", "-nostdin", ...args], { encoding: "utf8", maxBuffer: 1 << 28 });
if (run.error) throw new MasterError(`ffmpeg could not run (${run.error.code || run.error.message})`);
if (run.status !== 0) throw new MasterError(`ffmpeg failed: ${(run.stderr || "").trim().split("\n").slice(-3).join(" ")}`);
return run.stderr || "";
}
/** The last {...} block loudnorm prints with print_format=json. */
function loudnormJson(stderr) {
const start = stderr.lastIndexOf("{");
const end = stderr.lastIndexOf("}");
if (start < 0 || end < start) throw new MasterError("loudnorm printed no measurement");
return JSON.parse(stderr.slice(start, end + 1));
}
/** Integrated loudness, true peak and loudness range of a file, from ebur128's summary. */
export function measure(file) {
const stderr = ffmpeg(["-i", file, "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"]);
const summary = stderr.slice(stderr.lastIndexOf("Summary:"));
const num = (re) => {
const m = re.exec(summary);
return m ? Number(m[1]) : null;
};
const i = num(/I:\s*(-?[\d.]+|-inf)\s*LUFS/);
const lra = num(/LRA:\s*(-?[\d.]+)\s*LU/);
const tp = num(/True peak:\s*Peak:\s*(-?[\d.]+|-inf)\s*dBFS/);
if (i === null) throw new MasterError(`could not measure loudness of ${file}`);
return { i, tp, lra };
}
const CODECS = {
".wav": ["-c:a", "pcm_s24le"],
".mp3": ["-c:a", "libmp3lame", "-b:a", "320k"],
".m4a": ["-c:a", "aac", "-b:a", "256k"],
".aac": ["-c:a", "aac", "-b:a", "256k"],
};
const VIDEO = new Set([".mp4", ".mov", ".webm", ".mkv"]);
export function master(input, output, { target = -14, truePeak = -1, lra = 11 } = {}) {
if (!existsSync(input)) throw new MasterError(`input not found: ${input}`);
const ext = extname(output).toLowerCase();
if (!CODECS[ext] && !VIDEO.has(ext)) throw new MasterError(`unsupported output type ${ext || "(none)"}`);
const base = `I=${target}:TP=${truePeak}:LRA=${lra}`;
const first = loudnormJson(ffmpeg(["-i", input, "-vn", "-af", `loudnorm=${base}:print_format=json`, "-f", "null", "-"]));
if (!Number.isFinite(Number(first.input_i)) || Number(first.input_i) < -70) {
throw new MasterError(`the input is silent (${first.input_i} LUFS): nothing to master`);
}
const measured = [
`measured_I=${first.input_i}`, `measured_TP=${first.input_tp}`, `measured_LRA=${first.input_lra}`,
`measured_thresh=${first.input_thresh}`, `offset=${first.target_offset}`,
].join(":");
mkdirSync(dirname(resolve(output)), { recursive: true });
const work = mkdtempSync(join(tmpdir(), "master-"));
try {
const normalized = join(work, "normalized.wav");
const second = loudnormJson(ffmpeg(["-i", input, "-vn", "-af", `loudnorm=${base}:${measured}:linear=true:print_format=json`,
"-ar", "48000", "-c:a", "pcm_f32le", "-y", normalized]));
let mode = String(second.normalization_type || "unknown").toLowerCase();
const after = measure(normalized);
let filter = "anull";
if (Math.abs(after.i - target) > 0.5) {
const ceiling = 10 ** (truePeak / 20);
filter = `volume=${(target - after.i).toFixed(2)}dB,aresample=192000,alimiter=limit=${ceiling.toFixed(4)}:level=false,aresample=48000`;
mode += "+trim";
}
const encode = ["-af", filter, "-ar", "48000"];
ffmpeg(VIDEO.has(ext)
? ["-i", input, "-i", normalized, "-map", "0:v?", "-map", "1:a:0", "-c:v", "copy", ...encode, "-c:a", "aac", "-b:a", "256k", "-shortest", "-y", output]
: ["-i", normalized, ...encode, ...CODECS[ext], "-y", output]);
const result = measure(output);
const within = Math.abs(result.i - target) <= 1 && (result.tp === null || result.tp <= truePeak + 0.05);
return {
ok: within,
output,
mode,
target: { i: target, tp: truePeak, lra },
input: { i: Number(first.input_i), tp: Number(first.input_tp), lra: Number(first.input_lra) },
result,
};
} finally {
rmSync(work, { recursive: true, force: true });
}
}
function cli(argv) {
const positional = [];
const flags = {};
for (let k = 0; k < argv.length; k++) {
const a = argv[k];
if (!a.startsWith("--")) positional.push(a);
else if (["--target", "--true-peak", "--lra"].includes(a) && argv[k + 1] !== undefined) flags[a.slice(2)] = Number(argv[++k]);
else throw new MasterError(`unknown or incomplete flag ${a}`);
}
if (positional.length !== 2) throw new MasterError("usage: master.mjs <input> <output> [--target -14] [--true-peak -1] [--lra 11]");
const options = { target: flags.target ?? -14, truePeak: flags["true-peak"] ?? -1, lra: flags.lra ?? 11 };
if (!Object.values(options).every(Number.isFinite)) throw new MasterError("--target, --true-peak and --lra take numbers");
return master(positional[0], positional[1], options);
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
try {
const report = cli(process.argv.slice(2));
console.log(JSON.stringify(report));
process.exitCode = report.ok ? 0 : 1;
} catch (error) {
console.log(JSON.stringify({ ok: false, error: error.message }));
process.exitCode = 2;
}
}