tone 14.8.27

package/Tone/component/filter/LowpassCombFilter.test.ts

@@ -0,0 +1,75 @@
+import { LowpassCombFilter } from "./LowpassCombFilter";
+import { BasicTests } from "test/helper/Basic";
+import { Offline } from "test/helper/Offline";
+import { PassAudio } from "test/helper/PassAudio";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { expect } from "chai";
+
+describe("LowpassCombFilter", () => {
+
+	BasicTests(LowpassCombFilter);
+
+	context("Comb Filtering", () => {
+
+		it("can be constructed with an object", () => {
+			const lpcf = new LowpassCombFilter({
+				delayTime: 0.2,
+				resonance: 0.3,
+				dampening: 2400
+			});
+			expect(lpcf.delayTime.value).to.be.closeTo(0.2, 0.001);
+			expect(lpcf.resonance.value).to.be.closeTo(0.3, 0.001);
+			expect(lpcf.dampening).to.be.closeTo(2400, 0.001);
+			lpcf.dispose();
+		});
+
+		it("can be get and set through object", () => {
+			const lpcf = new LowpassCombFilter();
+			lpcf.set({
+				delayTime: 0.2,
+				resonance: 0.3,
+				dampening: 2000
+			});
+			expect(lpcf.get().delayTime).to.be.closeTo(0.2, 0.001);
+			expect(lpcf.get().resonance).to.be.closeTo(0.3, 0.001);
+			expect(lpcf.get().dampening).to.be.closeTo(2000, 0.001);
+			lpcf.dispose();
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio((input) => {
+				const lpcf = new LowpassCombFilter(0).toDestination();
+				input.connect(lpcf);
+			});
+		});
+
+		it("produces a decay signal at high resonance", () => {
+			return Offline(() => {
+				const lpcf = new LowpassCombFilter(0.01, 0.9, 5000).toDestination();
+				const burst = new Oscillator(440).connect(lpcf);
+				burst.start(0);
+				burst.stop(0.1);
+			}, 0.8).then((buffer) => {
+				expect(buffer.getRmsAtTime(0.05)).to.be.within(0.2, 0.6);
+				expect(buffer.getRmsAtTime(0.1)).to.be.within(0.2, 0.6);
+				expect(buffer.getRmsAtTime(0.15)).to.be.within(0.15, 0.4);
+				expect(buffer.getRmsAtTime(0.3)).to.be.within(0.01, 0.15);
+				expect(buffer.getRmsAtTime(0.7)).to.be.below(0.01);
+			});
+		});
+
+		it("produces a decay signal at moderate resonance", () => {
+			return Offline(() => {
+				const lpcf = new LowpassCombFilter(0.05, 0.5).toDestination();
+				const burst = new Oscillator(440).connect(lpcf);
+				burst.start(0);
+				burst.stop(0.1);
+			}, 0.6).then((buffer) => {
+				expect(buffer.getRmsAtTime(0.05)).to.be.closeTo(0.7, 0.1);
+				expect(buffer.getRmsAtTime(0.1)).to.be.within(0.7, 1.1);
+				expect(buffer.getRmsAtTime(0.2)).to.be.closeTo(0.25, 0.1);
+				expect(buffer.getRmsAtTime(0.4)).to.be.closeTo(0.015, 0.01);
+			});
+		});
+	});
+});

package/Tone/component/filter/LowpassCombFilter.ts

@@ -0,0 +1,100 @@
+import { Param } from "../../core/context/Param";
+import { InputNode, OutputNode, ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { Frequency, NormalRange, Time } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { RecursivePartial } from "../../core/util/Interface";
+import { FeedbackCombFilter } from "./FeedbackCombFilter";
+import { OnePoleFilter } from "./OnePoleFilter";
+
+interface LowpassCombFilterOptions extends ToneAudioNodeOptions {
+	delayTime: Time;
+	resonance: NormalRange;
+	dampening: Frequency;
+}
+
+/**
+ * A lowpass feedback comb filter. It is similar to
+ * [[FeedbackCombFilter]], but includes a lowpass filter.
+ * @category Component
+ */
+export class LowpassCombFilter extends ToneAudioNode<LowpassCombFilterOptions> {
+
+	readonly name = "LowpassCombFilter";
+
+	/**
+	 * The delay node
+	 */
+	private _combFilter: FeedbackCombFilter;
+
+	/**
+	 * The lowpass filter
+	 */
+	private _lowpass: OnePoleFilter;
+
+	/**
+	 * The delayTime of the comb filter.
+	 */
+	readonly delayTime: Param<"time">;
+
+	/**
+	 * The amount of feedback of the delayed signal.
+	 */
+	readonly resonance: Param<"normalRange">;
+
+	readonly input: InputNode;
+	readonly output: OutputNode;
+
+	/**
+	 * @param delayTime The delay time of the comb filter
+	 * @param resonance The resonance (feedback) of the comb filter
+	 * @param dampening The cutoff of the lowpass filter dampens the signal as it is fedback.
+	 */
+	constructor(delayTime?: Time, resonance?: NormalRange, dampening?: Frequency);
+	constructor(options?: RecursivePartial<LowpassCombFilterOptions>);
+	constructor() {
+		super(optionsFromArguments(LowpassCombFilter.getDefaults(), arguments, ["delayTime", "resonance", "dampening"]));
+		const options = optionsFromArguments(LowpassCombFilter.getDefaults(), arguments, ["delayTime", "resonance", "dampening"]);
+
+		this._combFilter = this.output = new FeedbackCombFilter({
+			context: this.context,
+			delayTime: options.delayTime,
+			resonance: options.resonance,
+		});
+		this.delayTime = this._combFilter.delayTime;
+		this.resonance = this._combFilter.resonance;
+
+		this._lowpass = this.input = new OnePoleFilter({
+			context: this.context,
+			frequency: options.dampening,
+			type: "lowpass",
+		});
+
+		// connections
+		this._lowpass.connect(this._combFilter);
+	}
+
+	static getDefaults(): LowpassCombFilterOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			dampening: 3000,
+			delayTime: 0.1,
+			resonance: 0.5,
+		});
+	}
+	
+	/**
+	 * The dampening control of the feedback
+	 */
+	get dampening(): Frequency {
+		return this._lowpass.frequency;
+	}
+	set dampening(fq) {
+		this._lowpass.frequency = fq;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._combFilter.dispose();
+		this._lowpass.dispose();
+		return this;
+	}
+}

package/Tone/component/filter/OnePoleFilter.test.ts

@@ -0,0 +1,90 @@
+import { OnePoleFilter } from "./OnePoleFilter";
+import { BasicTests } from "test/helper/Basic";
+import { PassAudio } from "test/helper/PassAudio";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { expect } from "chai";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { atTime, Offline } from "test/helper/Offline";
+
+describe("OnePoleFilter", () => {
+
+	BasicTests(OnePoleFilter);
+
+	it("matches a file when set to lowpass", () => {
+		return CompareToFile(() => {
+			const filter = new OnePoleFilter(300, "lowpass").toDestination();
+			const osc = new Oscillator().connect(filter);
+			osc.type = "square";
+			osc.start(0).stop(0.1);
+		}, "onePoleLowpass.wav", 0.05);
+	});
+
+	it("matches a file when set to highpass", () => {
+		return CompareToFile(() => {
+			const filter = new OnePoleFilter(700, "highpass").toDestination();
+			const osc = new Oscillator().connect(filter);
+			osc.type = "square";
+			osc.start(0).stop(0.1);
+		}, "onePoleHighpass.wav", 0.05);
+	});
+
+	context("Filtering", () => {
+
+		it("can set the frequency more than once", () => {
+			return Offline(() => {
+				const filter = new OnePoleFilter(200);	
+				filter.frequency = 300;
+				return atTime(0.1, () => {
+					filter.frequency = 400;
+				});
+			}, 1);
+		});
+
+		it("can be constructed with an object", () => {
+			const filter = new OnePoleFilter({
+				frequency: 400,
+				type: "lowpass"
+			});
+			expect(filter.frequency).to.be.closeTo(400, 0.1);
+			expect(filter.type).to.equal("lowpass");
+			filter.dispose();
+		});
+
+		it("can be constructed with args", () => {
+			const filter = new OnePoleFilter(120, "highpass");
+			expect(filter.frequency).to.be.closeTo(120, 0.1);
+			expect(filter.type).to.equal("highpass");
+			filter.dispose();
+		});
+
+		it("can be get and set through object", () => {
+			const filter = new OnePoleFilter();
+			filter.set({
+				frequency: 200,
+				type: "highpass"
+			});
+			expect(filter.get().type).to.equal("highpass");
+			expect(filter.get().frequency).to.be.closeTo(200, 0.1);
+			filter.dispose();
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio((input) => {
+				const filter = new OnePoleFilter(5000).toDestination();
+				input.connect(filter);
+			});
+		});
+	});
+
+	context("Response Curve", () => {
+
+		it("can get the response curve", () => {
+			const filter = new OnePoleFilter();
+			const response = filter.getFrequencyResponse(128);
+			expect(response.length).to.equal(128);
+			response.forEach(v => expect(v).to.be.within(0, 1));
+			filter.dispose();
+		});
+
+	});
+});

package/Tone/component/filter/OnePoleFilter.ts

@@ -0,0 +1,146 @@
+import { ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { Frequency } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { Gain } from "../../core/context/Gain";
+
+export type OnePoleFilterType = "highpass" | "lowpass";
+
+export interface OnePoleFilterOptions extends ToneAudioNodeOptions {
+	frequency: Frequency;
+	type: OnePoleFilterType;
+}
+
+/**
+ * A one pole filter with 6db-per-octave rolloff. Either "highpass" or "lowpass". 
+ * Note that changing the type or frequency may result in a discontinuity which
+ * can sound like a click or pop. 
+ * References: 
+ * * http://www.earlevel.com/main/2012/12/15/a-one-pole-filter/  
+ * * http://www.dspguide.com/ch19/2.htm
+ * * https://github.com/vitaliy-bobrov/js-rocks/blob/master/src/app/audio/effects/one-pole-filters.ts
+ * @category Component
+ */
+export class OnePoleFilter extends ToneAudioNode<OnePoleFilterOptions> {
+	
+	readonly name: string = "OnePoleFilter";
+
+	/**
+	 * Hold the current frequency
+	 */
+	private _frequency: Frequency;
+
+	/**
+	 * the current one pole type
+	 */
+	private _type: OnePoleFilterType;
+
+	/**
+	 * the current one pole filter
+	 */
+	private _filter!: IIRFilterNode;
+
+	readonly input: Gain;
+	readonly output: Gain;
+
+	/**
+	 * @param frequency The frequency
+	 * @param type The  filter type, either "lowpass" or "highpass"
+	 */
+	constructor(frequency?: Frequency, type?: OnePoleFilterType);
+	constructor(options?: Partial<OnePoleFilterOptions>)
+	constructor() {
+
+		super(optionsFromArguments(OnePoleFilter.getDefaults(), arguments, ["frequency", "type"]));
+		const options = optionsFromArguments(OnePoleFilter.getDefaults(), arguments, ["frequency", "type"]);
+
+		this._frequency = options.frequency;
+		this._type = options.type;
+		this.input = new Gain({ context: this.context });
+		this.output = new Gain({ context: this.context });
+		this._createFilter();
+	}
+
+	static getDefaults(): OnePoleFilterOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			frequency: 880,
+			type: "lowpass" as OnePoleFilterType
+		});
+	}
+
+	/**
+	 * Create a filter and dispose the old one
+	 */
+	private _createFilter() {
+		const oldFilter = this._filter;
+		const freq = this.toFrequency(this._frequency);
+		const t = 1 / (2 * Math.PI * freq);
+		if (this._type === "lowpass") {
+			const a0 = 1 / (t * this.context.sampleRate);
+			const b1 = a0 - 1;
+			this._filter = this.context.createIIRFilter([a0, 0], [1, b1]);
+		} else {
+			const b1 = 1 / (t * this.context.sampleRate) - 1;
+			this._filter = this.context.createIIRFilter([1, -1], [1, b1]);
+		}
+		
+		this.input.chain(this._filter, this.output);
+		if (oldFilter) {
+			// dispose it on the next block
+			this.context.setTimeout(() => {
+				if (!this.disposed) {
+					this.input.disconnect(oldFilter);
+					oldFilter.disconnect();
+				}
+			}, this.blockTime);
+		}
+	}
+
+	/**
+	 * The frequency value. 
+	 */
+	get frequency(): Frequency {
+		return this._frequency;
+	}
+	set frequency(fq) {
+		this._frequency = fq;
+		this._createFilter();
+	}
+	
+	/**
+	 * The OnePole Filter type, either "highpass" or "lowpass"
+	 */
+	get type(): OnePoleFilterType {
+		return this._type;
+	}
+	set type(t) {
+		this._type = t;
+		this._createFilter();
+	}
+
+	/**
+	 * Get the frequency response curve. This curve represents how the filter
+	 * responses to frequencies between 20hz-20khz.
+	 * @param  len The number of values to return
+	 * @return The frequency response curve between 20-20kHz
+	 */
+	getFrequencyResponse(len = 128): Float32Array {
+		const freqValues = new Float32Array(len);
+		for (let i = 0; i < len; i++) {
+			const norm = Math.pow(i / len, 2);
+			const freq = norm * (20000 - 20) + 20;
+			freqValues[i] = freq;
+		}
+		const magValues = new Float32Array(len);
+		const phaseValues = new Float32Array(len);
+		this._filter.getFrequencyResponse(freqValues, magValues, phaseValues);
+		return magValues;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.input.dispose();
+		this.output.dispose();
+		this._filter.disconnect();
+		return this;
+	}
+}

package/Tone/component/filter/PhaseShiftAllpass.test.ts

@@ -0,0 +1,71 @@
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { connectTo } from "test/helper/Connect";
+import { PassAudio } from "test/helper/PassAudio";
+import { connect } from "Tone/core/context/ToneAudioNode";
+import { Subtract } from "Tone/signal/Subtract";
+import { PhaseShiftAllpass } from "./PhaseShiftAllpass";
+
+describe("PhaseShiftAllpass", () => {
+
+	BasicTests(PhaseShiftAllpass);
+
+	context("PhaseShiftAllpass", () => {
+
+		it("handles output connections", () => {
+			const phaseShifter = new PhaseShiftAllpass();
+			phaseShifter.connect(connectTo());
+			phaseShifter.offset90.connect(connectTo());
+			phaseShifter.dispose();
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio((input) => {
+				const phaseShifter = new PhaseShiftAllpass().toDestination();
+				input.connect(phaseShifter);
+			});
+		});
+
+		it("generates correct values with the phase shifted channel", () => {
+			return CompareToFile((context) => {
+				// create impulse with 5 samples offset
+				const constantNode = context.createConstantSource();
+				constantNode.start(0);
+				const oneSampleDelay = context.createIIRFilter([0.0, 1.0], [1.0, 0.0]);
+				const fiveSampleDelay = context.createIIRFilter([0.0, 0.0, 0.0, 0.0, 0.0, 1.0], [1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
+				const sub = new Subtract();
+
+				connect(constantNode, oneSampleDelay);
+				connect(constantNode, sub);
+				connect(oneSampleDelay, sub.subtrahend);
+				connect(sub, fiveSampleDelay);
+
+				const phaseShifter = new PhaseShiftAllpass();
+				connect(fiveSampleDelay, phaseShifter);
+				phaseShifter.toDestination();
+
+			}, "phaseShiftAllpass.wav", 0.001);
+		});
+
+		it("generates correct values with the offset90 channel", () => {
+			return CompareToFile((context) => {
+				// create impulse with 5 samples offset
+				const constantNode = context.createConstantSource();
+				constantNode.start(0);
+				const oneSampleDelay = context.createIIRFilter([0.0, 1.0], [1.0, 0.0]);
+				const fiveSampleDelay = context.createIIRFilter([0.0, 0.0, 0.0, 0.0, 0.0, 1.0], [1.0, 0.0, 0.0, 0.0, 0.0, 0.0]);
+				const sub = new Subtract();
+
+				connect(constantNode, oneSampleDelay);
+				connect(constantNode, sub);
+				connect(oneSampleDelay, sub.subtrahend);
+				connect(sub, fiveSampleDelay);
+
+				const phaseShifter = new PhaseShiftAllpass();
+				connect(fiveSampleDelay, phaseShifter);
+				phaseShifter.offset90.toDestination();
+
+			}, "phaseShiftAllpass1.wav", 0.001);
+		});
+	});
+});

package/Tone/component/filter/PhaseShiftAllpass.ts

@@ -0,0 +1,81 @@
+import { Gain } from "../../core/context/Gain";
+import { connectSeries, ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+
+/**
+ * PhaseShiftAllpass is an very efficient implementation of a Hilbert Transform
+ * using two Allpass filter banks whose outputs have a phase difference of 90°.
+ * Here the `offset90` phase is offset by +90° in relation to `output`.
+ * Coefficients and structure was developed by Olli Niemitalo.
+ * For more details see: http://yehar.com/blog/?p=368
+ * @category Component
+ */
+export class PhaseShiftAllpass extends ToneAudioNode<ToneAudioNodeOptions> {
+
+	readonly name: string = "PhaseShiftAllpass";
+
+	readonly input = new Gain({ context: this.context });
+
+	/**
+	 * The Allpass filter in the first bank
+	 */
+	private _bank0: IIRFilterNode[];
+
+	/**
+	 * The Allpass filter in the seconds bank
+	 */
+	private _bank1: IIRFilterNode[];
+
+	/**
+	 * A IIR filter implementing a delay by one sample used by the first bank
+	 */
+	private _oneSampleDelay: IIRFilterNode;
+
+	/**
+	 * The phase shifted output
+	 */
+	readonly output = new Gain({ context: this.context });
+
+	/**
+	 * The PhaseShifted allpass output
+	 */
+	readonly offset90 = new Gain({ context: this.context });
+
+	constructor(options?: Partial<ToneAudioNodeOptions>) {
+
+		super(options);
+
+		const allpassBank1Values = [0.6923878, 0.9360654322959, 0.9882295226860, 0.9987488452737];
+		const allpassBank2Values = [0.4021921162426, 0.8561710882420, 0.9722909545651, 0.9952884791278];
+
+		this._bank0 = this._createAllPassFilterBank(allpassBank1Values);
+		this._bank1 = this._createAllPassFilterBank(allpassBank2Values);
+		this._oneSampleDelay = this.context.createIIRFilter([0.0, 1.0], [1.0, 0.0]);
+
+		// connect Allpass filter banks
+		connectSeries(this.input, ...this._bank0, this._oneSampleDelay, this.output);
+		connectSeries(this.input, ...this._bank1, this.offset90);
+	}
+
+	/**
+	 * Create all of the IIR filters from an array of values using the coefficient calculation.
+	 */
+	private _createAllPassFilterBank(bankValues: number[]): IIRFilterNode[] {
+		const nodes: IIRFilterNode[] = bankValues.map(value => {
+			const coefficients = [[value * value, 0, -1], [1, 0, -(value * value)]];
+			return this.context.createIIRFilter(coefficients[0], coefficients[1]);
+		});
+
+		return nodes;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.input.dispose();
+		this.output.dispose();
+		this.offset90.dispose();
+		this._bank0.forEach(f => f.disconnect());
+		this._bank1.forEach(f => f.disconnect());
+		this._oneSampleDelay.disconnect();
+		return this;
+	}
+}

package/Tone/component/index.ts

@@ -0,0 +1,39 @@
+export * from "./analysis/Analyser";
+export * from "./analysis/Meter";
+export * from "./analysis/FFT";
+export * from "./analysis/DCMeter";
+export * from "./analysis/Waveform";
+export * from "./analysis/Follower";
+
+export * from "./channel/Channel";
+export * from "./channel/CrossFade";
+export * from "./channel/Merge";
+export * from "./channel/MidSideMerge";
+export * from "./channel/MidSideSplit";
+export * from "./channel/Mono";
+export * from "./channel/MultibandSplit";
+export * from "./channel/Panner";
+export * from "./channel/Panner3D";
+export * from "./channel/PanVol";
+export * from "./channel/Recorder";
+export * from "./channel/Solo";
+export * from "./channel/Split";
+export * from "./channel/Volume";
+
+export * from "./dynamics/Compressor";
+export * from "./dynamics/Gate";
+export * from "./dynamics/Limiter";
+export * from "./dynamics/MidSideCompressor";
+export * from "./dynamics/MultibandCompressor";
+
+export * from "./envelope/AmplitudeEnvelope";
+export * from "./envelope/Envelope";
+export * from "./envelope/FrequencyEnvelope";
+
+export * from "./filter/EQ3";
+export * from "./filter/Filter";
+export * from "./filter/OnePoleFilter";
+export * from "./filter/FeedbackCombFilter";
+export * from "./filter/LowpassCombFilter";
+export * from "./filter/Convolver";
+export * from "./filter/BiquadFilter";

package/Tone/core/Global.ts

@@ -0,0 +1,73 @@
+import { version } from "../version";
+import { AnyAudioContext, hasAudioContext, theWindow } from "./context/AudioContext";
+import { Context } from "./context/Context";
+import { DummyContext } from "./context/DummyContext";
+import { BaseContext } from "./context/BaseContext";
+import { OfflineContext } from "./context/OfflineContext";
+import { isAudioContext, isOfflineAudioContext } from "./util/AdvancedTypeCheck";
+
+/**
+ * This dummy context is used to avoid throwing immediate errors when importing in Node.js
+ */
+const dummyContext = new DummyContext();
+
+/**
+ * The global audio context which is getable and assignable through
+ * getContext and setContext
+ */
+let globalContext: BaseContext = dummyContext;
+
+/**
+ * Returns the default system-wide [[Context]]
+ * @category Core
+ */
+export function getContext(): BaseContext {
+	if (globalContext === dummyContext && hasAudioContext) {
+		setContext(new Context());
+	}
+	return globalContext;
+}
+
+/**
+ * Set the default audio context
+ * @category Core
+ */
+export function setContext(context: BaseContext | AnyAudioContext): void {
+	if (isAudioContext(context)) {
+		globalContext = new Context(context);
+	} else if (isOfflineAudioContext(context)) {
+		globalContext = new OfflineContext(context);
+	} else {
+		globalContext = context;
+	}
+}
+
+/**
+ * Most browsers will not play _any_ audio until a user
+ * clicks something (like a play button). Invoke this method
+ * on a click or keypress event handler to start the audio context.
+ * More about the Autoplay policy
+ * [here](https://developers.google.com/web/updates/2017/09/autoplay-policy-changes#webaudio)
+ * @example
+ * document.querySelector("button").addEventListener("click", async () => {
+ * 	await Tone.start();
+ * 	console.log("context started");
+ * });
+ * @category Core
+ */
+export function start(): Promise<void> {
+	return globalContext.resume();
+}
+
+/**
+ * Log Tone.js + version in the console.
+ */
+if (theWindow && !theWindow.TONE_SILENCE_LOGGING) {
+	let prefix = "v";
+	if (version === "dev") {
+		prefix = "";
+	}
+	const printString = ` * Tone.js ${prefix}${version} * `;
+	// eslint-disable-next-line no-console
+	console.log(`%c${printString}`, "background: #000; color: #fff");
+}