Files
hyperframes/packages/core/src/audioCarve.test.ts
T
Vance IngallsandClaude Fable 5.1 e488871ce1 fix(audio): pin the slower release and the carve default, fold the requirement, sync the manifest
Review at fe53f51a: the moved test points passed at both 1.6s and 2.4s, so a
revert of DUCK_RELEASE_S was silent. Add the 9s probe that reds on 1.6s. Export
DEFAULT_STRENGTH and parseArgs from carve.mjs and pin 0.8 in carve.test.mjs.
Fold the new requirement paragraph into the existing 'Carve by default' one so
the rule is stated once. Regenerate skills-manifest.json after the last edit.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-11 13:57:07 -07:00

687 lines
29 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
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([]);
});
});