Files
hyperframes/packages/cli/src/commands/normalize-audio.test.ts
T
Michael WangandClaude Opus 5.5 870b1fa4dc fix(cli,studio-server): received-file guard covers subfolders and spellings; playlists named as media never reach ffmpeg (#7771)
* fix(cli): a subfolder of an imported project keeps its received-files record

Publish, cloud render and feedback now read the received-files record at
the nearest folder at or above the one they stage, so staging a subfolder
of an imported project still leaves out the outside files its received
files reference.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a received file counts under any spelling of the same file on disk

The received-files lookup now also matches a project file that is the
same file on disk as a listed path, so a name respelled in letter case on
a case-insensitive disk keeps its received status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): cloud render prepares only the GIFs staging kept

The entry GIF prep before a cloud render upload now reads only the staged
copies it is handed. An image whose source staging left out keeps its
reference as written and is never read from disk.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli,studio-server): never hand a playlist named as media to ffmpeg

A media file whose first bytes are an HLS playlist, an XML manifest or a
concat script now stays out of ffprobe and ffmpeg: cloud render leaves it
in the zip as authored, the media probe reports it as not media, and the
proxy copy refuses it. Real media never starts with these bytes, so it
probes and transcodes as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(studio-server): catch playlists with control bytes, and keep them from stills and audio probes

A text playlist or concat script is detected whatever bytes follow its
first line; only markup must be all text. A still frame and the audio
probe behind waveforms, peaks and loudness now refuse a file the probe
reads as not media, as the proxy copy already does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a parent folder's state the CLI cannot read never marks a project received

The walk up for a received-files record now skips a parent whose record
cannot be reached. Only a record file that is there but cannot be read
or parsed counts every file as received.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli): a drive that reports no file ids matches no received file by identity

Some network and virtual drives report a file id of 0 for every file, so
the same-file match now gives such a file no identity instead of
matching it to every listed file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(studio-server): read a media file's first bytes with a read stream

The playlist check reads the first 64 bytes through a bounded read
stream instead of a raw file descriptor, and the audio-track probe's doc
comment sits on its function again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* chore(studio-server): raise the packed size budget for the media playlist check

Main packs @hyperframes/studio-server close to the 1% tolerance on the
168500 budget, and the playlist check adds about 320 bytes, which put
the Build over. Set the budget to 172000.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli,studio-server): open media only through self-contained media demuxers

Every ffprobe and ffmpeg input that cloud render offload, the publish
proxy bake and Studio's media helpers open now carries a demuxer
whitelist built from the supported media extensions: MP4/MOV/M4A/AVIF,
Matroska/WebM, MXF, AVI, MPEG-PS/TS, FLV, ASF, Ogg, WAV, MP3, AAC, FLAC,
AIFF and the still-image formats. Playlist, manifest and concat demuxers
can no longer open, whatever a file's bytes say. The proxy's own concat
step is left as it is.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(cli,studio-server): keep media probe argv flat, and expect the demuxer list in loudness args

Two probe argv literals built from nested spreads are flat again, so
"--" stays the visible second-to-last entry the argv contract checks.
The normalize-audio test expects the demuxer list before the input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 00:33:29 +00:00

209 lines
8.5 KiB
TypeScript

import { resolve } from "node:path";
import { describe, expect, it } from "vitest";
import { MEDIA_INPUT_ARGS } from "@hyperframes/studio-server/outside-file";
import {
audioNormalizationPlan,
audioTags,
loudnessMeasureArgs,
parseEbur128Summary,
resolveLocalAudioPath,
updateAudioVolume,
} from "./normalize-audio.js";
const PROJECT = "/tmp/example-project";
describe("audioTags", () => {
it("reads quoted attributes without treating a quoted > as the end of the tag", () => {
const html = `<audio id='reference' title="a > b" src="assets/ref.mp4" data-volume="1"></audio>`;
expect(audioTags(html)).toEqual([
expect.objectContaining({ id: "reference", src: "assets/ref.mp4", volume: 1 }),
]);
});
it("rejects duplicate ids instead of normalizing an arbitrary element", () => {
const html = `<audio id="voice" src="a.wav"></audio><audio id="voice" src="b.wav"></audio>`;
expect(() => audioTags(html)).toThrow(/duplicate audio id "voice"/i);
});
it("ignores audio-like text in comments, scripts, and styles", () => {
const html = `
<!-- <audio id="comment" src="comment.wav"></audio> -->
<script>const example = '<audio id="script" src="script.wav"></audio>';</script>
<style>.demo::after { content: '<audio id="style" src="style.wav">'; }</style>
<audio id="real" src="real.wav"></audio>
`;
expect(audioTags(html).map((tag) => tag.id)).toEqual(["real"]);
});
it.each([
[`<audio id="bad" src="a.wav" data-volume="loud"></audio>`, /data-volume/i],
[`<audio id="bad" src="a.wav" data-media-start="-1"></audio>`, /data-media-start/i],
[`<audio id="bad" src="a.wav" data-duration="0"></audio>`, /data-duration/i],
])("rejects an invalid authored number", (html, expected) => {
expect(() => audioTags(html)).toThrow(expected);
});
it("measures only the window a data-end trim actually plays", () => {
// `data-end` is a first-class trim the parser, the runtime and the render
// mixer all honour. Measuring the whole source for one of these clips reads
// a loudness the composition never plays, and `--write` then "corrects" an
// already-matched clip by tens of dB.
const html = `<audio id="vo" src="vo.wav" data-start="4" data-end="8"></audio>`;
expect(audioTags(html)[0]).toEqual(expect.objectContaining({ duration: 4 }));
});
it("prefers an explicit data-duration over data-end", () => {
const html = `<audio id="vo" src="vo.wav" data-start="4" data-end="8" data-duration="3"></audio>`;
expect(audioTags(html)[0]).toEqual(expect.objectContaining({ duration: 3 }));
});
it("leaves an untrimmed clip unbounded", () => {
const html = `<audio id="vo" src="vo.wav" data-start="4"></audio>`;
expect(audioTags(html)[0]).toEqual(expect.objectContaining({ duration: null }));
});
it("ignores a data-end that does not outlast its start", () => {
const html = `<audio id="vo" src="vo.wav" data-start="8" data-end="4"></audio>`;
expect(audioTags(html)[0]).toEqual(expect.objectContaining({ duration: null }));
});
});
describe("loudnessMeasureArgs", () => {
it("bounds the INPUT, so the loudness filter never sees past the clip", () => {
// `-t` after `-i` bounds the output, and `-f null` has no output worth
// bounding: ffmpeg keeps feeding the graph and ebur128 integrates audio the
// clip never plays. Measured on a fixture whose played window is -61.8 LUFS,
// output-side `-t` reported -33.8.
const args = loudnessMeasureArgs("clip.wav", { mediaStart: 2, duration: 4 }, 0);
expect(args.indexOf("-ss")).toBeLessThan(args.indexOf("-i"));
expect(args.indexOf("-t")).toBeLessThan(args.indexOf("-i"));
expect(args.slice(args.indexOf("-ss"), args.indexOf("-i"))).toEqual([
"-ss",
"2",
"-t",
"4",
...MEDIA_INPUT_ARGS,
]);
});
it("leaves an untrimmed clip unbounded", () => {
const args = loudnessMeasureArgs("clip.wav", { mediaStart: 0, duration: null }, 0);
expect(args).not.toContain("-ss");
expect(args).not.toContain("-t");
});
});
describe("resolveLocalAudioPath", () => {
it("resolves a local source and strips query and fragment suffixes", () => {
expect(resolveLocalAudioPath(PROJECT, "assets/voice%20one.wav?v=2#clip")).toBe(
resolve(PROJECT, "assets/voice one.wav"),
);
});
it.each(["https://cdn.example.com/a.wav", "/etc/passwd", "../outside.wav", "data:x"])(
"rejects a non-project source: %s",
(src) => expect(() => resolveLocalAudioPath(PROJECT, src)).toThrow(/local project file/i),
);
});
describe("parseEbur128Summary", () => {
it("takes the final integrated loudness and true-peak summary", () => {
const stderr = `
[Parsed_ebur128_0] t: 1.0 I: -18.2 LUFS
[Parsed_ebur128_0] Summary:
Integrated loudness:
I: -15.5 LUFS
Threshold: -25.5 LUFS
True peak:
Peak: -3.2 dBFS
`;
expect(parseEbur128Summary(stderr)).toEqual({ integratedLufs: -15.5, truePeakDbfs: -3.2 });
});
it("fails when FFmpeg did not produce a usable summary", () => {
expect(() => parseEbur128Summary("no audio stream")).toThrow(/integrated loudness/i);
});
});
describe("audioNormalizationPlan", () => {
it("preserves the reference and attenuates the louder target", () => {
const plan = audioNormalizationPlan(
{ id: "target-audio", volume: 1, integratedLufs: -15.5, truePeakDbfs: -3.2 },
{ id: "user-audio", volume: 1, integratedLufs: -11.7, truePeakDbfs: -0.2 },
);
expect(plan.gainDb).toBeCloseTo(-3.8, 6);
expect(plan.volume).toBeCloseTo(0.645654, 5);
expect(plan.projectedLufs).toBeCloseTo(-15.5, 6);
expect(plan.projectedTruePeakDbfs).toBeCloseTo(-4, 6);
});
it("includes the reference's authored gain in the target", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 2, integratedLufs: -20, truePeakDbfs: -8 },
{ id: "target", volume: 0.5, integratedLufs: -18, truePeakDbfs: -6 },
);
expect(plan.referenceLufs).toBeCloseTo(-13.9794, 4);
expect(plan.volume).toBeCloseTo(1.588656, 6);
expect(plan.projectedLufs).toBeCloseTo(plan.referenceLufs, 6);
});
it("stops a boost at Studio's +12 dB ceiling and names it", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -5, truePeakDbfs: -1 },
{ id: "target", volume: 1, integratedLufs: -30, truePeakDbfs: -30 },
);
expect(plan.limitedBy).toBe("gain-ceiling");
expect(plan.gainDb).toBeCloseTo(12, 6);
expect(plan.projectedLufs).toBeCloseTo(-18, 6);
});
it("stops a boost that would pass -1.5 dBTP there, as the absolute target does", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -10, truePeakDbfs: -1 },
{ id: "target", volume: 1, integratedLufs: -15, truePeakDbfs: -2 },
);
expect(plan.limitedBy).toBe("true-peak");
expect(plan.gainDb).toBeCloseTo(0.5, 6);
expect(plan.projectedTruePeakDbfs).toBeCloseTo(-1.5, 6);
expect(plan.referenceLufs - plan.projectedLufs).toBeCloseTo(4.5, 6);
});
it("names no limit when the match fits", () => {
const plan = audioNormalizationPlan(
{ id: "reference", volume: 1, integratedLufs: -15.5, truePeakDbfs: -3.2 },
{ id: "target", volume: 1, integratedLufs: -11.7, truePeakDbfs: -0.2 },
);
expect(plan.limitedBy).toBeNull();
});
});
describe("updateAudioVolume", () => {
it("updates only the selected audio element and preserves surrounding source", () => {
const html = `<!doctype html>\n<audio id="ref" src="a.wav" data-volume="1"></audio>\n<audio data-volume='1' id='target' src='b.wav'></audio>\n`;
expect(updateAudioVolume(html, "target", 0.645654)).toBe(
`<!doctype html>\n<audio id="ref" src="a.wav" data-volume="1"></audio>\n<audio data-volume='0.645654' id='target' src='b.wav'></audio>\n`,
);
});
it("adds data-volume when it is absent", () => {
expect(updateAudioVolume(`<audio id="target" src="b.wav" />`, "target", 2)).toBe(
`<audio id="target" src="b.wav" data-volume="2" />`,
);
});
});
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>`,
);
});
});