@audio/window: own repo, split from audiojs/stft

Audio-facing window kit over window-function — typed periodic/symmetric fills,
in-place apply, COLA check. History of the original extraction lives in
audiojs/stft (formerly audiojs/primitives).

Author: dy

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

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.

README.md

@@ -0,0 +1,30 @@
+# @audio/window
+
+> Audio-facing window kit — typed fills (periodic/symmetric), in-place apply, COLA check.
+
+Thin layer over [`window-function`](https://github.com/scijs/window-function) (scijs — canonical per-sample math, re-exported whole): fills typed arrays with the DFT-even *periodic* variant STFT needs (or *symmetric* for filter design), and verifies constant-overlap-add for hop choices.
+
+```js
+import window, { apply, cola, hann } from '@audio/window'
+
+let w = window('hann', 1024)                     // periodic (DFT-even) — for STFT
+let sym = window('hann', 1024, { periodic: false }) // symmetric — for filter design
+
+apply(frame, w)                                  // multiply in place
+
+cola(w, 512)                                     // { ok, ripple, mean } — is this hop COLA?
+cola(w, 512, { squared: true })                  // analysis+synthesis (win²) variant
+
+hann(3, 7)                                       // any window-function export, re-exported
+```
+
+Any `window-function` name works: `hann`, `hamming`, `blackman`, `blackmanHarris`, `nuttall`, `gaussian`, `tukey`, `kaiser`, …
+
+## See also
+
+- [`@audio/stft`](https://github.com/audiojs/stft) — the canonical STFT this pairs with (its internal `hannWindow` is consistency-tested against this package)
+- [`window-function`](https://github.com/scijs/window-function) — the per-sample math underneath (scijs layer)
+
+## License
+
+MIT

package-lock.json

@@ -0,0 +1,49 @@
+{
+  "name": "@audio/window",
+  "version": "1.0.2",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Audio-facing window kit — typed fills (periodic/symmetric), apply, COLA check over window-function",
+  "main": "window.js",
+  "exports": {
+    ".": "./window.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "window.js"
+  ],
+  "dependencies": {
+    "window-function": "^3.0.1"
+  },
+  "keywords": [
+    "audio",
+    "dsp",
+    "window",
+    "hann",
+    "cola",
+    "stft"
+  ],
+  "license": "MIT",
+  "author": "Dmitry Iv. <dfcreative@gmail.com>",
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/audiojs/window.git"
+  },
+  "homepage": "https://github.com/audiojs/window#readme",
+  "bugs": {
+    "url": "https://github.com/audiojs/window/issues"
+  },
+  "scripts": {
+    "test": "node test.js"
+  },
+  "devDependencies": {
+    "tst": "^9.4.0",
+    "@audio/stft": "^1.0.1"
+  }
+}

package.json

@@ -0,0 +1,32 @@
+import test, { almost, ok, is } from 'tst'
+import window, { apply, cola, hann } from './window.js'
+import { hannWindow } from '@audio/stft'
+
+function maxDiff (a, b) {
+	let m = 0
+	for (let i = 0; i < Math.min(a.length, b.length); i++) m = Math.max(m, Math.abs(a[i] - b[i]))
+	return m
+}
+
+test('window — periodic hann COLA at N/2 and N/4 hops; symmetric differs', () => {
+	let w = window('hann', 1024)
+	ok(cola(w, 512).ok, 'hop N/2 COLA')
+	ok(cola(w, 256).ok, 'hop N/4 COLA')
+	let sym = window('hann', 1024, { periodic: false })
+	ok(!cola(sym, 512).ok, 'symmetric hann is not COLA at N/2')
+	almost(w[0], 0, 1e-12)
+	ok(Math.abs(sym[0] - sym[1023]) < 1e-12, 'symmetric endpoints match')
+	// consistency with the ecosystem's internal hannWindow
+	let hw = hannWindow(1024)
+	ok(maxDiff(w, hw) < 1e-12, 'matches @audio/stft hannWindow')
+})
+
+test('window — apply, unknown name throws, re-exports window-function', () => {
+	let d = Float64Array.from([1, 1, 1, 1])
+	apply(d, Float64Array.from([0.5, 1, 0.5, 1]))
+	almost(d[0], 0.5, 1e-12)
+	let threw = false
+	try { window('nosuch', 64) } catch { threw = true }
+	ok(threw)
+	is(typeof hann, 'function')
+})

test.js

@@ -0,0 +1,42 @@
+// Audio-facing window kit over window-function (scijs, canonical per-sample math):
+// typed-array fill with symmetric/periodic variants, in-place apply, and COLA
+// (constant-overlap-add) verification for STFT hop choices.
+
+import * as wf from 'window-function'
+
+/**
+ * Fill a Float64Array with the named window.
+ * @param {string} name — any window-function export (hann, hamming, blackman, …)
+ * @param {number} N — length
+ * @param {object} opts — { periodic=true } — periodic (DFT-even, for STFT) vs symmetric (filter design)
+ */
+export default function window (name, N, { periodic = true } = {}) {
+	let fn = wf[name]
+	if (typeof fn !== 'function') throw new RangeError(`window: unknown window "${name}"`)
+	let out = new Float64Array(N)
+	let M = periodic ? N + 1 : N
+	for (let i = 0; i < N; i++) out[i] = fn(i, M)
+	return out
+}
+
+/** Multiply data by win in place. */
+export function apply (data, win) {
+	for (let i = 0; i < data.length; i++) data[i] *= win[i % win.length]
+	return data
+}
+
+/**
+ * COLA check: does Σ win(n − m·hop) (or win² with {squared}) stay constant?
+ * @returns {{ ok, ripple, mean }} — ripple = (max−min)/mean over the steady region
+ */
+export function cola (win, hop, { squared = false, tolerance = 1e-6 } = {}) {
+	let N = win.length
+	let sum = new Float64Array(hop)
+	for (let i = 0; i < hop; i++)
+		for (let j = i; j < N; j += hop) sum[i] += squared ? win[j] * win[j] : win[j]
+	let min = Math.min(...sum), max = Math.max(...sum)
+	let mean = sum.reduce((a, x) => a + x, 0) / hop
+	return { ok: mean > 0 && (max - min) / mean < tolerance, ripple: mean > 0 ? (max - min) / mean : Infinity, mean }
+}
+
+export * from 'window-function'