@harmonia-audio/effects 0.1.0

package/dist/index.d.ts

@@ -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 };

package/dist/index.js

@@ -0,0 +1,328 @@
+// src/pipeline.ts
+var EffectsPipeline = class {
+  effects = [];
+  /**
+   * Add an effect to the pipeline.
+   *
+   * @example
+   * ```ts
+   * pipeline.add(new VolumeEffect(0.5));
+   * ```
+   */
+  add(effect) {
+    this.effects.push(effect);
+    return this;
+  }
+  /**
+   * Remove an effect from the pipeline.
+   *
+   * @example
+   * ```ts
+   * pipeline.remove(volumeEffect);
+   * ```
+   */
+  remove(effect) {
+    const index = this.effects.indexOf(effect);
+    if (index !== -1) {
+      this.effects.splice(index, 1);
+    }
+    return this;
+  }
+  /**
+   * Clear all effects from the pipeline.
+   *
+   * @example
+   * ```ts
+   * pipeline.clear();
+   * ```
+   */
+  clear() {
+    for (const effect of this.effects) {
+      effect.destroy();
+    }
+    this.effects.length = 0;
+    return this;
+  }
+  /**
+   * Process audio through all effects in the pipeline.
+   *
+   * @example
+   * ```ts
+   * const processed = pipeline.process(pcmBuffer);
+   * ```
+   */
+  process(samples) {
+    let current = samples;
+    for (const effect of this.effects) {
+      current = effect.process(current);
+    }
+    return current;
+  }
+  /**
+   * Reset all effects in the pipeline.
+   *
+   * @example
+   * ```ts
+   * pipeline.reset();
+   * ```
+   */
+  reset() {
+    for (const effect of this.effects) {
+      effect.reset();
+    }
+  }
+  /**
+   * Destroy the pipeline and all effects.
+   *
+   * @example
+   * ```ts
+   * pipeline.destroy();
+   * ```
+   */
+  destroy() {
+    this.clear();
+  }
+  /** The number of effects in the pipeline. */
+  get length() {
+    return this.effects.length;
+  }
+};
+
+// src/volume.ts
+import { applyVolume } from "@harmonia-audio/native";
+var VolumeEffect = class {
+  _volume;
+  constructor(volume = 1) {
+    this._volume = Math.max(0, Math.min(volume, 10));
+  }
+  /** Get the current volume level (0.0 to 10.0). */
+  get volume() {
+    return this._volume;
+  }
+  /**
+   * Set the volume level.
+   *
+   * @example
+   * ```ts
+   * vol.setVolume(0.8);
+   * ```
+   */
+  setVolume(volume) {
+    this._volume = Math.max(0, Math.min(volume, 10));
+  }
+  process(samples) {
+    if (this._volume === 1) {
+      return samples;
+    }
+    return applyVolume(samples, this._volume);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+
+// src/equalizer.ts
+import { BiquadFilter } from "@harmonia-audio/native";
+var EqualizerEffect = class {
+  filters;
+  sampleRate;
+  constructor(bands, sampleRate = 48e3) {
+    this.sampleRate = sampleRate;
+    this.filters = bands.map(
+      (band) => BiquadFilter.peakingEq(sampleRate, band.frequency, band.q, band.gain)
+    );
+  }
+  process(samples) {
+    let current = samples;
+    for (const filter of this.filters) {
+      current = filter.process(current);
+    }
+    return current;
+  }
+  reset() {
+    for (const filter of this.filters) {
+      filter.reset();
+    }
+  }
+  destroy() {
+  }
+};
+
+// src/compressor.ts
+import { Compressor } from "@harmonia-audio/native";
+var CompressorEffect = class {
+  native;
+  constructor(options) {
+    this.native = new Compressor(
+      options.threshold,
+      options.ratio,
+      options.attack,
+      options.release,
+      options.makeupGain ?? 0,
+      options.knee ?? 6,
+      options.sampleRate ?? 48e3
+    );
+  }
+  process(samples) {
+    return this.native.process(samples);
+  }
+  reset() {
+    this.native.reset();
+  }
+  destroy() {
+  }
+};
+
+// src/noise-gate.ts
+import { NoiseGate } from "@harmonia-audio/native";
+var NoiseGateEffect = class {
+  native;
+  constructor(options) {
+    this.native = new NoiseGate(
+      options.threshold,
+      options.attack,
+      options.release,
+      options.hold,
+      options.sampleRate ?? 48e3
+    );
+  }
+  process(samples) {
+    return this.native.process(samples);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+
+// src/delay.ts
+import { Delay } from "@harmonia-audio/native";
+var DelayEffect = class {
+  native;
+  constructor(options) {
+    this.native = new Delay(
+      options.delayMs,
+      options.feedback,
+      options.wet,
+      options.sampleRate ?? 48e3
+    );
+  }
+  process(samples) {
+    return this.native.process(samples);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+
+// src/reverb.ts
+import { ConvolutionReverb } from "@harmonia-audio/native";
+var ReverbEffect = class {
+  native;
+  constructor(impulseResponse) {
+    this.native = new ConvolutionReverb(impulseResponse);
+  }
+  process(samples) {
+    return this.native.process(samples);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+
+// src/pitch-shift.ts
+import { PhaseVocoder } from "@harmonia-audio/native";
+var PitchShiftEffect = class {
+  native;
+  constructor(pitchFactor, fftSize = 2048) {
+    this.native = new PhaseVocoder(fftSize, pitchFactor);
+  }
+  /**
+   * Update the pitch factor at runtime.
+   *
+   * @example
+   * ```ts
+   * pitch.setPitchFactor(0.8);
+   * ```
+   */
+  setPitchFactor(factor) {
+    this.native.setPitchFactor(factor);
+  }
+  process(samples) {
+    return this.native.process(samples);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+
+// src/stereo-widener.ts
+import { stereoWiden, monoDownmix } from "@harmonia-audio/native";
+var StereoWidenerEffect = class {
+  _width;
+  _monoOutput;
+  constructor(width = 1, monoOutput = false) {
+    this._width = width;
+    this._monoOutput = monoOutput;
+  }
+  /**
+   * Set the stereo width.
+   *
+   * @example
+   * ```ts
+   * widener.setWidth(2.0);
+   * ```
+   */
+  setWidth(width) {
+    this._width = width;
+  }
+  process(samples) {
+    if (this._monoOutput) {
+      return monoDownmix(samples);
+    }
+    if (this._width === 1) {
+      return samples;
+    }
+    return stereoWiden(samples, this._width);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+
+// src/loudness.ts
+import { LoudnessNormalizer } from "@harmonia-audio/native";
+var LoudnessNormalizerEffect = class {
+  native;
+  constructor(options) {
+    this.native = new LoudnessNormalizer(
+      options.targetLufs,
+      options.sampleRate ?? 48e3
+    );
+  }
+  process(samples) {
+    return this.native.process(samples);
+  }
+  reset() {
+  }
+  destroy() {
+  }
+};
+export {
+  CompressorEffect,
+  DelayEffect,
+  EffectsPipeline,
+  EqualizerEffect,
+  LoudnessNormalizerEffect,
+  NoiseGateEffect,
+  PitchShiftEffect,
+  ReverbEffect,
+  StereoWidenerEffect,
+  VolumeEffect
+};
+//# sourceMappingURL=index.js.map