mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 16:08:56 +00:00
* feat(audio): composition master bus (data-fx-chain on the root) A clip can belong to only one audio group, so there was no way to put one effect, such as a limiter, across the whole mix. The data-fx-chain on the top-level composition root now runs once over the sum of every clip and every group, after each group's own chain and fader. No new attribute: a sub-composition root's data-fx-chain was never applied to anything and still is not. Render: when a master chain exists, mixAudioTracks writes a float WAV instead of AAC, applyAudioFxChain runs the chain over it, and ffmpeg encodes AAC last, so the chain reads unclipped samples. An unreadable chain is a mix failure, as for a group. Preview: the transport splices the chain between the clips' sum and the monitor, re-anchored per play generation and watched for edits. Only the top-level root is read. No master automation: the root's data-automation is not read as the bus's. No lint rule: data-fx-chain is valid on clips, groups and roots, and the one place it does nothing (a sub-composition root) has always been silent. — Jerrai * fix(core): preview routes every audible video through the master bus A root data-fx-chain is attached only inside the Web Audio graph, but a plainly audible <video> joined that graph only for its own chain, group, automation or a volume over 1. So preview limited the music and left the talking head dry, and a composition whose only audio is video got no master chain at all, while export sums every audible element into the master. A master chain on the top-level composition root is now a reason to join, the same as a video's own chain. Elements under a root with no chain keep native output. Sub-composition roots are still ignored. — Jerrai * fix(audio): master bus review round 2 (temp dir, tests, docs, Studio meter) - audioMixer: a fatal FX error in the master pass or a group bus left the work directory (the full float sum, about 1.4 GB an hour) on disk. The final mix now runs in try/finally and the group rethrow removes it first. - Tests: the "once over the sum" case now uses a limiter then a gain, so a per-clip chain (-10.4) and a doubled one (-18) both fail it; a new case proves the sum stays float until the chain reads it; the fader case uses a group volume of 0.5 so the fader's position is exercised; the work-dir removal is covered for both paths. - Docs: "Three rules exist" (the master-bus lint rule is gone), a bad master chain stops the render with audio_processing_failed, a sub-composition file opened on its own has its root chain as the master bus, and a seek clears a group or master limiter. - Studio: TimelineElement.masterChain carries the root's data-fx-chain, so the program meter shows for a video-only composition whose only audio routing is the master chain, as preview now plays it. - Comment blocks over four lines cut; webAudioTransport.setRate split so its CRAP score is under the Fallow threshold. — Jerrai * fix(audio): master chain reaches tracks the render adds; honest plain-limiter copy - Master chain: it was carried on each parsed AudioElement, so a track the producer adds itself (appendAutoDetectedVideoAudio, the browser-discovered audio in probeStage) never had it, and a composition whose only audio was such a track exported with no master chain, no ceiling and no warning. It is now a composition property: parseMasterFxChain(html) at compile, carried on CompiledComposition and CompositionMetadata, passed to processCompositionAudio by runAudioStage (in-process and distributed plan). AudioElement.masterFxChain is removed so there is one source. Each forward (compile stage, local orchestrator, distributed plan) has a test that fails when it is dropped. - Plain limiter: it follows the level with no lookahead and Level after is applied past the ceiling, so it cannot promise "nothing gets past" or "never clips". Studio copy (description, panel text, knob label, summary) and the hyperframes-audio skill now say a fast or inter-sample peak can pass it and point to the true-peak limiter for a delivery limit. A copy test guards it. — Jerrai * fix(producer): keep master bus comments within the ratchet; run the plan test with the ffmpeg tests Drop three one-line field comments that raised their files' comment share, and list plan.masterBus.test.ts with the integration tests because plan() reads the ffmpeg version. — Jerrai * chore(ci): repin the producer test-classification source in the reachability map The reachability map pins the hash of test-classification.mjs, which now lists one more integration test. The map's producer lane command already covers every test under src, in both the unit and integration matrix lanes. — Jerrai
222 lines
9.7 KiB
TypeScript
222 lines
9.7 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import { defaultAudioFxParams, getAudioFxDef, HF_AUDIO_FX } from "./audioFx.js";
|
|
import { HF_AUDIO_FX_PRESETS } from "./audioFxPresets.js";
|
|
import { audioBandAt, BANDS, EFFECT_COPY, PRESET_PROBLEM, SUMMARY } from "./audioFxCopy.js";
|
|
|
|
/**
|
|
* The copy layer is only worth having if it covers everything that ships. A gap
|
|
* is not a missing nicety — it is a rack panel labelled `highpass` in front of
|
|
* somebody who came here to stop a hum, which is the exact failure this layer
|
|
* exists to prevent.
|
|
*
|
|
* This was a build step in `plans/audio-fx-ux/build-preview.mts`, which meant it
|
|
* only caught a gap when somebody remembered to rebuild the review page. Here it
|
|
* catches it on the commit that adds the effect.
|
|
*/
|
|
describe("every shipped effect has plain-language copy", () => {
|
|
for (const def of HF_AUDIO_FX) {
|
|
it(`${def.id}`, () => {
|
|
const copy = EFFECT_COPY[def.id];
|
|
expect(copy, `${def.id} has no copy`).toBeDefined();
|
|
if (!copy) return;
|
|
for (const param of def.params) {
|
|
expect(copy.params[param.key], `${def.id}.${param.key} has no plain name`).toBeDefined();
|
|
}
|
|
// "strength" is the one legal fiction: it means the module gets a single
|
|
// derived knob and its real parameters live behind Details. Anything else
|
|
// has to name a parameter the effect actually has, or the panel would put
|
|
// its headline control on a knob that does not exist.
|
|
if (copy.primary !== "strength") {
|
|
expect(
|
|
def.params.map((p) => p.key),
|
|
`${def.id}'s primary "${copy.primary}" is not one of its parameters`,
|
|
).toContain(copy.primary);
|
|
}
|
|
expect(SUMMARY[def.id], `${def.id} has no closed-state summary`).toBeDefined();
|
|
});
|
|
}
|
|
});
|
|
|
|
it("every preset says which everyday problem it answers", () => {
|
|
const missing = HF_AUDIO_FX_PRESETS.filter((p) => !PRESET_PROBLEM[p.id]).map((p) => p.id);
|
|
expect(missing).toEqual([]);
|
|
});
|
|
|
|
it("describes no effect the registry does not ship", () => {
|
|
const shipped = new Set(HF_AUDIO_FX.map((d) => d.id));
|
|
// The other direction. Copy for an effect that has been removed or renamed is
|
|
// dead text that reads as covered, and the count in the review page would say
|
|
// so too.
|
|
expect(Object.keys(EFFECT_COPY).filter((id) => !shipped.has(id))).toEqual([]);
|
|
expect(Object.keys(SUMMARY).filter((id) => !shipped.has(id))).toEqual([]);
|
|
});
|
|
|
|
it("summarises every effect at its own defaults without throwing", () => {
|
|
for (const def of HF_AUDIO_FX) {
|
|
const summary = SUMMARY[def.id];
|
|
if (!summary) continue;
|
|
// The first thing an author reads after adding an effect, so it has to be a
|
|
// sentence at the values it arrives with — not "undefined dB".
|
|
const text = summary(defaultAudioFxParams(def.id));
|
|
expect(text, `${def.id} summarised as "${text}"`).toMatch(/^[^u].*[^ ]$/);
|
|
expect(text).not.toContain("undefined");
|
|
expect(text).not.toContain("NaN");
|
|
}
|
|
});
|
|
|
|
it("covers the spectrum without a gap or an overlap", () => {
|
|
// The ruler is shared by every spectral module, so a hole in it is a frequency
|
|
// the rack can name in one place and not in another.
|
|
expect(BANDS[0]?.from).toBe(20);
|
|
expect(BANDS.at(-1)?.to).toBe(20000);
|
|
for (let i = 1; i < BANDS.length; i++) {
|
|
expect(BANDS[i]?.from, `gap or overlap before ${BANDS[i]?.name}`).toBe(BANDS[i - 1]?.to);
|
|
}
|
|
});
|
|
|
|
describe("audioBandAt", () => {
|
|
it("names the range a frequency sits in", () => {
|
|
expect(audioBandAt(50)?.name).toBe("Rumble");
|
|
expect(audioBandAt(250)?.name).toBe("Mud");
|
|
expect(audioBandAt(3000)?.name).toBe("Presence");
|
|
expect(audioBandAt(12000)?.name).toBe("Air");
|
|
});
|
|
|
|
it("puts a boundary in the band it opens, not the one it closes", () => {
|
|
// Off by one here means a filter at exactly 250 Hz reads as "Weight" while
|
|
// the ruler beside it highlights Mud.
|
|
for (let i = 1; i < BANDS.length; i++) {
|
|
const edge = BANDS[i]?.from;
|
|
if (edge === undefined) continue;
|
|
expect(audioBandAt(edge)?.name).toBe(BANDS[i]?.name);
|
|
}
|
|
});
|
|
|
|
it("clamps past both ends rather than going nameless", () => {
|
|
// A filter parked at the edge of its range still has to say where it works.
|
|
expect(audioBandAt(5)?.name).toBe(BANDS[0]?.name);
|
|
expect(audioBandAt(30000)?.name).toBe(BANDS.at(-1)?.name);
|
|
expect(audioBandAt(20000)?.name).toBe(BANDS.at(-1)?.name);
|
|
});
|
|
|
|
it("has no answer for a value that is not a frequency", () => {
|
|
expect(audioBandAt(Number.NaN)).toBeUndefined();
|
|
});
|
|
});
|
|
|
|
/**
|
|
* Copy that assumes the track is a voice.
|
|
*
|
|
* The rack sits on whatever the author selected — a music bed, a sound effect,
|
|
* a room tone. Every effect, every named job and every profile is offered on
|
|
* all of them, so a control that reads "Thins the voice out" on a synth pad is
|
|
* describing something the author cannot hear and does not have. It is the same
|
|
* rule this file's header already states — describe a control by what changes in
|
|
* THE SOUND — applied to the words rather than to the mechanism.
|
|
*
|
|
* The voice presets are the deliberate exception: they are voice by definition,
|
|
* and the shelf hides them on a track that classifies as music or as an effect,
|
|
* so "My voice sounds amateur" is only ever read next to a voice.
|
|
*
|
|
* This is a lint on the words, not a judgement about mixing. It exists because
|
|
* the offending strings were written one at a time over months and read fine in
|
|
* isolation — nobody notices the assumption until they apply Cut Rumble to a
|
|
* bass line and the panel tells them it will thin their voice out.
|
|
*/
|
|
describe("no copy assumes the track is a voice", () => {
|
|
/** Words that only mean something if the material is speech. */
|
|
const SPEECH =
|
|
/\b(voice|vocal|voices|speech|spoken|word|words|sentence|sentences|syllable|syllables|narration|narrator|talking|chest)\b/i;
|
|
|
|
/** Presets whose whole purpose is a voice, so their copy may say so. */
|
|
const VOICE_PRESETS = new Set(
|
|
HF_AUDIO_FX_PRESETS.filter((p) => p.family === "voice").map((p) => p.id),
|
|
);
|
|
|
|
const offenders = (entries: [string, string][]): string[] =>
|
|
entries.filter(([, text]) => SPEECH.test(text)).map(([where, text]) => `${where}: "${text}"`);
|
|
|
|
it("not in an effect's name, blurb, reach-for line or any knob", () => {
|
|
const entries: [string, string][] = [];
|
|
for (const [id, copy] of Object.entries(EFFECT_COPY)) {
|
|
entries.push([`${id}.title`, copy.title], [`${id}.does`, copy.does]);
|
|
entries.push([`${id}.reachFor`, copy.reachFor]);
|
|
entries.push([`${id}.primaryEnds.low`, copy.primaryEnds.low]);
|
|
entries.push([`${id}.primaryEnds.high`, copy.primaryEnds.high]);
|
|
for (const [key, param] of Object.entries(copy.params)) {
|
|
entries.push([`${id}.${key}.label`, param.label]);
|
|
if (param.hint) entries.push([`${id}.${key}.hint`, param.hint]);
|
|
if (param.ends) {
|
|
entries.push([`${id}.${key}.ends.low`, param.ends.low]);
|
|
entries.push([`${id}.${key}.ends.high`, param.ends.high]);
|
|
}
|
|
}
|
|
}
|
|
expect(offenders(entries)).toEqual([]);
|
|
});
|
|
|
|
it("not in the band vocabulary, which every spectral module shares", () => {
|
|
// These names get taught once and then reused everywhere, so a voice-only
|
|
// word here spreads to every filter in the rack.
|
|
expect(offenders(BANDS.map((b) => [b.name, b.says]))).toEqual([]);
|
|
});
|
|
|
|
it("not in the complaint a non-voice preset answers", () => {
|
|
const entries = Object.entries(PRESET_PROBLEM).filter(([id]) => !VOICE_PRESETS.has(id));
|
|
expect(offenders(entries as [string, string][])).toEqual([]);
|
|
});
|
|
|
|
it("still lets the voice presets say what they are for", () => {
|
|
// The exception has to be real, or the rule above is untested — a catalogue
|
|
// where nothing said "voice" would pass every assertion here vacuously.
|
|
const voiced = Object.entries(PRESET_PROBLEM).filter(([id]) => VOICE_PRESETS.has(id));
|
|
expect(voiced.length).toBeGreaterThan(0);
|
|
expect(voiced.some(([, text]) => SPEECH.test(text))).toBe(true);
|
|
});
|
|
});
|
|
|
|
/** Everything Studio shows for the true-peak limiter, and the ceiling knob's hint. */
|
|
function truePeakCopy(): { shown: string; hint: string } {
|
|
const copy = EFFECT_COPY.truepeak;
|
|
const ceiling = copy?.params.ceiling;
|
|
const summary = SUMMARY.truepeak;
|
|
if (!copy || !ceiling?.hint || !summary) throw new Error("truepeak copy is missing");
|
|
const shown = [copy.does, copy.reachFor, ceiling.label, ceiling.hint, summary({})];
|
|
return { shown: shown.join("\n"), hint: ceiling.hint };
|
|
}
|
|
|
|
describe("the true-peak copy does not promise a hard ceiling", () => {
|
|
it("never says never or must-not-clip", () => {
|
|
expect(truePeakCopy().shown).not.toMatch(/never exceed|must not clip|never above|guarantee/i);
|
|
});
|
|
|
|
it("tells the author about the 4x estimate and the headroom to leave", () => {
|
|
const { hint } = truePeakCopy();
|
|
expect(hint).toMatch(/4x/);
|
|
expect(hint).toMatch(/1\.7 dB/);
|
|
expect(hint).toMatch(/headroom/);
|
|
});
|
|
});
|
|
|
|
describe("the plain limiter copy does not promise a hard ceiling", () => {
|
|
// The limiter follows the signal's level with no lookahead, and Level after is applied past
|
|
// the ceiling, so a fast or inter-sample peak can end above it.
|
|
it("says nothing about never clipping or nothing getting past", () => {
|
|
const copy = EFFECT_COPY.limiter;
|
|
const summary = SUMMARY.limiter;
|
|
const description = getAudioFxDef("limiter")?.description;
|
|
if (!copy || !summary || !description) throw new Error("limiter copy is missing");
|
|
const shown = [
|
|
description,
|
|
copy.does,
|
|
copy.reachFor,
|
|
copy.params.limit?.label,
|
|
summary({}),
|
|
].join("\n");
|
|
expect(shown).not.toMatch(
|
|
/never|nothing|guarantee|hard ceiling|no louder|must not|cannot exceed/i,
|
|
);
|
|
expect(shown).toMatch(/can (still )?(get )?pass|get past/i);
|
|
});
|
|
});
|