Skip to content

Write HTML. Render video. Built for agents.

5.6 KB
Raw Blame
/**
 * How long a chain keeps ringing after its input stops.
 *
 * The render used to end the offline context at the last input sample, so a
 * reverb or a delay was cut mid-tail — the one place the render did not match
 * preview. The length is not a guess: every tail-producing effect here has a
 * decay that follows from its own settings, so the render can ask for exactly
 * the room it needs.
 */

import { fxAutomationTarget, type HfAutomation } from "../audioAutomation.js";
import {
  enabledAudioFxNodes,
  normalizeAudioFxParams,
  type HfAudioFxChain,
  type HfAudioFxNode,
} from "../audioFx.js";
import { truePeakLatencySamples } from "./audioFxTruePeak.js";

/**
 * Ceiling on the extension, in seconds.
 *
 * Delay is unbounded in principle: 5 s between repeats at 0.95 feedback decays
 * for eleven minutes, and the panel can dial exactly that. A tail that outruns
 * the composition costs render time and mixes into everything after it, so the
 * chain gets the room it asks for up to here and is cut beyond it.
 */
export const MAX_FX_TAIL_SECONDS = 5;

/**
 * Where a tail stops counting as audible: -60 dB below the signal that fed it,
 * the usual convention for a reverb time. Anything quieter is under the noise
 * floor of every codec this renders to.
 */
const TAIL_FLOOR = 0.001;

/**
 * The largest value a knob reaches, over the whole clip.
 *
 * A lane's `curve` is an exponent, so a segment is monotone between its two
 * points and cannot overshoot either — the maximum point value is the maximum
 * of the lane, no sampling needed. Room size has to be sized for the loudest
 * moment regardless of where in the clip it falls.
 */
function knobMax(node: HfAudioFxNode, key: string, automation?: HfAutomation): number {
  // Normalised, so a knob missing from the attribute reads as its default and
  // an out-of-range one is clamped the way the graph builder would clamp it.
  const fallback = Number(normalizeAudioFxParams(node.type, node.params)[key] ?? 0);
  if (!node.id || !automation) return Number.isFinite(fallback) ? fallback : 0;
  const lane = automation.lanes.find((l) => l.target === fxAutomationTarget(node.id ?? "", key));
  if (!lane || lane.points.length === 0) return Number.isFinite(fallback) ? fallback : 0;
  return lane.points.reduce((max, p) => Math.max(max, p.v), -Infinity);
}

/**
 * Repeats until a feedback loop falls under the floor, times the gap between
 * them. `feedback` is capped below 1 by the registry, so this terminates.
 */
export function delayTailSeconds(time: number, feedback: number): number {
  const gap = Math.min(5, time / 1000);
  if (gap <= 0) return 0;
  const fb = Math.max(0, Math.min(0.999, feedback));
  if (fb <= 0) return gap;
  return Math.ceil(Math.log(TAIL_FLOOR) / Math.log(fb)) * gap;
}

// Exactly the generated impulse's length — see synthesizeReverbImpulse, which
// is the same expression. A convolution is as long as its impulse.
export function reverbRoomSeconds(size: number): number {
  return 0.6 + Math.max(0, Math.min(1, size)) * 2.6;
}

function reverbTail(node: HfAudioFxNode, automation?: HfAutomation): number {
  return knobMax(node, "wet", automation) > 0
    ? reverbRoomSeconds(knobMax(node, "size", automation))
    : 0;
}

function delayNodeTail(node: HfAudioFxNode, automation?: HfAutomation): number {
  return knobMax(node, "mix", automation) > 0
    ? delayTailSeconds(knobMax(node, "time", automation), knobMax(node, "feedback", automation))
    : 0;
}

/** A single delay line, no feedback: it rings for one delay (≤100 ms). */
function chorusTail(node: HfAudioFxNode, automation?: HfAutomation): number {
  return knobMax(node, "mix", automation) > 0 ? knobMax(node, "delay", automation) / 1000 : 0;
}

/** Two 100 ms grains: worst case the tail is still draining the grain that was mid-crossfade when the input stopped. */
function pitchshiftTail(node: HfAudioFxNode, automation?: HfAutomation): number {
  return knobMax(node, "mix", automation) > 0 ? 0.2 : 0;
}

/** One node's tail. Zero when it has none, or when it is mixed out entirely. */
function nodeTail(node: HfAudioFxNode, automation?: HfAutomation): number {
  if (node.enabled === false) return 0;
  switch (node.type) {
    case "reverb":
      return reverbTail(node, automation);
    case "delay":
      return delayNodeTail(node, automation);
    case "chorus":
      return chorusTail(node, automation);
    case "pitchshift":
      return pitchshiftTail(node, automation);
    default:
      // Everything else settles with its input. The phaser is an all-pass chain
      // with no recirculation (group delay, not a tail); the dynamics nodes have
      // long releases but no signal to release — silence in, silence out; a
      // biquad rings for ~Q/f, which is microseconds.
      return 0;
  }
}

/**
 * The whole chain's tail, in seconds.
 *
 * Summed, not maxed: the chain is serial, so a delay in front of a reverb hands
 * each of its repeats to the room and the last one still gets a full tail.
 */
export function chainTailSeconds(chain: HfAudioFxChain, automation?: HfAutomation): number {
  const total = chain.nodes.reduce((sum, node) => sum + nodeTail(node, automation), 0);
  return Math.min(MAX_FX_TAIL_SECONDS, total);
}

/** Samples the offline render trims so a lookahead limiter does not shift a clip. */
export function chainLatencySamples(chain: HfAudioFxChain, sampleRate: number): number {
  return enabledAudioFxNodes(chain)
    .filter((node) => node.type === "truepeak")
    .reduce((sum, node) => {
      const { lookahead } = normalizeAudioFxParams(node.type, node.params);
      return sum + truePeakLatencySamples(Number(lookahead), sampleRate);
    }, 0);
}