Files
hyperframes/packages/core/src/audioLeveller.ts
Miguel Ángel 9825614d91 fix(studio): Studio's own text reads without em or en dashes (#5414)
* fix(studio): text in Studio reads without em or en dashes

* fix(studio): the dash check also catches HTML entities, and peak reads Unavailable

* test(studio): the dash check test covers every entity form

* fix(studio): messages Studio shows from lint, sdk, core and the renderer drop dashes too

* fix(producer): the gate check stops early on the engine's new fallback wording
2026-10-10 19:08:30 +00:00

253 lines
9.5 KiB
TypeScript

/**
* "Even Out Levels" — the first of the adaptive scripts.
*
* A preset cannot fix inconsistent loudness, because the right correction
* depends on the recording. So this measures the track and writes an automation
* lane that lifts the quiet passages toward the loud ones, exactly as the carve
* measures a voice and writes its bands.
*
* It is NOT loudness normalisation. Platform targets (-14 LUFS and friends) are
* ITU-R BS.1770 — K-weighted and gated — and this is plain windowed RMS, so
* calling it LUFS would be a claim the measurement does not support. It is
* named for what it does: evening out.
*
* ## Why the lane rides a `gain` node
*
* The obvious home is the track's volume lane, and the old reason not to use it
* — "volume is 0..1, so a lane can only ever attenuate" — is being retired in
* stages: `normaliseEnvelope` now clamps to 0..+12 dB, while `VOLUME_RANGE`,
* which bounds the lane itself, still stops at unity until the dB fader lands.
*
* The reason that survives either way is ownership: the volume lane is the
* fader the author draws, and a leveller that wrote into it would silently
* redraw their envelope. A `gain` node is a separate stage the leveller owns
* outright, which is what the audio skill means when it calls `gain` "what an
* automation lane rides when a track has to move".
*/
import {
fxAutomationTarget,
type HfAutomation,
type HfAutomationPoint,
} from "./audioAutomation.js";
import {
HF_AUDIO_FX_CHAIN_VERSION,
mintAudioFxNodeId,
normalizeAudioFxParams,
type HfAudioFxChain,
type HfAudioFxNode,
} from "./audioFx.js";
/** One window per emitted point; the hop keeps the lane inside its budget. */
const FRAME = 4096;
const POINT_BUDGET = 400;
/** Below this, a window is silence rather than a quiet passage worth lifting. */
const FLOOR_BELOW_PEAK_DB = 42;
/** How far a correction may go. Beyond this, lifting a whisper only lifts the room. */
const MAX_LIFT_DB = 12;
const MAX_CUT_DB = 12;
/** Ignore differences smaller than this — they are not audible and they add points. */
const SNAP_DB = 0.4;
/** Attack/release in seconds, so a correction rides the phrase and not the syllable. */
const ATTACK_S = 0.35;
const RELEASE_S = 0.9;
export interface HfLevellerSettings {
/** 0 = leave it alone, 1 = as even as this can make it. */
strength: number;
}
export const DEFAULT_LEVELLER: HfLevellerSettings = { strength: 0.5 };
export interface HfLevellerProfile {
/** How much of the measured difference to correct. */
correction: number;
}
/**
* One knob to a profile, the shape `carveProfile` established.
*
* At full strength this still corrects only most of the difference: driving a
* track to a flat line removes the performance along with the inconsistency.
*/
export function levellerProfile(strength: number): HfLevellerProfile {
const s = Number.isFinite(strength) ? Math.min(1, Math.max(0, strength)) : 0.5;
return { correction: Number((0.25 + s * 0.6).toFixed(3)) };
}
/** Level in dB of one window, or -Infinity for silence. */
function windowDb(samples: Float32Array, from: number, count: number): number {
let sum = 0;
let n = 0;
for (let i = from; i < from + count; i += 1) {
const s = samples[i];
if (s === undefined) break;
sum += s * s;
n += 1;
}
if (n === 0) return Number.NEGATIVE_INFINITY;
const rms = Math.sqrt(sum / n);
return rms > 0 ? 20 * Math.log10(rms) : Number.NEGATIVE_INFINITY;
}
/**
* Measure a track and return the gain moves that even it out, in dB against
* clip-local seconds. Empty when there is nothing worth correcting.
*/
export function analyseLevelling(
samples: Float32Array,
sampleRate: number,
strength = DEFAULT_LEVELLER.strength,
): HfAutomationPoint[] {
if (samples.length === 0 || sampleRate <= 0) return [];
const profile = levellerProfile(strength);
const hop = Math.max(FRAME, Math.ceil(samples.length / POINT_BUDGET));
const levels: number[] = [];
const times: number[] = [];
for (let start = 0; start < samples.length; start += hop) {
levels.push(windowDb(samples, start, FRAME));
times.push((start + FRAME / 2) / sampleRate);
}
const speaking = levels.filter((d) => Number.isFinite(d));
if (speaking.length === 0) return [];
const peak = Math.max(...speaking);
const floor = peak - FLOOR_BELOW_PEAK_DB;
/**
* The target is a level the track ALREADY REACHES — the 80th percentile of
* its speaking windows — not an absolute one.
*
* Anchoring it to an absolute figure means an already-even track gets pulled
* bodily up or down to meet it, which is a volume change wearing a
* levelling label. Against a level the track reaches, its loud passages
* correct to roughly nothing and only the quiet ones move, which is what
* evening out means. It is a percentile rather than the peak so one loud
* word cannot set the target for the whole track.
*/
const sorted = [...speaking].sort((a, b) => a - b);
const target = sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.8))] ?? peak;
const attack = 1 - Math.exp(-(hop / sampleRate) / ATTACK_S);
const release = 1 - Math.exp(-(hop / sampleRate) / RELEASE_S);
let applied = 0;
const raw: HfAutomationPoint[] = [];
levels.forEach((db, i) => {
// Silence is left alone. Lifting a pause only lifts the room with it.
const wanted =
Number.isFinite(db) && db > floor
? Math.max(-MAX_CUT_DB, Math.min(MAX_LIFT_DB, (target - db) * profile.correction))
: 0;
applied += (wanted > applied ? attack : release) * (wanted - applied);
const v = Math.abs(applied) < SNAP_DB ? 0 : Number(applied.toFixed(1));
raw.push({ t: Number((times[i] ?? 0).toFixed(3)), v });
});
// Keep only the moves. A run of equal values is held by keeping the last of
// the run, or interpolation would slide across a passage that is steady.
const points: HfAutomationPoint[] = [];
let lastKept = 0;
let keptIndex = -1;
raw.forEach((pt, i) => {
if (i !== raw.length - 1 && Math.abs(pt.v - lastKept) < SNAP_DB) return;
if (i > 0 && keptIndex !== i - 1) {
const prev = raw[i - 1];
if (prev) points.push(prev);
}
points.push(pt);
lastKept = pt.v;
keptIndex = i;
});
// A lane of zeroes is not a correction, it is a lane that says nothing. An
// author who runs this on an even track should be told there was nothing to
// do, not handed an inert envelope to wonder about.
if (points.length === 0 || points.every((p) => p.v === 0)) return [];
// A lane's first point has to sit at the clip's start, or everything before
// it is drawn from wherever the first move happens to be.
if ((points[0]?.t ?? 0) > 0) points.unshift({ t: 0, v: points[0]?.v ?? 0 });
return points;
}
/**
* The chain and lane for "Even Out Levels".
*
* Returns nothing when the track needs no correcting — a script that always
* writes something teaches an author that it is doing nothing.
*/
export function levellingResult(
chain: HfAudioFxChain,
samples: Float32Array,
sampleRate: number,
strength = DEFAULT_LEVELLER.strength,
): { chain: HfAudioFxChain; automation: HfAutomation } | null {
const points = analyseLevelling(samples, sampleRate, strength);
if (points.length === 0) return null;
const existing = chain.nodes.find((n) => n.fromLeveller);
const id = existing?.id ?? mintAudioFxNodeId(chain);
const node: HfAudioFxNode = {
type: "gain",
id,
fromLeveller: true,
label: "Even Out Levels",
enabled: true,
// Seeded at 0 dB: the lane is what moves it, and a non-zero seed would be
// heard for the instant before the first ramp is scheduled.
params: normalizeAudioFxParams("gain", { gain: 0 }),
};
/**
* In FRONT of a trailing limiter, not after it.
*
* The likely sequence is "apply Clean Voice, then even out the levels", and
* Clean Voice ends in a Peak Ceiling. Appending would put up to 12 dB of lift
* AFTER the ceiling that exists to bound the chain — so every quiet-to-loud
* transition leaves residual lift on loud material sitting at -1 dBFS, and
* the render shears it flat. A ceiling that something is added after is not
* a ceiling.
*/
const insertAt =
!existing && chain.nodes[chain.nodes.length - 1]?.type === "limiter"
? chain.nodes.length - 1
: chain.nodes.length;
return {
chain: {
version: HF_AUDIO_FX_CHAIN_VERSION,
nodes: existing
? chain.nodes.map((n) => (n.fromLeveller ? node : n))
: [...chain.nodes.slice(0, insertAt), node, ...chain.nodes.slice(insertAt)],
},
automation: {
version: 1,
lanes: [{ target: fxAutomationTarget(id, "gain"), points }],
},
};
}
/** Drop the leveller and say which lane went with it. */
export function removeLevelling(chain: HfAudioFxChain): {
chain: HfAudioFxChain;
removedTarget: string | null;
} {
const node = chain.nodes.find((n) => n.fromLeveller);
return {
chain: { ...chain, nodes: chain.nodes.filter((n) => !n.fromLeveller) },
removedTarget: node?.id ? fxAutomationTarget(node.id, "gain") : null,
};
}
/** What the module says when it is closed. */
export function levellingSummary(points: readonly HfAutomationPoint[]): string {
const moves = points.filter((p) => p.v !== 0);
if (moves.length === 0) return "Already even: nothing to do";
const lift = Math.max(...moves.map((p) => p.v));
const cut = Math.min(...moves.map((p) => p.v));
const parts: string[] = [];
if (lift > 0) parts.push(`lifting quiet parts up to ${lift.toFixed(1)} dB`);
if (cut < 0) parts.push(`holding loud parts down ${Math.abs(cut).toFixed(1)} dB`);
return parts.join(", ");
}