@thi.ng/colored-noise 0.3.22 → 1.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-10-28T19:08:39Z
+- **Last updated**: 2022-11-23T22:46:54Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,17 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/colored-noise@1.0.0) (2022-11-23)
+
+#### 🛑 Breaking changes
+
+- [#363](https://github.com/thi-ng/umbrella/issues/363) add ColoredNoiseOpts ([b2d1d13](https://github.com/thi-ng/umbrella/commit/b2d1d13))
+- BREAKING CHANGE: replace generator args with uniform options object
+  - add `ColoredNoiseOpts` config interface
+  - update all generators
+  - update tools/examples
+  - update readme
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/colored-noise@0.3.0) (2021-11-17)
 
 #### 🚀 Features
@@ -32,9 +43,9 @@ and/or version bumps of transitive dependencies.
 
 #### ♻️ Refactoring
 
-- update imports in all tests/pkgs ([effd591](https://github.com/thi-ng/umbrella/commit/effd591))
 - update imports in all pkgs ([5fa2b6f](https://github.com/thi-ng/umbrella/commit/5fa2b6f))
   - add .js suffix for all relative imports
+- update imports in all tests/pkgs ([effd591](https://github.com/thi-ng/umbrella/commit/effd591))
 
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/colored-noise@0.2.0) (2021-10-12)
 
@@ -55,11 +66,11 @@ and/or version bumps of transitive dependencies.
 
 #### ♻️ Refactoring
 
-- minor pkg restructure (various) ([47f88d2](https://github.com/thi-ng/umbrella/commit/47f88d2))
-- update imports ([c0d9e17](https://github.com/thi-ng/umbrella/commit/c0d9e17))
-- update all test stubs ([f2d6d53](https://github.com/thi-ng/umbrella/commit/f2d6d53))
 - update all tests in _all_ pkgs ([8b582bc](https://github.com/thi-ng/umbrella/commit/8b582bc))
   - update all to use [@thi.ng/testament](https://github.com/thi-ng/umbrella/tree/main/packages/testament)
+- update all test stubs ([f2d6d53](https://github.com/thi-ng/umbrella/commit/f2d6d53))
+- update imports ([c0d9e17](https://github.com/thi-ng/umbrella/commit/c0d9e17))
+- minor pkg restructure (various) ([47f88d2](https://github.com/thi-ng/umbrella/commit/47f88d2))
 
 ### [0.1.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/colored-noise@0.1.1) (2020-09-13)
 

package/README.md

@@ -375,7 +375,7 @@ node --experimental-repl-await
 > const coloredNoise = await import("@thi.ng/colored-noise");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 538 bytes
+Package sizes (gzipped, pre-treeshake): ESM: 562 bytes
 
 ## Dependencies
 
@@ -415,7 +415,7 @@ import { take } from "@thi.ng/transducers";
 // custom config
 import { XsAdd } from "@thi.ng/random";
 
-[...take(20, red(16, 1, new XsAdd(0xdecafbad)))]
+[...take(20, red({ bins: 16, scale: 1, rnd: new XsAdd(0xdecafbad) }))]
 // [ -0.17761799097704192, -0.10240132532836904, -0.1103387340810939, ...]
 ```
 
@@ -431,7 +431,7 @@ const FS = 44100;
 
 const signal = product(
     // wrap green noise as IGen
-    iterable(green(16), 0),
+    iterable(green({ bins: 16 }), 0),
     // apply gain envelope
     adsr({ a: 0.005 * FS, d: 0.2 * FS, s: 0 })
 );

package/api.d.ts

@@ -0,0 +1,26 @@
+import type { INorm } from "@thi.ng/random";
+export interface ColoredNoiseOpts {
+    /**
+     * Number of spectral accumulation bins.
+     *
+     * @remarks
+     * This option will be ignored by the {@link white} noise generator.
+     *
+     * Default value for {@link pink} noise is 8, for others 2.
+     */
+    bins: number;
+    /**
+     * Amplitude scale factor.
+     *
+     * @defaultValue 1
+     */
+    scale: number;
+    /**
+     * PRNG implementation (see thi.ng/random for further details & implementations)
+     *
+     * @default SYSTEM (aka Math.random)
+     */
+    rnd: INorm;
+}
+export declare const DEFAULT_OPTS: ColoredNoiseOpts;
+//# sourceMappingURL=api.d.ts.map

package/api.js

@@ -0,0 +1,6 @@
+import { SYSTEM } from "@thi.ng/random/system";
+export const DEFAULT_OPTS = {
+    bins: 2,
+    scale: 1,
+    rnd: SYSTEM,
+};

package/blue.d.ts

@@ -1,10 +1,8 @@
-import type { INorm } from "@thi.ng/random";
+import { ColoredNoiseOpts } from "./api.js";
 /**
  * High-pass filtered noise. Opposite of {@link red}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export declare function blue(n?: number, scale?: number, rnd?: INorm): Generator<number, void, unknown>;
+export declare function blue(opts?: Partial<ColoredNoiseOpts>): Generator<number, void, unknown>;
 //# sourceMappingURL=blue.d.ts.map

package/blue.js

@@ -1,18 +1,20 @@
-import { SYSTEM } from "@thi.ng/random/system";
+import { DEFAULT_OPTS } from "./api.js";
 import { preseed, sum } from "./utils.js";
 /**
  * High-pass filtered noise. Opposite of {@link red}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export function* blue(n = 2, scale = 1, rnd = SYSTEM) {
-    const state = preseed(n, scale, rnd);
+export function* blue(opts) {
+    const { bins, scale, rnd } = {
+        ...DEFAULT_OPTS,
+        ...opts,
+    };
+    const state = preseed(bins, scale, rnd);
     state.forEach((x, i) => (state[i] = i & 1 ? x : -x));
-    const invN = 1 / n;
+    const invN = 1 / bins;
     let acc = sum(state);
-    for (let i = 0, sign = -1; true; ++i >= n && (i = 0)) {
+    for (let i = 0, sign = -1; true; ++i >= bins && (i = 0)) {
         acc -= state[i];
         acc += state[i] = sign * rnd.norm(scale);
         sign ^= 0xfffffffe;

package/green.d.ts

@@ -1,11 +1,9 @@
-import type { INorm } from "@thi.ng/random";
+import type { ColoredNoiseOpts } from "./api.js";
 /**
  * Band-pass filtered noise (interleaved blue noise). Opposite of
  * {@link violet}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export declare const green: (n?: number, scale?: number, rnd?: INorm) => Generator<number, void, unknown>;
+export declare const green: (opts?: Partial<ColoredNoiseOpts>) => Generator<number, void, unknown>;
 //# sourceMappingURL=green.d.ts.map

package/green.js

@@ -1,12 +1,9 @@
-import { SYSTEM } from "@thi.ng/random/system";
 import { blue } from "./blue.js";
 import { interleave } from "./utils.js";
 /**
  * Band-pass filtered noise (interleaved blue noise). Opposite of
  * {@link violet}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export const green = (n = 2, scale = 1, rnd = SYSTEM) => interleave(blue(n, scale, rnd), blue(n, scale, rnd));
+export const green = (opts) => interleave(blue(opts), blue(opts));

package/index.d.ts

@@ -1,3 +1,4 @@
+export * from "./api.js";
 export * from "./blue.js";
 export * from "./green.js";
 export * from "./pink.js";

package/index.js

@@ -1,3 +1,4 @@
+export * from "./api.js";
 export * from "./blue.js";
 export * from "./green.js";
 export * from "./pink.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/colored-noise",
-  "version": "0.3.22",
+  "version": "1.0.0",
   "description": "Customizable O(1) ES6 generators for colored noise",
   "type": "module",
   "module": "./index.js",
@@ -34,21 +34,21 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/binary": "^3.3.8",
-    "@thi.ng/random": "^3.3.13"
+    "@thi.ng/binary": "^3.3.10",
+    "@thi.ng/random": "^3.3.15"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.5",
-    "@thi.ng/api": "^8.4.4",
-    "@thi.ng/dsp": "^4.2.19",
-    "@thi.ng/dsp-io-wav": "^2.1.25",
-    "@thi.ng/testament": "^0.3.4",
-    "@thi.ng/text-canvas": "^2.4.14",
-    "@thi.ng/transducers": "^8.3.20",
-    "@thi.ng/vectors": "^7.5.21",
+    "@thi.ng/api": "^8.4.6",
+    "@thi.ng/dsp": "^4.2.22",
+    "@thi.ng/dsp-io-wav": "^2.1.28",
+    "@thi.ng/testament": "^0.3.5",
+    "@thi.ng/text-canvas": "^2.4.17",
+    "@thi.ng/transducers": "^8.3.23",
+    "@thi.ng/vectors": "^7.5.24",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.18",
+    "typedoc": "^0.23.20",
     "typescript": "^4.8.4"
   },
   "keywords": [
@@ -74,13 +74,16 @@
     "node": ">=12.7"
   },
   "files": [
-    "*.js",
-    "*.d.ts"
+    "./*.js",
+    "./*.d.ts"
   ],
   "exports": {
     ".": {
       "default": "./index.js"
     },
+    "./api": {
+      "default": "./api.js"
+    },
     "./blue": {
       "default": "./blue.js"
     },
@@ -108,5 +111,5 @@
     ],
     "year": 2015
   },
-  "gitHead": "41e59c7ad9bf24bb0230a5f60d05715e0fc1c1e6\n"
+  "gitHead": "044ee6a3895720fc78e115032d4d831b63510929\n"
 }

package/pink.d.ts

@@ -1,4 +1,4 @@
-import type { INorm } from "@thi.ng/random";
+import { ColoredNoiseOpts } from "./api.js";
 /**
  * Exponential decay (1/f) noise, based on Voss-McCarthy algorithm.
  *
@@ -11,9 +11,7 @@ import type { INorm } from "@thi.ng/random";
  * - https://www.dsprelated.com/showarticle/908.php
  * - https://www.firstpr.com.au/dsp/pink-noise/#Voss-McCartney
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export declare function pink(n?: number, scale?: number, rnd?: INorm): Generator<number, void, unknown>;
+export declare function pink(opts?: Partial<ColoredNoiseOpts>): Generator<number, void, unknown>;
 //# sourceMappingURL=pink.d.ts.map

package/pink.js

@@ -1,5 +1,5 @@
 import { ctz32 } from "@thi.ng/binary/count";
-import { SYSTEM } from "@thi.ng/random/system";
+import { DEFAULT_OPTS } from "./api.js";
 import { preseed, sum } from "./utils.js";
 /**
  * Exponential decay (1/f) noise, based on Voss-McCarthy algorithm.
@@ -13,16 +13,19 @@ import { preseed, sum } from "./utils.js";
  * - https://www.dsprelated.com/showarticle/908.php
  * - https://www.firstpr.com.au/dsp/pink-noise/#Voss-McCartney
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export function* pink(n = 8, scale = 1, rnd = SYSTEM) {
-    const state = preseed(n, scale, rnd);
-    const invN = 1 / n;
+export function* pink(opts) {
+    const { bins, scale, rnd } = {
+        ...DEFAULT_OPTS,
+        bins: 8,
+        ...opts,
+    };
+    const state = preseed(bins, scale, rnd);
+    const invN = 1 / bins;
     let acc = sum(state);
     for (let i = 0; true; i = (i + 1) >>> 0) {
-        const id = ctz32(i) % n;
+        const id = ctz32(i) % bins;
         acc -= state[id];
         acc += state[id] = rnd.norm(scale);
         yield acc * invN;

package/red.d.ts

@@ -1,10 +1,8 @@
-import type { INorm } from "@thi.ng/random";
+import { ColoredNoiseOpts } from "./api.js";
 /**
  * Low-pass filtered noise (same as brown noise). Opposite of {@link blue}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export declare function red(n?: number, scale?: number, rnd?: INorm): Generator<number, void, unknown>;
+export declare function red(opts?: Partial<ColoredNoiseOpts>): Generator<number, void, unknown>;
 //# sourceMappingURL=red.d.ts.map

package/red.js

@@ -1,17 +1,19 @@
-import { SYSTEM } from "@thi.ng/random/system";
+import { DEFAULT_OPTS } from "./api.js";
 import { preseed, sum } from "./utils.js";
 /**
  * Low-pass filtered noise (same as brown noise). Opposite of {@link blue}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export function* red(n = 2, scale = 1, rnd = SYSTEM) {
-    const state = preseed(n, scale, rnd);
-    const invN = 1 / n;
+export function* red(opts) {
+    const { bins, scale, rnd } = {
+        ...DEFAULT_OPTS,
+        ...opts,
+    };
+    const state = preseed(bins, scale, rnd);
+    const invN = 1 / bins;
     let acc = sum(state);
-    for (let i = 0; true; ++i >= n && (i = 0)) {
+    for (let i = 0; true; ++i >= bins && (i = 0)) {
         acc -= state[i];
         acc += state[i] = rnd.norm(scale);
         yield acc * invN;

package/violet.d.ts

@@ -1,10 +1,8 @@
-import type { INorm } from "@thi.ng/random";
+import type { ColoredNoiseOpts } from "./api.js";
 /**
  * Band-stop filtered noise (interleaved red noise). Opposite of {@link green}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export declare const violet: (n?: number, scale?: number, rnd?: INorm) => Generator<number, void, unknown>;
+export declare const violet: (opts?: Partial<ColoredNoiseOpts>) => Generator<number, void, unknown>;
 //# sourceMappingURL=violet.d.ts.map

package/violet.js

@@ -1,11 +1,8 @@
-import { SYSTEM } from "@thi.ng/random/system";
 import { red } from "./red.js";
 import { interleave } from "./utils.js";
 /**
  * Band-stop filtered noise (interleaved red noise). Opposite of {@link green}.
  *
- * @param n -
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export const violet = (n = 2, scale = 1, rnd = SYSTEM) => interleave(red(n, scale, rnd), red(n, scale, rnd));
+export const violet = (opts) => interleave(red(opts), red(opts));

package/white.d.ts

@@ -1,10 +1,9 @@
-import type { INorm } from "@thi.ng/random";
+import { ColoredNoiseOpts } from "./api.js";
 /**
  * Unfiltered noise w/ uniform distribution. Merely yields samples from
  * given PRNG.
  *
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export declare function white(scale?: number, rnd?: INorm): Generator<number, void, unknown>;
+export declare function white(opts?: Partial<ColoredNoiseOpts>): Generator<number, void, unknown>;
 //# sourceMappingURL=white.d.ts.map

package/white.js

@@ -1,12 +1,12 @@
-import { SYSTEM } from "@thi.ng/random/system";
+import { DEFAULT_OPTS } from "./api.js";
 /**
  * Unfiltered noise w/ uniform distribution. Merely yields samples from
  * given PRNG.
  *
- * @param scale -
- * @param rnd -
+ * @param opts -
  */
-export function* white(scale = 1, rnd = SYSTEM) {
+export function* white(opts) {
+    const { scale, rnd } = { ...DEFAULT_OPTS, ...opts };
     while (true) {
         yield rnd.norm(scale);
     }