@harmonia-audio/effects 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,377 @@
+/**
+ * Interface for audio effects that can be chained in a pipeline.
+ *
+ * @example
+ * ```ts
+ * class MyEffect implements AudioEffect {
+ *   process(samples: Buffer): Buffer { return samples; }
+ *   reset(): void {}
+ *   destroy(): void {}
+ * }
+ * ```
+ */
+interface AudioEffect {
+    /** Process a buffer of audio samples in-place or returning a new buffer. */
+    process(samples: Buffer): Buffer;
+    /** Reset effect state (e.g., filter history). */
+    reset(): void;
+    /** Release any native resources. */
+    destroy(): void;
+}
+
+/**
+ * Chainable audio effects processing pipeline.
+ *
+ * @example
+ * ```ts
+ * import { EffectsPipeline, VolumeEffect, EqualizerEffect } from '@harmonia/effects';
+ *
+ * const pipeline = new EffectsPipeline()
+ *   .add(new VolumeEffect(0.8))
+ *   .add(new EqualizerEffect([{ frequency: 1000, gain: 3, q: 1.0 }]));
+ *
+ * const processed = pipeline.process(pcmBuffer);
+ * ```
+ */
+declare class EffectsPipeline {
+    private readonly effects;
+    /**
+     * Add an effect to the pipeline.
+     *
+     * @example
+     * ```ts
+     * pipeline.add(new VolumeEffect(0.5));
+     * ```
+     */
+    add(effect: AudioEffect): this;
+    /**
+     * Remove an effect from the pipeline.
+     *
+     * @example
+     * ```ts
+     * pipeline.remove(volumeEffect);
+     * ```
+     */
+    remove(effect: AudioEffect): this;
+    /**
+     * Clear all effects from the pipeline.
+     *
+     * @example
+     * ```ts
+     * pipeline.clear();
+     * ```
+     */
+    clear(): this;
+    /**
+     * Process audio through all effects in the pipeline.
+     *
+     * @example
+     * ```ts
+     * const processed = pipeline.process(pcmBuffer);
+     * ```
+     */
+    process(samples: Buffer): Buffer;
+    /**
+     * Reset all effects in the pipeline.
+     *
+     * @example
+     * ```ts
+     * pipeline.reset();
+     * ```
+     */
+    reset(): void;
+    /**
+     * Destroy the pipeline and all effects.
+     *
+     * @example
+     * ```ts
+     * pipeline.destroy();
+     * ```
+     */
+    destroy(): void;
+    /** The number of effects in the pipeline. */
+    get length(): number;
+}
+
+/**
+ * Volume control effect.
+ *
+ * @example
+ * ```ts
+ * const vol = new VolumeEffect(0.5); // 50% volume
+ * const output = vol.process(pcmBuffer);
+ * ```
+ */
+declare class VolumeEffect implements AudioEffect {
+    private _volume;
+    constructor(volume?: number);
+    /** Get the current volume level (0.0 to 10.0). */
+    get volume(): number;
+    /**
+     * Set the volume level.
+     *
+     * @example
+     * ```ts
+     * vol.setVolume(0.8);
+     * ```
+     */
+    setVolume(volume: number): void;
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Configuration for a single equalizer band.
+ *
+ * @example
+ * ```ts
+ * const band: EqualizerBand = { frequency: 1000, gain: 3, q: 1.0 };
+ * ```
+ */
+interface EqualizerBand {
+    readonly frequency: number;
+    readonly gain: number;
+    readonly q: number;
+}
+/**
+ * Multi-band parametric equalizer effect using biquad filters.
+ *
+ * @example
+ * ```ts
+ * const eq = new EqualizerEffect([
+ *   { frequency: 60, gain: 3, q: 0.7 },
+ *   { frequency: 1000, gain: -2, q: 1.0 },
+ *   { frequency: 8000, gain: 1, q: 1.4 },
+ * ]);
+ * const output = eq.process(pcmBuffer);
+ * ```
+ */
+declare class EqualizerEffect implements AudioEffect {
+    private readonly filters;
+    private readonly sampleRate;
+    constructor(bands: readonly EqualizerBand[], sampleRate?: number);
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for the compressor effect.
+ *
+ * @example
+ * ```ts
+ * const options: CompressorOptions = {
+ *   threshold: -20,
+ *   ratio: 4,
+ *   attack: 5,
+ *   release: 100,
+ * };
+ * ```
+ */
+interface CompressorOptions {
+    readonly threshold: number;
+    readonly ratio: number;
+    readonly attack: number;
+    readonly release: number;
+    readonly makeupGain?: number;
+    readonly knee?: number;
+    readonly sampleRate?: number;
+}
+/**
+ * Dynamic range compressor effect.
+ *
+ * @example
+ * ```ts
+ * const compressor = new CompressorEffect({
+ *   threshold: -20,
+ *   ratio: 4,
+ *   attack: 5,
+ *   release: 100,
+ * });
+ * const output = compressor.process(pcmBuffer);
+ * ```
+ */
+declare class CompressorEffect implements AudioEffect {
+    private readonly native;
+    constructor(options: CompressorOptions);
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for the noise gate effect.
+ *
+ * @example
+ * ```ts
+ * const gate = new NoiseGateEffect({ threshold: -40, attack: 1, release: 50, hold: 20 });
+ * ```
+ */
+interface NoiseGateOptions {
+    readonly threshold: number;
+    readonly attack: number;
+    readonly release: number;
+    readonly hold: number;
+    readonly sampleRate?: number;
+}
+/**
+ * Noise gate effect that silences audio below a threshold.
+ *
+ * @example
+ * ```ts
+ * const gate = new NoiseGateEffect({
+ *   threshold: -40,
+ *   attack: 1,
+ *   release: 50,
+ *   hold: 20,
+ * });
+ * const output = gate.process(pcmBuffer);
+ * ```
+ */
+declare class NoiseGateEffect implements AudioEffect {
+    private readonly native;
+    constructor(options: NoiseGateOptions);
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for the delay/echo effect.
+ *
+ * @example
+ * ```ts
+ * const delay = new DelayEffect({ delayMs: 300, feedback: 0.4, wet: 0.3 });
+ * ```
+ */
+interface DelayOptions {
+    readonly delayMs: number;
+    readonly feedback: number;
+    readonly wet: number;
+    readonly sampleRate?: number;
+}
+/**
+ * Delay/echo audio effect.
+ *
+ * @example
+ * ```ts
+ * const delay = new DelayEffect({
+ *   delayMs: 300,
+ *   feedback: 0.4,
+ *   wet: 0.3,
+ * });
+ * const output = delay.process(pcmBuffer);
+ * ```
+ */
+declare class DelayEffect implements AudioEffect {
+    private readonly native;
+    constructor(options: DelayOptions);
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Convolution reverb effect using an impulse response.
+ *
+ * @example
+ * ```ts
+ * import { readFileSync } from 'fs';
+ *
+ * const ir = readFileSync('./hall-ir.pcm');
+ * const reverb = new ReverbEffect(ir);
+ * const output = reverb.process(pcmBuffer);
+ * ```
+ */
+declare class ReverbEffect implements AudioEffect {
+    private readonly native;
+    constructor(impulseResponse: Buffer);
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Pitch shifting effect using a phase vocoder.
+ *
+ * @example
+ * ```ts
+ * const pitch = new PitchShiftEffect(1.5); // shift up by 50%
+ * const output = pitch.process(pcmBuffer);
+ * ```
+ */
+declare class PitchShiftEffect implements AudioEffect {
+    private readonly native;
+    constructor(pitchFactor: number, fftSize?: number);
+    /**
+     * Update the pitch factor at runtime.
+     *
+     * @example
+     * ```ts
+     * pitch.setPitchFactor(0.8);
+     * ```
+     */
+    setPitchFactor(factor: number): void;
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Stereo widening effect with mono downmix capability.
+ *
+ * @example
+ * ```ts
+ * const widener = new StereoWidenerEffect(1.5);
+ * const wider = widener.process(stereoBuffer);
+ * ```
+ */
+declare class StereoWidenerEffect implements AudioEffect {
+    private _width;
+    private _monoOutput;
+    constructor(width?: number, monoOutput?: boolean);
+    /**
+     * Set the stereo width.
+     *
+     * @example
+     * ```ts
+     * widener.setWidth(2.0);
+     * ```
+     */
+    setWidth(width: number): void;
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+/**
+ * Options for loudness normalization.
+ *
+ * @example
+ * ```ts
+ * const normalizer = new LoudnessNormalizerEffect({ targetLufs: -14 });
+ * ```
+ */
+interface LoudnessOptions {
+    readonly targetLufs: number;
+    readonly sampleRate?: number;
+}
+/**
+ * Loudness normalization effect targeting a specific LUFS level.
+ *
+ * @example
+ * ```ts
+ * const normalizer = new LoudnessNormalizerEffect({ targetLufs: -14 });
+ * const normalized = normalizer.process(pcmBuffer);
+ * ```
+ */
+declare class LoudnessNormalizerEffect implements AudioEffect {
+    private readonly native;
+    constructor(options: LoudnessOptions);
+    process(samples: Buffer): Buffer;
+    reset(): void;
+    destroy(): void;
+}
+
+export { type AudioEffect, CompressorEffect, type CompressorOptions, DelayEffect, type DelayOptions, EffectsPipeline, type EqualizerBand, EqualizerEffect, LoudnessNormalizerEffect, type LoudnessOptions, NoiseGateEffect, type NoiseGateOptions, PitchShiftEffect, ReverbEffect, StereoWidenerEffect, VolumeEffect };