ez-web-audio/dist/analyzer.d.ts

Making the Web Audio API super EZ since 2024.

/**
 * Configuration options for creating an Analyzer.
 */
export interface AnalyzerOptions {
    /**
     * FFT size for frequency analysis. Must be a power of 2 between 32 and 32768.
     * Larger values provide more frequency detail but less time precision.
     * @default 2048
     */
    fftSize?: number;
    /**
     * Minimum decibel value for frequency data scaling.
     * @default -100
     */
    minDecibels?: number;
    /**
     * Maximum decibel value for frequency data scaling.
     * @default -30
     */
    maxDecibels?: number;
    /**
     * Smoothing time constant (0-1). Higher values smooth data over time.
     * @default 0.8
     */
    smoothingTimeConstant?: number;
}
/**
 * Analyzer class for audio visualization.
 *
 * Wraps the Web Audio AnalyserNode with a convenient API for getting frequency
 * and waveform data. Uses pre-allocated typed arrays for zero-allocation polling.
 *
 * @example
 * ```typescript
 * const analyzer = createAnalyzer(audioContext, { fftSize: 2048 })
 * sound.setAnalyzer(analyzer)
 *
 * function draw() {
 *   const freqData = analyzer.getFrequencyData()
 *   // Draw frequency bars using freqData values (0-255)
 *
 *   const waveData = analyzer.getTimeDomainData()
 *   // Draw oscilloscope waveform using waveData (128 = zero crossing)
 *
 *   requestAnimationFrame(draw)
 * }
 * draw()
 * ```
 */
export declare class Analyzer {
    /**
     * The underlying AnalyserNode. Connect audio to this node for analysis.
     * Use this as the input when integrating with effect chains.
     */
    readonly input: AnalyserNode;
    private _frequencyData;
    private _timeDomainData;
    private _floatFrequencyData;
    constructor(audioContext: AudioContext, options?: AnalyzerOptions);
    /**
     * The number of data points available for visualization.
     * Equal to fftSize / 2.
     */
    get frequencyBinCount(): number;
    /**
     * The FFT size used for frequency analysis.
     * Must be a power of 2 between 32 and 32768.
     */
    get fftSize(): number;
    set fftSize(value: number);
    /**
     * Minimum decibel value for frequency data scaling.
     */
    get minDecibels(): number;
    set minDecibels(value: number);
    /**
     * Maximum decibel value for frequency data scaling.
     */
    get maxDecibels(): number;
    set maxDecibels(value: number);
    /**
     * Smoothing time constant (0-1). Higher values smooth data over time.
     */
    get smoothingTimeConstant(): number;
    set smoothingTimeConstant(value: number);
    /**
     * Get frequency data as unsigned byte array (0-255).
     * Call this in requestAnimationFrame for smooth animations.
     *
     * Each value represents the amplitude at that frequency bin.
     * Lower indices = lower frequencies, higher indices = higher frequencies.
     *
     * @returns Uint8Array of frequency amplitudes (same reference, use immediately or copy)
     *
     * @example
     * ```typescript
     * function draw() {
     *   const data = analyzer.getFrequencyData()
     *   for (let i = 0; i < data.length; i++) {
     *     const barHeight = data[i] / 255 * canvas.height
     *     // Draw bar at position i with height barHeight
     *   }
     *   requestAnimationFrame(draw)
     * }
     * ```
     */
    getFrequencyData(): Uint8Array;
    /**
     * Get waveform (time domain) data as unsigned byte array.
     * Call this in requestAnimationFrame for oscilloscope visualization.
     *
     * Value of 128 represents zero crossing (silence).
     * Values above 128 = positive amplitude, below 128 = negative amplitude.
     *
     * @returns Uint8Array of waveform samples (same reference, use immediately or copy)
     *
     * @example
     * ```typescript
     * function draw() {
     *   const data = analyzer.getTimeDomainData()
     *   for (let i = 0; i < data.length; i++) {
     *     const y = data[i] / 255 * canvas.height
     *     // Draw point at (i, y) for oscilloscope line
     *   }
     *   requestAnimationFrame(draw)
     * }
     * ```
     */
    getTimeDomainData(): Uint8Array;
    /**
     * Get precise frequency data as Float32Array with dB values.
     * Use when you need accurate dB readings rather than normalized 0-255 values.
     *
     * Values are in decibels, typically ranging from minDecibels to maxDecibels.
     *
     * @returns Float32Array of dB values (same reference, use immediately or copy)
     *
     * @example
     * ```typescript
     * const data = analyzer.getFloatFrequencyData()
     * const peakDb = Math.max(...data)
     * console.log(`Peak frequency at ${peakDb} dB`)
     * ```
     */
    getFloatFrequencyData(): Float32Array;
}
/**
 * Factory function to create an Analyzer.
 *
 * @param audioContext - The AudioContext to use
 * @param options - Optional analyzer configuration
 * @returns Analyzer instance
 *
 * @example
 * ```typescript
 * const analyzer = createAnalyzer(audioContext, { fftSize: 1024 })
 * sound.setAnalyzer(analyzer)
 *
 * function visualize() {
 *   const freqData = analyzer.getFrequencyData()
 *   // Use freqData for visualization
 *   requestAnimationFrame(visualize)
 * }
 * visualize()
 * ```
 */
export declare function createAnalyzer(audioContext: AudioContext, options?: AnalyzerOptions): Analyzer;
//# sourceMappingURL=analyzer.d.ts.map