Voice Leveling (untested)
This commit is contained in:
442
public/voice-leveling-worklet.js
Normal file
442
public/voice-leveling-worklet.js
Normal file
@@ -0,0 +1,442 @@
|
||||
/**
|
||||
* VoiceLevelingProcessor — AudioWorkletProcessor that implements
|
||||
* broadcast-grade per-speaker automatic gain control (AGC).
|
||||
*
|
||||
* ═══════════════════════════════════════════════════════════════════
|
||||
* DSP DESIGN NOTES
|
||||
* ═══════════════════════════════════════════════════════════════════
|
||||
*
|
||||
* This processor mimics WebRTC's Gain Controller 2 (AGC2) behaviour
|
||||
* using a lightweight algorithm suitable for real-time voice in an
|
||||
* AudioWorklet thread.
|
||||
*
|
||||
* Pipeline (per 128-sample render quantum ≈ 2.67 ms @ 48 kHz):
|
||||
*
|
||||
* 1. RMS level estimation (short-term envelope)
|
||||
* 2. Silence gate (freeze gain when below noise floor)
|
||||
* 3. Target gain compute (desired dBFS → linear gain)
|
||||
* 4. Gain smoothing (exponential attack / release)
|
||||
* 5. Max-gain clamp (prevent runaway boost)
|
||||
* 6. Soft-clip limiter (prevent digital overs)
|
||||
*
|
||||
* Key properties:
|
||||
* • No per-frame allocation — all buffers pre-allocated.
|
||||
* • Synchronous processing — no message passing in hot path.
|
||||
* • Uses Float32 throughout — native AudioWorklet format.
|
||||
* • 128-sample quantum fits within 10 ms at 48 kHz (2.67 ms).
|
||||
*
|
||||
* The processor receives configuration via AudioWorkletNode.port
|
||||
* messages and applies them on the next render quantum.
|
||||
*
|
||||
* ═══════════════════════════════════════════════════════════════════
|
||||
*/
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────── */
|
||||
/* Constants */
|
||||
/* ──────────────────────────────────────────────────────────────── */
|
||||
|
||||
/** Processor name registered with `registerProcessor`. */
|
||||
const PROCESSOR_NAME = 'VoiceLevelingProcessor';
|
||||
|
||||
/**
|
||||
* Web Audio render quantum size — the number of samples processed
|
||||
* in each call to `process()`. The AudioWorklet spec mandates 128.
|
||||
*/
|
||||
const RENDER_QUANTUM_FRAMES = 128;
|
||||
|
||||
/**
|
||||
* Minimum RMS level (linear) below which the input is considered
|
||||
* silence. Gain is frozen/decayed when the signal is this quiet.
|
||||
* Roughly −60 dBFS.
|
||||
*/
|
||||
const DEFAULT_SILENCE_THRESHOLD = 0.001;
|
||||
|
||||
/**
|
||||
* The target RMS level in dBFS. −18 dBFS is a comfortable
|
||||
* conversational loudness for headphone listening.
|
||||
*/
|
||||
const DEFAULT_TARGET_DBFS = -18;
|
||||
|
||||
/** Default maximum gain boost in dB. */
|
||||
const DEFAULT_MAX_GAIN_DB = 12;
|
||||
|
||||
/** Soft-clip ceiling — prevents digital overs. */
|
||||
const SOFT_CLIP_THRESHOLD = 0.95;
|
||||
|
||||
/**
|
||||
* Speed presets: attack and release time constants (seconds).
|
||||
*
|
||||
* Attack = how fast gain *decreases* when a loud signal arrives.
|
||||
* Release = how fast gain *increases* when the signal gets quieter.
|
||||
*
|
||||
* Asymmetric: fast attack prevents clipping, slow release sounds
|
||||
* natural and avoids "pumping".
|
||||
*/
|
||||
const SPEED_PRESETS = {
|
||||
slow: { attack: 0.015, release: 0.800 },
|
||||
medium: { attack: 0.010, release: 0.400 },
|
||||
fast: { attack: 0.005, release: 0.150 },
|
||||
};
|
||||
|
||||
/**
|
||||
* AGC strength presets: scale the computed gain adjustment.
|
||||
* 1.0 = full correction toward target; lower = gentler leveling.
|
||||
*/
|
||||
const STRENGTH_PRESETS = {
|
||||
low: 0.5,
|
||||
medium: 0.75,
|
||||
high: 1.0,
|
||||
};
|
||||
|
||||
/**
|
||||
* When silence is detected, the gain decays toward 1.0 (unity)
|
||||
* at this rate (seconds). This prevents the gain from sitting at
|
||||
* a huge value after long silence and then blasting when speech
|
||||
* resumes.
|
||||
*/
|
||||
const SILENCE_DECAY_TC = 2.0;
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────── */
|
||||
/* Helpers */
|
||||
/* ──────────────────────────────────────────────────────────────── */
|
||||
|
||||
/** Convert decibels to linear gain. */
|
||||
function dbToLinear(db) {
|
||||
return Math.pow(10, db / 20);
|
||||
}
|
||||
|
||||
/** Convert linear amplitude to dBFS. Returns −Infinity for 0. */
|
||||
function linearToDb(linear) {
|
||||
if (linear <= 0) return -Infinity;
|
||||
return 20 * Math.log10(linear);
|
||||
}
|
||||
|
||||
/**
|
||||
* Compute the exponential smoothing coefficient (α) for a given
|
||||
* time constant and **frame rate** (not sample rate!).
|
||||
*
|
||||
* Because the envelope / gain update runs once per render quantum
|
||||
* (128 samples), the rate passed here must be frames-per-second
|
||||
* (sampleRate / 128), NOT samples-per-second. Using the raw
|
||||
* sampleRate would produce absurdly small α values, making the
|
||||
* AGC appear frozen.
|
||||
*
|
||||
* α = 1 − e^(−1 / (tc * fps))
|
||||
*
|
||||
* Larger α → faster response.
|
||||
*
|
||||
* @param {number} tc Time constant in seconds.
|
||||
* @param {number} fps Frame rate (render quanta per second).
|
||||
* @returns {number} Smoothing coefficient (0–1).
|
||||
*/
|
||||
function timeConstantToAlpha(tc, fps) {
|
||||
if (tc <= 0) return 1.0;
|
||||
return 1.0 - Math.exp(-1.0 / (tc * fps));
|
||||
}
|
||||
|
||||
/**
|
||||
* Attempt to use SharedArrayBuffer for the envelope history if
|
||||
* the environment supports it. Falls back to a regular
|
||||
* Float32Array.
|
||||
*
|
||||
* @param {number} length Number of elements.
|
||||
* @returns {Float32Array}
|
||||
*/
|
||||
function allocateBuffer(length) {
|
||||
try {
|
||||
if (typeof SharedArrayBuffer !== 'undefined') {
|
||||
return new Float32Array(new SharedArrayBuffer(length * 4));
|
||||
}
|
||||
} catch { /* fall through */ }
|
||||
return new Float32Array(length);
|
||||
}
|
||||
|
||||
/**
|
||||
* Soft-clip function (tanh-based) that prevents digital overs
|
||||
* while preserving signal shape.
|
||||
*
|
||||
* Below the threshold the signal passes through unchanged.
|
||||
* Above it, tanh compression is applied symmetrically.
|
||||
*
|
||||
* @param {number} sample Input sample.
|
||||
* @returns {number} Clipped sample.
|
||||
*/
|
||||
function softClip(sample) {
|
||||
const abs = Math.abs(sample);
|
||||
if (abs <= SOFT_CLIP_THRESHOLD) return sample;
|
||||
const sign = sample >= 0 ? 1 : -1;
|
||||
// Map (threshold..∞) → (threshold..1) using tanh
|
||||
const excess = (abs - SOFT_CLIP_THRESHOLD) / (1 - SOFT_CLIP_THRESHOLD);
|
||||
return sign * (SOFT_CLIP_THRESHOLD + (1 - SOFT_CLIP_THRESHOLD) * Math.tanh(excess));
|
||||
}
|
||||
|
||||
/* ──────────────────────────────────────────────────────────────── */
|
||||
/* Processor */
|
||||
/* ──────────────────────────────────────────────────────────────── */
|
||||
|
||||
class VoiceLevelingProcessor extends AudioWorkletProcessor {
|
||||
|
||||
/* ── State ──────────────────────────────────────────────────── */
|
||||
|
||||
/** Whether processing is enabled (bypass when false). */
|
||||
_enabled = true;
|
||||
|
||||
/** Target loudness in dBFS. */
|
||||
_targetDbfs = DEFAULT_TARGET_DBFS;
|
||||
|
||||
/** Maximum gain boost in dB. */
|
||||
_maxGainDb = DEFAULT_MAX_GAIN_DB;
|
||||
|
||||
/** Linear ceiling for the gain multiplier. */
|
||||
_maxGainLinear = dbToLinear(DEFAULT_MAX_GAIN_DB);
|
||||
|
||||
/** AGC strength factor (0–1). Scales the gain correction. */
|
||||
_strength = STRENGTH_PRESETS.medium;
|
||||
|
||||
/** Whether the silence/noise gate is active. */
|
||||
_noiseGateEnabled = false;
|
||||
|
||||
/** RMS threshold below which input is treated as silence. */
|
||||
_silenceThreshold = DEFAULT_SILENCE_THRESHOLD;
|
||||
|
||||
/** Attack smoothing coefficient. */
|
||||
_alphaAttack = 0;
|
||||
|
||||
/** Release smoothing coefficient. */
|
||||
_alphaRelease = 0;
|
||||
|
||||
/** Silence decay smoothing coefficient. */
|
||||
_alphaSilenceDecay = 0;
|
||||
|
||||
/**
|
||||
* Running RMS envelope (squared, to avoid sqrt every frame).
|
||||
* Smoothed with a one-pole filter.
|
||||
*/
|
||||
_envelopeSq = 0;
|
||||
|
||||
/** Current applied gain (linear). Smoothed toward target. */
|
||||
_currentGain = 1.0;
|
||||
|
||||
/**
|
||||
* Pre-allocated buffer used for RMS computation.
|
||||
* Sized to the largest possible render quantum (128 samples).
|
||||
*/
|
||||
_scratchBuffer = allocateBuffer(128);
|
||||
|
||||
/* ── Constructor ────────────────────────────────────────────── */
|
||||
|
||||
constructor(options) {
|
||||
super(options);
|
||||
|
||||
// Compute smoothing coefficients from default speed
|
||||
this._applySpeed('medium');
|
||||
|
||||
// Listen for configuration changes from the main thread.
|
||||
// Messages are consumed before the next render quantum.
|
||||
this.port.onmessage = (event) => this._handleMessage(event.data);
|
||||
}
|
||||
|
||||
/* ── Configuration ──────────────────────────────────────────── */
|
||||
|
||||
/**
|
||||
* Handle a configuration message from the main thread.
|
||||
*
|
||||
* Accepted keys:
|
||||
* enabled : boolean
|
||||
* targetDbfs : number (-30 … -12)
|
||||
* maxGainDb : number (3 … 20)
|
||||
* strength : 'low' | 'medium' | 'high'
|
||||
* speed : 'slow' | 'medium' | 'fast'
|
||||
* noiseGate : boolean
|
||||
*
|
||||
* @param {object} msg
|
||||
*/
|
||||
_handleMessage(msg) {
|
||||
if (msg == null || typeof msg !== 'object') return;
|
||||
|
||||
if (typeof msg.enabled === 'boolean') {
|
||||
this._enabled = msg.enabled;
|
||||
if (!msg.enabled) {
|
||||
// Reset gain to unity on disable so re-enabling starts clean
|
||||
this._currentGain = 1.0;
|
||||
this._envelopeSq = 0;
|
||||
}
|
||||
}
|
||||
|
||||
if (typeof msg.targetDbfs === 'number') {
|
||||
this._targetDbfs = Math.max(-30, Math.min(-12, msg.targetDbfs));
|
||||
}
|
||||
|
||||
if (typeof msg.maxGainDb === 'number') {
|
||||
const clamped = Math.max(3, Math.min(20, msg.maxGainDb));
|
||||
this._maxGainDb = clamped;
|
||||
this._maxGainLinear = dbToLinear(clamped);
|
||||
}
|
||||
|
||||
if (typeof msg.strength === 'string' && STRENGTH_PRESETS[msg.strength] != null) {
|
||||
this._strength = STRENGTH_PRESETS[msg.strength];
|
||||
}
|
||||
|
||||
if (typeof msg.speed === 'string' && SPEED_PRESETS[msg.speed] != null) {
|
||||
this._applySpeed(msg.speed);
|
||||
}
|
||||
|
||||
if (typeof msg.noiseGate === 'boolean') {
|
||||
this._noiseGateEnabled = msg.noiseGate;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Recompute attack/release/silence-decay coefficients for
|
||||
* the current sample rate.
|
||||
*
|
||||
* IMPORTANT: We use frames-per-second (sampleRate / 128), NOT
|
||||
* the raw sampleRate, because the smoothing filter is applied
|
||||
* once per render quantum — not once per sample.
|
||||
*
|
||||
* @param {'slow' | 'medium' | 'fast'} preset
|
||||
*/
|
||||
_applySpeed(preset) {
|
||||
const { attack, release } = SPEED_PRESETS[preset];
|
||||
const fps = sampleRate / RENDER_QUANTUM_FRAMES;
|
||||
this._alphaAttack = timeConstantToAlpha(attack, fps);
|
||||
this._alphaRelease = timeConstantToAlpha(release, fps);
|
||||
this._alphaSilenceDecay = timeConstantToAlpha(SILENCE_DECAY_TC, fps);
|
||||
}
|
||||
|
||||
/* ── DSP ────────────────────────────────────────────────────── */
|
||||
|
||||
/**
|
||||
* Main audio processing callback.
|
||||
*
|
||||
* @param {Float32Array[][]} inputs Input channels.
|
||||
* @param {Float32Array[][]} outputs Output channels.
|
||||
* @returns {boolean} `true` to keep the processor alive.
|
||||
*/
|
||||
process(inputs, outputs) {
|
||||
const input = inputs[0];
|
||||
const output = outputs[0];
|
||||
|
||||
// No input → silence pass-through
|
||||
if (!input || input.length === 0 || !input[0]) {
|
||||
return true;
|
||||
}
|
||||
|
||||
const inputChannel = input[0];
|
||||
const outputChannel = output[0];
|
||||
const numSamples = inputChannel.length;
|
||||
|
||||
// ── Bypass mode ──────────────────────────────────────────
|
||||
if (!this._enabled) {
|
||||
// Copy input → output unchanged
|
||||
for (let i = 0; i < numSamples; i++) {
|
||||
outputChannel[i] = inputChannel[i];
|
||||
}
|
||||
// Also copy any additional channels (stereo, etc.)
|
||||
for (let ch = 1; ch < input.length; ch++) {
|
||||
if (output[ch] && input[ch]) {
|
||||
for (let i = 0; i < numSamples; i++) {
|
||||
output[ch][i] = input[ch][i];
|
||||
}
|
||||
}
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
// ── 1. RMS level estimation ──────────────────────────────
|
||||
//
|
||||
// Compute the RMS of this render quantum and smooth it with
|
||||
// a one-pole IIR filter (exponential moving average).
|
||||
//
|
||||
// We work in the squared domain to avoid a sqrt per sample;
|
||||
// the sqrt is taken only once per quantum for the gain calc.
|
||||
|
||||
let sumSq = 0;
|
||||
for (let i = 0; i < numSamples; i++) {
|
||||
const s = inputChannel[i];
|
||||
sumSq += s * s;
|
||||
}
|
||||
const frameMeanSq = sumSq / numSamples;
|
||||
|
||||
// Smooth envelope: use attack for rising levels, release for falling
|
||||
const alpha = frameMeanSq > this._envelopeSq
|
||||
? this._alphaAttack
|
||||
: this._alphaRelease;
|
||||
this._envelopeSq += alpha * (frameMeanSq - this._envelopeSq);
|
||||
|
||||
// Current smoothed RMS (linear)
|
||||
const rms = Math.sqrt(Math.max(this._envelopeSq, 1e-12));
|
||||
|
||||
// ── 2. Silence gate ──────────────────────────────────────
|
||||
//
|
||||
// If the RMS is below the silence threshold, do NOT compute
|
||||
// a new gain target. Instead, decay the current gain slowly
|
||||
// toward unity (1.0) so we don't slam the listener when
|
||||
// speech resumes.
|
||||
|
||||
const isSilence = rms < this._silenceThreshold;
|
||||
|
||||
if (isSilence && this._noiseGateEnabled) {
|
||||
// Decay gain toward 1.0
|
||||
this._currentGain += this._alphaSilenceDecay * (1.0 - this._currentGain);
|
||||
} else if (!isSilence) {
|
||||
// ── 3. Target gain computation ───────────────────────
|
||||
//
|
||||
// Desired gain = 10^((targetDbfs − currentDbfs) / 20)
|
||||
//
|
||||
// We scale the correction by the strength factor so that
|
||||
// "low" strength applies only 50 % of the correction.
|
||||
|
||||
const currentDbfs = linearToDb(rms);
|
||||
const errorDb = this._targetDbfs - currentDbfs;
|
||||
|
||||
// Scale the correction by strength.
|
||||
// A strength of 1.0 means "correct fully to target".
|
||||
const correctionDb = errorDb * this._strength;
|
||||
let desiredGain = dbToLinear(correctionDb);
|
||||
|
||||
// Clamp to max gain
|
||||
if (desiredGain > this._maxGainLinear) {
|
||||
desiredGain = this._maxGainLinear;
|
||||
}
|
||||
// Never attenuate below a certain floor (we're leveling UP,
|
||||
// but very loud signals still need to be pulled down).
|
||||
// Allow attenuation down to −6 dB.
|
||||
if (desiredGain < 0.5) {
|
||||
desiredGain = 0.5;
|
||||
}
|
||||
|
||||
// ── 4. Gain smoothing ──────────────────────────────
|
||||
//
|
||||
// Exponentially interpolate the current gain toward the
|
||||
// desired gain. Use fast attack (gain DOWN) and slow
|
||||
// release (gain UP) for natural dynamics.
|
||||
|
||||
const gainAlpha = desiredGain < this._currentGain
|
||||
? this._alphaAttack // Gain is decreasing (loud signal arrived)
|
||||
: this._alphaRelease; // Gain is increasing (signal got quieter)
|
||||
|
||||
this._currentGain += gainAlpha * (desiredGain - this._currentGain);
|
||||
}
|
||||
// If isSilence && !noiseGateEnabled → gain stays as-is (frozen)
|
||||
|
||||
// ── 5. Apply gain & soft-clip ─────────────────────────────
|
||||
const gain = this._currentGain;
|
||||
for (let i = 0; i < numSamples; i++) {
|
||||
outputChannel[i] = softClip(inputChannel[i] * gain);
|
||||
}
|
||||
|
||||
// Copy any additional channels with same gain
|
||||
for (let ch = 1; ch < input.length; ch++) {
|
||||
if (output[ch] && input[ch]) {
|
||||
for (let i = 0; i < numSamples; i++) {
|
||||
output[ch][i] = softClip(input[ch][i] * gain);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return true;
|
||||
}
|
||||
}
|
||||
|
||||
registerProcessor(PROCESSOR_NAME, VoiceLevelingProcessor);
|
||||
Reference in New Issue
Block a user