Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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.tsindex 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): AudioTaginterface 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<Normalizereturn { 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.tsindex 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.tsindex 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 bediff --git a/packages/producer/src/services/render/audioPadTrim.test.ts b/packages/producer/src/services/render/audioPadTrim.test.tsindex 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.tsindex 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.tsindex 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.tsindex 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<Assemif (!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.tsindex 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.jsonindex 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.jsonindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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): voidstatus: 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): voidconst 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): voidcreatedAt: 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.tsindex 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 (thediff --git a/packages/studio-server/tsup.config.ts b/packages/studio-server/tsup.config.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 sourcediff --git a/packages/studio/src/index.ts b/packages/studio/src/index.tsindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsnew file mode 100644index 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.tsindex 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) {