Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
import { describe, expect, it } from "vitest";
import { MAX_AUTOMATION_POINTS, sampleAutomationLane } from "./audioAutomation.js";
import {
analyseCarveBands,
analyseCarveDuck,
analyseCarveDynamics,
carveBandsToChain,
carveProfile,
classifyAudioName,
clipsOverlap,
mixCarveSources,
couldBeCarveSource,
couldBeCarveBed,
isNamedCarveBed,
DEFAULT_CARVE,
normalizeCarveSettings,
} from "./audioCarve.js";
/** The profile the panel's default strength produces — what the separate controls defaulted to. */
const PROFILE = carveProfile(DEFAULT_CARVE.strength);
const SR = 48000;
/** A tone-plus-harmonics stand-in for a voice, centred on `f0`. */
function voiceLike(f0: number, seconds = 0.5): Float32Array {
const n = Math.floor(SR * seconds);
const out = new Float32Array(n);
for (let i = 0; i < n; i++) {
const t = i / SR;
out[i] =
0.6 * Math.sin(2 * Math.PI * f0 * t) +
0.3 * Math.sin(2 * Math.PI * f0 * 2 * t) +
0.1 * Math.sin(2 * Math.PI * f0 * 3 * t);
}
return out;
}
describe("normalizeCarveSettings", () => {
it("fills defaults and clamps nonsense", () => {
expect(normalizeCarveSettings(undefined)).toEqual(DEFAULT_CARVE);
expect(normalizeCarveSettings({ strength: 40 }).strength).toBe(1);
expect(normalizeCarveSettings({ strength: -3 }).strength).toBe(0);
expect(normalizeCarveSettings({ strength: Number.NaN }).strength).toBe(DEFAULT_CARVE.strength);
});
it("reads a carve written before the controls collapsed into one", () => {
// Depth is the number that said most about intent, so it maps back onto the
// strength that reproduces it rather than being dropped.
expect(normalizeCarveSettings({ maxCutDb: 6, bands: 3, q: 1.4 }).strength).toBe(0.25);
expect(carveProfile(normalizeCarveSettings({ maxCutDb: 6 }).strength).maxCutDb).toBe(6);
expect(normalizeCarveSettings({ maxCutDb: 10 }).strength).toBe(0.5);
expect(normalizeCarveSettings({ maxCutDb: 24 }).strength).toBe(1);
});
it("keeps an explicit strength over a legacy depth", () => {
expect(normalizeCarveSettings({ strength: 0.25, maxCutDb: 10 }).strength).toBe(0.25);
});
});
describe("carveProfile", () => {
it("lands on the old defaults at the strength the panel starts at", () => {
// The separate controls shipped 6 dB, 3 bands, Q 1.4, bias 0.7, and the duck
// pair defaulted to 6/9 — a project carved before the collapse must sound the
// same after it. That point is a quarter of the way up, since the knob's range
// was later doubled above it.
expect(DEFAULT_CARVE.strength).toBe(0.25);
expect(PROFILE).toEqual({
maxCutDb: 6,
bands: 3,
q: 1.4,
intelligibilityBias: 0.7,
duckDb: 6,
headroomDb: 9,
});
});
it("moves every number the same direction, monotonically", () => {
const steps = [0, 0.25, 0.5, 0.75, 1].map(carveProfile);
for (let i = 1; i < steps.length; i++) {
const a = steps[i - 1]!;
const b = steps[i]!;
expect(b.maxCutDb).toBeGreaterThan(a.maxCutDb);
expect(b.bands).toBeGreaterThanOrEqual(a.bands);
expect(b.q).toBeGreaterThan(a.q);
expect(b.duckDb).toBeGreaterThan(a.duckDb);
expect(b.headroomDb).toBeGreaterThan(a.headroomDb);
}
});
it("carves frequencies only at zero, and goes hard at the top", () => {
expect(carveProfile(0).duckDb).toBe(0);
expect(carveProfile(0).bands).toBe(1);
expect(carveProfile(1).maxCutDb).toBe(18);
expect(carveProfile(1).bands).toBe(6);
expect(carveProfile(1).duckDb).toBe(24);
// The bias is a 0..1 weight, so the top of the knob is all the way over
// rather than past it.
expect(carveProfile(1).intelligibilityBias).toBe(1);
});
it("puts the old top of the knob at the halfway mark", () => {
// The range was doubled because full strength could not sit a bed under a
// loud voice. Everything the knob used to reach is now the bottom half.
expect(carveProfile(0.5)).toEqual({
maxCutDb: 10,
bands: 4,
q: 1.7,
intelligibilityBias: 0.8,
duckDb: 12,
headroomDb: 12,
});
});
it("clamps a strength outside the knob's own range", () => {
expect(carveProfile(9)).toEqual(carveProfile(1));
expect(carveProfile(-9)).toEqual(carveProfile(0));
});
});
describe("analyseCarveBands", () => {
it("returns nothing for silence-length input", () => {
expect(analyseCarveBands(new Float32Array(0), SR, PROFILE)).toEqual([]);
});
it("returns the requested number of bands, ascending, all cuts", () => {
const bands = analyseCarveBands(voiceLike(250), SR, { ...PROFILE, bands: 3 });
expect(bands).toHaveLength(3);
expect(bands.map((b) => b.freq)).toEqual([...bands.map((b) => b.freq)].sort((a, b) => a - b));
for (const b of bands) expect(b.gainDb).toBeLessThan(0);
});
it("never cuts deeper than the configured maximum", () => {
const bands = analyseCarveBands(voiceLike(400), SR, { ...PROFILE, maxCutDb: 5 });
for (const b of bands) expect(Math.abs(b.gainDb)).toBeLessThanOrEqual(5);
});
it("follows raw voice power when the bias is off", () => {
// With no bias, a low-pitched voice should select its own fundamental
// region — this is the behaviour that makes an unbiased carve thin the bed
// rather than unmask the voice.
const bands = analyseCarveBands(voiceLike(160), SR, {
...DEFAULT_CARVE,
bands: 1,
intelligibilityBias: 0,
});
expect(bands[0]!.freq).toBeLessThanOrEqual(400);
});
it("moves selection upward when the bias is on", () => {
// The bias reweights ranking, it does not override the spectrum: a band the
// voice has no energy in is not worth carving. So the guarantee is that
// biasing never selects *lower* than the unbiased ranking, and lifts it
// whenever there is competing energy up top to select.
const broadband = (() => {
const n = Math.floor(SR * 0.5);
const out = new Float32Array(n);
for (let i = 0; i < n; i++) {
const t = i / SR;
out[i] =
0.5 * Math.sin(2 * Math.PI * 160 * t) +
0.45 * Math.sin(2 * Math.PI * 1000 * t) +
0.4 * Math.sin(2 * Math.PI * 2500 * t);
}
return out;
})();
const flat = analyseCarveBands(broadband, SR, {
...DEFAULT_CARVE,
bands: 1,
intelligibilityBias: 0,
});
const biased = analyseCarveBands(broadband, SR, {
...DEFAULT_CARVE,
bands: 1,
intelligibilityBias: 1,
});
expect(biased[0]!.freq).toBeGreaterThanOrEqual(flat[0]!.freq);
expect(biased[0]!.freq).toBeGreaterThanOrEqual(1000);
});
/**
* A voice with the spectral tilt real speech has: energy falls off about 6 dB
* per octave above the fundamental, so the low bands carry 20-30 dB more power
* than the presence region. `broadband` above spreads its three tones over
* roughly 2 dB, which is why it cannot tell a working bias from an inert one.
*/
function tiltedVoice(f0 = 120, seconds = 0.5): Float32Array {
const n = Math.floor(SR * seconds);
const out = new Float32Array(n);
for (let i = 0; i < n; i++) {
const t = i / SR;
let v = 0;
// Harmonics out past 6 kHz, each 6 dB/octave down, so every candidate band
// has real energy to rank and the ranking is decided by the weighting
// rather than by which band happens to be the only one occupied.
for (let h = 1; h * f0 < SR / 2 && h <= 64; h++) {
v += (1 / h) * Math.sin(2 * Math.PI * f0 * h * t);
}
out[i] = 0.5 * v;
}
return out;
}
it("reaches the presence region at the default bias, not just at bias 1", () => {
// The point of the feature: dip the bed where the voice is MASKED, 1-3 kHz,
// not where the voice is loudest. DEFAULT_CARVE is what a user gets from
// clicking "Analyse and apply", so the default has to do this — a knob that
// only works at its extreme does not work.
const bands = analyseCarveBands(tiltedVoice(), SR, { ...PROFILE, bands: 3 });
expect(bands.map((b) => b.freq).some((f) => f >= 1000)).toBe(true);
});
it("gives the bias enough authority to cross a speech-sized tilt", () => {
// The authority, stated in the unit that decides it: a multiplicative weight
// bounded below by (1 - bias) can move a ranking by at most
// 10*log10(1/(1 - bias)) — 5.2 dB at the 0.7 default. Speech tilts 20-30 dB.
//
// Two tones, the low one 9 dB louder, both on candidate centres (the bands
// are a third of an octave wide but their centres step about two thirds
// apart, so a tone between two of them — 2 kHz, say — falls in a gap and is
// invisible to the analysis). Raw power says 250 Hz; the default bias has to
// be able to say 1.6 kHz anyway.
//
// 9 dB rather than the 21 dB the bias nominally carries at 0.7: a lone tone
// is diluted by `bandPower` averaging across the band's bins, and the 1.6 kHz
// band spans about six times as many bins as the 250 Hz one, which costs
// roughly 8 dB. Broadband content — a real voice — fills both and keeps it.
const twoTone = (() => {
const n = Math.floor(SR * 0.5);
const out = new Float32Array(n);
const quiet = Math.pow(10, -9 / 20);
for (let i = 0; i < n; i++) {
const t = i / SR;
out[i] =
0.5 * Math.sin(2 * Math.PI * 250 * t) + 0.5 * quiet * Math.sin(2 * Math.PI * 1600 * t);
}
return out;
})();
const one = { ...PROFILE, bands: 1 };
expect(analyseCarveBands(twoTone, SR, { ...one, intelligibilityBias: 0 })[0]!.freq).toBe(250);
expect(analyseCarveBands(twoTone, SR, one)[0]!.freq).toBe(1600);
});
it("still follows raw power exactly when the bias is off", () => {
// The escape hatch keeps working: at bias 0 selection is the voice's own
// loudest band, whatever the weighting curve would have preferred.
const bands = analyseCarveBands(tiltedVoice(), SR, {
...DEFAULT_CARVE,
bands: 1,
intelligibilityBias: 0,
});
expect(bands[0]!.freq).toBeLessThanOrEqual(400);
});
});
/**
* Both analysis loops reuse one pair of FFT scratch arrays across every window
* rather than allocating a pair per hop — a 5-minute 48 kHz voiceover is ~7000
* hops, so ~460 MB of transient Float64Array used to churn through the main
* thread for one carve. `re` is fully overwritten each window, but `im` is only
* ever added to, so it has to be cleared; missing that, the imaginary part
* accumulates across windows and every spectrum after the first is wrong by a
* growing amount.
*/
describe("reused FFT scratch across windows", () => {
/** A steady tone on an exact bin centre (48000/4096 x 128), so every window is identical. */
const steady = (seconds: number): Float32Array => {
const n = Math.floor(SR * seconds);
const out = new Float32Array(n);
for (let i = 0; i < n; i++) out[i] = 0.5 * Math.sin((2 * Math.PI * 1500 * i) / SR);
return out;
};
it("measures the same bands however many windows the clip has", () => {
// Every window carries the same spectrum, so the Welch average cannot
// depend on how many were averaged — unless one window is contaminating
// the next.
const short = analyseCarveBands(steady(0.5), SR, PROFILE);
const long = analyseCarveBands(steady(12), SR, PROFILE);
expect(short.length).toBeGreaterThan(0);
expect(long).toEqual(short);
});
it("keeps a steady tone's dynamics envelope flat instead of drifting", () => {
const [lane] = analyseCarveDynamics(steady(12), SR, [{ freq: 1600, gainDb: -8, q: 1.4 }]);
const value = (t: number): number =>
sampleAutomationLane({ target: "fx.n1.gain", points: lane!.points }, t);
// Past the attack the cut has to sit still, because the signal does. A
// window contaminated by the one before it grows the measured power over
// the clip, and the envelope — which is relative to the band's own peak —
// slides with it.
expect(value(4)).toBeLessThan(-1);
expect(value(8)).toBeCloseTo(value(4), 0);
expect(value(11)).toBeCloseTo(value(4), 0);
});
});
describe("carveBandsToChain", () => {
it("turns bands into peaking nodes carrying the analysed values", () => {
const chain = carveBandsToChain([{ freq: 1000, gainDb: -6, q: 1.4 }]);
expect(chain.nodes).toHaveLength(1);
expect(chain.nodes[0]!.type).toBe("peaking");
expect(chain.nodes[0]!.params).toMatchObject({ frequency: 1000, gain: -6, q: 1.4 });
});
it("produces an empty chain for no bands", () => {
expect(carveBandsToChain([]).nodes).toEqual([]);
});
});
describe("analyseCarveDuck", () => {
const SR8 = 8000;
/** Steady tone at a given amplitude — stands in for a bed or a voice. */
function tone(amp: number, seconds: number, f = 300, sr = SR8): Float32Array {
const out = new Float32Array(Math.floor(sr * seconds));
for (let i = 0; i < out.length; i++) out[i] = amp * Math.sin(2 * Math.PI * f * (i / sr));
return out;
}
/** Silence, then speech-level tone, then silence. */
function voiceWithPause(amp: number, seconds: number, from: number, to: number): Float32Array {
const out = new Float32Array(Math.floor(SR8 * seconds));
for (let i = 0; i < out.length; i++) {
const t = i / SR8;
out[i] = t >= from && t < to ? amp * Math.sin(2 * Math.PI * 700 * t) : 0;
}
return out;
}
const at = (points: { t: number; v: number }[], t: number): number =>
sampleAutomationLane({ target: "fx.n1.gain", points }, t);
const settings = (over: Partial<typeof PROFILE> = {}) => ({
...PROFILE,
duckDb: 12,
headroomDb: 9,
...over,
});
it("leaves the bed alone where the voice is silent", () => {
// The whole point of a follower: no voice, nothing to make room for. Before
// the first word it is exactly flat; afterwards it eases back rather than
// snapping, so the tail is checked by the release cases below.
const duck = analyseCarveDuck(voiceWithPause(0.5, 16, 3, 6), tone(0.5, 16), SR8, settings(), 0);
expect(at(duck, 1)).toBe(0);
// A window is half a second wide and its value is stamped at its centre, so
// the duck begins up to half a window before the first word — checked clear
// of that rather than right against it.
expect(at(duck, 2)).toBe(0);
// Back to inaudible by the end of a long tail rather than held down for the
// clip; the envelope's last point is pinned at exactly no cut. Ten seconds
// after the last word is four release constants, so the residue has snapped.
expect(at(duck, 15.9)).toBeCloseTo(0, 1);
expect(duck.at(-1)?.v).toBe(0);
});
it("ducks a loud bed under a quiet voice", () => {
// Bed 12 dB above the voice with 9 dB of headroom asked for: the bed has to
// come down by about 21 dB, which the cap holds at 12.
const duck = analyseCarveDuck(
voiceWithPause(0.12, 8, 2, 7),
tone(0.5, 8),
SR8,
settings({ duckDb: 24 }),
0,
);
expect(at(duck, 4.5)).toBeLessThan(-15);
});
it("barely touches a bed already sitting under the voice", () => {
const duck = analyseCarveDuck(voiceWithPause(0.8, 8, 2, 7), tone(0.05, 8), SR8, settings(), 0);
expect(at(duck, 4.5)).toBeGreaterThan(-1);
});
it("lets the bed come back slowly after the voice stops", () => {
// A bed that jumps back to full the instant a word ends is heard as the
// effect switching off. It has to ease back over seconds — and the envelope's
// own step is ~0.3s on a long voice, so a release near that lands the whole
// recovery inside one step, which is exactly the flip this pins against.
const voice = voiceWithPause(0.5, 14, 2, 6);
const duck = analyseCarveDuck(voice, tone(0.5, 14), SR8, settings({ duckDb: 12 }), 0);
const atSpeech = at(duck, 5.5);
expect(atSpeech).toBeLessThan(-6);
// Still most of the way down a third of a second after the last word...
expect(at(duck, 6.3)).toBeLessThan(atSpeech * 0.6);
// Three seconds past the last word the bed is still audibly down — at a 1.6s
// release it is all but back (−1.5 dB), which is the sentence-break flip this
// constant exists to stop. This is the point that reds on the old value.
expect(at(duck, 9)).toBeLessThan(-2);
// ...noticeably recovered two and a half seconds on...
expect(at(duck, 8.5)).toBeGreaterThan(atSpeech * 0.5);
// ...and within a hair of flat several seconds later, rather than held down.
expect(at(duck, 13.5)).toBeGreaterThan(-0.6);
});
it("finishes the release past the last word instead of snapping at the end", () => {
// A lane's last point has to be no cut, or the bed stays dipped for the rest
// of the clip. Jumping there from full duck is the same flip the slow release
// exists to prevent, just moved to the end of the narration — so the envelope
// keeps decaying past the voice and pins once it is inaudible.
const voice = voiceWithPause(0.5, 8, 1, 7.9);
const duck = analyseCarveDuck(voice, tone(0.5, 12), SR8, settings({ duckDb: 12 }), 0);
const steps = duck.slice(1).map((p, i) => Math.abs(p.v - duck[i]!.v));
expect(Math.max(...steps.slice(-4))).toBeLessThan(2);
// Still ducked a moment after the voice stops, and flat well after.
expect(at(duck, 8.2)).toBeLessThan(-2);
expect(duck.at(-1)?.v).toBe(0);
expect(duck.at(-1)!.t).toBeGreaterThan(8);
});
it("comes back up more slowly than it ducks", () => {
// Asymmetric on purpose: the cut has to be there by the time a word is
// audible, and gone slowly enough that the bed does not pump between
// sentences.
const voice = voiceWithPause(0.5, 14, 4, 8);
const duck = analyseCarveDuck(voice, tone(0.5, 14), SR8, settings({ duckDb: 12 }), 0);
const floor = Math.min(...duck.map((p) => p.v));
const toHalfDown = duck.find((p) => p.v <= floor * 0.5)?.t ?? Infinity;
const backToHalfUp =
[...duck].reverse().find((p) => p.v <= floor * 0.5)?.t ?? Number.NEGATIVE_INFINITY;
const attackSpan = toHalfDown - 4;
const releaseSpan = backToHalfUp - 8;
expect(releaseSpan).toBeGreaterThan(attackSpan * 2);
});
it("never exceeds the configured maximum", () => {
const duck = analyseCarveDuck(
voiceWithPause(0.02, 8, 2, 7),
tone(0.9, 8),
SR8,
settings({ duckDb: 6 }),
0,
);
expect(Math.min(...duck.map((p) => p.v))).toBeGreaterThanOrEqual(-6);
});
it("reads the bed at the offset between the two clips", () => {
// The bed starts before the voice, so voice-local 0 is bed-local `offset`.
// Given a bed that is loud only in its first half, a voice that starts 4s
// into it must see the quiet half and duck less than the same voice at 0.
const bed = new Float32Array(Math.floor(SR8 * 8));
for (let i = 0; i < bed.length; i++) {
const t = i / SR8;
bed[i] = (t < 4 ? 0.9 : 0.02) * Math.sin(2 * Math.PI * 300 * t);
}
const voice = voiceWithPause(0.3, 4, 0.5, 3.5);
const aligned = analyseCarveDuck(voice, bed, SR8, settings({ duckDb: 24 }), 0);
const shifted = analyseCarveDuck(voice, bed, SR8, settings({ duckDb: 24 }), 4);
expect(at(aligned, 2)).toBeLessThan(at(shifted, 2));
});
it("returns nothing without a voice, and stays inside the point budget", () => {
expect(analyseCarveDuck(new Float32Array(0), tone(0.5, 2), SR8, settings(), 0)).toEqual([]);
const long = analyseCarveDuck(
voiceWithPause(0.4, 200, 5, 195),
tone(0.5, 200),
SR8,
settings(),
0,
);
expect(long.length).toBeLessThanOrEqual(MAX_AUTOMATION_POINTS);
});
});
describe("analyseCarveDynamics", () => {
const BAND = { freq: 1000, gainDb: -8, q: 1.4 };
/** Silence, then a 1 kHz burst, then silence again. */
function burst(sampleRate: number, seconds: number, from: number, to: number): Float32Array {
const out = new Float32Array(Math.floor(sampleRate * seconds));
for (let i = 0; i < out.length; i++) {
const t = i / sampleRate;
out[i] = t >= from && t < to ? 0.7 * Math.sin(2 * Math.PI * 1000 * t) : 0;
}
return out;
}
const at = (points: { t: number; v: number }[], t: number): number =>
sampleAutomationLane({ target: "fx.n1.gain", points }, t);
it("holds the filter flat where the voice is silent and cuts where it speaks", () => {
const [lane] = analyseCarveDynamics(burst(SR, 6, 2, 4), SR, [BAND]);
expect(lane!.freq).toBe(1000);
expect(at(lane!.points, 0.7)).toBeCloseTo(0, 1);
expect(at(lane!.points, 3)).toBeLessThan(-6);
expect(at(lane!.points, 5.3)).toBeCloseTo(0, 1);
});
it("pins both ends of the envelope to no cut", () => {
const [lane] = analyseCarveDynamics(burst(SR, 6, 2, 4), SR, [BAND]);
const points = lane!.points;
expect(points[0]).toMatchObject({ t: 0, v: 0 });
expect(points.at(-1)!.v).toBe(0);
// Held past the end, so the bed comes back up rather than staying dipped.
expect(points.at(-1)!.t).toBeGreaterThanOrEqual(5.9);
});
it("never exceeds the point budget a lane can hold", () => {
const long = burst(8000, 200, 10, 190);
const [lane] = analyseCarveDynamics(long, 8000, [BAND]);
expect(lane!.points.length).toBeLessThanOrEqual(MAX_AUTOMATION_POINTS);
expect(lane!.points.length).toBeGreaterThan(2);
});
it("returns one envelope per band, and nothing for no input", () => {
const sig = burst(SR, 3, 0.5, 2.5);
expect(analyseCarveDynamics(sig, SR, [BAND, { freq: 2500, gainDb: -4, q: 1.4 }])).toHaveLength(
2,
);
expect(analyseCarveDynamics(new Float32Array(0), SR, [BAND])).toEqual([]);
});
});
describe("classifyAudioName", () => {
it("reads a track's kind from its id and its filename together", () => {
// Either can be the informative one: elements named a1/a2 may still have
// narration.mp3 and bgm.mp3 behind them.
expect(classifyAudioName("narration")).toBe("voice");
expect(classifyAudioName("a1", "voiceover-take3.wav")).toBe("voice");
expect(classifyAudioName("music-bed")).toBe("music");
expect(classifyAudioName("a2", "bgm_loop.m4a")).toBe("music");
expect(classifyAudioName("sfx-explosion")).toBe("sfx");
expect(classifyAudioName("whoosh-01")).toBe("sfx");
});
it("says nothing about a name that says nothing", () => {
// The common case, and the reason nothing downstream may treat "unknown" as
// "not a voice": it would hide the one track somebody needs to pick.
expect(classifyAudioName("a1")).toBe("unknown");
expect(classifyAudioName("clip-2", "0f9c1a.mp3")).toBe("unknown");
expect(classifyAudioName(undefined, null)).toBe("unknown");
});
it("prefers voice when a name carries both hints", () => {
// A file called voiceover-over-music-bed.wav is the voiceover, and a track
// matching both is better offered than hidden.
expect(classifyAudioName("voiceover-over-music-bed.wav")).toBe("voice");
});
it("offers speech and unnamed tracks as carve sources, never music or effects", () => {
expect(couldBeCarveSource("recap-audio")).toBe(true);
expect(couldBeCarveSource("a1")).toBe(true);
expect(couldBeCarveSource("music-bed")).toBe(false);
expect(couldBeCarveSource("sfx-explosion")).toBe(false);
});
// The near-end rule, which nothing used to ask. `couldBeCarveSource` shipped
// with its own doc comment ("music and sfx are out") and no caller; the bed
// side had no predicate at all, so a narration clip was offered the carve and
// — finding one candidate — had one applied for it, against the group it was
// a member of.
it("never offers a voice track as the bed, but keeps an unnamed one eligible", () => {
expect(couldBeCarveBed("music-bed")).toBe(true);
expect(couldBeCarveBed("sfx-riser")).toBe(true);
expect(couldBeCarveBed("a1")).toBe(true);
expect(couldBeCarveBed("vo-2")).toBe(false);
expect(couldBeCarveBed("voiceover")).toBe(false);
expect(couldBeCarveBed("narration-3")).toBe(false);
});
// Showing the control is a suggestion; writing the attribute is a decision.
// A decision taken off a name that said nothing is how a carve appears that
// nobody remembers configuring — so `a1` may be offered but never chosen.
it("only self-applies to a name that positively reads as a bed", () => {
expect(isNamedCarveBed("music-bed")).toBe(true);
expect(isNamedCarveBed("sfx-riser")).toBe(true);
expect(isNamedCarveBed("a1")).toBe(false);
expect(isNamedCarveBed("vo-2")).toBe(false);
});
it("treats underscores as separators, not word characters, for short hints", () => {
// `\b` treats `_` as a word character, so `\bbed\b` used to miss `bed_01` —
// an underscore-separated bed classified as "unknown" and could end up
// offered as its own carve source.
expect(classifyAudioName("bed_01")).toBe("music");
expect(classifyAudioName("my_bed")).toBe("music");
expect(classifyAudioName("music_bed_loop")).toBe("music");
expect(classifyAudioName("theme_song")).toBe("music");
expect(classifyAudioName("vo_take3")).toBe("voice");
expect(classifyAudioName("main_vox")).toBe("voice");
expect(couldBeCarveSource("bed_01")).toBe(false);
});
});
describe("clipsOverlap", () => {
it("overlaps when the spans genuinely share time", () => {
expect(clipsOverlap({ start: 0, duration: 5 }, { start: 3, duration: 5 })).toBe(true);
});
it("does not overlap when one span ends before the other starts", () => {
expect(clipsOverlap({ start: 0, duration: 5 }, { start: 5, duration: 5 })).toBe(false);
expect(clipsOverlap({ start: 10, duration: 5 }, { start: 0, duration: 5 })).toBe(false);
});
it("does not overlap two clips that only touch at an edge", () => {
// Half-open: an end exactly at the other's start shares no time to carve.
expect(clipsOverlap({ start: 0, duration: 5 }, { start: 5, duration: 5 })).toBe(false);
});
it("treats a null or undefined duration as unbounded", () => {
expect(clipsOverlap({ start: 0, duration: null }, { start: 100, duration: 1 })).toBe(true);
expect(clipsOverlap({ start: 0 }, { start: 100, duration: 1 })).toBe(true);
// Symmetric: the unbounded span can be on either side.
expect(clipsOverlap({ start: 100, duration: 1 }, { start: 0, duration: undefined })).toBe(true);
});
it("gives a zero-duration clip a single instant, not a span", () => {
expect(clipsOverlap({ start: 5, duration: 0 }, { start: 5, duration: 5 })).toBe(false);
expect(clipsOverlap({ start: 5, duration: 0 }, { start: 4, duration: 5 })).toBe(true);
});
it("clamps a negative duration to zero rather than inverting the interval", () => {
// The regression: end = start + duration puts a negative-duration clip's
// end BEFORE its start, and end(a) is what the other clip's start gets
// compared against — so a smaller (earlier) broken end silently rejects
// real overlaps too. {start:10, duration:-5} clamped is a zero-length
// clip AT t=10, which genuinely sits inside {start:6, duration:20}'s
// [6, 26) span; the unclamped math missed it (end(a) came out to 5).
expect(clipsOverlap({ start: 10, duration: -5 }, { start: 6, duration: 20 })).toBe(true);
// And it stays correct where it isn't inside anything.
expect(clipsOverlap({ start: 10, duration: -5 }, { start: 20, duration: 5 })).toBe(false);
});
});
describe("mixCarveSources", () => {
const tone = (seconds: number, level: number, sampleRate = 48000) =>
new Float32Array(Math.round(seconds * sampleRate)).fill(level);
it("places every voice where it starts on the bed's clock", () => {
// Three people talking at different times is still one question — where and
// when is speech masking this bed — so they become one signal.
const mixed = mixCarveSources(
[
{ samples: tone(1, 0.5), offsetSeconds: 1 },
{ samples: tone(1, 0.25), offsetSeconds: 3 },
],
48000,
);
expect(mixed.length).toBe(4 * 48000);
const at = (t: number) => mixed[Math.round(t * 48000)];
expect(at(0.5)).toBe(0); // before anyone speaks
expect(at(1.5)).toBeCloseTo(0.5, 5);
expect(at(2.5)).toBe(0); // the gap between them
expect(at(3.5)).toBeCloseTo(0.25, 5);
});
it("sums voices that overlap, because two at once mask more than one", () => {
const mixed = mixCarveSources(
[
{ samples: tone(1, 0.3), offsetSeconds: 0 },
{ samples: tone(1, 0.3), offsetSeconds: 0 },
],
48000,
);
expect(mixed[0]).toBeCloseTo(0.6, 5);
});
it("drops the part of a voice that plays before the bed starts", () => {
// It masks nothing there, and folding it in at zero would put a cut where
// there is no voice.
const mixed = mixCarveSources([{ samples: tone(1, 0.5), offsetSeconds: -0.5 }], 48000);
expect(mixed.length).toBe(0.5 * 48000);
expect(mixed[0]).toBeCloseTo(0.5, 5);
});
it("has nothing to mix when there are no voices", () => {
expect(mixCarveSources([], 48000)).toHaveLength(0);
});
});
describe("carve settings written before this took a list of voices", () => {
it("reads a single `source` as a one-voice list, and forgets `dynamic`", () => {
// Every carve is dynamic now: a static one thinned the bed through every pause,
// and nobody wanted that once they had heard both.
const read = normalizeCarveSettings({ source: "vo", strength: 0.4, dynamic: false } as never);
expect(read.sources).toEqual(["vo"]);
expect(read.strength).toBe(0.4);
expect("dynamic" in read).toBe(false);
});
it("drops empty ids rather than carrying a source that names nothing", () => {
expect(normalizeCarveSettings({ sources: ["", "vo", ""] } as never).sources).toEqual(["vo"]);
expect(normalizeCarveSettings({ source: "" } as never).sources).toEqual([]);
});
});