@thi.ng/dsp 4.1.3 → 4.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2021-12-13T10:26:00Z
+- **Last updated**: 2022-04-07T14:17:30Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,16 @@ 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.
 
+## [4.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/dsp@4.2.0) (2022-04-07)
+
+#### 🚀 Features
+
+- add opt Osc() ctor phase arg, fix [#340](https://github.com/thi-ng/umbrella/issues/340) ([f798c9d](https://github.com/thi-ng/umbrella/commit/f798c9d))
+  - update osc() factory fn
+  - update Osc.setFreq() signatures
+  - add tests
+  - add/update docs
+
 ## [4.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/dsp@4.1.0) (2021-11-17)
 
 #### 🚀 Features

package/README.md

@@ -86,7 +86,7 @@ node --experimental-repl-await
 > const dsp = await import("@thi.ng/dsp");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 7.54 KB
+Package sizes (gzipped, pre-treeshake): ESM: 7.56 KB
 
 ## Dependencies
 
@@ -583,4 +583,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2015 - 2021 Karsten Schmidt // Apache Software License 2.0
+© 2015 - 2022 Karsten Schmidt // Apache Software License 2.0

package/add.d.ts

@@ -6,9 +6,9 @@ import { AGen } from "./agen.js";
  * given, the resulting output will be clamped to that value (min or max depends
  * on sign of `start - clamp`).
  *
- * @param step
- * @param start
- * @param clamp
+ * @param step -
+ * @param start -
+ * @param clamp -
  */
 export declare const add: (step?: number | undefined, start?: number | undefined, clamp?: number | undefined) => Add;
 export declare class Add extends AGen<number> implements IReset {

package/add.js

@@ -5,9 +5,9 @@ import { AGen } from "./agen.js";
  * given, the resulting output will be clamped to that value (min or max depends
  * on sign of `start - clamp`).
  *
- * @param step
- * @param start
- * @param clamp
+ * @param step -
+ * @param start -
+ * @param clamp -
  */
 export const add = (step, start, clamp) => new Add(step, start, clamp);
 export class Add extends AGen {

package/addg.d.ts

@@ -14,8 +14,8 @@ import type { IGen } from "./api.js";
  * // [ 10, 11, 12, 13, 14 ]
  * ```
  *
- * @param step
- * @param start
+ * @param step -
+ * @param start -
  */
 export declare const addG: (step: IGen<number>, start?: number) => IGen<number>;
 //# sourceMappingURL=addg.d.ts.map

package/addg.js

@@ -14,7 +14,7 @@ import { MapG1 } from "./mapg.js";
  * // [ 10, 11, 12, 13, 14 ]
  * ```
  *
- * @param step
- * @param start
+ * @param step -
+ * @param start -
  */
 export const addG = (step, start = 0) => new MapG1((a, b) => a + b, step, start - step.deref());

package/const.d.ts

@@ -2,7 +2,7 @@ import { AGen } from "./agen.js";
 /**
  * Returns new gen yielding always the same given value `x`.
  *
- * @param x
+ * @param x -
  */
 export declare const constant: <T>(x: T) => Const<T>;
 export declare class Const<T> extends AGen<T> {

package/const.js

@@ -2,7 +2,7 @@ import { AGen } from "./agen.js";
 /**
  * Returns new gen yielding always the same given value `x`.
  *
- * @param x
+ * @param x -
  */
 export const constant = (x) => new Const(x);
 export class Const extends AGen {

package/convert.d.ts

@@ -3,29 +3,29 @@ import type { FnN, FnN2 } from "@thi.ng/api";
  * Returns frequency `f` normalized to sample rate `fs`:
  * `fnorm = f / fs`
  *
- * @param f
- * @param fs
+ * @param f -
+ * @param fs -
  */
 export declare const normFreq: FnN2;
 /**
  * Returns frequency `f` in radians, based on sample rate `fs`.
  * I.e. Nyquist freq = PI
  *
- * @param f
- * @param fs
+ * @param f -
+ * @param fs -
  */
 export declare const freqRad: FnN2;
 /**
  * Returns period length in milliseconds for given frequency in Hz.
  *
- * @param f
+ * @param f -
  */
 export declare const freqMs: FnN;
 /**
  * Reverse op of {@link freqRad}.
  *
- * @param rad
- * @param fs
+ * @param rad -
+ * @param fs -
  */
 export declare const radFreq: FnN2;
 /**
@@ -39,28 +39,28 @@ export declare const radFreq: FnN2;
  * // 882
  * ```
  *
- * @param t
- * @param fs
+ * @param t -
+ * @param fs -
  */
 export declare const msFrames: FnN2;
 /**
  * Reverse op of {@link msFrames}.
  *
- * @param frames
- * @param fs
+ * @param frames -
+ * @param fs -
  */
 export declare const framesMs: FnN2;
 /**
  * Converts given linear magnitude to dBFS (i.e. `20 * log10(x)`)
  *
- * @param x
+ * @param x -
  */
 export declare const magDb: FnN;
 /**
  * Converts given dBFS value to linear magnitude
  * (i.e. `pow(10, x / 20)`)
  *
- * @param x
+ * @param x -
  */
 export declare const dbMag: FnN;
 //# sourceMappingURL=convert.d.ts.map

package/convert.js

@@ -3,29 +3,29 @@ import { TAU } from "@thi.ng/math/api";
  * Returns frequency `f` normalized to sample rate `fs`:
  * `fnorm = f / fs`
  *
- * @param f
- * @param fs
+ * @param f -
+ * @param fs -
  */
 export const normFreq = (f, fs) => f / fs;
 /**
  * Returns frequency `f` in radians, based on sample rate `fs`.
  * I.e. Nyquist freq = PI
  *
- * @param f
- * @param fs
+ * @param f -
+ * @param fs -
  */
 export const freqRad = (f, fs) => (f / fs) * TAU;
 /**
  * Returns period length in milliseconds for given frequency in Hz.
  *
- * @param f
+ * @param f -
  */
 export const freqMs = (f) => 1000 / f;
 /**
  * Reverse op of {@link freqRad}.
  *
- * @param rad
- * @param fs
+ * @param rad -
+ * @param fs -
  */
 export const radFreq = (rad, fs) => (rad / TAU) * fs;
 /**
@@ -39,27 +39,27 @@ export const radFreq = (rad, fs) => (rad / TAU) * fs;
  * // 882
  * ```
  *
- * @param t
- * @param fs
+ * @param t -
+ * @param fs -
  */
 export const msFrames = (t, fs) => t * 0.001 * fs;
 /**
  * Reverse op of {@link msFrames}.
  *
- * @param frames
- * @param fs
+ * @param frames -
+ * @param fs -
  */
 export const framesMs = (frames, fs) => (frames / fs) * 1000;
 /**
  * Converts given linear magnitude to dBFS (i.e. `20 * log10(x)`)
  *
- * @param x
+ * @param x -
  */
 export const magDb = (x) => (20 * Math.log(x)) / Math.LN10;
 /**
  * Converts given dBFS value to linear magnitude
  * (i.e. `pow(10, x / 20)`)
  *
- * @param x
+ * @param x -
  */
 export const dbMag = (x) => 10 ** (x / 20);

package/dcblock.d.ts

@@ -2,7 +2,7 @@ import { OnePole } from "./onepole.js";
 /**
  * One-pole DC blocker based on {@link OnePole}.
  *
- * @param freq
+ * @param freq -
  */
 export declare const dcBlock: (freq: number) => DCBlock;
 export declare class DCBlock extends OnePole {

package/dcblock.js

@@ -2,7 +2,7 @@ import { OnePole } from "./onepole.js";
 /**
  * One-pole DC blocker based on {@link OnePole}.
  *
- * @param freq
+ * @param freq -
  */
 export const dcBlock = (freq) => new DCBlock("lp", freq);
 export class DCBlock extends OnePole {

package/delay.d.ts

@@ -3,13 +3,13 @@ import { AProc } from "./aproc.js";
 /**
  * Delay line of length `n` for numeric values.
  *
- * @param n
+ * @param n -
  */
 export declare const delay: (n: number) => Delay<number>;
 /**
  * Delay line of length `n` for arbitrary typed values.
  *
- * @param n
+ * @param n -
  */
 export declare const delayT: <T>(n: number, off: T | Fn0<T>) => Delay<T>;
 /**
@@ -27,8 +27,8 @@ export declare class Delay<T> extends AProc<T, T> implements IClear, ILength, IR
      * be initialized with the results of that function (called for each
      * element).
      *
-     * @param n
-     * @param _empty
+     * @param n -
+     * @param _empty -
      */
     constructor(n: number, _empty: T | Fn0<T>);
     get length(): number;
@@ -48,7 +48,7 @@ export declare class Delay<T> extends AProc<T, T> implements IClear, ILength, IR
      * be in `(-∞..0)` interval. E.g. `tap(-1)` returns the second
      * most recent value written.
      *
-     * @param t
+     * @param t -
      */
     tap(t: number): T;
     /**
@@ -60,7 +60,7 @@ export declare class Delay<T> extends AProc<T, T> implements IClear, ILength, IR
     /**
      * Progresses read & write pos, stores & returns new value.
      *
-     * @param x
+     * @param x -
      */
     next(x: T): T;
     /**

package/delay.js

@@ -4,13 +4,13 @@ import { AProc } from "./aproc.js";
 /**
  * Delay line of length `n` for numeric values.
  *
- * @param n
+ * @param n -
  */
 export const delay = (n) => new Delay(n, 0);
 /**
  * Delay line of length `n` for arbitrary typed values.
  *
- * @param n
+ * @param n -
  */
 export const delayT = (n, off) => new Delay(n, off);
 /**
@@ -24,8 +24,8 @@ export class Delay extends AProc {
      * be initialized with the results of that function (called for each
      * element).
      *
-     * @param n
-     * @param _empty
+     * @param n -
+     * @param _empty -
      */
     constructor(n, _empty) {
         super(isFunction(_empty) ? _empty() : _empty);
@@ -69,7 +69,7 @@ export class Delay extends AProc {
      * be in `(-∞..0)` interval. E.g. `tap(-1)` returns the second
      * most recent value written.
      *
-     * @param t
+     * @param t -
      */
     tap(t) {
         return this._buf[wrap((t | 0) + this._wpos, 0, this._buf.length - 1)];
@@ -88,7 +88,7 @@ export class Delay extends AProc {
     /**
      * Progresses read & write pos, stores & returns new value.
      *
-     * @param x
+     * @param x -
      */
     next(x) {
         this.step();

package/fft.d.ts

@@ -3,13 +3,13 @@ import type { ComplexArray } from "./api.js";
 /**
  * Returns a new tuple of real/img F64 buffers of given size.
  *
- * @param n
+ * @param n -
  */
 export declare const complexArray: (n: number) => ComplexArray;
 /**
  * Creates a deep copy of given {@link ComplexArray}.
  *
- * @param complex
+ * @param complex -
  */
 export declare const copyComplex: (complex: ComplexArray) => ComplexArray;
 /**
@@ -53,8 +53,8 @@ export declare const copyComplex: (complex: ComplexArray) => ComplexArray;
  * // ]
  * ```
  *
- * @param src
- * @param isImg
+ * @param src -
+ * @param isImg -
  */
 export declare function conjugate(src: NumericArray, isImg?: boolean): NumericArray;
 export declare function conjugate(complex: ComplexArray): ComplexArray;
@@ -74,8 +74,8 @@ export declare function conjugate(complex: ComplexArray): ComplexArray;
  * - https://betterexplained.com/articles/an-interactive-guide-to-the-fourier-transform/
  * - http://toxi.co.uk/p5/fftDebug/fft4amit.pde
  *
- * @param complex
- * @param window
+ * @param complex -
+ * @param window -
  */
 export declare const fft: (complex: NumericArray | ComplexArray, window?: NumericArray | undefined) => ComplexArray;
 /**
@@ -87,7 +87,7 @@ export declare const fft: (complex: NumericArray | ComplexArray, window?: Numeri
  *
  * - https://www.dsprelated.com/showarticle/800.php (method #3)
  *
- * @param complex
+ * @param complex -
  */
 export declare const ifft: (src: NumericArray | ComplexArray) => ComplexArray;
 export declare const scaleFFT: (complex: ComplexArray, scale: number) => ComplexArray;
@@ -103,8 +103,8 @@ export declare const scaleFFT: (complex: ComplexArray, scale: number) => Complex
  * References:
  * - https://holometer.fnal.gov/GH_FFT.pdf
  *
- * @param complex
- * @param window
+ * @param complex -
+ * @param window -
  */
 export declare const normalizeFFT: (complex: ComplexArray, window?: number | NumericArray) => ComplexArray;
 /**
@@ -119,8 +119,8 @@ export declare const normalizeFFT: (complex: ComplexArray, window?: number | Num
  * References:
  * - https://holometer.fnal.gov/GH_FFT.pdf
  *
- * @param complex
- * @param window
+ * @param complex -
+ * @param window -
  */
 export declare const denormalizeFFT: (complex: ComplexArray, window?: number | NumericArray) => ComplexArray;
 /**
@@ -135,8 +135,8 @@ export declare const denormalizeFFT: (complex: ComplexArray, window?: number | N
  * References:
  * - https://www.gaussianwaves.com/2015/11/interpreting-fft-results-obtaining-magnitude-and-phase-information/
  *
- * @param complex
- * @param eps
+ * @param complex -
+ * @param eps -
  */
 export declare const thresholdFFT: (complex: ComplexArray, eps?: number) => ComplexArray;
 /**
@@ -170,11 +170,11 @@ export declare const spectrumMag: (complex: ComplexArray, n?: number, out?: Nume
  * - https://dsp.stackexchange.com/a/14935
  * - https://www.kvraudio.com/forum/viewtopic.php?t=276092
  *
- * @param complex
- * @param db
- * @param window
- * @param n
- * @param out
+ * @param complex -
+ * @param db -
+ * @param window -
+ * @param n -
+ * @param out -
  */
 export declare const spectrumPow: (complex: ComplexArray, db?: boolean, window?: number | NumericArray, n?: number, out?: NumericArray) => NumericArray;
 /**

package/fft.js

@@ -5,7 +5,7 @@ import { applyWindow } from "./window.js";
 /**
  * Returns a new tuple of real/img F64 buffers of given size.
  *
- * @param n
+ * @param n -
  */
 export const complexArray = (n) => [
     new Float64Array(n),
@@ -14,7 +14,7 @@ export const complexArray = (n) => [
 /**
  * Creates a deep copy of given {@link ComplexArray}.
  *
- * @param complex
+ * @param complex -
  */
 export const copyComplex = (complex) => [
     complex[0].slice(),
@@ -140,8 +140,8 @@ const transform = (real, img, n) => {
  * - https://betterexplained.com/articles/an-interactive-guide-to-the-fourier-transform/
  * - http://toxi.co.uk/p5/fftDebug/fft4amit.pde
  *
- * @param complex
- * @param window
+ * @param complex -
+ * @param window -
  */
 export const fft = (complex, window) => {
     let real, img;
@@ -175,7 +175,7 @@ export const fft = (complex, window) => {
  *
  * - https://www.dsprelated.com/showarticle/800.php (method #3)
  *
- * @param complex
+ * @param complex -
  */
 export const ifft = (src) => {
     let complex = isComplex(src)
@@ -205,8 +205,8 @@ export const scaleFFT = (complex, scale) => {
  * References:
  * - https://holometer.fnal.gov/GH_FFT.pdf
  *
- * @param complex
- * @param window
+ * @param complex -
+ * @param window -
  */
 export const normalizeFFT = (complex, window = 2 / complex[0].length) => scaleFFT(complex, powerScale(window, 2));
 /**
@@ -221,8 +221,8 @@ export const normalizeFFT = (complex, window = 2 / complex[0].length) => scaleFF
  * References:
  * - https://holometer.fnal.gov/GH_FFT.pdf
  *
- * @param complex
- * @param window
+ * @param complex -
+ * @param window -
  */
 export const denormalizeFFT = (complex, window = complex[0].length / 2) => scaleFFT(complex, invPowerScale(window, 2));
 /**
@@ -237,8 +237,8 @@ export const denormalizeFFT = (complex, window = complex[0].length / 2) => scale
  * References:
  * - https://www.gaussianwaves.com/2015/11/interpreting-fft-results-obtaining-magnitude-and-phase-information/
  *
- * @param complex
- * @param eps
+ * @param complex -
+ * @param eps -
  */
 export const thresholdFFT = (complex, eps = 1e-12) => {
     const [real, img] = complex;
@@ -286,11 +286,11 @@ export const spectrumMag = (complex, n = complex[0].length / 2, out = []) => {
  * - https://dsp.stackexchange.com/a/14935
  * - https://www.kvraudio.com/forum/viewtopic.php?t=276092
  *
- * @param complex
- * @param db
- * @param window
- * @param n
- * @param out
+ * @param complex -
+ * @param db -
+ * @param window -
+ * @param n -
+ * @param out -
  */
 export const spectrumPow = (complex, db = false, window = 2 / complex[0].length, n = complex[0].length / 2, out = []) => {
     const [real, img] = complex;

package/impulse.d.ts

@@ -4,7 +4,7 @@ import { AGen } from "./agen.js";
  * Numeric version of {@link impulseT}, using given `on` (default: 1) as
  * initial value and zero for the remaining values.
  *
- * @param on
+ * @param on -
  */
 export declare const impulse: (on?: number) => Impulse<number>;
 /**
@@ -19,7 +19,7 @@ export declare const impulseT: <T>(on: T, off: T) => Impulse<T>;
  * Boolean version of {@link impulseT}, using given `start` (default:
  * true) as initial value and its inverse for the remaining values.
  *
- * @param start
+ * @param start -
  */
 export declare const impulseB: (start?: boolean) => Impulse<boolean>;
 export declare class Impulse<T> extends AGen<T> implements IReset {

package/impulse.js

@@ -3,7 +3,7 @@ import { AGen } from "./agen.js";
  * Numeric version of {@link impulseT}, using given `on` (default: 1) as
  * initial value and zero for the remaining values.
  *
- * @param on
+ * @param on -
  */
 export const impulse = (on = 1) => new Impulse(on, 0);
 /**
@@ -18,7 +18,7 @@ export const impulseT = (on, off) => new Impulse(on, off);
  * Boolean version of {@link impulseT}, using given `start` (default:
  * true) as initial value and its inverse for the remaining values.
  *
- * @param start
+ * @param start -
  */
 export const impulseB = (start = true) => new Impulse(start, !start);
 export class Impulse extends AGen {

package/iterable.d.ts

@@ -10,8 +10,8 @@ import type { IGen } from "./api.js";
  * The `initial` value is required to satisfy `.deref()` and the case where the
  * iterable doesn't provide a single value.
  *
- * @param src
- * @param initial
+ * @param src -
+ * @param initial -
  */
 export declare const iterable: <T>(src: Iterable<T>, initial: T) => $Iterable<T>;
 export declare class $Iterable<T> implements IGen<T> {

package/iterable.js

@@ -10,8 +10,8 @@ import { __take } from "./internal/take.js";
  * The `initial` value is required to satisfy `.deref()` and the case where the
  * iterable doesn't provide a single value.
  *
- * @param src
- * @param initial
+ * @param src -
+ * @param initial -
  */
 export const iterable = (src, initial) => new $Iterable(src, initial);
 export class $Iterable {

package/multiplex.d.ts

@@ -12,8 +12,8 @@ import { AProc } from "./aproc.js";
  *
  * See {@link bounce} for combining results back into a single channel output.
  *
- * @param a
- * @param b
+ * @param a -
+ * @param b -
  */
 export declare function multiplex<T, A, B>(a: IProc<T, A>, b: IProc<T, B>): Multiplex<T, [A, B]>;
 export declare function multiplex<T, A, B, C>(a: IProc<T, A>, b: IProc<T, B>, c: IProc<T, C>): Multiplex<T, [A, B, C]>;

package/osc-additive.d.ts

@@ -9,10 +9,10 @@ import type { StatelessOscillator } from "./api.js";
  * and amplitude factors for each of the `n` requested harmonics (given in [i,n]
  * range).
  *
- * @param osc
- * @param freqFn
- * @param ampFn
- * @param n
+ * @param osc -
+ * @param freqFn -
+ * @param ampFn -
+ * @param n -
  */
 export declare const additive: (osc: StatelessOscillator, freqFn: Fn<number, number>, ampFn: Fn<number, number>, n: number) => StatelessOscillator;
 /**

package/osc-additive.js

@@ -9,10 +9,10 @@ import { sin } from "./osc-sin.js";
  * and amplitude factors for each of the `n` requested harmonics (given in [i,n]
  * range).
  *
- * @param osc
- * @param freqFn
- * @param ampFn
- * @param n
+ * @param osc -
+ * @param freqFn -
+ * @param ampFn -
+ * @param n -
  */
 export const additive = (osc, freqFn, ampFn, n) => {
     const fcache = [];