@audio/filter 3.0.0

package/LICENSE

@@ -0,0 +1,40 @@
+Kṛṣnized
+
+This is a reminder that, in the absolute sense, all results of work belong to the Supreme.
+
+While software and intellectual property (IP) require a formal license to define authorship,
+responsibilities, or distribution limitations, these are temporary material designations.
+The origin and destination of all ideas, as well as the ultimate owner of all results,
+is the Supreme. The most meaningful action is to dedicate these results to the Supreme.
+This process is known as Karma-Yoga and is described in BG 3.9, BG 12.10 and BG 18.46.
+
+"Work done as a sacrifice for the Supreme must be performed;
+otherwise, work binds one to the material world."
+
+This license does not override or alter the terms specified by the material-level license below.
+
+ॐ
+
+---
+
+MIT License
+
+Copyright (c) Dmitry Iv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/index.d.ts

@@ -0,0 +1,121 @@
+// @audio/filter — TypeScript declarations
+
+export type Buf = Float32Array | Float64Array | number[]
+export interface BiquadCoef { b0: number; b1: number; b2: number; a1: number; a2: number }
+export type SOS = BiquadCoef[]
+
+export interface LadderParams {
+  fc?: number        // cutoff frequency Hz (default 1000)
+  resonance?: number // 0–1, self-oscillation at 1 (moogLadder) / ≈1.15–1.2 (diodeLadder)
+  fs?: number        // sample rate (default 44100)
+  drive?: number     // input drive / saturation amount (default 1)
+  [key: string]: unknown
+}
+
+/** Moog 4-pole transistor ladder lowpass — ZDF, –24 dB/oct, self-oscillates at resonance=1 */
+export function moogLadder(data: Buf, params: LadderParams): Buf
+
+/** Diode ladder lowpass (Roland TB-303 style) — bidirectionally-coupled ZDF tridiagonal solve, –24 dB/oct, self-oscillates at resonance≈1.15–1.2 */
+export function diodeLadder(data: Buf, params: LadderParams): Buf
+
+export interface Korg35Params extends LadderParams {
+  type?: 'lowpass' | 'highpass' // default 'lowpass'. Never self-oscillates (2-pole loop can't reach -180° phase at finite frequency); LP+HP=input holds exactly only at resonance=0
+}
+
+/** Korg35 2-pole filter (MS-20 style) — ZDF, –12 dB/oct */
+export function korg35(data: Buf, params: Korg35Params): Buf
+
+export interface OberheimParams {
+  fc?: number        // cutoff frequency Hz (default 1000)
+  resonance?: number // 0–1 (default 0), maps to SVF damping R=1-resonance; peak gain 1/(2R)
+  type?: 'lowpass' | 'highpass' | 'bandpass' | 'notch' // default 'lowpass'
+  fs?: number        // sample rate (default 44100)
+  [key: string]: unknown
+}
+
+/** Oberheim SEM 2-pole state-variable filter — ZDF, –12 dB/oct, multimode. No drive param. */
+export function oberheim(data: Buf, params: OberheimParams): Buf
+
+export interface DcBlockerParams { R?: number; [key: string]: unknown } // R default 0.995
+/** DC blocking filter H(z) = (1−z⁻¹)/(1−R·z⁻¹) */
+export function dcBlocker(data: Buf, params?: DcBlockerParams): Buf
+
+export interface CombParams {
+  delay: number      // delay in samples
+  gain?: number      // feedback/feedforward gain (default 0.5)
+  type?: 'feedforward' | 'feedback' // default 'feedforward'
+  [key: string]: unknown
+}
+/** Comb filter (feedforward FIR or feedback IIR). Reallocates the delay line when params.delay changes on a reused params object. */
+export function comb(data: Buf, params: CombParams): Buf
+
+export interface AllpassParams { a?: number; fc?: number; Q?: number; fs?: number; [key: string]: unknown }
+/** Allpass filters — unity magnitude, frequency-dependent phase shift */
+export declare namespace allpass {
+  /** First-order allpass: H(z) = (a + z⁻¹) / (1 + a·z⁻¹). params.a is required for meaningful output. */
+  function first(data: Buf, params: AllpassParams): Buf
+  /** Second-order allpass via RBJ biquad. params.fc required, Q default 0.707, fs default 44100. */
+  function second(data: Buf, params: AllpassParams): Buf
+}
+
+export interface EmphasisParams { alpha?: number; [key: string]: unknown } // alpha default 0.97
+/** Pre-emphasis H(z) = 1 − α·z⁻¹ */
+export function emphasis(data: Buf, params?: EmphasisParams): Buf
+/** De-emphasis H(z) = 1/(1 − α·z⁻¹) */
+export function deemphasis(data: Buf, params?: EmphasisParams): Buf
+
+export interface ResonatorParams { fc: number; bw?: number; fs?: number; [key: string]: unknown } // bw default 50
+/** Constant-peak-gain resonator (JOS two-zero form) — modal synthesis (bells, drums, formants). Peak gain is exactly 0dB at fc for any bw. Throws if params.fc is omitted. */
+export function resonator(data: Buf, params: ResonatorParams): Buf
+
+export interface SpectralTiltParams { slope?: number; fs?: number; [key: string]: unknown } // slope default 0 (dB/octave, positive = boost highs)
+/** Spectral tilt — cascade of octave-spaced first-order shelving sections, ±dB/oct */
+export function spectralTilt(data: Buf, params?: SpectralTiltParams): Buf
+
+export interface VariableBandwidthParams {
+  fc?: number        // default 1000
+  Q?: number         // default 0.707
+  fs?: number        // default 44100
+  type?: 'lowpass' | 'highpass' | 'bandpass' // default 'lowpass'
+  [key: string]: unknown
+}
+/** Variable-bandwidth biquad filter — fc/Q exponentially smoothed (5ms time constant) and coefficients recomputed every sample, eliminating coefficient-jump clicks on mid-stream parameter changes */
+export function variableBandwidth(data: Buf, params?: VariableBandwidthParams): Buf
+
+export interface FilterParams {
+  fc: number         // cutoff/center frequency Hz — required, throws if omitted
+  Q?: number         // quality factor (default 0.707)
+  order?: number     // filter order: 2 = biquad, 4+ = Butterworth cascade (default 2)
+  fs?: number        // sample rate (default 44100)
+  [key: string]: unknown
+}
+
+type Butterworth = (order: number, fc: number, fs: number, type: 'lowpass' | 'highpass') => SOS
+
+/** Highpass filter — removes below cutoff. Order 2: RBJ biquad. Order 4+: Butterworth SOS (requires highpass.useButterworth(butterworth) to be called once, see digital-filter/iir/butterworth.js). Throws if params.fc is omitted. */
+export function highpass(data: Buf, params: FilterParams): Buf
+export declare namespace highpass { function useButterworth(bw: Butterworth): void }
+
+/** Lowpass filter — removes above cutoff. Order 2: RBJ biquad. Order 4+: Butterworth SOS (requires lowpass.useButterworth(butterworth) to be called once, see digital-filter/iir/butterworth.js). Throws if params.fc is omitted. */
+export function lowpass(data: Buf, params: FilterParams): Buf
+export declare namespace lowpass { function useButterworth(bw: Butterworth): void }
+
+export interface BandpassParams {
+  fc: number         // center frequency Hz — required, throws if omitted
+  Q?: number         // quality factor (default 0.707)
+  fs?: number        // sample rate (default 44100)
+  [key: string]: unknown
+}
+
+/** Bandpass filter — passes around center frequency, rejects rest. RBJ biquad (constant 0dB peak gain). Throws if params.fc is omitted. */
+export function bandpass(data: Buf, params: BandpassParams): Buf
+
+export interface NotchParams {
+  fc: number         // notch frequency Hz — required, throws if omitted
+  Q?: number         // quality factor (default 30)
+  fs?: number        // sample rate (default 44100)
+  [key: string]: unknown
+}
+
+/** Notch (band-reject) filter — unity gain except null at fc. Throws if params.fc is omitted. */
+export function notch(data: Buf, params: NotchParams): Buf

package/index.js

@@ -0,0 +1,16 @@
+// @audio/filter — audio-facing filters umbrella re-exporting every @audio/filter-* atom.
+// For smaller bundles, depend directly on the individual atom.
+// Weighting → @audio/weighting, auditory banks → @audio/auditory, EQ → @audio/eq,
+// crossfeed → @audio/spatial-crossfeed, speech atoms → @audio/speech-* (in this repo).
+
+export { highpass, lowpass, bandpass, notch, allpass } from '@audio/filter-biquad'
+export { default as comb } from '@audio/filter-comb'
+export { default as dcBlocker } from '@audio/filter-dcblocker'
+export { default as resonator } from '@audio/filter-resonator'
+export { default as variableBandwidth } from '@audio/filter-variable'
+export { emphasis, deemphasis } from '@audio/filter-preemphasis'
+export { default as spectralTilt } from '@audio/filter-spectral-tilt'
+export { default as moogLadder } from '@audio/filter-moog-ladder'
+export { default as diodeLadder } from '@audio/filter-diode-ladder'
+export { default as korg35 } from '@audio/filter-korg35'
+export { default as oberheim } from '@audio/filter-oberheim'

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@audio/filter",
+  "version": "3.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Audio-facing filters — umbrella for @audio/filter-* atoms (biquads, comb, resonator, DC blocker, pre-emphasis, spectral tilt, analog ladder models)",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./index.d.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node test.js",
+    "test:types": "tsc --noEmit --strict --module nodenext --moduleResolution nodenext test/types.ts",
+    "test:all": "npm test --workspaces --if-present && npm test",
+    "plot": "node plot/generate.js",
+    "publish:all": "npm publish --workspaces && npm publish"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/filter.git"
+  },
+  "bugs": {
+    "url": "https://github.com/audiojs/filter/issues"
+  },
+  "homepage": "https://github.com/audiojs/filter#readme",
+  "keywords": [
+    "audio",
+    "dsp",
+    "filter",
+    "a-weighting",
+    "c-weighting",
+    "k-weighting",
+    "itu-468",
+    "riaa",
+    "equalizer",
+    "parametric-eq",
+    "graphic-eq",
+    "crossover",
+    "crossfeed",
+    "moog",
+    "korg",
+    "diode-ladder",
+    "vocoder",
+    "formant",
+    "gammatone",
+    "bark",
+    "erb",
+    "octave-band",
+    "psychoacoustics",
+    "signal-processing"
+  ],
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@audio/filter-biquad": "^1.0.0",
+    "@audio/filter-comb": "^1.0.0",
+    "@audio/filter-dcblocker": "^1.0.0",
+    "@audio/filter-resonator": "^1.0.0",
+    "@audio/filter-variable": "^1.0.0",
+    "@audio/filter-preemphasis": "^1.0.0",
+    "@audio/filter-spectral-tilt": "^1.0.0",
+    "@audio/filter-moog-ladder": "^1.0.0",
+    "@audio/filter-diode-ladder": "^1.0.0",
+    "@audio/filter-korg35": "^1.0.0",
+    "@audio/filter-oberheim": "^1.0.0"
+  },
+  "devDependencies": {
+    "tst": "^9.4.0",
+    "typescript": "^5.8.2"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js"
+}