Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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);
});
});