@audio/stretch-transient 1.0.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,26 @@
+# @audio/stretch-transient
+
+Transient-aware phase-locked vocoder (Röbel, 2003). Measures spectral flux between frames; on a sharp onset resets to the original analysis phase instead of propagating it, preserving attack sharpness on drums and plucks. Implies phase locking.
+
+```js
+import transient from '@audio/stretch-transient'
+
+transient(data, { factor: 2 })
+transient(data, { factor: 1.5, transientThreshold: 2.0 })   // less sensitive
+```
+
+| Param | Default | |
+|---|---|---|
+| `factor` | `1` | Time stretch ratio |
+| `frameSize` | `2048` | FFT size (power of 2) |
+| `hopSize` | `frameSize/4` | Hop between frames |
+| `transientThreshold` | `1.5` | Spectral flux threshold (higher = fewer resets) |
+
+**Use when:** the right default for most music — percussion, mixed sources.<br>
+**Not for:** voice/speech (use [`@audio/stretch-psola`](../stretch-psola)) or extreme stretch (use [`@audio/stretch-paulstretch`](../stretch-paulstretch)).
+
+Part of [`@audio/stretch`](../..).
+
+## License
+
+[MIT](./LICENSE) · [ॐ](https://github.com/krishnized/license/)

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@audio/stretch-transient",
+  "version": "1.0.0",
+  "description": "Transient-aware phase-locked vocoder (Röbel 2003) — preserves attacks on drums and plucks",
+  "type": "module",
+  "sideEffects": false,
+  "main": "transient.js",
+  "types": "transient.d.ts",
+  "exports": {
+    ".": "./transient.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "transient.js",
+    "transient.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@audio/stretch-core": "^1.0.0",
+    "fourier-transform": "^2.3.0"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "time-stretch",
+    "phase-vocoder",
+    "transient",
+    "onset",
+    "stft"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "homepage": "https://github.com/audiojs/stretch/tree/main/packages/stretch-transient",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/stretch.git",
+    "directory": "packages/stretch-transient"
+  },
+  "bugs": "https://github.com/audiojs/stretch/issues",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/transient.d.ts

@@ -0,0 +1,11 @@
+import type { StreamWriter, StretchOpts } from '@audio/stretch-core'
+
+export interface TransientOpts extends StretchOpts {
+  transientThreshold?: number
+}
+
+declare const transient: {
+  (data: Float32Array, opts?: TransientOpts): Float32Array
+  (opts?: TransientOpts): StreamWriter
+}
+export default transient

package/transient.js

@@ -0,0 +1,76 @@
+// Transient-aware phase-locked vocoder (Röbel, 2003). Measures spectral flux
+// between frames; on a sharp onset, resets to the original analysis phase
+// instead of propagating it — preserving attack sharpness on drums and plucks.
+// Implies phase locking.
+
+import { stftBatch, stftStream } from 'fourier-transform/stft'
+import { writer, wrapPhase, lockPhase, stretchOpts } from '@audio/stretch-core'
+
+function updateFluxStats(state, value, alpha) {
+  if (state.fluxMean == null) { state.fluxMean = value; state.fluxVar = 0; return }
+  let delta = value - state.fluxMean
+  state.fluxMean += alpha * delta
+  state.fluxVar = (1 - alpha) * (state.fluxVar + alpha * delta * delta)
+}
+
+function makeProcess(threshold) {
+  return function (mag, phase, state, ctx) {
+    let { half, anaHop, synHop, freqPerBin } = ctx
+
+    if (!state.prev) {
+      state.prev = new Float64Array(half + 1)
+      state.synPrev = new Float64Array(half + 1)
+      state.prevMag = new Float64Array(half + 1)
+      state.p = new Float64Array(half + 1)
+      state.frames = 0
+      state.cooldown = 0
+      state.first = true
+    }
+
+    let isTransient = false
+    if (!state.first) {
+      let flux = 0, energy = 0
+      for (let k = 0; k <= half; k++) {
+        let weight = 0.5 + 0.5 * k / Math.max(1, half)
+        let d = Math.log1p(mag[k]) - Math.log1p(state.prevMag[k])
+        if (d > 0) flux += d
+        energy += weight * Math.log1p(mag[k])
+      }
+      let normFlux = energy > 1e-10 ? flux / energy : 0
+      let mean = state.fluxMean ?? normFlux
+      let std = Math.sqrt(state.fluxVar ?? 0)
+      // Std floor 0.07: steady polyphonic beating measures ≤ ~0.07 normFlux (p90),
+      // genuine onsets ≥ ~0.19 — the floor keeps chord beats from firing resets.
+      isTransient = state.frames > 4 && state.cooldown === 0 &&
+        normFlux > mean + threshold * Math.max(0.07, std) && normFlux > mean * 1.35
+      updateFluxStats(state, normFlux, isTransient ? 0.3 : 0.12)
+      state.cooldown = isTransient ? 1 : Math.max(0, state.cooldown - 1)
+    }
+
+    let p = state.p
+    if (state.first || isTransient) {
+      p.set(phase)
+      state.first = false
+    } else {
+      for (let k = 0; k <= half; k++) {
+        let dp = wrapPhase(phase[k] - state.prev[k] - k * freqPerBin * anaHop)
+        p[k] = state.synPrev[k] + (k * freqPerBin + dp / anaHop) * synHop
+      }
+      lockPhase(phase, p, mag, half)
+    }
+
+    state.prev.set(phase)
+    state.synPrev.set(p)
+    state.prevMag.set(mag)
+    state.frames++
+    return { mag, phase: p }
+  }
+}
+
+export default function transient(data, opts) {
+  let threshold = (data instanceof Float32Array ? opts?.transientThreshold : data?.transientThreshold) ?? 1.5
+  let process = makeProcess(threshold)
+  if (!(data instanceof Float32Array)) return writer(stftStream(process, stretchOpts(data)))
+  if ((opts?.factor ?? 1) === 1) return new Float32Array(data)
+  return stftBatch(data, process, stretchOpts(opts))
+}