Skip to content

Write HTML. Render video. Built for agents.

feat(studio): normalize loudness and duck under voice, with a limiter report (4/8) (#4816)

Vance Ingalls9244c47328e4
diff --git a/packages/cli/src/commands/normalize-audio.test.ts b/packages/cli/src/commands/normalize-audio.test.ts
index 87f1f6ce47..a9a93753b6 100644
--- a/packages/cli/src/commands/normalize-audio.test.ts
+++ b/packages/cli/src/commands/normalize-audio.test.ts
@@ -175,3 +175,13 @@ describe("updateAudioVolume", () => {
);
});
});
+
+describe("normalize-audio on video clips", () => {
+ it("finds a video with sound as a target and skips a muted one", () => {
+ const html = `<video id="a-roll" src="talk.mp4" data-has-audio="true"></video><video id="b-roll" src="b.mp4" muted></video><audio id="music" src="m.mp3"></audio>`;
+ expect(audioTags(html).map((tag) => tag.id)).toEqual(["a-roll", "music"]);
+ expect(updateAudioVolume(html, "a-roll", 0.5)).toContain(
+ `<video id="a-roll" src="talk.mp4" data-has-audio="true" data-volume="0.5"></video>`,
+ );
+ });
+});
diff --git a/packages/cli/src/commands/normalize-audio.ts b/packages/cli/src/commands/normalize-audio.ts
index e85528ca6f..f31ef96336 100644
--- a/packages/cli/src/commands/normalize-audio.ts
+++ b/packages/cli/src/commands/normalize-audio.ts
@@ -1,410 +1,36 @@
-import { execFile } from "node:child_process";
import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { isAbsolute, relative, resolve } from "node:path";
-import { promisify } from "node:util";
-import { formatAudioGain, MAX_AUDIO_GAIN_DB } from "@hyperframes/core/audio-gain";
-import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
+import { relative } from "node:path";
+import {
+ absoluteLoudnessPlan,
+ audioNormalizationPlan,
+ audioTags,
+ DEFAULT_TARGET_LUFS,
+ measureAudio,
+ requiredFfmpeg,
+ resolveLocalAudioPath,
+ updateAudioVolume,
+ type AbsoluteLoudnessPlan,
+ type AudioNormalizationPlan,
+ type AudioTag,
+ type LoudnessLimit,
+} from "@hyperframes/studio-server/loudness";
import { defineCommand } from "citty";
import { c } from "../ui/colors.js";
import { resolveProject } from "../utils/project.js";
import { failCommand } from "../utils/commandResult.js";
import type { Example } from "./_examples.js";
-const execFileAsync = promisify(execFile);
-const FFMPEG_TIMEOUT_MS = 120_000;
-const DEFAULT_TOLERANCE_LU = 0.5;
-
-interface AttributeSpan {
- value: string;
- valueStart: number;
- valueEnd: number;
-}
-
-interface TagRange {
- start: number;
- end: number;
-}
-
-interface ParsedStartTag extends TagRange {
- closing: boolean;
- name: string;
-}
-
-interface ScanResult {
- cursor: number;
- audioRange: TagRange | null;
-}
-
-export interface AudioTag {
- id: string;
- src: string;
- volume: number;
- mediaStart: number;
- duration: number | null;
- start: number;
- end: number;
- volumeAttribute: AttributeSpan | null;
-}
-
-export interface LoudnessMeasurement {
- integratedLufs: number;
- truePeakDbfs: number;
-}
-
-export interface NormalizationTrack extends LoudnessMeasurement {
- id: string;
- volume: number;
-}
-
-export interface AudioNormalizationPlan {
- referenceId: string;
- targetId: string;
- referenceLufs: number;
- targetLufs: number;
- previousVolume: number;
- volume: number;
- gainDb: number;
- changeDb: number;
- projectedLufs: number;
- projectedTruePeakDbfs: number;
-}
-
-function authoredNumber(
- raw: string | undefined,
- fallback: number,
- attribute: string,
- id: string,
- strictlyPositive = false,
-): number {
- if (raw === undefined) return fallback;
- const value = Number(raw);
- if (!Number.isFinite(value) || (strictlyPositive ? value <= 0 : value < 0)) {
- throw new Error(`Audio #${id} has an invalid ${attribute}: ${raw}`);
- }
- return value;
-}
-
-function attributeFromMatch(
- match: RegExpMatchArray,
- absoluteOffset: number,
-): [string, AttributeSpan] | null {
- if (match.index === undefined) return null;
- const name = match[1]?.toLowerCase();
- const value = matchedAttributeValue(match);
- if (!name || value === undefined) return null;
-
- const whole = match[0];
- const localValueStart = attributeValueStart(whole);
- const valueStart = absoluteOffset + match.index + localValueStart;
- return [name, { value, valueStart, valueEnd: valueStart + value.length }];
-}
-
-function matchedAttributeValue(match: RegExpMatchArray): string | undefined {
- return match[2] ?? match[3] ?? match[4];
-}
-
-function attributeValueStart(attribute: string): number {
- let cursor = attribute.indexOf("=") + 1;
- while (/\s/.test(attribute[cursor] ?? "")) cursor += 1;
- const quote = attribute[cursor];
- return quote === '"' || quote === "'" ? cursor + 1 : cursor;
-}
-
-function attributesInTag(html: string, from: number, to: number): Map<string, AttributeSpan> {
- const tag = html.slice(from, to);
- const nameEnd = tag.search(/\s|\/?\s*>/);
- const attributes = new Map<string, AttributeSpan>();
- if (nameEnd < 0) return attributes;
-
- const pattern = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
- for (const match of tag.slice(nameEnd).matchAll(pattern)) {
- const attribute = attributeFromMatch(match, from + nameEnd);
- if (attribute) attributes.set(...attribute);
- }
- return attributes;
-}
-
-function startTagEnd(html: string, start: number): number {
- let quote = "";
- let end = start + 1;
- for (; end < html.length; end += 1) {
- const char = html[end];
- if (quote) {
- if (char === quote) quote = "";
- } else if (char === '"' || char === "'") {
- quote = char;
- } else if (char === ">") {
- return end + 1;
- }
- }
- throw new Error("Unterminated HTML start tag");
-}
-
-function commentEnd(html: string, start: number): number {
- const end = html.indexOf("-->", start + 4);
- if (end < 0) throw new Error("Unterminated HTML comment");
- return end + 3;
-}
-
-function parsedStartTag(html: string, start: number): ParsedStartTag | null {
- const match = html.slice(start).match(/^<\s*(\/?)\s*([a-z][a-z\d:-]*)\b/i);
- if (!match) return null;
- return {
- start,
- end: startTagEnd(html, start),
- closing: match[1] === "/",
- name: match[2]?.toLowerCase() ?? "",
- };
-}
-
-function rawTextElementEnd(html: string, lower: string, tag: ParsedStartTag): number | null {
- if (tag.closing || (tag.name !== "script" && tag.name !== "style")) return null;
- const closeStart = lower.indexOf(`</${tag.name}`, tag.end);
- if (closeStart < 0) throw new Error(`Unterminated <${tag.name}> element`);
- return startTagEnd(html, closeStart);
-}
-
-function scanMarkup(html: string, lower: string, start: number): ScanResult {
- if (html.startsWith("<!--", start)) {
- return { cursor: commentEnd(html, start), audioRange: null };
- }
- const tag = parsedStartTag(html, start);
- if (!tag) {
- const marker = html[start + 1];
- const cursor = marker === "!" || marker === "?" ? startTagEnd(html, start) : start + 1;
- return { cursor, audioRange: null };
- }
- const rawTextEnd = rawTextElementEnd(html, lower, tag);
- if (rawTextEnd !== null) return { cursor: rawTextEnd, audioRange: null };
- const audioRange = !tag.closing && tag.name === "audio" ? { start, end: tag.end } : null;
- return { cursor: tag.end, audioRange };
-}
-
-function audioTagRanges(html: string): TagRange[] {
- const lower = html.toLowerCase();
- const ranges: TagRange[] = [];
- let cursor = 0;
- while (cursor < html.length) {
- const start = html.indexOf("<", cursor);
- if (start < 0) break;
- const scanned = scanMarkup(html, lower, start);
- if (scanned.audioRange) ranges.push(scanned.audioRange);
- cursor = scanned.cursor;
- }
- return ranges;
-}
-
-function trimmedAttribute(attributes: Map<string, AttributeSpan>, name: string): string {
- return attributes.get(name)?.value.trim() ?? "";
-}
-
-/**
- * How much of the source the composition actually plays.
- *
- * `data-duration` is the explicit trim; absent, `data-end` still bounds the
- * clip's timeline window, and the parser, the runtime and the render mixer all
- * honour it. Measuring the whole file for a `data-end`-trimmed clip reads a
- * loudness the composition never plays — and `--write` then "corrects" an
- * already-matched clip by tens of dB.
- */
-function authoredDuration(attributes: Map<string, AttributeSpan>, id: string): number | null {
- const raw = attributes.get("data-duration")?.value;
- if (raw !== undefined) return authoredNumber(raw, 0, "data-duration", id, true);
-
- const rawEnd = attributes.get("data-end")?.value;
- if (rawEnd === undefined) return null;
- const end = authoredNumber(rawEnd, 0, "data-end", id, true);
- const start = authoredNumber(attributes.get("data-start")?.value, 0, "data-start", id);
- return end > start ? end - start : null;
-}
-
-function requiredAudioIdentity(attributes: Map<string, AttributeSpan>) {
- const id = trimmedAttribute(attributes, "id");
- const src = trimmedAttribute(attributes, "src");
- if (!id) throw new Error("Every normalized <audio> element needs an id");
- if (!src) throw new Error(`Audio #${id} has no src`);
- return { id, src };
-}
-
-function audioTagFromRange(html: string, range: TagRange): AudioTag {
- const attributes = attributesInTag(html, range.start, range.end);
- const { id, src } = requiredAudioIdentity(attributes);
- const volumeAttribute = attributes.get("data-volume") ?? null;
- return {
- id,
- src,
- volume: authoredNumber(volumeAttribute?.value, 1, "data-volume", id),
- mediaStart: authoredNumber(
- attributes.get("data-media-start")?.value,
- 0,
- "data-media-start",
- id,
- ),
- duration: authoredDuration(attributes, id),
- start: range.start,
- end: range.end,
- volumeAttribute,
- };
-}
-
-/** Read the authored audio clips without reserializing the composition. */
-export function audioTags(html: string): AudioTag[] {
- const seen = new Set<string>();
- const tags: AudioTag[] = [];
- for (const range of audioTagRanges(html)) {
- const tag = audioTagFromRange(html, range);
- if (seen.has(tag.id)) throw new Error(`Duplicate audio id "${tag.id}"`);
- seen.add(tag.id);
- tags.push(tag);
- }
- return tags;
-}
-
-/** Resolve only a file contained by the project. Remote and traversal sources are not measured. */
-export function resolveLocalAudioPath(projectDir: string, src: string): string {
- const withoutSuffix = src.split(/[?#]/, 1)[0] ?? "";
- let decoded = "";
- try {
- decoded = decodeURIComponent(withoutSuffix);
- } catch {
- throw new Error(`Audio source must be a local project file: ${src}`);
- }
- if (!decoded || isAbsolute(decoded) || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(decoded)) {
- throw new Error(`Audio source must be a local project file: ${src}`);
- }
- const root = resolve(projectDir);
- const file = resolve(root, decoded);
- const rel = relative(root, file);
- if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
- throw new Error(`Audio source must be a local project file: ${src}`);
- }
- return file;
-}
-
-/** Parse FFmpeg's final EBU R128 summary, not its per-window log lines. */
-export function parseEbur128Summary(stderr: string): LoudnessMeasurement {
- const summaryAt = stderr.lastIndexOf("Summary:");
- const summary = summaryAt >= 0 ? stderr.slice(summaryAt) : "";
- const integrated = summary.match(/\bI:\s*(-?\d+(?:\.\d+)?)\s+LUFS\b/);
- const peak = summary.match(/\bPeak:\s*(-?\d+(?:\.\d+)?)\s+dBFS\b/);
- const integratedLufs = Number(integrated?.[1]);
- const truePeakDbfs = Number(peak?.[1]);
- if (!Number.isFinite(integratedLufs)) {
- throw new Error("FFmpeg did not report integrated loudness for this audio stream");
- }
- if (!Number.isFinite(truePeakDbfs)) {
- throw new Error("FFmpeg did not report true peak for this audio stream");
- }
- return { integratedLufs, truePeakDbfs };
-}
-
-function gainDb(volume: number): number {
- return volume > 0 ? 20 * Math.log10(volume) : Number.NEGATIVE_INFINITY;
-}
-
-/** Calculate the target's absolute authored gain while keeping the reference unchanged. */
-export function audioNormalizationPlan(
- referenceTrack: NormalizationTrack,
- targetTrack: NormalizationTrack,
-): AudioNormalizationPlan {
- if (!(referenceTrack.volume > 0) || !(targetTrack.volume > 0)) {
- throw new Error("Muted audio cannot be used for loudness matching");
- }
- const referenceLufs = referenceTrack.integratedLufs + gainDb(referenceTrack.volume);
- const targetLufs = targetTrack.integratedLufs + gainDb(targetTrack.volume);
- const wantedGainDb = referenceLufs - targetTrack.integratedLufs;
- if (wantedGainDb > MAX_AUDIO_GAIN_DB + 1e-9) {
- throw new Error(
- `Matching #${targetTrack.id} needs ${wantedGainDb.toFixed(1)} dB, beyond the +${MAX_AUDIO_GAIN_DB} dB authoring ceiling. ` +
- `A gap this large belongs in the source file, not the mixer — mixer gain raises the noise floor with the signal. ` +
- `Normalize ${targetTrack.id}'s asset offline (e.g. ffmpeg loudnorm), or lower #${referenceTrack.id} instead.`,
- );
- }
- const volume = 10 ** (wantedGainDb / 20);
- const projectedTruePeakDbfs = targetTrack.truePeakDbfs + wantedGainDb;
- if (projectedTruePeakDbfs > 0) {
- throw new Error(
- `Matching #${targetTrack.id} would clip at +${projectedTruePeakDbfs.toFixed(1)} dBFS; limit or preprocess the source first`,
- );
- }
- return {
- referenceId: referenceTrack.id,
- targetId: targetTrack.id,
- referenceLufs,
- targetLufs,
- previousVolume: targetTrack.volume,
- volume,
- gainDb: wantedGainDb,
- changeDb: wantedGainDb - gainDb(targetTrack.volume),
- projectedLufs: targetTrack.integratedLufs + wantedGainDb,
- projectedTruePeakDbfs,
- };
-}
-
-/** Patch one authored attribute in place so scripts/styles/comments remain byte-stable. */
-export function updateAudioVolume(html: string, id: string, volume: number): string {
- const tag = audioTags(html).find((candidate) => candidate.id === id);
- if (!tag) throw new Error(`Audio #${id} was not found`);
- const value = formatAudioGain(volume);
- if (tag.volumeAttribute) {
- return (
- html.slice(0, tag.volumeAttribute.valueStart) +
- value +
- html.slice(tag.volumeAttribute.valueEnd)
- );
- }
-
- let insertion = tag.end - 1;
- let tail = insertion - 1;
- while (tail >= tag.start && /\s/.test(html[tail] ?? "")) tail -= 1;
- if (html[tail] === "/") {
- insertion = tail;
- while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
- } else {
- while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
- }
- return html.slice(0, insertion) + ` data-volume="${value}"` + html.slice(insertion);
-}
-
-/**
- * FFmpeg arguments that measure exactly the window the composition plays.
- *
- * `-ss` / `-t` go BEFORE `-i`, as INPUT options. After `-i` they bound the
- * output, and with `-f null` there is no real output to bound: ffmpeg keeps
- * feeding the filter graph past the limit, so ebur128 integrates audio the clip
- * never plays. Measured on a 12 s file whose first 4 s — the played window — is
- * -61.8 LUFS: output-side `-t 4` reported -33.8 LUFS, input-side reports -61.8,
- * the same as physically cutting the file first.
- */
-export function loudnessMeasureArgs(
- file: string,
- tag: Pick<AudioTag, "mediaStart" | "duration">,
-): string[] {
- const args = ["-hide_banner", "-nostats"];
- if (tag.mediaStart > 0) args.push("-ss", String(tag.mediaStart));
- if (tag.duration !== null && tag.duration > 0) args.push("-t", String(tag.duration));
- args.push("-i", file, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-");
- return args;
-}
+export {
+ audioNormalizationPlan,
+ audioTags,
+ loudnessMeasureArgs,
+ parseEbur128Summary,
+ resolveLocalAudioPath,
+ updateAudioVolume,
+} from "@hyperframes/studio-server/loudness";
-async function measureAudio(
- ffmpegPath: string,
- file: string,
- tag: Pick<AudioTag, "mediaStart" | "duration">,
-): Promise<LoudnessMeasurement> {
- const result = await execFileAsync(ffmpegPath, loudnessMeasureArgs(file, tag), {
- encoding: "utf8",
- maxBuffer: 16 * 1024 * 1024,
- timeout: FFMPEG_TIMEOUT_MS,
- });
- return parseEbur128Summary(result.stderr);
-}
+const DEFAULT_TOLERANCE_LU = 0.5;
-/**
- * Under `--json` every outcome has to be one parseable document, including the
- * failures — this command exists to be driven by an agent, and an agent doing
- * `JSON.parse(stdout)` on a bare error line just throws.
- */
function fail(message: string, json: boolean, cause?: unknown): never {
if (json) console.log(JSON.stringify({ ok: false, error: message }, null, 2));
else console.error(c.error(message));
@@ -420,13 +46,14 @@ function byId(tags: readonly AudioTag[], rawId: string, role: string): AudioTag
interface NormalizeAudioOptions {
dir?: string;
- reference: string;
+ reference?: string;
target: string;
+ lufs: string;
tolerance: string;
write: boolean;
}
-interface NormalizeAudioResult extends AudioNormalizationPlan {
+interface WriteOutcome {
ok: true;
wrote: boolean;
withinTolerance: boolean;
@@ -434,6 +61,8 @@ interface NormalizeAudioResult extends AudioNormalizationPlan {
indexPath: string;
}
+type NormalizeAudioResult = WriteOutcome & ModePlan;
+
function selectedTags(html: string, referenceId: string, targetId: string) {
const tags = audioTags(html);
const referenceTag = byId(tags, referenceId, "Reference");
@@ -444,12 +73,6 @@ function selectedTags(html: string, referenceId: string, targetId: string) {
return { referenceTag, targetTag };
}
-function requiredFfmpeg(): string {
- const ffmpegPath = findFfBinary("ffmpeg", { configuredMustExist: true });
- if (!ffmpegPath) throw new Error("FFmpeg is required to measure integrated loudness");
- return ffmpegPath;
-}
-
function existingAudioFile(projectDir: string, tag: AudioTag): string {
const file = resolveLocalAudioPath(projectDir, tag.src);
if (!existsSync(file)) {
@@ -476,7 +99,6 @@ async function measuredPlan(
);
}
-/** Never leave a half-written composition behind if the process dies mid-write. */
function writeAtomically(path: string, contents: string): void {
const temporary = `${path}.hf-normalize-${process.pid}.tmp`;
writeFileSync(temporary, contents);
@@ -491,22 +113,61 @@ function parsedTolerance(raw: string): number {
return tolerance;
}
+function parsedLufs(raw: string): number {
+ const lufs = Number(raw);
+ if (!Number.isFinite(lufs) || lufs >= 0) throw new Error("--lufs must be a negative number");
+ return lufs;
+}
+
+async function measuredAbsolutePlan(
+ projectDir: string,
+ targetTag: AudioTag,
+ targetLufs: number,
+): Promise<AbsoluteLoudnessPlan> {
+ const measurement = await measureAudio(
+ requiredFfmpeg(),
+ existingAudioFile(projectDir, targetTag),
+ targetTag,
+ );
+ return absoluteLoudnessPlan(
+ { id: targetTag.id, volume: targetTag.volume, ...measurement },
+ targetLufs,
+ );
+}
+
+type ModePlan =
+ | (AudioNormalizationPlan & { mode: "reference" })
+ | (AbsoluteLoudnessPlan & { mode: "absolute" });
+
+async function plannedNormalization(
+ projectDir: string,
+ html: string,
+ options: NormalizeAudioOptions,
+ tolerance: number,
+): Promise<{ targetTag: AudioTag; withinTolerance: boolean; plan: ModePlan }> {
+ if (options.reference === undefined) {
+ const targetTag = byId(audioTags(html), options.target, "Target");
+ const plan = await measuredAbsolutePlan(projectDir, targetTag, parsedLufs(options.lufs));
+ const withinTolerance = Math.abs(plan.changeDb) <= tolerance;
+ return { targetTag, withinTolerance, plan: { mode: "absolute", ...plan } };
+ }
+ const { referenceTag, targetTag } = selectedTags(html, options.reference, options.target);
+ const plan = await measuredPlan(projectDir, referenceTag, targetTag);
+ const withinTolerance = Math.abs(plan.referenceLufs - plan.targetLufs) <= tolerance;
+ return { targetTag, withinTolerance, plan: { mode: "reference", ...plan } };
+}
+
async function normalizeAudio(options: NormalizeAudioOptions): Promise<NormalizeAudioResult> {
const project = resolveProject(options.dir);
const html = readFileSync(project.indexPath, "utf8");
- const { referenceTag, targetTag } = selectedTags(html, options.reference, options.target);
- // Before the measurement, not after: each EBU R128 pass is bounded at 120s, so
- // validating this afterwards made a typo'd --tolerance cost two of them before
- // failing on an argument that was wrong the whole time.
const tolerance = parsedTolerance(options.tolerance);
- const plan = await measuredPlan(project.dir, referenceTag, targetTag);
- const withinTolerance = Math.abs(plan.referenceLufs - plan.targetLufs) <= tolerance;
+ const { targetTag, withinTolerance, plan } = await plannedNormalization(
+ project.dir,
+ html,
+ options,
+ tolerance,
+ );
const wrote = options.write && !withinTolerance;
- // Re-read: two EBU R128 passes ran since the snapshot above, each bounded
- // only by FFMPEG_TIMEOUT_MS, and the skill tells agents to keep Studio open
- // on the project while normalizing. Serializing the stale snapshot would
- // silently revert every edit made during that window. The write is one
- // attribute patch, so re-applying it to the current file is the same edit.
if (wrote) {
writeAtomically(
project.indexPath,
@@ -516,11 +177,28 @@ async function normalizeAudio(options: NormalizeAudioOptions): Promise<Normalize
return { ok: true, wrote, withinTolerance, tolerance, indexPath: project.indexPath, ...plan };
}
-function printHumanResult(result: NormalizeAudioResult): void {
+const LIMIT_TEXT: Record<LoudnessLimit, string> = {
+ "gain-ceiling": "stopped at the +12 dB authoring ceiling",
+ "true-peak": "stopped short of -1.5 dBTP",
+};
+
+function printMeasuredLine(result: NormalizeAudioResult): void {
+ if (result.mode === "reference") {
+ console.log(
+ `${c.bold(`#${result.referenceId}`)} ${result.referenceLufs.toFixed(1)} LUFS → ` +
+ `${c.bold(`#${result.targetId}`)} ${result.targetLufs.toFixed(1)} LUFS`,
+ );
+ return;
+ }
+ const limit = result.limitedBy ? ` (${LIMIT_TEXT[result.limitedBy]})` : "";
console.log(
- `${c.bold(`#${result.referenceId}`)} ${result.referenceLufs.toFixed(1)} LUFS → ` +
- `${c.bold(`#${result.targetId}`)} ${result.targetLufs.toFixed(1)} LUFS`,
+ `${c.bold(`#${result.targetId}`)} ${result.sourceLufs.toFixed(1)} LUFS → ` +
+ `${result.projectedLufs.toFixed(1)} LUFS, target ${result.targetLufs.toFixed(1)}${limit}`,
);
+}
+
+function printHumanResult(result: NormalizeAudioResult): void {
+ printMeasuredLine(result);
if (result.withinTolerance) {
console.log(
c.success(`Already matched within ${result.tolerance.toFixed(1)} LU; no change needed.`),
@@ -540,6 +218,10 @@ function printHumanResult(result: NormalizeAudioResult): void {
}
export const examples: Example[] = [
+ [
+ "Bring one clip (audio or a video with sound) to -16 LUFS",
+ "hyperframes normalize-audio --target voiceover --write",
+ ],
[
"Measure two authored clips and preview the matching gain",
"hyperframes normalize-audio --reference target-audio --target user-audio",
@@ -553,20 +235,27 @@ export const examples: Example[] = [
export default defineCommand({
meta: {
name: "normalize-audio",
- description: "Match one local audio clip to another using integrated LUFS",
+ description:
+ "Normalize a clip with sound to an absolute LUFS target, or match it to another clip",
},
args: {
dir: { type: "positional", description: "Project directory", required: false },
reference: {
type: "string",
- description: "Audio element id whose effective loudness should be preserved",
- required: true,
+ description:
+ "Audio or video element id whose effective loudness should be preserved (omit to use --lufs)",
+ required: false,
},
target: {
type: "string",
- description: "Audio element id whose data-volume should be matched",
+ description: "Audio or video element id whose data-volume should be set",
required: true,
},
+ lufs: {
+ type: "string",
+ description: `Absolute integrated loudness target without --reference (default ${DEFAULT_TARGET_LUFS})`,
+ default: String(DEFAULT_TARGET_LUFS),
+ },
write: {
type: "boolean",
description: "Persist the measured target gain into index.html",
@@ -585,6 +274,7 @@ export default defineCommand({
dir: args.dir,
reference: args.reference,
target: args.target,
+ lufs: args.lufs,
tolerance: args.tolerance,
write: args.write,
});
diff --git a/packages/cli/src/server/studioServer.test.ts b/packages/cli/src/server/studioServer.test.ts
index 67d366a4d7..bd9bea6152 100644
--- a/packages/cli/src/server/studioServer.test.ts
+++ b/packages/cli/src/server/studioServer.test.ts
@@ -55,6 +55,7 @@ vi.mock("@hyperframes/engine", () => ({
buildChromeArgs: () => [],
killTrackedProcesses: () => {},
closeBrowserPool: () => engineState.closeBrowserPool(),
+ getSystemTotalMb: () => 0,
}));
vi.mock("../browser/gpuPolicy.js", () => ({
resolveCaptureBrowserGpuMode: async () => "software",
@@ -291,6 +292,19 @@ describe("createStudioServer shutdown", () => {
};
}
+ it("hands the limiter's audioLoweredDb to the job state and the render sidecar", async () => {
+ producerState.executeRenderJob = async (job) => {
+ if (typeof job === "object" && job !== null) Reflect.set(job, "audioLoweredDb", 1.44);
+ };
+ const outputPath = join(mkdtempSync(join(tmpdir(), "hf-lowered-")), "out.mp4");
+ server = createStudioServer({ projectDir: tmpProject() });
+ const state = server.adapter.startRender(startRenderOpts("job-lowered", outputPath));
+ await vi.waitFor(() => expect(state.status, state.error).toBe("complete"), { timeout: 5_000 });
+ expect(state.audioLoweredDb).toBe(1.44);
+ const meta = JSON.parse(readFileSync(outputPath.replace(/\.mp4$/, ".meta.json"), "utf8"));
+ expect(meta.audioLoweredDb).toBe(1.44);
+ });
+
it("cancels an in-flight render's signal and waits for it before draining the browser pool", async () => {
const events: string[] = [];
let started!: () => void;
diff --git a/packages/cli/src/server/studioServer.ts b/packages/cli/src/server/studioServer.ts
index 4463450418..de80551dbf 100644
--- a/packages/cli/src/server/studioServer.ts
+++ b/packages/cli/src/server/studioServer.ts
@@ -621,12 +621,17 @@ export function createStudioServer(options: StudioServerOptions): StudioServer {
removeCancelledOutput();
return;
}
+ if (job.audioLoweredDb !== undefined) state.audioLoweredDb = job.audioLoweredDb;
state.status = "complete";
state.progress = 100;
const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");
writeFileSync(
metaPath,
- JSON.stringify({ status: "complete", durationMs: Date.now() - startTime }),
+ JSON.stringify({
+ status: "complete",
+ durationMs: Date.now() - startTime,
+ ...(job.audioLoweredDb !== undefined ? { audioLoweredDb: job.audioLoweredDb } : {}),
+ }),
);
// Refreshed HERE, not just at render start: a render can run for
// minutes, and `hyperframes telemetry disable` during one must be
diff --git a/packages/producer/src/services/render/audioPadTrim.test.ts b/packages/producer/src/services/render/audioPadTrim.test.ts
index 30e5841b22..af4637e7da 100644
--- a/packages/producer/src/services/render/audioPadTrim.test.ts
+++ b/packages/producer/src/services/render/audioPadTrim.test.ts
@@ -307,6 +307,7 @@ describe("padOrTrimAudioToVideoFrameCount", () => {
expect(result.success).toBe(true);
expect(captured.args).toHaveLength(1);
+ expect(result).not.toHaveProperty("audioLoweredDb");
});
it("attenuates the duration-normalized artifact with AAC correction headroom", async () => {
@@ -360,6 +361,7 @@ describe("padOrTrimAudioToVideoFrameCount", () => {
expect(result.success, result.error).toBe(true);
expect(corrections).toEqual([-1.5, -2.4, -2.94]);
+ expect(result.audioLoweredDb).toBe(2.94);
} finally {
rmSync(dir, { recursive: true, force: true });
}
diff --git a/packages/producer/src/services/render/audioPadTrim.ts b/packages/producer/src/services/render/audioPadTrim.ts
index db16b01bec..b8481ad2b7 100644
--- a/packages/producer/src/services/render/audioPadTrim.ts
+++ b/packages/producer/src/services/render/audioPadTrim.ts
@@ -102,6 +102,8 @@ export interface PadTrimAudioResult {
error?: string;
/** Stable machine-readable cause for failures safe to retry on a fresh host. */
failureReason?: "external_interruption";
+ /** dB the true-peak limiter lowered the whole mix by; absent when it did not engage. */
+ audioLoweredDb?: number;
}
export type PadTrimAudioStepKind = "copy" | "trim" | "normalize";
@@ -384,6 +386,7 @@ export async function padOrTrimAudioToVideoFrameCount(
for (const path of plan.cleanupPaths) rmSync(path, { force: true });
}
+ let loweredDb = 0;
if (probeTruePeak) {
const correction = await enforceAacTruePeak({
audioPath: input.outputPath,
@@ -403,6 +406,7 @@ export async function padOrTrimAudioToVideoFrameCount(
failureReason: correction.failureReason,
};
}
+ loweredDb = correction.loweredDb ?? 0;
}
return {
success: true,
@@ -410,6 +414,7 @@ export async function padOrTrimAudioToVideoFrameCount(
targetDurationSeconds,
sourceDurationSeconds: audioInfo.durationSeconds,
operation: plan.operation,
+ ...(loweredDb > 0 ? { audioLoweredDb: loweredDb } : {}),
};
}
@@ -425,9 +430,12 @@ interface EnforceAacTruePeakInput {
}>;
}
-async function enforceAacTruePeak(
- input: EnforceAacTruePeakInput,
-): Promise<{ success: boolean; error?: string; failureReason?: "external_interruption" }> {
+async function enforceAacTruePeak(input: EnforceAacTruePeakInput): Promise<{
+ success: boolean;
+ error?: string;
+ failureReason?: "external_interruption";
+ loweredDb?: number;
+}> {
let scratchDir: string | undefined;
try {
scratchDir = mkdtempSync(join(dirname(input.audioPath), ".true-peak-"));
@@ -445,8 +453,9 @@ async function enforceAacTruePeak(
return { success: false, error: "audioPadTrim: FFmpeg reported an invalid true peak" };
}
if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
- if (measuredPath === correctedPath) renameSync(correctedPath, input.audioPath);
- return { success: true };
+ if (measuredPath !== correctedPath) return { success: true };
+ renameSync(correctedPath, input.audioPath);
+ return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
}
if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
diff --git a/packages/producer/src/services/render/stages/assembleStage.test.ts b/packages/producer/src/services/render/stages/assembleStage.test.ts
index 80cce8aa4b..afd7f15329 100644
--- a/packages/producer/src/services/render/stages/assembleStage.test.ts
+++ b/packages/producer/src/services/render/stages/assembleStage.test.ts
@@ -16,6 +16,7 @@ vi.mock("@hyperframes/engine", () => ({
}));
vi.mock("../audioPadTrim.js", () => ({
+ AAC_DELIVERY_TRUE_PEAK_DBFS: -1,
padOrTrimAudioToVideoFrameCount: padOrTrimAudioMock,
}));
@@ -238,3 +239,34 @@ describe("runAssembleStage HLS packaging", () => {
expect(packageHlsMock).not.toHaveBeenCalled();
});
});
+
+describe("runAssembleStage limiter honesty", () => {
+ beforeEach(resetMocks);
+
+ it("records and logs how far the true-peak limiter lowered the mix", async () => {
+ padOrTrimAudioMock.mockResolvedValue({
+ success: true,
+ outputPath: "/tmp/audio.duration-normalized.m4a",
+ targetDurationSeconds: 1,
+ sourceDurationSeconds: 1,
+ operation: "copy",
+ audioLoweredDb: 1.44,
+ });
+ const logger = { error: vi.fn(), warn: vi.fn(), info: vi.fn(), debug: vi.fn() };
+ const input = makeInput();
+ input.job.config.logger = logger;
+
+ await runAssembleStage(input);
+
+ expect(input.job.audioLoweredDb).toBe(1.44);
+ expect(logger.info).toHaveBeenCalledWith("Audio lowered by 1.4 dB to stay under −1 dBTP", {
+ audioLoweredDb: 1.44,
+ });
+ });
+
+ it("leaves the job untouched when the limiter did not engage", async () => {
+ const input = makeInput();
+ await runAssembleStage(input);
+ expect(input.job).not.toHaveProperty("audioLoweredDb");
+ });
+});
diff --git a/packages/producer/src/services/render/stages/assembleStage.ts b/packages/producer/src/services/render/stages/assembleStage.ts
index 542e3481e5..adabe3b675 100644
--- a/packages/producer/src/services/render/stages/assembleStage.ts
+++ b/packages/producer/src/services/render/stages/assembleStage.ts
@@ -23,11 +23,12 @@
import { applyFaststart, muxVideoWithAudio, packageHls } from "@hyperframes/engine";
import { extname } from "node:path";
import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
-import { padOrTrimAudioToVideoFrameCount } from "../audioPadTrim.js";
+import { AAC_DELIVERY_TRUE_PEAK_DBFS, padOrTrimAudioToVideoFrameCount } from "../audioPadTrim.js";
import { encoderFailureError } from "../encoderInterruption.js";
import { DEFAULT_HLS_SEGMENT_SECONDS } from "../hlsConfig.js";
import type { RenderOutputFormat } from "../renderFormat.js";
import { updateJobStatus } from "../shared.js";
+import { defaultLogger } from "../../../logger.js";
export interface AssembleStageInput {
job: RenderJob;
@@ -55,6 +56,16 @@ export interface AssembleStageResult {
assembleMs: number;
}
+function recordLimiterAttenuation(job: RenderJob, audioLoweredDb: number | undefined): void {
+ if (audioLoweredDb === undefined) return;
+ job.audioLoweredDb = audioLoweredDb;
+ const ceiling = `−${Math.abs(AAC_DELIVERY_TRUE_PEAK_DBFS)} dBTP`;
+ (job.config.logger ?? defaultLogger).info(
+ `Audio lowered by ${audioLoweredDb.toFixed(1)} dB to stay under ${ceiling}`,
+ { audioLoweredDb },
+ );
+}
+
export async function runAssembleStage(input: AssembleStageInput): Promise<AssembleStageResult> {
const {
job,
@@ -88,6 +99,7 @@ export async function runAssembleStage(input: AssembleStageInput): Promise<Assem
if (!normalizeResult.success) {
throw encoderFailureError("Audio duration normalization failed", normalizeResult);
}
+ recordLimiterAttenuation(job, normalizeResult.audioLoweredDb);
if (isHls) {
await runHlsPackaging(input, normalizeResult.outputPath);
} else {
diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts
index d3f814f115..d147c31a4f 100644
--- a/packages/producer/src/services/renderOrchestrator.ts
+++ b/packages/producer/src/services/renderOrchestrator.ts
@@ -725,6 +725,7 @@ export interface RenderJob {
totalFrames?: number;
framesRendered?: number;
perfSummary?: RenderPerfSummary;
+ audioLoweredDb?: number;
failedStage?: string;
errorDetails?: {
message: string;
diff --git a/packages/studio-server/package-subpaths.json b/packages/studio-server/package-subpaths.json
index 1e6b5f1ada..287eda0b10 100644
--- a/packages/studio-server/package-subpaths.json
+++ b/packages/studio-server/package-subpaths.json
@@ -80,6 +80,12 @@
"types": "./dist/helpers/proxyTranscoder.d.ts",
"environments": ["bun", "node"]
},
+ "./loudness": {
+ "source": "./src/helpers/loudness.ts",
+ "runtime": "./dist/helpers/loudness.js",
+ "types": "./dist/helpers/loudness.d.ts",
+ "environments": ["bun", "node"]
+ },
"./media-proxy-preview": {
"source": "./src/helpers/mediaProxyPreview.ts",
"runtime": "./dist/helpers/mediaProxyPreview.js",
diff --git a/packages/studio-server/package.json b/packages/studio-server/package.json
index d406ce4af2..203525c164 100644
--- a/packages/studio-server/package.json
+++ b/packages/studio-server/package.json
@@ -87,6 +87,12 @@
"import": "./src/helpers/proxyTranscoder.ts",
"types": "./src/helpers/proxyTranscoder.ts"
},
+ "./loudness": {
+ "bun": "./src/helpers/loudness.ts",
+ "node": "./dist/helpers/loudness.js",
+ "import": "./src/helpers/loudness.ts",
+ "types": "./src/helpers/loudness.ts"
+ },
"./media-proxy-preview": {
"bun": "./src/helpers/mediaProxyPreview.ts",
"node": "./dist/helpers/mediaProxyPreview.js",
@@ -146,6 +152,10 @@
"import": "./dist/helpers/proxyTranscoder.js",
"types": "./dist/helpers/proxyTranscoder.d.ts"
},
+ "./loudness": {
+ "import": "./dist/helpers/loudness.js",
+ "types": "./dist/helpers/loudness.d.ts"
+ },
"./media-proxy-preview": {
"import": "./dist/helpers/mediaProxyPreview.js",
"types": "./dist/helpers/mediaProxyPreview.d.ts"
diff --git a/packages/studio-server/src/createStudioApi.ts b/packages/studio-server/src/createStudioApi.ts
index 36932d0480..d39576c446 100644
--- a/packages/studio-server/src/createStudioApi.ts
+++ b/packages/studio-server/src/createStudioApi.ts
@@ -9,6 +9,7 @@ import { registerImageThumbnailRoutes } from "./routes/imageThumbnail.js";
import { registerThumbnailRoutes } from "./routes/thumbnail.js";
import { registerWaveformRoutes } from "./routes/waveform.js";
import { registerFreezeFrameRoutes } from "./routes/freezeFrame.js";
+import { registerLoudnessRoutes } from "./routes/loudness.js";
import { registerFontRoutes } from "./routes/fonts.js";
import { registerRegistryRoutes } from "./routes/registry.js";
import { registerSelectionRoutes } from "./routes/selection.js";
@@ -63,6 +64,7 @@ export function createStudioApi(adapter: StudioApiAdapter): Hono {
registerMediaRoutes(api, adapter);
registerWaveformRoutes(api, adapter);
registerFreezeFrameRoutes(api, adapter);
+ registerLoudnessRoutes(api, adapter);
registerFontRoutes(api);
registerRegistryRoutes(api, adapter);
registerGlobalAssetRoutes(api);
diff --git a/packages/studio-server/src/helpers/loudness.test.ts b/packages/studio-server/src/helpers/loudness.test.ts
new file mode 100644
index 0000000000..f49d16006f
--- /dev/null
+++ b/packages/studio-server/src/helpers/loudness.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from "vitest";
+import {
+ absoluteLoudnessPlan,
+ audioTags,
+ loudnessMeasureArgs,
+ updateAudioVolume,
+} from "./loudness.js";
+
+const track = (integratedLufs: number, truePeakDbfs: number, volume = 1) => ({
+ id: "vo",
+ volume,
+ integratedLufs,
+ truePeakDbfs,
+});
+
+describe("audioTags with video", () => {
+ it("includes a video with sound as a normalizable clip", () => {
+ const html = `<video id="a-roll" src="talk.mp4" data-has-audio="true" data-duration="4"></video>`;
+ expect(audioTags(html)).toEqual([
+ expect.objectContaining({ tag: "video", id: "a-roll", src: "talk.mp4", duration: 4 }),
+ ]);
+ });
+
+ it("includes an unmuted video that does not declare data-has-audio", () => {
+ expect(audioTags(`<video id="v" src="v.mp4"></video>`).map((t) => t.id)).toEqual(["v"]);
+ });
+
+ it.each([
+ `<video id="b-roll" src="b.mp4" muted></video>`,
+ `<video id="b-roll" src="b.mp4" muted data-start="0"></video>`,
+ `<video id="b-roll" src="b.mp4" muted=""></video>`,
+ `<video id="b-roll" src="b.mp4" data-has-audio="false"></video>`,
+ `<video id="b-roll" src="b.mp4" data-has-audio=""></video>`,
+ ])("skips a silent video without throwing: %s", (html) => {
+ expect(audioTags(html)).toEqual([]);
+ });
+
+ it("does not read muted out of another attribute's value", () => {
+ const html = `<video id="v" src="v.mp4" title="be muted later"></video>`;
+ expect(audioTags(html).map((t) => t.id)).toEqual(["v"]);
+ });
+
+ it("skips a video it could not address instead of failing the run", () => {
+ const html = `<video src="v.mp4"></video><audio id="music" src="m.mp3"></audio>`;
+ expect(audioTags(html).map((t) => t.id)).toEqual(["music"]);
+ });
+
+ it("still requires an id on every audio element", () => {
+ expect(() => audioTags(`<audio src="m.mp3"></audio>`)).toThrow(/needs an id/);
+ });
+
+ it("rejects an id shared by an audio and a video", () => {
+ const html = `<audio id="x" src="a.mp3"></audio><video id="x" src="v.mp4"></video>`;
+ expect(() => audioTags(html)).toThrow(/duplicate/i);
+ });
+
+ it("writes data-volume on the video tag", () => {
+ const html = `<video id="a-roll" src="talk.mp4" data-has-audio="true"></video>`;
+ expect(updateAudioVolume(html, "a-roll", 2)).toBe(
+ `<video id="a-roll" src="talk.mp4" data-has-audio="true" data-volume="2"></video>`,
+ );
+ });
+});
+
+describe("loudnessMeasureArgs with a playback rate", () => {
+ it("measures the source span a sped-up clip actually plays", () => {
+ const args = loudnessMeasureArgs("clip.mp4", { mediaStart: 0, duration: 4, playbackRate: 2 });
+ expect(args.slice(args.indexOf("-t"), args.indexOf("-t") + 2)).toEqual(["-t", "8"]);
+ });
+
+ it("reads data-playback-rate from the tag", () => {
+ const html = `<audio id="a" src="a.wav" data-duration="3" data-playback-rate="0.5"></audio>`;
+ expect(audioTags(html)[0]).toEqual(expect.objectContaining({ playbackRate: 0.5 }));
+ });
+});
+
+describe("absoluteLoudnessPlan", () => {
+ it("targets -16 LUFS by default", () => {
+ const plan = absoluteLoudnessPlan(track(-19.2, -8));
+ expect(plan.gainDb).toBeCloseTo(3.2, 6);
+ expect(plan.projectedLufs).toBeCloseTo(-16, 6);
+ expect(plan.volume).toBeCloseTo(10 ** (3.2 / 20), 6);
+ expect(plan.limitedBy).toBeNull();
+ });
+
+ it("reports the change relative to the clip's current gain", () => {
+ const plan = absoluteLoudnessPlan(track(-16, -6, 2));
+ expect(plan.gainDb).toBeCloseTo(0, 6);
+ expect(plan.changeDb).toBeCloseTo(-6.0206, 3);
+ });
+
+ it("stops at the +12 dB ceiling and says so", () => {
+ const plan = absoluteLoudnessPlan(track(-40, -30));
+ expect(plan.gainDb).toBeCloseTo(12, 6);
+ expect(plan.limitedBy).toBe("gain-ceiling");
+ });
+
+ it("stops short of -1.5 dBTP and says so", () => {
+ const plan = absoluteLoudnessPlan(track(-22, -3));
+ expect(plan.gainDb).toBeCloseTo(1.5, 6);
+ expect(plan.projectedTruePeakDbfs).toBeCloseTo(-1.5, 6);
+ expect(plan.limitedBy).toBe("true-peak");
+ });
+
+ it("attenuates a clip that is too loud", () => {
+ const plan = absoluteLoudnessPlan(track(-10, 0));
+ expect(plan.gainDb).toBeCloseTo(-6, 6);
+ expect(plan.limitedBy).toBeNull();
+ });
+
+ it("refuses a silent window", () => {
+ expect(() => absoluteLoudnessPlan(track(-70, -90))).toThrow(/silent/);
+ });
+
+ it("treats a muted clip's change as the applied gain", () => {
+ expect(absoluteLoudnessPlan(track(-19, -10, 0)).changeDb).toBeCloseTo(3, 6);
+ });
+});
+
+describe("audioTags on hostile markup", () => {
+ it("scans '<' followed by many spaces in linear time", () => {
+ const html = `${"<" + " ".repeat(50_000)}<audio id="vo" src="vo.mp3"></audio>`;
+ const started = performance.now();
+ expect(audioTags(html).map((t) => t.id)).toEqual(["vo"]);
+ expect(performance.now() - started).toBeLessThan(500);
+ });
+
+ it("scans many '<' + spaces runs in linear time", () => {
+ const html = `${("<" + " ".repeat(20)).repeat(20_000)}<audio id="vo" src="vo.mp3"></audio>`;
+ const started = performance.now();
+ expect(audioTags(html).map((t) => t.id)).toEqual(["vo"]);
+ expect(performance.now() - started).toBeLessThan(1000);
+ });
+
+ it("still reads tags written with spaces around the slash and name", () => {
+ const html = `< audio id="vo" src="vo.mp3">< / audio><a_b></a_b>`;
+ expect(audioTags(html).map((t) => t.id)).toEqual(["vo"]);
+ });
+});
diff --git a/packages/studio-server/src/helpers/loudness.ts b/packages/studio-server/src/helpers/loudness.ts
new file mode 100644
index 0000000000..75c8790dea
--- /dev/null
+++ b/packages/studio-server/src/helpers/loudness.ts
@@ -0,0 +1,537 @@
+import { execFile } from "node:child_process";
+import { isAbsolute, relative, resolve } from "node:path";
+import { promisify } from "node:util";
+import { isAudibleVideoElement } from "@hyperframes/core/audible-video";
+import { formatAudioGain, MAX_AUDIO_GAIN_DB } from "@hyperframes/core/audio-gain";
+import { findFfBinary } from "@hyperframes/parsers/ff-binaries";
+
+const execFileAsync = promisify(execFile);
+
+const FFMPEG_TIMEOUT_MS = 120_000;
+
+interface AttributeSpan {
+ value: string;
+ valueStart: number;
+ valueEnd: number;
+}
+
+interface TagRange {
+ start: number;
+ end: number;
+}
+
+type MediaTagName = "audio" | "video";
+
+interface MediaTagRange extends TagRange {
+ name: MediaTagName;
+}
+
+interface ParsedStartTag extends TagRange {
+ closing: boolean;
+ name: string;
+}
+
+interface ScanResult {
+ cursor: number;
+ mediaRange: MediaTagRange | null;
+}
+
+export interface AudioTag {
+ tag: MediaTagName;
+ id: string;
+ src: string;
+ volume: number;
+ mediaStart: number;
+ duration: number | null;
+ playbackRate: number;
+ start: number;
+ end: number;
+ volumeAttribute: AttributeSpan | null;
+}
+
+export interface LoudnessMeasurement {
+ integratedLufs: number;
+ truePeakDbfs: number;
+}
+
+export interface NormalizationTrack extends LoudnessMeasurement {
+ id: string;
+ volume: number;
+}
+
+export interface AudioNormalizationPlan {
+ referenceId: string;
+ targetId: string;
+ referenceLufs: number;
+ targetLufs: number;
+ previousVolume: number;
+ volume: number;
+ gainDb: number;
+ changeDb: number;
+ projectedLufs: number;
+ projectedTruePeakDbfs: number;
+}
+
+function authoredNumber(
+ raw: string | undefined,
+ fallback: number,
+ attribute: string,
+ id: string,
+ strictlyPositive = false,
+): number {
+ if (raw === undefined) return fallback;
+ const value = Number(raw);
+ if (!Number.isFinite(value) || (strictlyPositive ? value <= 0 : value < 0)) {
+ throw new Error(`Audio #${id} has an invalid ${attribute}: ${raw}`);
+ }
+ return value;
+}
+
+function attributeFromMatch(
+ match: RegExpMatchArray,
+ absoluteOffset: number,
+): [string, AttributeSpan] | null {
+ if (match.index === undefined) return null;
+ const name = match[1]?.toLowerCase();
+ const value = matchedAttributeValue(match);
+ if (!name || value === undefined) return null;
+
+ const whole = match[0];
+ const localValueStart = attributeValueStart(whole);
+ const valueStart = absoluteOffset + match.index + localValueStart;
+ return [name, { value, valueStart, valueEnd: valueStart + value.length }];
+}
+
+function matchedAttributeValue(match: RegExpMatchArray): string | undefined {
+ return match[2] ?? match[3] ?? match[4];
+}
+
+function attributeValueStart(attribute: string): number {
+ let cursor = attribute.indexOf("=") + 1;
+ while (/\s/.test(attribute[cursor] ?? "")) cursor += 1;
+ const quote = attribute[cursor];
+ return quote === '"' || quote === "'" ? cursor + 1 : cursor;
+}
+
+function attributesInTag(html: string, from: number, to: number): Map<string, AttributeSpan> {
+ const tag = html.slice(from, to);
+ const nameEnd = tag.search(/\s|\/?\s*>/);
+ const attributes = new Map<string, AttributeSpan>();
+ if (nameEnd < 0) return attributes;
+
+ const pattern = /([^\s=/>]+)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+))/g;
+ for (const match of tag.slice(nameEnd).matchAll(pattern)) {
+ const attribute = attributeFromMatch(match, from + nameEnd);
+ if (attribute) attributes.set(...attribute);
+ }
+ return attributes;
+}
+
+function startTagEnd(html: string, start: number): number {
+ let quote = "";
+ let end = start + 1;
+ for (; end < html.length; end += 1) {
+ const char = html[end];
+ if (quote) {
+ if (char === quote) quote = "";
+ } else if (char === '"' || char === "'") {
+ quote = char;
+ } else if (char === ">") {
+ return end + 1;
+ }
+ }
+ throw new Error("Unterminated HTML start tag");
+}
+
+function commentEnd(html: string, start: number): number {
+ const end = html.indexOf("-->", start + 4);
+ if (end < 0) throw new Error("Unterminated HTML comment");
+ return end + 3;
+}
+
+const isSpaceAt = (html: string, index: number) => /\s/.test(html.charAt(index));
+const isWordAt = (html: string, index: number) => /\w/.test(html.charAt(index));
+
+function skipSpaces(html: string, index: number): number {
+ let cursor = index;
+ while (cursor < html.length && isSpaceAt(html, cursor)) cursor++;
+ return cursor;
+}
+
+function parsedStartTag(html: string, start: number): ParsedStartTag | null {
+ let cursor = skipSpaces(html, start + 1);
+ const closing = html.charAt(cursor) === "/";
+ if (closing) cursor = skipSpaces(html, cursor + 1);
+ const nameStart = cursor;
+ if (!/[a-z]/i.test(html.charAt(cursor))) return null;
+ while (/[a-z\d:-]/i.test(html.charAt(cursor + 1))) cursor++;
+ let nameEnd = cursor + 1;
+ while (nameEnd > nameStart && isWordAt(html, nameEnd - 1) === isWordAt(html, nameEnd)) nameEnd--;
+ if (nameEnd === nameStart) return null;
+ return {
+ start,
+ end: startTagEnd(html, start),
+ closing,
+ name: html.slice(nameStart, nameEnd).toLowerCase(),
+ };
+}
+
+function rawTextElementEnd(html: string, lower: string, tag: ParsedStartTag): number | null {
+ if (tag.closing || (tag.name !== "script" && tag.name !== "style")) return null;
+ const closeStart = lower.indexOf(`</${tag.name}`, tag.end);
+ if (closeStart < 0) throw new Error(`Unterminated <${tag.name}> element`);
+ return startTagEnd(html, closeStart);
+}
+
+function scanMarkup(html: string, lower: string, start: number): ScanResult {
+ if (html.startsWith("<!--", start)) {
+ return { cursor: commentEnd(html, start), mediaRange: null };
+ }
+ const tag = parsedStartTag(html, start);
+ if (!tag) {
+ const marker = html[start + 1];
+ const cursor = marker === "!" || marker === "?" ? startTagEnd(html, start) : start + 1;
+ return { cursor, mediaRange: null };
+ }
+ const rawTextEnd = rawTextElementEnd(html, lower, tag);
+ if (rawTextEnd !== null) return { cursor: rawTextEnd, mediaRange: null };
+ return { cursor: tag.end, mediaRange: mediaRangeOf(tag) };
+}
+
+function mediaRangeOf(tag: ParsedStartTag): MediaTagRange | null {
+ if (tag.closing) return null;
+ if (tag.name === "audio" || tag.name === "video") {
+ return { start: tag.start, end: tag.end, name: tag.name };
+ }
+ return null;
+}
+
+function mediaTagRanges(html: string): MediaTagRange[] {
+ const lower = html.toLowerCase();
+ const ranges: MediaTagRange[] = [];
+ let cursor = 0;
+ while (cursor < html.length) {
+ const start = html.indexOf("<", cursor);
+ if (start < 0) break;
+ const scanned = scanMarkup(html, lower, start);
+ if (scanned.mediaRange) ranges.push(scanned.mediaRange);
+ cursor = scanned.cursor;
+ }
+ return ranges;
+}
+
+function trimmedAttribute(attributes: Map<string, AttributeSpan>, name: string): string {
+ return attributes.get(name)?.value.trim() ?? "";
+}
+
+/**
+ * How much of the source the composition actually plays.
+ *
+ * `data-duration` is the explicit trim; absent, `data-end` still bounds the
+ * clip's timeline window, and the parser, the runtime and the render mixer all
+ * honour it. Measuring the whole file for a `data-end`-trimmed clip reads a
+ * loudness the composition never plays — and `--write` then "corrects" an
+ * already-matched clip by tens of dB.
+ */
+function authoredDuration(attributes: Map<string, AttributeSpan>, id: string): number | null {
+ const raw = attributes.get("data-duration")?.value;
+ if (raw !== undefined) return authoredNumber(raw, 0, "data-duration", id, true);
+
+ const rawEnd = attributes.get("data-end")?.value;
+ if (rawEnd === undefined) return null;
+ const end = authoredNumber(rawEnd, 0, "data-end", id, true);
+ const start = authoredNumber(attributes.get("data-start")?.value, 0, "data-start", id);
+ return end > start ? end - start : null;
+}
+
+function requiredAudioIdentity(attributes: Map<string, AttributeSpan>) {
+ const id = trimmedAttribute(attributes, "id");
+ const src = trimmedAttribute(attributes, "src");
+ if (!id) throw new Error("Every normalized <audio> element needs an id");
+ if (!src) throw new Error(`Audio #${id} has no src`);
+ return { id, src };
+}
+
+/** Boolean attributes carry no `=`, so the value map cannot see them. */
+function hasBareAttribute(html: string, range: TagRange, name: string): boolean {
+ const unquoted = html.slice(range.start, range.end).replace(/"[^"]*"|'[^']*'/g, '""');
+ return new RegExp(`\\s${name}(?=[\\s/>=])`, "i").test(unquoted);
+}
+
+function isAudibleVideoTag(
+ html: string,
+ range: TagRange,
+ attributes: Map<string, AttributeSpan>,
+): boolean {
+ return isAudibleVideoElement({
+ tagName: "video",
+ hasAttribute: (name) => attributes.has(name) || hasBareAttribute(html, range, name),
+ getAttribute: (name) => attributes.get(name)?.value ?? null,
+ });
+}
+
+/**
+ * A video joins the scan only when it carries sound and can be addressed.
+ * Silent footage, and a video no command could name, are skipped rather than
+ * failing a run that is about some other clip.
+ */
+function inScopeVideo(
+ html: string,
+ range: TagRange,
+ attributes: Map<string, AttributeSpan>,
+): boolean {
+ return (
+ isAudibleVideoTag(html, range, attributes) &&
+ trimmedAttribute(attributes, "id") !== "" &&
+ trimmedAttribute(attributes, "src") !== ""
+ );
+}
+
+function mediaTagFromRange(html: string, range: MediaTagRange): AudioTag | null {
+ const attributes = attributesInTag(html, range.start, range.end);
+ if (range.name === "video" && !inScopeVideo(html, range, attributes)) return null;
+ const { id, src } = requiredAudioIdentity(attributes);
+ const volumeAttribute = attributes.get("data-volume") ?? null;
+ return {
+ tag: range.name,
+ id,
+ src,
+ volume: authoredNumber(volumeAttribute?.value, 1, "data-volume", id),
+ mediaStart: authoredNumber(
+ attributes.get("data-media-start")?.value,
+ 0,
+ "data-media-start",
+ id,
+ ),
+ duration: authoredDuration(attributes, id),
+ playbackRate: authoredNumber(
+ attributes.get("data-playback-rate")?.value,
+ 1,
+ "data-playback-rate",
+ id,
+ true,
+ ),
+ start: range.start,
+ end: range.end,
+ volumeAttribute,
+ };
+}
+
+/** Read the authored clips with sound — `<audio>` and audible `<video>` — without reserializing. */
+export function audioTags(html: string): AudioTag[] {
+ const seen = new Set<string>();
+ const tags: AudioTag[] = [];
+ for (const range of mediaTagRanges(html)) {
+ const tag = mediaTagFromRange(html, range);
+ if (!tag) continue;
+ if (seen.has(tag.id)) throw new Error(`Duplicate audio id "${tag.id}"`);
+ seen.add(tag.id);
+ tags.push(tag);
+ }
+ return tags;
+}
+
+/** Resolve only a file contained by the project. Remote and traversal sources are not measured. */
+export function resolveLocalAudioPath(projectDir: string, src: string): string {
+ const withoutSuffix = src.split(/[?#]/, 1)[0] ?? "";
+ let decoded = "";
+ try {
+ decoded = decodeURIComponent(withoutSuffix);
+ } catch {
+ throw new Error(`Audio source must be a local project file: ${src}`);
+ }
+ if (!decoded || isAbsolute(decoded) || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(decoded)) {
+ throw new Error(`Audio source must be a local project file: ${src}`);
+ }
+ const root = resolve(projectDir);
+ const file = resolve(root, decoded);
+ const rel = relative(root, file);
+ if (!rel || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)) {
+ throw new Error(`Audio source must be a local project file: ${src}`);
+ }
+ return file;
+}
+
+/** Parse FFmpeg's final EBU R128 summary, not its per-window log lines. */
+export function parseEbur128Summary(stderr: string): LoudnessMeasurement {
+ const summaryAt = stderr.lastIndexOf("Summary:");
+ const summary = summaryAt >= 0 ? stderr.slice(summaryAt) : "";
+ const integrated = summary.match(/\bI:\s*(-?\d+(?:\.\d+)?)\s+LUFS\b/);
+ const peak = summary.match(/\bPeak:\s*(-?\d+(?:\.\d+)?)\s+dBFS\b/);
+ const integratedLufs = Number(integrated?.[1]);
+ const truePeakDbfs = Number(peak?.[1]);
+ if (!Number.isFinite(integratedLufs)) {
+ throw new Error("FFmpeg did not report integrated loudness for this audio stream");
+ }
+ if (!Number.isFinite(truePeakDbfs)) {
+ throw new Error("FFmpeg did not report true peak for this audio stream");
+ }
+ return { integratedLufs, truePeakDbfs };
+}
+
+export function gainDb(volume: number): number {
+ return volume > 0 ? 20 * Math.log10(volume) : Number.NEGATIVE_INFINITY;
+}
+
+/** Calculate the target's absolute authored gain while keeping the reference unchanged. */
+export function audioNormalizationPlan(
+ referenceTrack: NormalizationTrack,
+ targetTrack: NormalizationTrack,
+): AudioNormalizationPlan {
+ if (!(referenceTrack.volume > 0) || !(targetTrack.volume > 0)) {
+ throw new Error("Muted audio cannot be used for loudness matching");
+ }
+ const referenceLufs = referenceTrack.integratedLufs + gainDb(referenceTrack.volume);
+ const targetLufs = targetTrack.integratedLufs + gainDb(targetTrack.volume);
+ const wantedGainDb = referenceLufs - targetTrack.integratedLufs;
+ if (wantedGainDb > MAX_AUDIO_GAIN_DB + 1e-9) {
+ throw new Error(
+ `Matching #${targetTrack.id} needs ${wantedGainDb.toFixed(1)} dB, beyond the +${MAX_AUDIO_GAIN_DB} dB authoring ceiling. ` +
+ `A gap this large belongs in the source file, not the mixer — mixer gain raises the noise floor with the signal. ` +
+ `Normalize ${targetTrack.id}'s asset offline (e.g. ffmpeg loudnorm), or lower #${referenceTrack.id} instead.`,
+ );
+ }
+ const volume = 10 ** (wantedGainDb / 20);
+ const projectedTruePeakDbfs = targetTrack.truePeakDbfs + wantedGainDb;
+ if (projectedTruePeakDbfs > 0) {
+ throw new Error(
+ `Matching #${targetTrack.id} would clip at +${projectedTruePeakDbfs.toFixed(1)} dBFS; limit or preprocess the source first`,
+ );
+ }
+ return {
+ referenceId: referenceTrack.id,
+ targetId: targetTrack.id,
+ referenceLufs,
+ targetLufs,
+ previousVolume: targetTrack.volume,
+ volume,
+ gainDb: wantedGainDb,
+ changeDb: wantedGainDb - gainDb(targetTrack.volume),
+ projectedLufs: targetTrack.integratedLufs + wantedGainDb,
+ projectedTruePeakDbfs,
+ };
+}
+
+/** Patch one authored attribute in place so scripts/styles/comments remain byte-stable. */
+export function updateAudioVolume(html: string, id: string, volume: number): string {
+ const tag = audioTags(html).find((candidate) => candidate.id === id);
+ if (!tag) throw new Error(`Audio #${id} was not found`);
+ const value = formatAudioGain(volume);
+ if (tag.volumeAttribute) {
+ return (
+ html.slice(0, tag.volumeAttribute.valueStart) +
+ value +
+ html.slice(tag.volumeAttribute.valueEnd)
+ );
+ }
+
+ let insertion = tag.end - 1;
+ let tail = insertion - 1;
+ while (tail >= tag.start && /\s/.test(html[tail] ?? "")) tail -= 1;
+ if (html[tail] === "/") {
+ insertion = tail;
+ while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
+ } else {
+ while (insertion > tag.start && /\s/.test(html[insertion - 1] ?? "")) insertion -= 1;
+ }
+ return html.slice(0, insertion) + ` data-volume="${value}"` + html.slice(insertion);
+}
+
+/**
+ * FFmpeg arguments that measure exactly the window the composition plays.
+ *
+ * `-ss` / `-t` go BEFORE `-i`, as INPUT options. After `-i` they bound the
+ * output, and with `-f null` there is no real output to bound: ffmpeg keeps
+ * feeding the filter graph past the limit, so ebur128 integrates audio the clip
+ * never plays. Measured on a 12 s file whose first 4 s — the played window — is
+ * -61.8 LUFS: output-side `-t 4` reported -33.8 LUFS, input-side reports -61.8,
+ * the same as physically cutting the file first.
+ */
+export function loudnessMeasureArgs(file: string, tag: MeasuredWindow): string[] {
+ const args = ["-hide_banner", "-nostats"];
+ if (tag.mediaStart > 0) args.push("-ss", String(tag.mediaStart));
+ const sourceSpan = tag.duration === null ? null : tag.duration * (tag.playbackRate ?? 1);
+ if (sourceSpan !== null && sourceSpan > 0) args.push("-t", String(sourceSpan));
+ args.push("-i", file, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-");
+ return args;
+}
+
+export type MeasuredWindow = Pick<AudioTag, "mediaStart" | "duration"> &
+ Partial<Pick<AudioTag, "playbackRate">>;
+
+export async function measureAudio(
+ ffmpegPath: string,
+ file: string,
+ tag: MeasuredWindow,
+): Promise<LoudnessMeasurement> {
+ const result = await execFileAsync(ffmpegPath, loudnessMeasureArgs(file, tag), {
+ encoding: "utf8",
+ maxBuffer: 16 * 1024 * 1024,
+ timeout: FFMPEG_TIMEOUT_MS,
+ });
+ return parseEbur128Summary(result.stderr);
+}
+
+export function requiredFfmpeg(): string {
+ const ffmpegPath = findFfBinary("ffmpeg", { configuredMustExist: true });
+ if (!ffmpegPath) throw new Error("FFmpeg is required to measure integrated loudness");
+ return ffmpegPath;
+}
+
+export const DEFAULT_TARGET_LUFS = -16;
+export const NORMALIZE_TRUE_PEAK_CEILING_DBFS = -1.5;
+/** EBU R128's absolute gate: a window this quiet has no integrated loudness to match. */
+const SILENCE_LUFS = -70;
+
+export type LoudnessLimit = "gain-ceiling" | "true-peak";
+
+export interface AbsoluteLoudnessPlan {
+ targetId: string;
+ targetLufs: number;
+ sourceLufs: number;
+ previousVolume: number;
+ volume: number;
+ gainDb: number;
+ changeDb: number;
+ projectedLufs: number;
+ projectedTruePeakDbfs: number;
+ limitedBy: LoudnessLimit | null;
+}
+
+/**
+ * The authored gain that brings one clip's played window to an absolute
+ * loudness. Unlike reference matching it never refuses: past the +12 dB
+ * authoring ceiling or the true-peak ceiling it applies the most that fits and
+ * names which limit stopped it.
+ */
+export function absoluteLoudnessPlan(
+ track: NormalizationTrack,
+ targetLufs: number = DEFAULT_TARGET_LUFS,
+): AbsoluteLoudnessPlan {
+ if (track.integratedLufs <= SILENCE_LUFS) {
+ throw new Error(`#${track.id} is silent in the played window; there is nothing to normalize`);
+ }
+ const wantedGainDb = targetLufs - track.integratedLufs;
+ const peakRoomDb = NORMALIZE_TRUE_PEAK_CEILING_DBFS - track.truePeakDbfs;
+ const limits: Array<[LoudnessLimit | null, number]> = [
+ [null, wantedGainDb],
+ ["gain-ceiling", MAX_AUDIO_GAIN_DB],
+ ["true-peak", peakRoomDb],
+ ];
+ const [limitedBy, appliedGainDb] = limits.reduce((lowest, candidate) =>
+ candidate[1] < lowest[1] - 1e-9 ? candidate : lowest,
+ );
+ const previousGainDb = track.volume > 0 ? gainDb(track.volume) : 0;
+ return {
+ targetId: track.id,
+ targetLufs,
+ sourceLufs: track.integratedLufs,
+ previousVolume: track.volume,
+ volume: 10 ** (appliedGainDb / 20),
+ gainDb: appliedGainDb,
+ changeDb: appliedGainDb - previousGainDb,
+ projectedLufs: track.integratedLufs + appliedGainDb,
+ projectedTruePeakDbfs: track.truePeakDbfs + appliedGainDb,
+ limitedBy,
+ };
+}
diff --git a/packages/studio-server/src/routes/loudness.test.ts b/packages/studio-server/src/routes/loudness.test.ts
new file mode 100644
index 0000000000..c089c22975
--- /dev/null
+++ b/packages/studio-server/src/routes/loudness.test.ts
@@ -0,0 +1,90 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Hono } from "hono";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerLoudnessRoutes, type MeasureLoudness } from "./loudness";
+import type { StudioApiAdapter } from "../types";
+
+const dirs: string[] = [];
+afterEach(() => {
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+function setup(measure: MeasureLoudness) {
+ const projectDir = mkdtempSync(join(tmpdir(), "hf-loudness-route-"));
+ dirs.push(projectDir);
+ writeFileSync(join(projectDir, "talk.mp4"), "video");
+ const adapter: StudioApiAdapter = {
+ listProjects: () => [],
+ resolveProject: async (id: string) => ({ id, dir: projectDir }),
+ bundle: async () => null,
+ lint: async () => ({ findings: [] }),
+ runtimeUrl: "/api/runtime.js",
+ rendersDir: () => "/tmp/renders",
+ startRender: () => ({ id: "j", status: "rendering", progress: 0, outputPath: "/tmp/o.mp4" }),
+ };
+ const app = new Hono();
+ registerLoudnessRoutes(app, adapter, measure);
+ const post = (body: unknown) =>
+ app.request("/projects/p/loudness/normalize", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify(body),
+ });
+ return { post, projectDir };
+}
+
+describe("POST /projects/:id/loudness/normalize", () => {
+ it("measures the played source window of a video and answers the -16 LUFS gain", async () => {
+ const measure = vi.fn<MeasureLoudness>(async () => ({
+ integratedLufs: -19.2,
+ truePeakDbfs: -8,
+ }));
+ const { post, projectDir } = setup(measure);
+ const res = await post({
+ id: "a-roll",
+ src: "talk.mp4",
+ mediaStart: 1,
+ duration: 4,
+ playbackRate: 2,
+ volume: 1,
+ });
+ expect(res.status).toBe(200);
+ const { plan } = await res.json();
+ expect(plan.gainDb).toBeCloseTo(3.2, 6);
+ expect(plan.targetId).toBe("a-roll");
+ expect(measure).toHaveBeenCalledWith(join(projectDir, "talk.mp4"), {
+ mediaStart: 1,
+ duration: 4,
+ playbackRate: 2,
+ });
+ });
+
+ it("names the limit when the gain had to stop short", async () => {
+ const { post } = setup(async () => ({ integratedLufs: -22, truePeakDbfs: -3 }));
+ const { plan } = await (await post({ src: "talk.mp4" })).json();
+ expect(plan.limitedBy).toBe("true-peak");
+ });
+
+ it("refuses a source outside the project", async () => {
+ const { post } = setup(async () => ({ integratedLufs: -16, truePeakDbfs: -3 }));
+ expect((await post({ src: "../etc/passwd" })).status).toBe(400);
+ expect((await post({ src: "https://x.test/a.mp3" })).status).toBe(400);
+ });
+
+ it("rejects malformed numbers", async () => {
+ const { post } = setup(async () => ({ integratedLufs: -16, truePeakDbfs: -3 }));
+ const res = await post({ src: "talk.mp4", playbackRate: 0 });
+ expect(res.status).toBe(400);
+ expect((await res.json()).error).toMatch(/playbackRate/);
+ });
+
+ it("404s a missing file and 422s a silent one", async () => {
+ const { post } = setup(async () => ({ integratedLufs: -70, truePeakDbfs: -90 }));
+ expect((await post({ src: "missing.wav" })).status).toBe(404);
+ const silent = await post({ src: "talk.mp4" });
+ expect(silent.status).toBe(422);
+ expect((await silent.json()).error).toMatch(/silent/);
+ });
+});
diff --git a/packages/studio-server/src/routes/loudness.ts b/packages/studio-server/src/routes/loudness.ts
new file mode 100644
index 0000000000..cd49910c68
--- /dev/null
+++ b/packages/studio-server/src/routes/loudness.ts
@@ -0,0 +1,111 @@
+import { existsSync } from "node:fs";
+import type { Hono } from "hono";
+import type { StudioApiAdapter } from "../types.js";
+import {
+ absoluteLoudnessPlan,
+ DEFAULT_TARGET_LUFS,
+ measureAudio,
+ requiredFfmpeg,
+ resolveLocalAudioPath,
+ type LoudnessMeasurement,
+ type MeasuredWindow,
+} from "../helpers/loudness.js";
+
+export type MeasureLoudness = (
+ file: string,
+ window: MeasuredWindow,
+) => Promise<LoudnessMeasurement>;
+
+interface NormalizeRequest {
+ id: string;
+ src: string;
+ window: MeasuredWindow;
+ volume: number;
+ targetLufs: number;
+}
+
+const defaultMeasure: MeasureLoudness = (file, window) =>
+ measureAudio(requiredFfmpeg(), file, window);
+
+class InvalidField extends Error {}
+
+function numberField(
+ body: Record<string, unknown>,
+ name: string,
+ fallback: number,
+ valid: (value: number) => boolean,
+): number {
+ const raw = body[name];
+ if (raw === undefined || raw === null) return fallback;
+ if (typeof raw === "number" && Number.isFinite(raw) && valid(raw)) return raw;
+ throw new InvalidField(`${name} is out of range`);
+}
+
+function readNormalizeRequest(body: Record<string, unknown>): NormalizeRequest {
+ const src = typeof body.src === "string" ? body.src.trim() : "";
+ if (!src) throw new InvalidField("src is required");
+ const duration = numberField(body, "duration", 0, (v) => v > 0);
+ return {
+ id: typeof body.id === "string" && body.id ? body.id : src,
+ src,
+ window: {
+ mediaStart: numberField(body, "mediaStart", 0, (v) => v >= 0),
+ duration: duration > 0 ? duration : null,
+ playbackRate: numberField(body, "playbackRate", 1, (v) => v > 0),
+ },
+ volume: numberField(body, "volume", 1, (v) => v >= 0),
+ targetLufs: numberField(body, "targetLufs", DEFAULT_TARGET_LUFS, (v) => v < 0),
+ };
+}
+
+function parseNormalizeRequest(body: Record<string, unknown>): NormalizeRequest | string {
+ try {
+ return readNormalizeRequest(body);
+ } catch (error) {
+ if (error instanceof InvalidField) return error.message;
+ throw error;
+ }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Measure one clip's played window and answer the `data-volume` that brings it
+ * to the target. Measure-only: Studio writes the attribute through its own
+ * edit path so the change is one undo step like any other.
+ */
+export function registerLoudnessRoutes(
+ api: Hono,
+ adapter: StudioApiAdapter,
+ measure: MeasureLoudness = defaultMeasure,
+): void {
+ api.post("/projects/:id/loudness/normalize", async (c) => {
+ const project = await adapter.resolveProject(c.req.param("id"));
+ if (!project) return c.json({ error: "not found" }, 404);
+ const body: unknown = await c.req.json().catch(() => null);
+ if (!isRecord(body)) return c.json({ error: "invalid body" }, 400);
+ const request = parseNormalizeRequest(body);
+ if (typeof request === "string") return c.json({ error: request }, 400);
+
+ let file: string;
+ try {
+ file = resolveLocalAudioPath(project.dir, request.src);
+ } catch (error) {
+ return c.json({ error: error instanceof Error ? error.message : String(error) }, 400);
+ }
+ if (!existsSync(file)) return c.json({ error: "file not found" }, 404);
+
+ try {
+ const measurement = await measure(file, request.window);
+ const plan = absoluteLoudnessPlan(
+ { id: request.id, volume: request.volume, ...measurement },
+ request.targetLufs,
+ );
+ return c.json({ plan });
+ } catch (error) {
+ return c.json({ error: error instanceof Error ? error.message : String(error) }, 422);
+ }
+ });
+}
diff --git a/packages/studio-server/src/routes/render.test.ts b/packages/studio-server/src/routes/render.test.ts
index b4853a2def..e888951de1 100644
--- a/packages/studio-server/src/routes/render.test.ts
+++ b/packages/studio-server/src/routes/render.test.ts
@@ -763,3 +763,61 @@ describe("POST /projects/:id/render — variables forwarding", () => {
}
});
});
+
+describe("audioLoweredDb — the limiter's attenuation reaches the host", () => {
+ async function completedJobProgress(audioLoweredDb: number | undefined): Promise<string> {
+ const spy = vi.fn();
+ const { adapter, rendersDir } = createAdapter(spy);
+ const baseStartRender = adapter.startRender.bind(adapter);
+ adapter.startRender = (opts) => {
+ const state = baseStartRender(opts);
+ state.status = "complete";
+ state.progress = 100;
+ if (audioLoweredDb !== undefined) state.audioLoweredDb = audioLoweredDb;
+ return state;
+ };
+ const app = new Hono();
+ registerRenderRoutes(app, adapter);
+ try {
+ const started = await app.request("http://localhost/projects/demo/render", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({ fps: 30, quality: "standard", format: "mp4" }),
+ });
+ const { jobId } = (await started.json()) as { jobId: string };
+ return await (await app.request(`http://localhost/render/${jobId}/progress`)).text();
+ } finally {
+ rmSync(rendersDir, { recursive: true, force: true });
+ }
+ }
+
+ it("carries audioLoweredDb in the complete progress event", async () => {
+ const body = await completedJobProgress(1.44);
+ expect(body).toContain('"status":"complete"');
+ expect(body).toContain('"audioLoweredDb":1.44');
+ });
+
+ it("omits it when the limiter did not engage", async () => {
+ expect(await completedJobProgress(undefined)).not.toContain("audioLoweredDb");
+ });
+
+ it("lists it on the render record from the sidecar, and omits it otherwise", async () => {
+ const { app, rendersDir, cleanup } = buildApp(vi.fn());
+ try {
+ writeFileSync(join(rendersDir, "loud.mp4"), "x");
+ writeFileSync(
+ join(rendersDir, "loud.meta.json"),
+ JSON.stringify({ status: "complete", audioLoweredDb: 1.44 }),
+ );
+ writeFileSync(join(rendersDir, "quiet.mp4"), "x");
+ writeFileSync(join(rendersDir, "quiet.meta.json"), JSON.stringify({ status: "complete" }));
+ const { renders } = (await (
+ await app.request("http://localhost/projects/demo/renders")
+ ).json()) as { renders: Array<{ id: string; audioLoweredDb?: number }> };
+ expect(renders.find((r) => r.id === "loud")?.audioLoweredDb).toBe(1.44);
+ expect(renders.find((r) => r.id === "quiet")).not.toHaveProperty("audioLoweredDb");
+ } finally {
+ cleanup();
+ }
+ });
+});
diff --git a/packages/studio-server/src/routes/render.ts b/packages/studio-server/src/routes/render.ts
index 951188e28c..9e312a97fc 100644
--- a/packages/studio-server/src/routes/render.ts
+++ b/packages/studio-server/src/routes/render.ts
@@ -168,6 +168,9 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
status: current.status,
stage: current.stage,
error: current.error,
+ ...(current.status === "complete" && current.audioLoweredDb !== undefined
+ ? { audioLoweredDb: current.audioLoweredDb }
+ : {}),
}),
});
if (current.status !== "rendering") break;
@@ -300,6 +303,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
const metaPath = join(rendersDir, `${rid}.meta.json`);
let status: "complete" | "failed" = "complete";
let durationMs: number | undefined;
+ let audioLoweredDb: number | undefined;
if (existsSync(metaPath)) {
try {
const meta = JSON.parse(readFileSync(metaPath, "utf-8"));
@@ -309,6 +313,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
// an earlier attempt left behind failed metadata.
if (meta.status === "failed" && !existsSync(fp)) status = "failed";
if (meta.durationMs) durationMs = meta.durationMs;
+ if (typeof meta.audioLoweredDb === "number") audioLoweredDb = meta.audioLoweredDb;
} catch {
/* ignore */
}
@@ -320,6 +325,7 @@ export function registerRenderRoutes(api: Hono, adapter: StudioApiAdapter): void
createdAt: stat.mtimeMs,
status,
durationMs,
+ ...(audioLoweredDb !== undefined ? { audioLoweredDb } : {}),
};
})
.sort((a, b) => b.createdAt - a.createdAt);
diff --git a/packages/studio-server/src/types.ts b/packages/studio-server/src/types.ts
index 3d79952f15..719bbc317f 100644
--- a/packages/studio-server/src/types.ts
+++ b/packages/studio-server/src/types.ts
@@ -19,6 +19,7 @@ export interface RenderJobState {
stage?: string;
outputPath: string;
error?: string;
+ audioLoweredDb?: number;
/**
* Optional abort hook set by the adapter. The cancel route calls this to
* stop an in-flight render; adapters that can't abort may omit it (the
diff --git a/packages/studio-server/tsup.config.ts b/packages/studio-server/tsup.config.ts
index 19148acb89..1f828c16cc 100644
--- a/packages/studio-server/tsup.config.ts
+++ b/packages/studio-server/tsup.config.ts
@@ -6,6 +6,7 @@ export default defineConfig({
"helpers/screenshotClip": "src/helpers/screenshotClip.ts",
"helpers/mediaCodecMap": "src/helpers/mediaCodecMap.ts",
"helpers/proxyTranscoder": "src/helpers/proxyTranscoder.ts",
+ "helpers/loudness": "src/helpers/loudness.ts",
"helpers/mediaProxyPreview": "src/helpers/mediaProxyPreview.ts",
"helpers/manualEditsRenderScript": "src/helpers/manualEditsRenderScript.ts",
"helpers/studioMotionRenderScript": "src/helpers/studioMotionRenderScript.ts",
diff --git a/packages/studio/src/components/editor/carveOutput.ts b/packages/studio/src/components/editor/carveOutput.ts
new file mode 100644
index 0000000000..e605c6025e
--- /dev/null
+++ b/packages/studio/src/components/editor/carveOutput.ts
@@ -0,0 +1,54 @@
+import {
+ HF_AUDIO_FX_ATTR,
+ serializeAudioFxChain,
+ type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import { type HfAutomation } from "@hyperframes/core/audio-automation";
+import { isCarveVoiceElement } from "./useFxCarveGrouping.js";
+import { automationAttrValue, HF_AUDIO_AUTOMATION_ATTR } from "./propertyPanelAutomation";
+import type { CarveClip } from "./useFxCarveNodes.js";
+import { readClipClock } from "./clipAudioClock.js";
+
+/** Lanes belonging to nodes the carve generated, which a re-run replaces. */
+export function withoutCarveLanes(automation: HfAutomation, chain: HfAudioFxChain): HfAutomation {
+ const prefixes = chain.nodes.filter((n) => n.fromCarve && n.id).map((n) => `fx.${n.id}.`);
+ if (prefixes.length === 0) return automation;
+ return {
+ version: automation.version,
+ lanes: automation.lanes.filter((lane) => !prefixes.some((p) => lane.target.startsWith(p))),
+ };
+}
+
+/** Every named voice still present with a src; a deleted source is skipped, not fatal. */
+export function resolveCarveVoices(doc: Document, sources: readonly string[]): CarveClip[] {
+ const voices: CarveClip[] = [];
+ for (const id of sources) {
+ const el = doc.getElementById(id);
+ // By tag name: iframe-realm elements fail `instanceof HTMLAudioElement`.
+ if (!isCarveVoiceElement(el)) continue;
+ const src = el.getAttribute("src");
+ if (!src) continue;
+ const clock = readClipClock((name) => el.getAttribute(name));
+ voices.push({ src, start: el.getAttribute("data-start"), clock });
+ }
+ return voices;
+}
+
+/** Remove the filters and lanes a carve generated once it no longer names a voice. */
+export async function dropCarveOutput(
+ chain: HfAudioFxChain,
+ automation: HfAutomation,
+ onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
+): Promise<void> {
+ const carriedOver = withoutCarveLanes(automation, chain);
+ if (carriedOver.lanes.length !== automation.lanes.length) {
+ await onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(carriedOver) || null);
+ }
+ const kept = chain.nodes.filter((n) => !n.fromCarve);
+ if (kept.length !== chain.nodes.length) {
+ await onSetAttributeQuiet(
+ HF_AUDIO_FX_ATTR,
+ kept.length ? serializeAudioFxChain({ version: 1, nodes: kept }) : null,
+ );
+ }
+}
diff --git a/packages/studio/src/components/editor/useFxCarve.ts b/packages/studio/src/components/editor/useFxCarve.ts
index 44959f0826..8f5752850c 100644
--- a/packages/studio/src/components/editor/useFxCarve.ts
+++ b/packages/studio/src/components/editor/useFxCarve.ts
@@ -25,16 +25,15 @@ import {
carverAgainst,
collectCarveCandidates,
CARVE_ABORTED,
- isCarveVoiceElement,
isPromiseLike,
resolveNextCarveSettings,
} from "./useFxCarveGrouping.js";
import { type HfAutomation } from "@hyperframes/core/audio-automation";
-import { automationAttrValue, HF_AUDIO_AUTOMATION_ATTR } from "./propertyPanelAutomation";
import { trackCarveChanged } from "./audioFxTelemetry.js";
import type { DomEditSelection } from "./domEditingTypes";
import { usePlayerStore } from "../../player";
-import { carveLanes, measureCarve, mintCarveNodes, type CarveClip } from "./useFxCarveNodes.js";
+import { dropCarveOutput, resolveCarveVoices, withoutCarveLanes } from "./carveOutput.js";
+import { carveLanes, measureCarve, mintCarveNodes } from "./useFxCarveNodes.js";
import { readClipClock } from "./clipAudioClock.js";
import { spanOf } from "./propertyPanelAudioFxGroupUtils.js";
import type { AudioTrackOption } from "./propertyPanelFxCarveModule.js";
@@ -56,16 +55,6 @@ function carveAction(
return "strength";
}
-/** Lanes belonging to nodes the carve generated, which a re-run replaces. */
-function withoutCarveLanes(automation: HfAutomation, chain: HfAudioFxChain): HfAutomation {
- const prefixes = chain.nodes.filter((n) => n.fromCarve && n.id).map((n) => `fx.${n.id}.`);
- if (prefixes.length === 0) return automation;
- return {
- version: automation.version,
- lanes: automation.lanes.filter((lane) => !prefixes.some((p) => lane.target.startsWith(p))),
- };
-}
-
/**
* Every setting here describes the filters, so changing one rebuilds them.
* There is no apply button: a carve naming a voice with no filters behind it
@@ -87,54 +76,6 @@ function carveNeedsReanalysis(
);
}
-/**
- * Every named voice that is actually there with something to decode. A source
- * naming a deleted track is skipped rather than failing the whole analysis.
- *
- * Read out to plain values here rather than carrying elements around: it is
- * what lets the src and the start be non-null by construction downstream
- * instead of by assertion.
- */
-function resolveCarveVoices(doc: Document, sources: readonly string[]): CarveClip[] {
- const voices: CarveClip[] = [];
- for (const id of sources) {
- const el = doc.getElementById(id);
- // By tag name, not `instanceof HTMLAudioElement`: these elements belong to
- // the composition's iframe document, so the constructor they were made
- // from is not this realm's and the instanceof is false for every one.
- if (!isCarveVoiceElement(el)) continue;
- const src = el.getAttribute("src");
- if (!src) continue;
- const clock = readClipClock((name) => el.getAttribute(name));
- voices.push({ src, start: el.getAttribute("data-start"), clock });
- }
- return voices;
-}
-
-/**
- * What the carve generated is only justified by the voices it was measured
- * from: switched off, or left naming none — every source deleted, say — there
- * is nothing those filters are making room for. Left behind they keep dipping
- * the bed with nothing in the panel to explain them.
- */
-async function dropCarveOutput(
- chain: HfAudioFxChain,
- automation: HfAutomation,
- onSetAttributeQuiet: (attr: string, value: string | null) => void | Promise<void>,
-): Promise<void> {
- const carriedOver = withoutCarveLanes(automation, chain);
- if (carriedOver.lanes.length !== automation.lanes.length) {
- await onSetAttributeQuiet(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(carriedOver) || null);
- }
- const kept = chain.nodes.filter((n) => !n.fromCarve);
- if (kept.length !== chain.nodes.length) {
- await onSetAttributeQuiet(
- HF_AUDIO_FX_ATTR,
- kept.length ? serializeAudioFxChain({ version: 1, nodes: kept }) : null,
- );
- }
-}
-
export function useFxCarve(
element: DomEditSelection,
chain: HfAudioFxChain,
diff --git a/packages/studio/src/hooks/useRenderClipContent.ts b/packages/studio/src/hooks/useRenderClipContent.ts
index aa6d7b7200..f0b4eac451 100644
--- a/packages/studio/src/hooks/useRenderClipContent.ts
+++ b/packages/studio/src/hooks/useRenderClipContent.ts
@@ -1,4 +1,5 @@
import { buildProjectApiPath } from "../utils/projectRouting";
+import { resolvePreviewRelative } from "../utils/previewRelativePath";
import { useCallback, type ReactNode } from "react";
import { createElement } from "react";
import { CompositionThumbnail, VideoThumbnail } from "../player";
@@ -33,24 +34,6 @@ export function normalizeCompositionSrc(
return compSrc;
}
-/** Resolve a media src to its project-relative preview path, or null. */
-function resolvePreviewRelative(
- src: string | undefined,
- pid: string,
- origin: string,
-): string | null {
- if (!src) return null;
- try {
- const parsed = new URL(src, origin);
- const base = new URL(buildProjectApiPath(pid, `/preview/`), origin).pathname;
- return parsed.pathname.startsWith(base)
- ? decodeURIComponent(parsed.pathname.slice(base.length))
- : null;
- } catch {
- return null;
- }
-}
-
/**
* The trimmed source slice as start/end fractions (0–1) of the source, so the
* waveform can window its peaks to the clip edges. Undefined when the source
diff --git a/packages/studio/src/index.ts b/packages/studio/src/index.ts
index f12013cced..b79b3d6df6 100644
--- a/packages/studio/src/index.ts
+++ b/packages/studio/src/index.ts
@@ -175,6 +175,7 @@ export { TimelineHistoryButtons } from "./components/TimelineHistoryButtons";
export type { TimelineHistoryButtonsProps } from "./components/TimelineHistoryButtons";
export { AudioMeterStrip } from "./components/nle/AudioMeterStrip";
export type { AudioMeterStripProps } from "./components/nle/AudioMeterStrip";
+export { useAudioMetersVisible } from "./utils/audioMeterVisibility";
export { useClipboard } from "./hooks/useClipboard";
export type { UseClipboardOptions } from "./hooks/useClipboard";
diff --git a/packages/studio/src/player/components/ClipContextMenu.tsx b/packages/studio/src/player/components/ClipContextMenu.tsx
index 77f76a784d..723e3f455c 100644
--- a/packages/studio/src/player/components/ClipContextMenu.tsx
+++ b/packages/studio/src/player/components/ClipContextMenu.tsx
@@ -6,6 +6,7 @@ import { useContextMenuDismiss } from "../../hooks/useContextMenuDismiss";
import { useMenuKeyboardNav } from "./menuKeyboardNav";
import type { TimelineClipMenuItem } from "./TimelineTypes";
import { ClipMenuToolItems } from "./clipMenuToolItems";
+import { ClipMenuAudioItems } from "./clipMenuAudioItems";
interface ClipContextMenuProps {
x: number;
@@ -155,6 +156,8 @@ export const ClipContextMenu = memo(function ClipContextMenu({
</>
)}
+ <ClipMenuAudioItems element={element} onClose={onClose} />
+
{(onCopy || onPaste || onDuplicate) && (
<>
{onCopy && (
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.test.tsx b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
new file mode 100644
index 0000000000..7b1a35820e
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuAudioItems.test.tsx
@@ -0,0 +1,125 @@
+// @vitest-environment happy-dom
+import { act } from "react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createHappyDomRootHarness } from "./testRootHarness";
+import { ClipMenuAudioItems } from "./clipMenuAudioItems";
+import type { TimelineElement } from "../store/timelineElement";
+
+const showToast = vi.fn();
+const setQuiet = vi.fn<(...args: unknown[]) => Promise<unknown>>(async () => {});
+const iframe = document.createElement("iframe");
+
+vi.mock("../../contexts/StudioContext", () => ({
+ useStudioShellContextOptional: () => ({
+ projectId: "p1",
+ showToast,
+ previewIframeRef: { current: iframe },
+ }),
+}));
+vi.mock("../../contexts/TimelineEditContext", () => ({
+ useTimelineEditContextOptional: () => ({ onSetElementAttributeQuiet: setQuiet }),
+}));
+
+const harness = createHappyDomRootHarness();
+
+function render(element: TimelineElement) {
+ const host = document.createElement("div");
+ document.body.appendChild(host);
+ act(() =>
+ harness.mount(host).render(<ClipMenuAudioItems element={element} onClose={() => {}} />),
+ );
+ return host;
+}
+
+const base = { start: 0, duration: 4, track: 0 };
+const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+const clickItem = async (host: HTMLElement, label: string) => {
+ const button = [...host.querySelectorAll("button")].find((b) => b.textContent?.includes(label));
+ await act(async () => button?.click());
+};
+
+beforeEach(() => {
+ showToast.mockClear();
+ setQuiet.mockReset();
+ setQuiet.mockResolvedValue(undefined);
+});
+
+describe("ClipMenuAudioItems", () => {
+ it("offers nothing on a muted video", () => {
+ const host = render({ ...base, id: "b", tag: "video", hasAudio: true, muted: true });
+ expect(host.textContent).toBe("");
+ });
+
+ it("normalizes a video with sound by writing data-volume as one edit", async () => {
+ const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async () => Response.json({ plan })),
+ );
+ const element: TimelineElement = {
+ ...base,
+ id: "a-roll",
+ tag: "video",
+ hasAudio: true,
+ src: "talk.mp4",
+ };
+ const host = render(element);
+ const button = [...host.querySelectorAll("button")].find((b) =>
+ b.textContent?.includes("Normalize loudness"),
+ );
+ await act(async () => button?.click());
+ await vi.waitFor(() => expect(setQuiet).toHaveBeenCalled());
+ expect(setQuiet).toHaveBeenCalledWith(element, "data-volume", "2", "Normalize loudness");
+ expect(showToast).toHaveBeenCalledWith("Normalized to −16 LUFS (+6.0 dB)", "info");
+ vi.unstubAllGlobals();
+ });
+
+ it("refuses to normalize a clip whose volume lane owns its gain", async () => {
+ const fetchSpy = vi.fn(async () => Response.json({ plan }));
+ vi.stubGlobal("fetch", fetchSpy);
+ const automation = JSON.stringify({
+ version: 1,
+ lanes: [{ target: "volume", points: [{ t: 0, v: 0.25 }] }],
+ });
+ const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3", automation });
+ await clickItem(host, "Normalize loudness");
+ await vi.waitFor(() => expect(showToast).toHaveBeenCalled());
+ expect(showToast).toHaveBeenCalledWith(expect.stringContaining("volume is automated"), "error");
+ expect(setQuiet).not.toHaveBeenCalled();
+ expect(fetchSpy).not.toHaveBeenCalled();
+ vi.unstubAllGlobals();
+ });
+
+ it("reports a failed save instead of claiming the clip was normalized", async () => {
+ vi.stubGlobal(
+ "fetch",
+ vi.fn(async () => Response.json({ plan })),
+ );
+ setQuiet.mockResolvedValue({ status: "failed", reason: "disk full" });
+ const host = render({ ...base, id: "vo", tag: "audio", src: "vo.mp3" });
+ await clickItem(host, "Normalize loudness");
+ await vi.waitFor(() => expect(showToast).toHaveBeenCalledWith("disk full", "error"));
+ expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Normalized"), "info");
+ vi.unstubAllGlobals();
+ });
+
+ it("stops ducking at the first refused save and says why", async () => {
+ document.body.appendChild(iframe);
+ const doc = iframe.contentDocument;
+ if (!doc) throw new Error("fixture");
+ doc.body.innerHTML = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>
+ <audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`;
+ setQuiet.mockResolvedValue({
+ status: "refused",
+ reason: "Cannot edit timeline while recording",
+ });
+ const host = render({ ...base, id: "music", tag: "audio", src: "music.mp3" });
+ await clickItem(host, "Duck under voice");
+ await vi.waitFor(() =>
+ expect(showToast).toHaveBeenCalledWith("Cannot edit timeline while recording", "error"),
+ );
+ expect(setQuiet).toHaveBeenCalledTimes(1);
+ expect(showToast).not.toHaveBeenCalledWith(expect.stringContaining("Ducks under"), "info");
+ iframe.remove();
+ });
+});
diff --git a/packages/studio/src/player/components/clipMenuAudioItems.tsx b/packages/studio/src/player/components/clipMenuAudioItems.tsx
new file mode 100644
index 0000000000..0df27dd0f2
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuAudioItems.tsx
@@ -0,0 +1,108 @@
+import { formatAudioGain } from "@hyperframes/core/audio-gain";
+import type { TimelineElement } from "../store/timelineElement";
+import { useTimelineEditContextOptional } from "../../contexts/TimelineEditContext";
+import { useStudioShellContextOptional } from "../../contexts/StudioContext";
+import {
+ clipHasSound,
+ normalizeToastText,
+ requestNormalizePlan,
+ throwUnlessSaved,
+ TimelineSaveError,
+ VOLUME_LANE_REFUSAL,
+ volumeLaneOwnsGain,
+} from "./clipMenuNormalize";
+import { isDuckableBed, readBedCarve, setDuckUnderVoice, type DuckOutcome } from "./clipMenuDuck";
+
+const ITEM_CLASS =
+ "w-full flex items-center justify-between px-3 py-1.5 text-xs text-left outline-hidden text-neutral-300 hover:bg-neutral-800 focus-visible:bg-neutral-800 cursor-pointer";
+
+const DUCK_TOAST: Record<DuckOutcome, string> = {
+ ducked: "Ducks under the voice. Normalize the voice first for the most even result.",
+ off: "No longer ducks under the voice.",
+ "no-voice": "No overlapping voice to duck under.",
+ aborted: "Could not group the voices to duck under.",
+};
+
+/** Sound group of the clip menu: Normalize loudness (one-shot) and Duck under voice (toggle). */
+export function ClipMenuAudioItems({
+ element,
+ onClose,
+}: {
+ element: TimelineElement;
+ onClose: () => void;
+}) {
+ const shell = useStudioShellContextOptional();
+ const { onSetElementAttributeQuiet, onGroupClips } = useTimelineEditContextOptional();
+ const doc = shell?.previewIframeRef.current?.contentDocument ?? null;
+ const bed = doc?.getElementById(element.domId ?? element.id) ?? null;
+ const ducked = bed ? readBedCarve(bed)?.enabled === true : false;
+ if (!clipHasSound(element) || !shell || !onSetElementAttributeQuiet) return null;
+ const { showToast, projectId } = shell;
+
+ const normalize = async () => {
+ onClose();
+ if (volumeLaneOwnsGain(element)) {
+ showToast(VOLUME_LANE_REFUSAL, "error");
+ return;
+ }
+ try {
+ const plan = await requestNormalizePlan(projectId, element);
+ throwUnlessSaved(
+ await onSetElementAttributeQuiet(
+ element,
+ "data-volume",
+ formatAudioGain(plan.volume),
+ "Normalize loudness",
+ ),
+ );
+ showToast(normalizeToastText(plan), "info");
+ } catch (error) {
+ showToast(error instanceof Error ? error.message : String(error), "error");
+ }
+ };
+
+ const toggleDuck = async () => {
+ onClose();
+ if (!doc || !bed) return;
+ const outcome = await setDuckUnderVoice(
+ doc,
+ bed,
+ !ducked,
+ async (attr, value) => {
+ throwUnlessSaved(
+ await onSetElementAttributeQuiet(element, attr, value, "Duck under voice"),
+ );
+ },
+ onGroupClips ? (ids, groupId) => onGroupClips(ids, groupId, "Voice") : undefined,
+ ).catch((error: unknown): DuckOutcome | TimelineSaveError =>
+ error instanceof TimelineSaveError ? error : "aborted",
+ );
+ if (outcome instanceof TimelineSaveError) {
+ showToast(outcome.message, "error");
+ return;
+ }
+ showToast(DUCK_TOAST[outcome], outcome === "aborted" ? "error" : "info");
+ };
+
+ return (
+ <>
+ <button type="button" role="menuitem" className={ITEM_CLASS} onClick={() => void normalize()}>
+ <span>Normalize loudness</span>
+ </button>
+ {isDuckableBed(bed) && (
+ <button
+ type="button"
+ role="menuitemcheckbox"
+ aria-checked={ducked}
+ className={ITEM_CLASS}
+ onClick={() => void toggleDuck()}
+ >
+ <span>
+ <span className="inline-block w-3">{ducked ? "✓" : ""}</span>Duck under voice
+ </span>
+ </button>
+ )}
+ <div className="my-1 border-t border-neutral-700/60" />
+ </>
+ );
+}
diff --git a/packages/studio/src/player/components/clipMenuDuck.test.ts b/packages/studio/src/player/components/clipMenuDuck.test.ts
new file mode 100644
index 0000000000..0431eb439a
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuDuck.test.ts
@@ -0,0 +1,110 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import { duckVoiceSources, isDuckableBed, readBedCarve, setDuckUnderVoice } from "./clipMenuDuck";
+
+function compose(body: string): Document {
+ const doc = document.implementation.createHTMLDocument("c");
+ doc.body.innerHTML = body;
+ return doc;
+}
+
+const BED = `<audio id="music" src="music.mp3" data-start="0" data-duration="10"></audio>`;
+
+describe("duckVoiceSources", () => {
+ it("offers an overlapping video with sound and a voiceover, never the bed or silent video", () => {
+ const doc = compose(`${BED}
+ <video id="talk" src="talk.mp4" data-start="0" data-duration="6" data-has-audio="true"></video>
+ <video id="b-roll" src="b.mp4" data-start="0" data-duration="6" muted></video>
+ <audio id="voiceover" src="vo.wav" data-start="2" data-duration="3"></audio>
+ <audio id="late-vo" src="vo2.wav" data-start="20" data-duration="3"></audio>`);
+ const bed = doc.getElementById("music");
+ expect(bed && duckVoiceSources(doc, bed)).toEqual(["talk", "voiceover"]);
+ });
+});
+
+describe("isDuckableBed", () => {
+ it("allows a music clip and refuses a voice clip", () => {
+ const doc = compose(`${BED}<audio id="voiceover" src="voiceover.wav"></audio>`);
+ expect(isDuckableBed(doc.getElementById("music"))).toBe(true);
+ expect(isDuckableBed(doc.getElementById("voiceover"))).toBe(false);
+ });
+});
+
+describe("setDuckUnderVoice", () => {
+ it("writes a carve at core's default strength naming the one voice", async () => {
+ const doc = compose(
+ `${BED}<audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>`,
+ );
+ const bed = doc.getElementById("music");
+ if (!bed) throw new Error("fixture");
+ const write = vi.fn(async (attr: string, value: string | null) => {
+ if (value === null) bed.removeAttribute(attr);
+ else bed.setAttribute(attr, value);
+ });
+ await expect(setDuckUnderVoice(doc, bed, true, write)).resolves.toBe("ducked");
+ expect(readBedCarve(bed)).toEqual({ enabled: true, sources: ["voiceover"], strength: 0.25 });
+ });
+
+ it("groups several voices first so the carve names one group", async () => {
+ const doc = compose(`${BED}
+ <audio id="voiceover" src="vo.wav" data-start="1" data-duration="3"></audio>
+ <audio id="narration" src="n.wav" data-start="5" data-duration="3"></audio>`);
+ const bed = doc.getElementById("music");
+ if (!bed) throw new Error("fixture");
+ const write = vi.fn(async (attr: string, value: string | null) => {
+ if (value !== null) bed.setAttribute(attr, value);
+ });
+ const group = vi.fn(async () => {});
+ await setDuckUnderVoice(doc, bed, true, write, group);
+ expect(group).toHaveBeenCalledWith(["voiceover", "narration"], "voiceover-2");
+ expect(readBedCarve(bed)?.sources).toEqual(["voiceover-2"]);
+ });
+
+ it("reports no voice instead of writing an empty carve", async () => {
+ const doc = compose(BED);
+ const bed = doc.getElementById("music");
+ if (!bed) throw new Error("fixture");
+ const write = vi.fn(async () => {});
+ await expect(setDuckUnderVoice(doc, bed, true, write)).resolves.toBe("no-voice");
+ expect(write).not.toHaveBeenCalled();
+ });
+
+ it("turning it off disables the carve and drops the generated nodes and lanes", async () => {
+ const chain = {
+ version: 1,
+ nodes: [
+ { id: "c1", type: "peaking", enabled: true, fromCarve: true, params: {} },
+ { id: "eq", type: "highpass", enabled: true, params: {} },
+ ],
+ };
+ const automation = {
+ version: 1,
+ lanes: [
+ {
+ target: "fx.c1.gain",
+ points: [
+ { t: 0, v: 0 },
+ { t: 1, v: -3 },
+ ],
+ },
+ ],
+ };
+ const doc = compose(BED);
+ const bed = doc.getElementById("music");
+ if (!bed) throw new Error("fixture");
+ bed.setAttribute(
+ "data-fx-carve",
+ JSON.stringify({ enabled: true, sources: ["vo"], strength: 0.25 }),
+ );
+ bed.setAttribute("data-fx-chain", JSON.stringify(chain));
+ bed.setAttribute("data-automation", JSON.stringify(automation));
+ const writes: Array<[string, string | null]> = [];
+ await setDuckUnderVoice(doc, bed, false, async (attr, value) => {
+ writes.push([attr, value]);
+ });
+ const byAttr = new Map(writes);
+ expect(JSON.parse(byAttr.get("data-fx-carve") ?? "{}").enabled).toBe(false);
+ expect(byAttr.get("data-automation")).toBeNull();
+ expect(byAttr.get("data-fx-chain")).not.toContain("c1");
+ });
+});
diff --git a/packages/studio/src/player/components/clipMenuDuck.ts b/packages/studio/src/player/components/clipMenuDuck.ts
new file mode 100644
index 0000000000..168b060643
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuDuck.ts
@@ -0,0 +1,140 @@
+import {
+ HF_AUDIO_FX_ATTR,
+ parseAudioFxChain,
+ serializeAudioFxChain,
+ type HfAudioFxChain,
+} from "@hyperframes/core/audio-fx";
+import {
+ clipsOverlap,
+ DEFAULT_CARVE,
+ HF_AUDIO_CARVE_ATTR,
+ normalizeCarveSettings,
+ type HfCarveSettings,
+} from "@hyperframes/core/audio-carve";
+import { resolveCarveSourceIds } from "@hyperframes/core/audio-groups";
+import { parseAutomation, type HfAutomation } from "@hyperframes/core/audio-automation";
+import {
+ carveBedRoles,
+ collectCarveCandidates,
+ CARVE_ABORTED,
+ isPromiseLike,
+ resolveNextCarveSettings,
+} from "../../components/editor/useFxCarveGrouping";
+import {
+ dropCarveOutput,
+ resolveCarveVoices,
+ withoutCarveLanes,
+} from "../../components/editor/carveOutput";
+import { carveLanes, measureCarve, mintCarveNodes } from "../../components/editor/useFxCarveNodes";
+import { readClipClock } from "../../components/editor/clipAudioClock";
+import {
+ automationAttrValue,
+ HF_AUDIO_AUTOMATION_ATTR,
+} from "../../components/editor/propertyPanelAutomation";
+import { spanOf } from "../../components/editor/propertyPanelAudioFxGroupUtils";
+
+export type WriteBedAttribute = (attr: string, value: string | null) => Promise<void>;
+export type GroupClips = (clipIds: readonly string[], groupId: string) => Promise<void>;
+
+export function readBedCarve(bed: Element): HfCarveSettings | null {
+ const raw = bed.getAttribute(HF_AUDIO_CARVE_ATTR);
+ if (!raw) return null;
+ try {
+ return normalizeCarveSettings(JSON.parse(raw));
+ } catch {
+ return null;
+ }
+}
+
+function readChain(bed: Element): HfAudioFxChain {
+ const raw = bed.getAttribute(HF_AUDIO_FX_ATTR);
+ try {
+ return raw ? parseAudioFxChain(raw) : { version: 1, nodes: [] };
+ } catch {
+ return { version: 1, nodes: [] };
+ }
+}
+
+function readAutomation(bed: Element): HfAutomation {
+ const raw = bed.getAttribute(HF_AUDIO_AUTOMATION_ATTR);
+ try {
+ return raw ? parseAutomation(raw) : { version: 1, lanes: [] };
+ } catch {
+ return { version: 1, lanes: [] };
+ }
+}
+
+export function isDuckableBed(bed: Element | null): bed is Element {
+ return bed !== null && carveBedRoles(bed.id, bed).couldBeBed;
+}
+
+/** Every overlapping clip with speech, including a video's own sound; never the bed itself. */
+export function duckVoiceSources(doc: Document, bed: Element): string[] {
+ const bedSpan = spanOf(bed.getAttribute("data-start"), bed.getAttribute("data-duration"));
+ const others = Array.from(doc.querySelectorAll("audio[id], video[id]")).filter(
+ (el) => el.id !== bed.id,
+ );
+ const overlaps = (el: Element) =>
+ clipsOverlap(bedSpan, spanOf(el.getAttribute("data-start"), el.getAttribute("data-duration")));
+ return collectCarveCandidates(doc, others, overlaps, bed.id)
+ .filter((candidate) => candidate.kind === "voice" || candidate.kind === "unknown")
+ .map((candidate) => candidate.id);
+}
+
+async function writeMeasuredCarve(
+ doc: Document,
+ bed: Element,
+ settings: HfCarveSettings,
+ write: WriteBedAttribute,
+): Promise<void> {
+ const expanded = resolveCarveSourceIds(doc, settings.sources).filter((id) => id !== bed.id);
+ const voices = resolveCarveVoices(doc, expanded);
+ if (voices.length === 0) return;
+ const measured = await measureCarve(doc, voices, settings.strength, {
+ src: bed.getAttribute("src"),
+ start: bed.getAttribute("data-start"),
+ clock: readClipClock((name) => bed.getAttribute(name)),
+ });
+ if (!measured) return;
+ const chain = readChain(bed);
+ const automation = readAutomation(bed);
+ const { next, carvedNodes, duckNode } = mintCarveNodes(chain, measured.carved, measured.duck);
+ await write(HF_AUDIO_FX_ATTR, serializeAudioFxChain(next));
+ const lanes = carveLanes(carvedNodes, duckNode, measured.duck, measured.voiceMix, measured.bands);
+ const carriedOver = withoutCarveLanes(automation, chain);
+ const nextAutomation = { version: 1, lanes: [...carriedOver.lanes, ...lanes] };
+ await write(HF_AUDIO_AUTOMATION_ATTR, automationAttrValue(nextAutomation) || null);
+}
+
+export type DuckOutcome = "ducked" | "no-voice" | "aborted" | "off";
+
+/**
+ * Switch the carve on a music bed. On: carve against every overlapping voice at
+ * core's default strength (several voices are grouped first, as the carve lint
+ * requires). Off: `enabled:false`, which drops the generated filters and lanes.
+ */
+export async function setDuckUnderVoice(
+ doc: Document,
+ bed: Element,
+ on: boolean,
+ write: WriteBedAttribute,
+ groupClips?: GroupClips,
+): Promise<DuckOutcome> {
+ const current = readBedCarve(bed);
+ if (!on) {
+ await dropCarveOutput(readChain(bed), readAutomation(bed), write);
+ await write(
+ HF_AUDIO_CARVE_ATTR,
+ JSON.stringify({ ...(current ?? DEFAULT_CARVE), enabled: false }),
+ );
+ return "off";
+ }
+ const sources = duckVoiceSources(doc, bed);
+ if (sources.length === 0) return "no-voice";
+ const resolved = resolveNextCarveSettings({ ...DEFAULT_CARVE, sources }, doc, groupClips);
+ const settings = isPromiseLike(resolved) ? await resolved : resolved;
+ if (settings === CARVE_ABORTED || settings === null) return "aborted";
+ await write(HF_AUDIO_CARVE_ATTR, JSON.stringify(settings));
+ await writeMeasuredCarve(doc, bed, settings, write);
+ return "ducked";
+}
diff --git a/packages/studio/src/player/components/clipMenuNormalize.test.ts b/packages/studio/src/player/components/clipMenuNormalize.test.ts
new file mode 100644
index 0000000000..e19a041bc0
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuNormalize.test.ts
@@ -0,0 +1,95 @@
+// @vitest-environment happy-dom
+import { describe, expect, it, vi } from "vitest";
+import {
+ clipHasSound,
+ normalizeRequestBody,
+ normalizeToastText,
+ requestNormalizePlan,
+} from "./clipMenuNormalize";
+import type { TimelineElement } from "../store/timelineElement";
+
+const clip = (over: Partial<TimelineElement>): TimelineElement => ({
+ id: "vo",
+ tag: "audio",
+ start: 0,
+ duration: 4,
+ track: 0,
+ ...over,
+});
+
+describe("clipHasSound", () => {
+ it("is true for audio and for a video with sound, false for silent or muted video", () => {
+ expect(clipHasSound(clip({}))).toBe(true);
+ expect(clipHasSound(clip({ tag: "video", hasAudio: true }))).toBe(true);
+ expect(clipHasSound(clip({ tag: "video", hasAudio: false }))).toBe(false);
+ expect(clipHasSound(clip({ tag: "video", hasAudio: true, muted: true }))).toBe(false);
+ expect(clipHasSound(clip({ tag: "img" }))).toBe(false);
+ });
+});
+
+describe("normalizeRequestBody", () => {
+ it("sends the played source window and the current gain", () => {
+ const body = normalizeRequestBody(
+ clip({ domId: "a-roll", playbackStart: 2, playbackRate: 2, volume: 0.5, duration: 3 }),
+ "talk.mp4",
+ );
+ expect(body).toEqual({
+ id: "a-roll",
+ src: "talk.mp4",
+ mediaStart: 2,
+ duration: 3,
+ playbackRate: 2,
+ volume: 0.5,
+ });
+ });
+});
+
+describe("normalizeToastText", () => {
+ it("names the target and the change", () => {
+ expect(
+ normalizeToastText({
+ targetLufs: -16,
+ projectedLufs: -16,
+ volume: 1.44,
+ changeDb: 3.2,
+ limitedBy: null,
+ }),
+ ).toBe("Normalized to −16 LUFS (+3.2 dB)");
+ });
+
+ it("says so when a limit held it back", () => {
+ expect(
+ normalizeToastText({
+ targetLufs: -16,
+ projectedLufs: -18.4,
+ volume: 4,
+ changeDb: 12,
+ limitedBy: "gain-ceiling",
+ }),
+ ).toBe("Raised to −18 LUFS (+12.0 dB), the most the +12 dB ceiling allows");
+ });
+});
+
+describe("requestNormalizePlan", () => {
+ it("posts the project-relative source and returns the plan", async () => {
+ const plan = { targetLufs: -16, projectedLufs: -16, volume: 2, changeDb: 6, limitedBy: null };
+ const fetchImpl = vi.fn<typeof fetch>(async () => Response.json({ plan }));
+ const origin = window.location.origin;
+ const el = clip({ src: `${origin}/api/projects/p1/preview/assets/vo.wav` });
+ await expect(requestNormalizePlan("p1", el, fetchImpl)).resolves.toEqual(plan);
+ const [url, init] = fetchImpl.mock.calls[0] ?? [];
+ expect(url).toBe("/api/projects/p1/loudness/normalize");
+ expect(JSON.parse(String(init?.body))).toEqual(
+ expect.objectContaining({ src: "assets/vo.wav" }),
+ );
+ });
+
+ it("surfaces the server's reason", async () => {
+ const fetchImpl = vi.fn<typeof fetch>(async () =>
+ Response.json({ error: "#vo is silent" }, { status: 422 }),
+ );
+ await expect(
+ requestNormalizePlan("p1", clip({ src: "assets/vo.wav" }), fetchImpl),
+ ).rejects.toThrow(/silent/);
+ });
+});
diff --git a/packages/studio/src/player/components/clipMenuNormalize.ts b/packages/studio/src/player/components/clipMenuNormalize.ts
new file mode 100644
index 0000000000..50b6e50dd9
--- /dev/null
+++ b/packages/studio/src/player/components/clipMenuNormalize.ts
@@ -0,0 +1,96 @@
+import { buildProjectApiPath } from "../../utils/projectRouting";
+import { resolvePreviewRelative } from "../../utils/previewRelativePath";
+import { resolveMediaPreviewUrl } from "./thumbnailUtils";
+import type { TimelineElement } from "../store/timelineElement";
+import { parseAutomation, VOLUME_TARGET } from "@hyperframes/core/audio-automation";
+import type { TimelineEditOutcome } from "../../hooks/timelineEditPermission";
+
+export interface NormalizePlan {
+ targetLufs: number;
+ projectedLufs: number;
+ volume: number;
+ changeDb: number;
+ limitedBy: "gain-ceiling" | "true-peak" | null;
+}
+
+export function clipHasSound(el: TimelineElement): boolean {
+ if (el.tag === "audio") return true;
+ return el.tag === "video" && el.hasAudio === true && el.muted !== true;
+}
+
+export const VOLUME_LANE_REFUSAL =
+ "This clip's volume is automated. Remove its volume automation to normalize it.";
+
+export function volumeLaneOwnsGain(el: TimelineElement): boolean {
+ if (!el.automation) return false;
+ try {
+ return parseAutomation(el.automation).lanes.some(
+ (lane) => lane.target === VOLUME_TARGET && lane.points.length > 0,
+ );
+ } catch {
+ return false;
+ }
+}
+
+export class TimelineSaveError extends Error {}
+
+export function throwUnlessSaved(outcome: TimelineEditOutcome | void): void {
+ if (outcome && outcome.status !== "saved") throw new TimelineSaveError(outcome.reason);
+}
+
+export function normalizeRequestBody(el: TimelineElement, projectRelativeSrc: string) {
+ return {
+ id: el.domId ?? el.id,
+ src: projectRelativeSrc,
+ mediaStart: el.playbackStart ?? 0,
+ duration: el.duration > 0 ? el.duration : undefined,
+ playbackRate: el.playbackRate ?? 1,
+ volume: el.volume ?? 1,
+ };
+}
+
+const signedDb = (db: number) => `${db >= 0 ? "+" : "−"}${Math.abs(db).toFixed(1)} dB`;
+const lufsText = (lufs: number) => `${lufs < 0 ? "−" : ""}${Math.abs(lufs).toFixed(0)} LUFS`;
+
+const LIMIT_SUFFIX = {
+ "gain-ceiling": "the most the +12 dB ceiling allows",
+ "true-peak": "held back to keep peaks under −1.5 dBTP",
+} satisfies Record<NonNullable<NormalizePlan["limitedBy"]>, string>;
+
+export function normalizeToastText(plan: NormalizePlan): string {
+ if (!plan.limitedBy)
+ return `Normalized to ${lufsText(plan.targetLufs)} (${signedDb(plan.changeDb)})`;
+ const reached = `${lufsText(Math.round(plan.projectedLufs))}`;
+ return `Raised to ${reached} (${signedDb(plan.changeDb)}), ${LIMIT_SUFFIX[plan.limitedBy]}`;
+}
+
+function isNormalizePlan(value: unknown): value is NormalizePlan {
+ if (typeof value !== "object" || value === null) return false;
+ return ["targetLufs", "projectedLufs", "volume", "changeDb"].every(
+ (key) => typeof Reflect.get(value, key) === "number",
+ );
+}
+
+export async function requestNormalizePlan(
+ projectId: string,
+ el: TimelineElement,
+ fetchImpl: typeof fetch = fetch,
+): Promise<NormalizePlan> {
+ const origin = window.location.origin;
+ const relative = resolvePreviewRelative(
+ resolveMediaPreviewUrl(el.src ?? "", projectId, origin),
+ projectId,
+ origin,
+ );
+ if (!relative) throw new Error("Only project media can be normalized");
+ const res = await fetchImpl(buildProjectApiPath(projectId, "/loudness/normalize"), {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify(normalizeRequestBody(el, relative)),
+ });
+ const body: unknown = await res.json().catch(() => null);
+ const plan = typeof body === "object" && body !== null ? Reflect.get(body, "plan") : null;
+ if (res.ok && isNormalizePlan(plan)) return plan;
+ const error = typeof body === "object" && body !== null ? Reflect.get(body, "error") : null;
+ throw new Error(typeof error === "string" ? error : "Could not measure this clip");
+}
diff --git a/packages/studio/src/timelineChromeExports.test.tsx b/packages/studio/src/timelineChromeExports.test.tsx
index 1fa3554787..c52f84edf0 100644
--- a/packages/studio/src/timelineChromeExports.test.tsx
+++ b/packages/studio/src/timelineChromeExports.test.tsx
@@ -6,6 +6,7 @@ import {
AudioMeterStrip,
TimelineHistoryButtons,
TimelineToolbar,
+ useAudioMetersVisible as exportedAudioMetersVisible,
useClipboard,
usePlayerStore,
type UseClipboardOptions,
@@ -51,6 +52,12 @@ describe("timeline chrome package exports, outside Studio's shell", () => {
await act(async () => root.unmount());
});
+ it("exports the meter visibility store a host toggles", () => {
+ expect(exportedAudioMetersVisible).toBe(useAudioMetersVisible);
+ exportedAudioMetersVisible.getState().setVisible(true);
+ expect(useAudioMetersVisible.getState().visible).toBe(true);
+ });
+
it("runs the clipboard with no DOM edit session", async () => {
const toasts: string[] = [];
const options: UseClipboardOptions = {
diff --git a/packages/studio/src/utils/previewRelativePath.ts b/packages/studio/src/utils/previewRelativePath.ts
new file mode 100644
index 0000000000..19a4c95436
--- /dev/null
+++ b/packages/studio/src/utils/previewRelativePath.ts
@@ -0,0 +1,19 @@
+import { buildProjectApiPath } from "./projectRouting";
+
+/** Resolve a media src to its project-relative preview path, or null. */
+export function resolvePreviewRelative(
+ src: string | undefined,
+ pid: string,
+ origin: string,
+): string | null {
+ if (!src) return null;
+ try {
+ const parsed = new URL(src, origin);
+ const base = new URL(buildProjectApiPath(pid, `/preview/`), origin).pathname;
+ return parsed.pathname.startsWith(base)
+ ? decodeURIComponent(parsed.pathname.slice(base.length))
+ : null;
+ } catch {
+ return null;
+ }
+}
diff --git a/packages/studio/vite.adapter.ts b/packages/studio/vite.adapter.ts
index 939f33aec7..76c1815de0 100644
--- a/packages/studio/vite.adapter.ts
+++ b/packages/studio/vite.adapter.ts
@@ -369,12 +369,17 @@ export function createViteAdapter(
removeCancelledOutput();
return;
}
+ if (job.audioLoweredDb !== undefined) state.audioLoweredDb = job.audioLoweredDb;
state.status = "complete";
state.progress = 100;
const metaPath = opts.outputPath.replace(/\.(mp4|webm|mov)$/, ".meta.json");
writeFileSync(
metaPath,
- JSON.stringify({ status: "complete", durationMs: Date.now() - startTime }),
+ JSON.stringify({
+ status: "complete",
+ durationMs: Date.now() - startTime,
+ ...(job.audioLoweredDb !== undefined ? { audioLoweredDb: job.audioLoweredDb } : {}),
+ }),
);
} catch (err) {
if (abortController.signal.aborted) {