@audio/defeedback 1.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/README.md

@@ -0,0 +1,15 @@
+# @audio/defeedback
+
+> Adaptive feedback (howling) suppression — live-sound AFS class, **zero-latency direct path**.
+
+| Package | What |
+|---|---|
+| `@audio/defeedback-analyzer` | spectral peaks + PNPR/PHPR howl criteria, parabolic freqs, relational harmonic gate (Waterschoot & Moonen 2011) |
+| `@audio/defeedback-tracker` | persistence/stability/growth gating — the music discriminator |
+| `@audio/defeedback-notchbank` | ≤12 pooled narrow IIR cuts, click-free coefficient morphing, deepen-on-redeploy |
+
+The umbrella exports a streaming factory: `defeedback({fs, strength}) → {process(chunk), notches()}`. The audio path is pure IIR notches (0 samples latency); detection runs on the **post-notch** signal in parallel, so an insufficient notch deepens itself.
+
+Verified by tests: a growing howl over music is suppressed ≥12 dB while the music stays ±1 dB; harmonic-rich tones deploy zero notches; and a **closed electro-acoustic loop simulation** (resonant room, loop gain > 1) runs away without the suppressor and stays bounded with it inline.
+
+Design notes: detection must catch the howl pre-saturation (a clipped howl grows harmonics and reads as musical — same physics limits every AFS). Alpha Labs DeFeedback-class ML suppression (speech-trained model) is a different lane — see `@audio/neural`.

package/index.js

@@ -0,0 +1,44 @@
+// @audio/defeedback — adaptive feedback (howling) suppression, live-sound AFS class
+// (dbx AFS / Sabine): ZERO-LATENCY direct path (pure IIR notch bank, no lookahead),
+// detection runs on the post-notch signal in parallel — residual howl deepens its notch.
+// Alpha Labs DeFeedback-style ML suppression is the @audio/neural lane; this is classical.
+
+import analyze from '@audio/defeedback-analyzer'
+import tracker from '@audio/defeedback-tracker'
+import notchbank from '@audio/defeedback-notchbank'
+
+export { analyze, tracker, notchbank }
+
+/**
+ * Streaming suppressor factory.
+ * @param {object} opts — { fs=44100, window=2048, hop=1024, maxNotches=12, q=30,
+ *   strength=1 (0..1 scales notch depth), ...tracker/analyzer thresholds }
+ * @returns {{ process(chunk): chunk (in place, any block size), notches(): Array, reset() }}
+ */
+export default function defeedback ({ fs = 44100, window = 2048, hop = 1024, maxNotches = 12, q = 30, strength = 1, ...rest } = {}) {
+	let bank = notchbank({ fs, size: maxNotches, q, depth: -9 * strength, ...rest })
+	let trk = tracker(rest)
+	let ring = new Float32Array(window)
+	let fill = 0, sinceAnalysis = 0
+
+	return {
+		process (chunk) {
+			bank.process(chunk) // zero-latency direct path
+			// sidechain: accumulate post-notch signal, analyze every `hop` samples
+			for (let i = 0; i < chunk.length; i++) {
+				ring[fill % window] = chunk[i]
+				fill++
+				if (++sinceAnalysis >= hop && fill >= window) {
+					sinceAnalysis = 0
+					let frame = new Float32Array(window)
+					let start = fill % window
+					for (let j = 0; j < window; j++) frame[j] = ring[(start + j) % window]
+					for (let howl of trk.update(analyze(frame, { fs, ...rest }))) bank.deploy(howl.freq)
+				}
+			}
+			return chunk
+		},
+		notches: () => bank.notches(),
+		reset () { trk.reset() },
+	}
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@audio/defeedback",
+  "version": "1.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Adaptive feedback suppression — umbrella for @audio/defeedback-* atoms (analyzer, tracker, notch bank)",
+  "workspaces": [
+    "packages/*"
+  ],
+  "keywords": [
+    "audio",
+    "dsp",
+    "feedback",
+    "howling",
+    "notch",
+    "live-sound"
+  ],
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "test:all": "npm test --workspaces --if-present && npm test",
+    "publish:all": "npm publish --workspaces && npm publish"
+  },
+  "dependencies": {
+    "@audio/defeedback-analyzer": "^1.0.0",
+    "@audio/defeedback-tracker": "^1.0.0",
+    "@audio/defeedback-notchbank": "^1.0.0"
+  },
+  "devDependencies": {
+    "tst": "^9.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}