Files
hyperframes/packages/core/src/audioGain.ts
T
Miguel Ángel a8ac55dc30 fix: data-volume multiplies the volume lane in preview and render (#6068)
* fix: data-volume multiplies the volume lane in preview and render

* fix: a clip's data-volume plays ahead of its audio effects, in preview and render

* feat(studio): the media panel shows a clip's Gain beside its Volume level

* fix(audio): cap gain times volume lanes through each ramp

* chore(core): account for shared volume envelopes in package budget

* fix(core): restore static gain when a playing lane is removed
2026-10-22 20:12:49 +00:00

129 lines
4.9 KiB
TypeScript

/**
* Authoring gain for a media clip.
*
* HTMLMediaElement.volume is limited to 0..1, but HyperFrames' Web Audio
* preview and FFmpeg render paths both support gain above unity. Keep the
* shared ceiling here so Studio, preview, and render cannot drift.
*/
export const MAX_AUDIO_GAIN_DB = 12;
/** Linear gain from a decibel value. Owner of the dB → gain formula. */
export function audioDbToGain(db: number): number {
return 10 ** (db / 20);
}
/** Inverse of `audioDbToGain`. Caller must pass a positive finite gain. */
export function audioGainToDb(gain: number): number {
return 20 * Math.log10(gain);
}
export const MAX_AUDIO_GAIN = audioDbToGain(MAX_AUDIO_GAIN_DB);
/** Studio fader coordinates. Unity is deliberately the physical midpoint. */
export const AUDIO_GAIN_FADER_MIN = -100;
export const AUDIO_GAIN_FADER_MAX = 100;
const MIN_AUDIO_GAIN_DB = -60;
export function clampAudioGain(value: number): number {
if (!Number.isFinite(value)) return 1;
return Math.max(0, Math.min(MAX_AUDIO_GAIN, value));
}
/** `data-volume` is a gain on the volume lane, as clip gain offsets the keyframes in an NLE. */
export function gainTimesLane(gain: number, lane: number): number {
return clampAudioGain(gain * lane);
}
/** `data-volume` as clip gain, ahead of the FX chain; unity when a GSAP tween's absolute values own the level. */
export function clipGain(volume: number, tweened: boolean): number {
return tweened ? 1 : clampAudioGain(volume);
}
export function clampNativeMediaVolume(value: number): number {
if (!Number.isFinite(value)) return 1;
return Math.max(0, Math.min(1, value));
}
/**
* Serialize an authored gain for `data-volume`.
*
* The fader travels in dB, so its stops are irrational (position -70 is
* 10 ** (-42/20)). Rounding to two decimals — what the generic numeric
* attribute formatter does — collapses the whole bottom of the fader onto
* `"0"` (a hard mute) and makes the knob jump on release everywhere below
* unity. Six decimals round-trip every integer fader stop back to itself.
*/
export function formatAudioGain(gain: number): string {
return clampAudioGain(gain)
.toFixed(6)
.replace(/\.?0+$/, "");
}
/**
* Run `probe` with `el.volume` shadowed by an accessor that keeps the authored
* value instead of the spec's [0,1] clamp.
*
* `HTMLMediaElement.volume` cannot hold gain above unity, so a clip authored
* at `data-volume="1.95"` reads back as 1 the moment the probe seeds it — and
* a GSAP tween started from that seed fades from 0 dB rather than from the
* authored boost. Both the FFmpeg mixer and the Web Audio transport carry gain
* up to MAX_AUDIO_GAIN, so the clamp is a probe artefact, not a real ceiling.
* The native setter still receives the clamped value, so nothing outside the
* probe observes an out-of-range volume, and the shadow is removed afterwards.
*/
export function withUnclampedVolume<T>(el: HTMLMediaElement, probe: () => T): T {
// Guarded for non-DOM runtimes: the probe that calls this is also reachable
// from tests and tools that run outside a browser, where the clamped path is
// the right (and only) answer.
const descriptor =
typeof HTMLMediaElement === "undefined"
? undefined
: Object.getOwnPropertyDescriptor(HTMLMediaElement.prototype, "volume");
const nativeGet = descriptor?.get;
const nativeSet = descriptor?.set;
if (!nativeGet || !nativeSet) return probe();
let authored = Number(nativeGet.call(el));
Object.defineProperty(el, "volume", {
configurable: true,
get: () => authored,
set: (value: number) => {
authored = Number(value);
nativeSet.call(el, clampNativeMediaVolume(authored));
},
});
try {
return probe();
} finally {
delete (el as unknown as Record<"volume", unknown>).volume;
nativeSet.call(el, clampNativeMediaVolume(authored));
}
}
export function audioFaderPositionToGain(position: number): number {
const safe = Math.max(AUDIO_GAIN_FADER_MIN, Math.min(AUDIO_GAIN_FADER_MAX, position));
if (safe === AUDIO_GAIN_FADER_MIN) return 0;
const db =
safe < 0
? (safe / Math.abs(AUDIO_GAIN_FADER_MIN)) * Math.abs(MIN_AUDIO_GAIN_DB)
: (safe / AUDIO_GAIN_FADER_MAX) * MAX_AUDIO_GAIN_DB;
return audioDbToGain(db);
}
export function audioGainToFaderPosition(gain: number): number {
const safe = clampAudioGain(gain);
if (safe === 0) return AUDIO_GAIN_FADER_MIN;
const db = audioGainToDb(safe);
const position =
db < 0
? (db / Math.abs(MIN_AUDIO_GAIN_DB)) * Math.abs(AUDIO_GAIN_FADER_MIN)
: (db / MAX_AUDIO_GAIN_DB) * AUDIO_GAIN_FADER_MAX;
return Math.max(AUDIO_GAIN_FADER_MIN, Math.min(AUDIO_GAIN_FADER_MAX, position));
}
export function audioGainToText(gain: number): string {
const safe = clampAudioGain(gain);
if (safe === 0) return "-∞ dB";
const db = audioGainToDb(safe);
const rounded = Math.abs(db) < 0.05 ? 0 : db;
return (rounded > 0 ? "+" : "") + rounded.toFixed(1) + " dB";
}