tone 14.8.27

package/Tone/component/envelope/FrequencyEnvelope.ts

@@ -0,0 +1,134 @@
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { Frequency, Hertz, NormalRange, Time } from "../../core/type/Units";
+import { Envelope, EnvelopeOptions } from "./Envelope";
+import { Scale } from "../../signal/Scale";
+import { Pow } from "../../signal/Pow";
+import { assertRange } from "../../core/util/Debug";
+
+export interface FrequencyEnvelopeOptions extends EnvelopeOptions {
+	baseFrequency: Frequency;
+	octaves: number;
+	exponent: number;
+}
+/**
+ * FrequencyEnvelope is an [[Envelope]] which ramps between [[baseFrequency]]
+ * and [[octaves]]. It can also have an optional [[exponent]] to adjust the curve
+ * which it ramps. 
+ * @example
+ * const oscillator = new Tone.Oscillator().toDestination().start();
+ * const freqEnv = new Tone.FrequencyEnvelope({
+ * 	attack: 0.2,
+ * 	baseFrequency: "C2",
+ * 	octaves: 4
+ * });
+ * freqEnv.connect(oscillator.frequency);
+ * freqEnv.triggerAttack();
+ * @category Component
+ */
+export class FrequencyEnvelope extends Envelope {
+
+	readonly name: string = "FrequencyEnvelope";
+
+	/**
+	 * Private reference to the base frequency as a number
+	 */
+	private _baseFrequency: Hertz;
+
+	/**
+	 * The number of octaves
+	 */
+	private _octaves: number;
+
+	/**
+	 * Internal scaler from 0-1 to the final output range
+	 */
+	private _scale: Scale;
+
+	/**
+	 * Apply a power curve to the output
+	 */
+	private _exponent: Pow;
+
+	/**
+	 * @param attack	the attack time in seconds
+	 * @param decay		the decay time in seconds
+	 * @param sustain 	a percentage (0-1) of the full amplitude
+	 * @param release	the release time in seconds
+	 */
+	constructor(attack?: Time, decay?: Time, sustain?: NormalRange, release?: Time);
+	constructor(options?: Partial<FrequencyEnvelopeOptions>)
+	constructor() {
+		super(optionsFromArguments(FrequencyEnvelope.getDefaults(), arguments, ["attack", "decay", "sustain", "release"]));
+		const options = optionsFromArguments(FrequencyEnvelope.getDefaults(), arguments, ["attack", "decay", "sustain", "release"]);
+
+		this._octaves = options.octaves;
+		this._baseFrequency = this.toFrequency(options.baseFrequency);
+
+		this._exponent = this.input = new Pow({
+			context: this.context,
+			value: options.exponent
+		});
+		this._scale = this.output = new Scale({
+			context: this.context,
+			min: this._baseFrequency,
+			max: this._baseFrequency * Math.pow(2, this._octaves),
+		});
+		this._sig.chain(this._exponent, this._scale);
+	}
+
+	static getDefaults(): FrequencyEnvelopeOptions {
+		return Object.assign(Envelope.getDefaults(), {
+			baseFrequency: 200,
+			exponent: 1,
+			octaves: 4,
+		});
+	}
+
+	/**
+	 * The envelope's minimum output value. This is the value which it
+	 * starts at.
+	 */
+	get baseFrequency(): Frequency {
+		return this._baseFrequency;
+	}
+	set baseFrequency(min) {
+		const freq = this.toFrequency(min);
+		assertRange(freq, 0);
+		this._baseFrequency = freq;
+		this._scale.min = this._baseFrequency;
+		// update the max value when the min changes
+		this.octaves = this._octaves;
+	}
+
+	/**
+	 * The number of octaves above the baseFrequency that the
+	 * envelope will scale to.
+	 */
+	get octaves(): number {
+		return this._octaves;
+	}
+	set octaves(octaves: number) {
+		this._octaves = octaves;
+		this._scale.max = this._baseFrequency * Math.pow(2, octaves);
+	}
+
+	/**
+	 * The envelope's exponent value.
+	 */
+	get exponent(): number {
+		return this._exponent.value;
+	}
+	set exponent(exponent) {
+		this._exponent.value = exponent;
+	}
+
+	/**
+	 * Clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		this._exponent.dispose();
+		this._scale.dispose();
+		return this;
+	}
+}

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

@@ -0,0 +1,94 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { Offline } from "test/helper/Offline";
+import { PassAudio } from "test/helper/PassAudio";
+import { Oscillator } from "../../source/oscillator/Oscillator";
+import { BiquadFilter } from "./BiquadFilter";
+
+describe("BiquadFilter", () => {
+
+	BasicTests(BiquadFilter);
+
+	context("BiquadFiltering", () => {
+
+		it("can be constructed with a arguments", () => {
+			const filter = new BiquadFilter(200, "highpass");
+			expect(filter.frequency.value).to.be.closeTo(200, 0.001);
+			expect(filter.type).to.equal("highpass");
+			filter.dispose();
+		});
+
+		it("can be constructed with an object", () => {
+			const filter = new BiquadFilter({
+				frequency: 340,
+				type: "bandpass",
+			});
+			expect(filter.frequency.value).to.be.closeTo(340, 0.001);
+			expect(filter.type).to.equal("bandpass");
+			filter.dispose();
+		});
+
+		it("can set/get values as an Object", () => {
+			const filter = new BiquadFilter();
+			const values = {
+				Q: 2,
+				frequency: 440,
+				gain: -6,
+				type: "lowshelf" as const
+			};
+			filter.set(values);
+			expect(filter.get()).to.include.keys(["type", "frequency", "Q", "gain"]);
+			expect(filter.type).to.equal(values.type);
+			expect(filter.frequency.value).to.equal(values.frequency);
+			expect(filter.Q.value).to.equal(values.Q);
+			expect(filter.gain.value).to.be.closeTo(values.gain, 0.04);
+			filter.dispose();
+		});
+
+		it("can get the frequency response curve", () => {
+			const filter = new BiquadFilter();
+			const curve = filter.getFrequencyResponse(32);
+			expect(curve.length).to.equal(32);
+			expect(curve[0]).be.closeTo(1, 0.01);
+			expect(curve[5]).be.closeTo(0.5, 0.1);
+			expect(curve[15]).be.closeTo(0, 0.01);
+			expect(curve[31]).be.closeTo(0, 0.01);
+			filter.dispose();
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio(input => {
+				const filter = new BiquadFilter().toDestination();
+				input.connect(filter);
+			});
+		});
+
+		it("can set the basic filter types", () => {
+			const filter = new BiquadFilter();
+			const types: BiquadFilterType[] = ["lowpass", "highpass",
+				"bandpass", "lowshelf", "highshelf", "notch", "allpass", "peaking"];
+			for (const type of types) {
+				filter.type = type;
+				expect(filter.type).to.equal(type);
+			}
+			expect(() => {
+				// @ts-ignore
+				filter.type = "nontype";
+			}).to.throw(Error);
+			filter.dispose();
+		});
+
+		it("attenuates the incoming signal", () => {
+			return Offline(() => {
+				const filter = new BiquadFilter(700, "lowpass").toDestination();
+				filter.Q.value = 0;
+				const osc = new Oscillator(880).connect(filter);
+				osc.start(0);
+			}, 0.2).then((buffer) => {
+				expect(buffer.getRmsAtTime(0.05)).to.be.within(0.37, 0.53);
+				expect(buffer.getRmsAtTime(0.1)).to.be.within(0.37, 0.53);
+			});
+		});
+
+	});
+});

package/Tone/component/filter/BiquadFilter.ts

@@ -0,0 +1,158 @@
+import { ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { Cents, Frequency, GainFactor } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { Param } from "../../core/context/Param";
+import { assert } from "../../core/util/Debug";
+
+export interface BiquadFilterOptions extends ToneAudioNodeOptions {
+	frequency: Frequency;
+	detune: Cents;
+	Q: number;
+	type: BiquadFilterType;
+	gain: GainFactor;
+}
+
+/**
+ * Thin wrapper around the native Web Audio [BiquadFilterNode](https://webaudio.github.io/web-audio-api/#biquadfilternode). 
+ * BiquadFilter is similar to [[Filter]] but doesn't have the option to set the "rolloff" value. 
+ * @category Component
+ */
+export class BiquadFilter extends ToneAudioNode<BiquadFilterOptions> {
+	readonly name: string = "BiquadFilter";
+
+	readonly input: BiquadFilterNode;
+	readonly output: BiquadFilterNode;
+
+	/**
+	 * The frequency of the filter
+	 */
+	readonly frequency: Param<"frequency">;
+
+	/**
+	 * A detune value, in cents, for the frequency.
+	 */
+	readonly detune: Param<"cents">;
+	
+	/**
+	 * The Q factor of the filter.
+	 * For lowpass and highpass filters the Q value is interpreted to be in dB. 
+	 * For these filters the nominal range is [−𝑄𝑙𝑖𝑚,𝑄𝑙𝑖𝑚] where 𝑄𝑙𝑖𝑚 is the largest value for which 10𝑄/20 does not overflow. This is approximately 770.63678.
+	 * For the bandpass, notch, allpass, and peaking filters, this value is a linear value. 
+	 * The value is related to the bandwidth of the filter and hence should be a positive value. The nominal range is 
+	 * [0,3.4028235𝑒38], the upper limit being the most-positive-single-float.
+	 * This is not used for the lowshelf and highshelf filters.
+	 */
+	readonly Q: Param<"number">;
+
+	/**
+	 * The gain of the filter. Its value is in dB units. The gain is only used for lowshelf, highshelf, and peaking filters.
+	 */
+	readonly gain: Param<"decibels">;
+
+	private readonly _filter: BiquadFilterNode;
+
+	/**
+	 * @param frequency The cutoff frequency of the filter.
+	 * @param type The type of filter.
+	 */
+	constructor(frequency?: Frequency, type?: BiquadFilterType);
+	constructor(options?: Partial<BiquadFilterOptions>);
+	constructor() {
+		super(optionsFromArguments(BiquadFilter.getDefaults(), arguments, ["frequency", "type"]));
+		const options = optionsFromArguments(BiquadFilter.getDefaults(), arguments, ["frequency", "type"]);
+
+		this._filter = this.context.createBiquadFilter();
+		this.input = this.output = this._filter;
+
+		this.Q = new Param({
+			context: this.context,
+			units: "number",
+			value: options.Q,
+			param: this._filter.Q,
+		});
+		
+		this.frequency = new Param({
+			context: this.context,
+			units: "frequency",
+			value: options.frequency,
+			param: this._filter.frequency,
+		});
+		
+		this.detune = new Param({
+			context: this.context,
+			units: "cents",
+			value: options.detune,
+			param: this._filter.detune,
+		});
+		
+		this.gain = new Param({
+			context: this.context,
+			units: "decibels",
+			convert: false,
+			value: options.gain,
+			param: this._filter.gain,
+		});
+
+		this.type = options.type;
+	}
+
+	static getDefaults(): BiquadFilterOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			Q: 1,
+			type: "lowpass" as const,
+			frequency: 350,
+			detune: 0,
+			gain: 0,
+		});
+	}
+
+	/**
+	 * The type of this BiquadFilterNode. For a complete list of types and their attributes, see the
+	 * [Web Audio API](https://webaudio.github.io/web-audio-api/#dom-biquadfiltertype-lowpass)
+	 */
+	get type(): BiquadFilterType {
+		return this._filter.type;
+	}
+	set type(type) {
+		const types: BiquadFilterType[] = ["lowpass", "highpass", "bandpass",
+			"lowshelf", "highshelf", "notch", "allpass", "peaking"];
+		assert(types.indexOf(type) !== -1, `Invalid filter type: ${type}`);
+		this._filter.type = type;
+	}
+
+	/**
+	 * 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 {
+		// start with all 1s
+		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);
+		// clone the filter to remove any connections which may be changing the value
+		const filterClone = this.context.createBiquadFilter();
+		filterClone.type = this.type;
+		filterClone.Q.value = this.Q.value;
+		filterClone.frequency.value = this.frequency.value as number;
+		filterClone.gain.value = this.gain.value as number;
+		filterClone.getFrequencyResponse(freqValues, magValues, phaseValues);
+		return magValues;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._filter.disconnect();
+		this.Q.dispose();
+		this.frequency.dispose();
+		this.gain.dispose();
+		this.detune.dispose();
+		return this;
+	}
+}

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

@@ -0,0 +1,106 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { ToneAudioBuffer } from "Tone/core/context/ToneAudioBuffer";
+import { Convolver } from "./Convolver";
+
+// @ts-ignore
+if (window.__karma__) {
+	ToneAudioBuffer.baseUrl = "/base/test/";
+}
+
+describe("Convolver", () => {
+
+	BasicTests(Convolver);
+
+	const ir = new ToneAudioBuffer();
+
+	const testFile = "./audio/sineStereo.wav";
+
+	before(() => {
+		return ir.load(testFile);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const convolver = new Convolver({
+				normalize: false,
+				url: testFile,
+			});
+			expect(convolver.normalize).to.be.false;
+			convolver.dispose();
+		});
+
+		it("can get set normalize", () => {
+			const convolver = new Convolver();
+			convolver.normalize = false;
+			expect(convolver.normalize).to.be.false;
+			convolver.dispose();
+		});
+
+		it("invokes the onload function when loaded", (done) => {
+			const convolver = new Convolver({
+				url: testFile,
+				onload(): void {
+					convolver.dispose();
+					done();
+				},
+			});
+		});
+
+		it("load returns a Promise", (done) => {
+			const convolver = new Convolver();
+			convolver.load(testFile).then(() => {
+				convolver.dispose();
+				done();
+			});
+		});
+
+		it("load invokes the second callback", () => {
+			const convolver = new Convolver();
+			return convolver.load(testFile).then(() => {
+				convolver.dispose();
+			});
+		});
+
+		it("can assign the buffer twice", () => {
+			const convolver = new Convolver(ir);
+			convolver.buffer = ir;
+			convolver.dispose();
+		});
+
+		it("can be constructed with a buffer", () => {
+			const convolver = new Convolver(ir);
+			expect((convolver.buffer as ToneAudioBuffer).get()).to.equal(ir.get());
+			convolver.dispose();
+		});
+
+		it("can be constructed with loaded buffer", (done) => {
+			const buffer = new ToneAudioBuffer({
+				url: testFile,
+				onload(): void {
+					const convolver = new Convolver(buffer);
+					expect(convolver.buffer).is.not.null;
+					buffer.dispose();
+					convolver.dispose();
+					done();
+				},
+			});
+		});
+
+		it("can be constructed with unloaded buffer", (done) => {
+			const convolver = new Convolver({
+				url: new ToneAudioBuffer({
+					url: testFile,
+				}),
+				onload(): void {
+					expect(convolver.buffer).is.not.null;
+					convolver.dispose();
+					done();
+				},
+			});
+			// is null before then
+			expect(convolver.buffer).to.be.null;
+		});
+	});
+});

package/Tone/component/filter/Convolver.ts

@@ -0,0 +1,134 @@
+import { ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { ToneAudioBuffer } from "../../core/context/ToneAudioBuffer";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { Gain } from "../../core/context/Gain";
+import { noOp } from "../../core/util/Interface";
+
+export interface ConvolverOptions extends ToneAudioNodeOptions {
+	onload: () => void;
+	normalize: boolean;
+	url?: string | AudioBuffer | ToneAudioBuffer;
+}
+
+/**
+ * Convolver is a wrapper around the Native Web Audio
+ * [ConvolverNode](http://webaudio.github.io/web-audio-api/#the-convolvernode-interface).
+ * Convolution is useful for reverb and filter emulation. Read more about convolution reverb on
+ * [Wikipedia](https://en.wikipedia.org/wiki/Convolution_reverb).
+ *
+ * @example
+ * // initializing the convolver with an impulse response
+ * const convolver = new Tone.Convolver("./path/to/ir.wav").toDestination();
+ * @category Component
+ */
+export class Convolver extends ToneAudioNode<ConvolverOptions> {
+
+	readonly name: string = "Convolver";
+
+	/**
+	 * The native ConvolverNode
+	 */
+	private _convolver: ConvolverNode = this.context.createConvolver();
+
+	/**
+	 * The Buffer belonging to the convolver
+	 */
+	private _buffer: ToneAudioBuffer;
+
+	readonly input: Gain;
+	readonly output: Gain;
+
+	/**
+	 * @param url The URL of the impulse response or the ToneAudioBuffer containing the impulse response.
+	 * @param onload The callback to invoke when the url is loaded.
+	 */
+	constructor(url?: string | AudioBuffer | ToneAudioBuffer, onload?: () => void);
+	constructor(options?: Partial<ConvolverOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Convolver.getDefaults(), arguments, ["url", "onload"]));
+		const options = optionsFromArguments(Convolver.getDefaults(), arguments, ["url", "onload"]);
+
+		this._buffer = new ToneAudioBuffer(options.url, buffer => {
+			this.buffer = buffer;
+			options.onload();
+		});
+
+		this.input = new Gain({ context: this.context });
+		this.output = new Gain({ context: this.context });
+
+		// set if it's already loaded, set it immediately
+		if (this._buffer.loaded) {
+			this.buffer = this._buffer;
+		}
+
+		// initially set normalization
+		this.normalize = options.normalize;
+
+		// connect it up
+		this.input.chain(this._convolver, this.output);
+	}
+
+	static getDefaults(): ConvolverOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			normalize: true,
+			onload: noOp,
+		});
+	}
+
+	/**
+	 * Load an impulse response url as an audio buffer.
+	 * Decodes the audio asynchronously and invokes
+	 * the callback once the audio buffer loads.
+	 * @param url The url of the buffer to load. filetype support depends on the browser.
+	 */
+	async load(url: string): Promise<void> {
+		this.buffer = await this._buffer.load(url);
+	}
+
+	/**
+	 * The convolver's buffer
+	 */
+	get buffer(): ToneAudioBuffer | null {
+		if (this._buffer.length) {
+			return this._buffer;
+		} else {
+			return null;
+		}
+	}
+	set buffer(buffer) {
+		if (buffer) {
+			this._buffer.set(buffer);
+		}
+		// if it's already got a buffer, create a new one
+		if (this._convolver.buffer) {
+			// disconnect the old one
+			this.input.disconnect();
+			this._convolver.disconnect();
+			// create and connect a new one
+			this._convolver = this.context.createConvolver();
+			this.input.chain(this._convolver, this.output);
+		}
+		const buff = this._buffer.get();
+		this._convolver.buffer = buff ? buff : null;
+	}
+
+	/**
+	 * The normalize property of the ConvolverNode interface is a boolean that
+	 * controls whether the impulse response from the buffer will be scaled by
+	 * an equal-power normalization when the buffer attribute is set, or not.
+	 */
+	get normalize(): boolean {
+		return this._convolver.normalize;
+	}
+	set normalize(norm) {
+		this._convolver.normalize = norm;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._buffer.dispose();
+		this._convolver.disconnect();
+		return this;
+	}
+}

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

@@ -0,0 +1,60 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { connectFrom } from "test/helper/Connect";
+import { PassAudio } from "test/helper/PassAudio";
+import { EQ3 } from "./EQ3";
+
+describe("EQ3", () => {
+
+	BasicTests(EQ3);
+
+	context("EQing", () => {
+
+		it("can be constructed with an object", () => {
+			const eq3 = new EQ3({
+				high: -10,
+				highFrequency: 2700,
+				low: -8,
+				lowFrequency: 500,
+				mid: -9,
+			});
+			expect(eq3.low.value).to.be.closeTo(-8, 0.1);
+			expect(eq3.mid.value).to.be.closeTo(-9, 0.1);
+			expect(eq3.high.value).to.be.closeTo(-10, 0.1);
+			expect(eq3.lowFrequency.value).to.be.closeTo(500, 0.01);
+			expect(eq3.highFrequency.value).to.be.closeTo(2700, 0.01);
+			eq3.dispose();
+		});
+
+		it("can be get and set through object", () => {
+			const eq3 = new EQ3();
+			eq3.set({
+				high: -4,
+				lowFrequency: 250,
+			});
+			expect(eq3.get().high).to.be.closeTo(-4, 0.1);
+			expect(eq3.get().lowFrequency).to.be.closeTo(250, 0.01);
+			eq3.dispose();
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio(input => {
+				const eq3 = new EQ3({
+					high: 12,
+					low: -20,
+				}).toDestination();
+				input.connect(eq3);
+			});
+		});
+
+		it.skip("passes the incoming stereo signal through", () => {
+			// return PassAudioStereo(function(input){
+			// 	var eq3 = new EQ3({
+			// 		"mid" : -2,
+			// 		"high" : 2
+			// 	}).toDestination();
+			// 	input.connect(eq3);
+			// });
+		});
+	});
+});