/**
 * Named tap points for level monitoring. A list of nodes under one name is
 * metered as their sum, not individually.
 */
declare type GainStages = Record<string, AudioNode | AudioNode[]>;

export declare interface LevelMonitors {
    readLevels(): Record<string, LevelReading>;
    stop(): void;
}

export declare interface LevelReading {
    /** Highest absolute sample in the last reported window. */
    peakDB: number;
    /** RMS across the last reported window. */
    rmsDB: number;
    /** Samples exceeding the clip threshold since monitoring started. Monotonic. */
    clipCount: number;
}

/**
 * Attaches a metering tap to each named stage and starts measuring. A stage given
 * as a list of nodes is metered as their sum, on one meter.
 *
 * Each meter is a sink: the stage fans out to it and its own output goes nowhere,
 * so the signal path is unchanged and no latency is added. Attaching and detaching
 * while audio is playing is glitch-free for the same reason.
 *
 * Nothing is created until this is awaited, and `stop()` releases everything, so an
 * unmonitored graph carries no cost.
 *
 * Mid-graph, `clipCount` means the stage has run out of headroom, not that it is
 * distorting: Web Audio carries float32 internally, so samples above 1 pass through
 * intact. Only the hardware output clamps. A stage over 0 dB is still worth fixing,
 * since everything downstream of it is working harder than it should be.
 */
export declare function monitorLevels(stages: GainStages, options?: MonitorLevelsOptions): Promise<LevelMonitors>;

export declare interface MonitorLevelsOptions {
    /** How often each meter reports. Lower values cost more main-thread messages. */
    reportIntervalMs?: number;
    /** Absolute sample value counted as a clip. */
    clipThreshold?: number;
}

export { }