mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-19 19:36:04 +00:00
* 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
129 lines
4.9 KiB
TypeScript
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";
|
|
}
|