@audio/dynamics 0.2.0

package/LICENSE

@@ -0,0 +1,25 @@
+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.
+
+---
+
+This work is offered under the Krishnized License (https://github.com/krishnized/license).

package/README.md

@@ -0,0 +1,276 @@
+## @audio/dynamics [![test](https://github.com/audiojs/dynamics/actions/workflows/test.yml/badge.svg)](https://github.com/audiojs/dynamics/actions/workflows/test.yml) [![npm](https://img.shields.io/npm/v/@audio/dynamics)](https://npmjs.org/dynamics-processor) [![license](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/audiojs/dynamics/blob/main/LICENSE)
+
+Dynamics processing — compressor, limiter, gate, expander, de-esser, ducker, softclip, compand. All built on a single branching envelope follower; differences are purely in the gain curve. Part of [audiojs](https://github.com/audiojs).
+
+| | Kind | Gain function | Typical use |
+|---|---|---|---|
+| [compressor](#compressor) | envelope | soft-knee above threshold | leveling vocals, mix glue |
+| [limiter](#limiter) | lookahead | brickwall at ceiling | master bus, peak control |
+| [gate](#gate) | envelope | hard cut below threshold | silence between phrases |
+| [expander](#expander) | envelope | gentle below-threshold reduction | soft gating, noise bed shaping |
+| [deesser](#deesser) | sidechain | compressor on sibilance band | harsh 's' / 't' in voice |
+| [ducker](#ducker) | ext. sidechain | compressor keyed by side signal | music-under-voice, podcast |
+| [softclip](#softclip) | waveshaper | static transfer curve | gentle peak limiting + coloration |
+| [compand](#compand) | envelope | piecewise-linear transfer | SoX-style multi-segment |
+
+
+## Usage
+
+```
+npm install @audio/dynamics
+```
+
+```js
+import { compressor, limiter, gate, ducker } from '@audio/dynamics'
+
+let glued = compressor(samples, { threshold: -18, ratio: 4, attack: 5, release: 100 })
+let safe = limiter(glued, { ceiling: -0.3, lookahead: 5 })
+
+let write = compressor({ threshold: -18, ratio: 4 })    // streaming
+write(block1)
+write(block2)
+write()                                                  // → remaining samples
+
+let ducked = ducker(music, voice, { threshold: -30, range: -12 })
+```
+
+> Mono `Float32Array` in/out. For stereo, process channels independently or feed a linked detector. Sample rate defaults to 44100; pass `sampleRate` for anything else.
+
+
+## envelope
+
+Every processor except `softclip` is built on this: a branching one-pole follower with separate attack/release time constants, peak or RMS detection.
+
+```js
+import { envelope } from '@audio/dynamics'
+
+let follow = envelope({ attack: 5, release: 100, detector: 'peak' })
+let level = []
+for (let x of samples) level.push(follow(x))
+```
+
+| Param | Default | |
+|---|---|---|
+| `sampleRate` | `44100` | — |
+| `attack` | `5` | ms |
+| `release` | `50` | ms |
+| `detector` | `'peak'` | `'peak'` or `'rms'` |
+| `rmsWindow` | `256` | samples, for RMS detector |
+
+
+## compressor
+
+Feed-forward soft-knee downward compressor — Giannoulis-Massberg topology. Envelope → log domain → quadratic soft-knee gain curve → linear gain applied to input.
+
+```js
+import { compressor } from '@audio/dynamics'
+
+compressor(data, { threshold: -18, ratio: 4 })
+compressor(data, { threshold: -24, ratio: 2, knee: 12, attack: 10, release: 200, makeup: 6 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `threshold` | `-20` | dB |
+| `ratio` | `4` | — |
+| `knee` | `6` | dB (soft-knee width) |
+| `attack` | `5` | ms |
+| `release` | `100` | ms |
+| `makeup` | `0` | dB |
+
+**Use when:** vocals, bass, drum bus, mix glue.<br>
+**Not for:** peak control at the master bus — use [limiter](#limiter). Transparent loudness shaping — use [compand](#compand) with gentle slope.
+
+
+## limiter
+
+Lookahead brickwall limiter. A sliding-window maximum over the lookahead span drives the envelope, so gain reduction always covers every sample in transit — instant attack `lookahead` ms before a peak emerges, exponential release after it passes.
+
+```js
+import { limiter } from '@audio/dynamics'
+
+limiter(data, { ceiling: -0.3 })
+limiter(data, { ceiling: -1, lookahead: 10, release: 100 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `ceiling` | `-0.3` | dB (brickwall) |
+| `lookahead` | `5` | ms (introduces delay) |
+| `release` | `50` | ms |
+
+**Use when:** master bus ceiling, true-peak safety, preventing inter-sample clipping.<br>
+**Not for:** musical dynamics shaping — use [compressor](#compressor). Low-latency paths — use [softclip](#softclip).
+
+
+## gate
+
+Noise gate with hold-then-close logic. Below threshold, signal is attenuated by `range` dB. A `hold` timer keeps the gate open after a drop-out to avoid chatter; attack/release smooth the gain transitions.
+
+```js
+import { gate } from '@audio/dynamics'
+
+gate(data, { threshold: -40 })
+gate(data, { threshold: -35, range: -80, hold: 20, attack: 1, release: 150 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `threshold` | `-40` | dB |
+| `range` | `-60` | dB attenuation when closed |
+| `hold` | `10` | ms |
+| `attack` | `0.1` | ms (opening) |
+| `release` | `100` | ms (closing) |
+
+**Use when:** drum mics, voice dialogue with ambient noise, removing hiss between phrases.<br>
+**Not for:** subtle low-level reduction — use [expander](#expander).
+
+
+## expander
+
+Downward expander — a softer gate. Below threshold, gain is reduced by `(threshold − level) × (ratio − 1)` dB, clamped at `range`.
+
+```js
+import { expander } from '@audio/dynamics'
+
+expander(data, { threshold: -30, ratio: 2 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `threshold` | `-30` | dB |
+| `ratio` | `2` | — |
+| `knee` | `6` | dB |
+| `range` | `-40` | dB, max reduction |
+| `attack` | `5` | ms |
+| `release` | `50` | ms |
+
+**Use when:** gentle noise-floor suppression without the abruptness of a gate.<br>
+**Not for:** hard removal of sound between phrases — use [gate](#gate).
+
+
+## deesser
+
+Sibilance compressor. A biquad bandpass drives the envelope follower; the resulting gain reduction is applied broadband. Simple and transparent.
+
+```js
+import { deesser } from '@audio/dynamics'
+
+deesser(data, { freq: 6500, threshold: -20 })
+deesser(data, { freq: 5500, q: 3, threshold: -24, ratio: 6 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `freq` | `6500` | Hz, sibilance center |
+| `q` | `2` | bandpass Q |
+| `threshold` | `-20` | dB (on sidechain level) |
+| `ratio` | `4` | — |
+| `knee` | `6` | dB |
+| `attack` | `1` | ms |
+| `release` | `40` | ms |
+
+**Use when:** harsh 's' / 't' / 'sh' in close-miked voice, bright vocal takes.<br>
+**Not for:** broadband brightness — use an EQ. Generic compression — use [compressor](#compressor).
+
+
+## ducker
+
+External-sidechain compressor. Main signal's gain tracks the level of a separate side signal.
+
+```js
+import { ducker } from '@audio/dynamics'
+
+// batch
+let podcast = ducker(music, voice, { threshold: -30, range: -12 })
+
+// streaming — callable takes (main, side); call with no args to flush
+let duck = ducker({ threshold: -30, range: -15 })
+let out1 = duck(musicBlock1, voiceBlock1)
+let out2 = duck(musicBlock2, voiceBlock2)
+let tail = duck()
+```
+
+| Param | Default | |
+|---|---|---|
+| `threshold` | `-30` | dB (on side level) |
+| `ratio` | `4` | — |
+| `knee` | `6` | dB |
+| `range` | `-24` | dB, max reduction |
+| `attack` | `20` | ms |
+| `release` | `300` | ms |
+
+**Use when:** music-under-voice podcasts, dialogue ducking, sidechain-pumped mixes.<br>
+**Not for:** sidechain from the same signal — use [compressor](#compressor).
+
+
+## softclip
+
+Static waveshaping — no time state, no pumping. Maps input through a fixed transfer curve; peaks saturate smoothly, introducing controlled harmonic content.
+
+```js
+import { softclip } from '@audio/dynamics'
+
+softclip(data, { curve: 'tanh', drive: 1.5 })
+softclip(data, { curve: 'cubic', drive: 2, ceiling: 0.9 })
+```
+
+| Param | Default | |
+|---|---|---|
+| `curve` | `'tanh'` | `'tanh'`, `'atan'`, `'cubic'`, `'sin'`, `'hard'` |
+| `drive` | `1` | input pre-gain |
+| `ceiling` | `1` | output asymptote |
+
+**Use when:** gentle peak control with musical saturation, avoiding pumping artifacts of a limiter, lo-fi character.<br>
+**Not for:** transparent true-peak safety — use [limiter](#limiter). Clean gain reduction — use [compressor](#compressor).
+
+
+## compand
+
+SoX-style multi-segment compander. Arbitrary piecewise-linear transfer in dB unifies compression, expansion, and gating under one curve — points below the identity line compress; above, they expand.
+
+```js
+import { compand } from '@audio/dynamics'
+
+// Default: compress above -20 dB
+compand(data)
+
+// Broadcast leveler: lift -40..-20 dB, compress above -10 dB
+compand(data, {
+  points: [[-90, -90], [-40, -30], [-20, -18], [-10, -10], [0, -4]],
+  attack: 20, release: 500
+})
+```
+
+| Param | Default | |
+|---|---|---|
+| `points` | `[[-90,-90],[-60,-60],[-20,-20],[0,-8]]` | `[[inDb, outDb], ...]` |
+| `attack` | `5` | ms |
+| `release` | `200` | ms |
+
+**Use when:** broadcast leveling, speech normalization, any time a single compressor's fixed ratio is too rigid.<br>
+**Not for:** simple threshold compression — use [compressor](#compressor).
+
+
+## See also
+
+* [denoise](https://github.com/audiojs/denoise) — gate belongs here too; umbrella for everything noise
+* [filter](https://github.com/audiojs/filter) — biquads for deesser sidechain
+* [effect](https://github.com/audiojs/effect) — modulation effects
+* [stretch](https://github.com/audiojs/stretch) — sibling package
+
+
+## References
+
+* Giannoulis, D., Massberg, M. & Reiss, J.D. (2012). "Digital dynamic range compressor design — a tutorial and analysis." _JAES_, 60(6).
+* Zölzer, U. (ed., 2011). _DAFX — Digital Audio Effects_ (2nd ed.), chapter on dynamics processing.
+* Reiss, J.D. & McPherson, A. (2014). _Audio Effects — Theory, Implementation and Application_, Ch. 6.
+* Bristow-Johnson, R. (2005). "Audio EQ Cookbook." (RBJ biquad formulae, used in deesser sidechain.)
+* SoX manual — `compand` (piecewise-linear compander semantics).
+
+
+<div align="center">
+
+[MIT](https://github.com/audiojs/dynamics/blob/main/LICENSE) [ॐ](https://github.com/krishnized/license)
+
+</div>

package/index.d.ts

@@ -0,0 +1,104 @@
+type Writer = (chunk?: Float32Array) => Float32Array
+type Writer2 = (main?: Float32Array, side?: Float32Array) => Float32Array
+
+export interface EnvelopeOpts {
+  sampleRate?: number
+  attack?: number       // ms
+  release?: number      // ms
+  detector?: 'peak' | 'rms'
+  rmsWindow?: number    // samples
+}
+
+export interface CompressorOpts extends EnvelopeOpts {
+  threshold?: number    // dB
+  ratio?: number
+  knee?: number         // dB
+  makeup?: number       // dB
+}
+
+export interface LimiterOpts {
+  sampleRate?: number
+  ceiling?: number      // dB (e.g. -0.3)
+  lookahead?: number    // ms
+  release?: number      // ms
+}
+
+export interface GateOpts extends EnvelopeOpts {
+  threshold?: number    // dB
+  range?: number        // dB reduction when closed (e.g. -60)
+  hold?: number         // ms
+}
+
+export interface ExpanderOpts extends EnvelopeOpts {
+  threshold?: number
+  ratio?: number
+  knee?: number
+  range?: number        // dB, max reduction (e.g. -40)
+}
+
+export interface DeesserOpts extends EnvelopeOpts {
+  freq?: number         // Hz, sibilance center
+  q?: number
+  threshold?: number
+  ratio?: number
+  knee?: number
+}
+
+export interface DuckerOpts extends EnvelopeOpts {
+  threshold?: number
+  ratio?: number
+  knee?: number
+  range?: number        // dB, max reduction
+}
+
+export interface SoftclipOpts {
+  curve?: 'tanh' | 'atan' | 'cubic' | 'sin' | 'hard'
+  drive?: number
+  ceiling?: number
+}
+
+export interface CompandOpts extends EnvelopeOpts {
+  points?: [number, number][]   // [[inDb, outDb], ...]
+}
+
+export declare const compressor: {
+  (data: Float32Array, opts?: CompressorOpts): Float32Array
+  (opts?: CompressorOpts): Writer
+}
+
+export declare const limiter: {
+  (data: Float32Array, opts?: LimiterOpts): Float32Array
+  (opts?: LimiterOpts): Writer
+}
+
+export declare const gate: {
+  (data: Float32Array, opts?: GateOpts): Float32Array
+  (opts?: GateOpts): Writer
+}
+
+export declare const expander: {
+  (data: Float32Array, opts?: ExpanderOpts): Float32Array
+  (opts?: ExpanderOpts): Writer
+}
+
+export declare const deesser: {
+  (data: Float32Array, opts?: DeesserOpts): Float32Array
+  (opts?: DeesserOpts): Writer
+}
+
+export declare const ducker: {
+  (main: Float32Array, side: Float32Array, opts?: DuckerOpts): Float32Array
+  (opts?: DuckerOpts): Writer2
+}
+
+export declare const softclip: {
+  (data: Float32Array, opts?: SoftclipOpts): Float32Array
+  (opts?: SoftclipOpts): Writer
+}
+
+export declare const compand: {
+  (data: Float32Array, opts?: CompandOpts): Float32Array
+  (opts?: CompandOpts): Writer
+}
+
+export declare function envelope(opts?: EnvelopeOpts): (x: number) => number

package/index.js

@@ -0,0 +1,19 @@
+// @audio/dynamics — dynamics processing umbrella re-exporting every @audio/dynamics-* atom.
+// For smaller bundles, depend directly on the individual atom.
+
+export { default as compressor, compressorGain } from '@audio/dynamics-compressor'
+export { default as limiter } from '@audio/dynamics-limiter'
+export { default as gate } from '@audio/dynamics-gate'
+export { default as expander } from '@audio/dynamics-expander'
+export { default as deesser } from '@audio/dynamics-deesser'
+export { default as ducker } from '@audio/dynamics-ducker'
+export { default as softclip } from '@audio/dynamics-softclip'
+export { default as compand } from '@audio/dynamics-compand'
+export { default as transientShaper } from '@audio/dynamics-transient-shaper'
+export { default as multiband } from '@audio/dynamics-multiband'
+export { envelope } from '@audio/dynamics-envelope'
+export { default as opto } from '@audio/dynamics-opto'
+export { default as fet } from '@audio/dynamics-fet'
+export { default as vca } from '@audio/dynamics-vca'
+export { default as varimu } from '@audio/dynamics-varimu'
+export { default as leveler } from '@audio/dynamics-leveler'

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "@audio/dynamics",
+  "version": "0.2.0",
+  "type": "module",
+  "types": "index.d.ts",
+  "description": "Dynamics processing — umbrella for @audio/dynamics-* atoms (compressor, limiter, gate, expander, de-esser, ducker, softclip, compand, transient shaper)",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "scripts": {
+    "test": "node test.js",
+    "test:all": "npm test --workspaces --if-present && npm test",
+    "publish:all": "npm publish --workspaces && npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/dynamics.git"
+  },
+  "keywords": [
+    "dynamics",
+    "compressor",
+    "limiter",
+    "gate",
+    "expander",
+    "deesser",
+    "ducker",
+    "softclip",
+    "compand",
+    "sidechain",
+    "audio",
+    "audiojs",
+    "dsp"
+  ],
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/audiojs/dynamics/issues"
+  },
+  "homepage": "https://github.com/audiojs/dynamics#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "tst": "^9.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "index.js",
+  "workspaces": [
+    "packages/*"
+  ],
+  "dependencies": {
+    "@audio/dynamics-core": "^0.1.0",
+    "@audio/dynamics-envelope": "^0.1.0",
+    "@audio/dynamics-compressor": "^0.1.0",
+    "@audio/dynamics-limiter": "^0.1.0",
+    "@audio/dynamics-gate": "^0.1.0",
+    "@audio/dynamics-expander": "^0.1.0",
+    "@audio/dynamics-deesser": "^0.1.0",
+    "@audio/dynamics-ducker": "^0.1.0",
+    "@audio/dynamics-softclip": "^0.1.0",
+    "@audio/dynamics-compand": "^0.1.0",
+    "@audio/dynamics-transient-shaper": "^0.1.0",
+    "@audio/dynamics-multiband": "^0.1.0",
+    "@audio/dynamics-opto": "^0.1.0",
+    "@audio/dynamics-fet": "^0.1.0",
+    "@audio/dynamics-vca": "^0.1.0",
+    "@audio/dynamics-varimu": "^0.1.0",
+    "@audio/dynamics-leveler": "^0.1.0"
+  }
+}