tone 14.8.27

package/Tone/component/filter/EQ3.ts

@@ -0,0 +1,163 @@
+import { Gain } from "../../core/context/Gain";
+import { Param } from "../../core/context/Param";
+import { ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { Decibels, Frequency } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { readOnly, writable } from "../../core/util/Interface";
+import { Signal } from "../../signal/Signal";
+import { MultibandSplit } from "../channel/MultibandSplit";
+
+interface EQ3Options extends ToneAudioNodeOptions {
+	low: Decibels;
+	mid: Decibels;
+	high: Decibels;
+	lowFrequency: Frequency;
+	highFrequency: Frequency;
+}
+
+/**
+ * EQ3 provides 3 equalizer bins: Low/Mid/High. 
+ * @category Component
+ */
+export class EQ3 extends ToneAudioNode<EQ3Options> {
+
+	readonly name: string = "EQ3";
+
+	/**
+	 * the input
+	 */
+	readonly input: MultibandSplit;
+
+	/**
+	 * the output
+	 */
+	readonly output = new Gain({ context: this.context });
+
+	/**
+	 * Splits the input into three outputs
+	 */
+	private _multibandSplit: MultibandSplit;
+
+	/**
+	 * The gain for the lower signals
+	 */
+	private _lowGain: Gain<"decibels">;
+
+	/**
+	 * The gain for the mid signals
+	 */
+	private _midGain: Gain<"decibels">;
+
+	/**
+	 * The gain for the high signals
+	 */
+	private _highGain: Gain<"decibels">;
+
+	/**
+	 * The gain in decibels of the low part
+	 */
+	readonly low: Param<"decibels">;
+
+	/**
+	 * The gain in decibels of the mid part
+	 */
+	readonly mid: Param<"decibels">;
+
+	/**
+	 * The gain in decibels of the high part
+	 */
+	readonly high: Param<"decibels">;
+
+	/**
+	 * The Q value for all of the filters.
+	 */
+	readonly Q: Signal<"positive">;
+
+	/**
+	 * The low/mid crossover frequency.
+	 */
+	readonly lowFrequency: Signal<"frequency">;
+
+	/**
+	 * The mid/high crossover frequency.
+	 */
+	readonly highFrequency: Signal<"frequency">;
+
+	protected _internalChannels: ToneAudioNode[] = [];
+
+	constructor(lowLevel?: Decibels, midLevel?: Decibels, highLevel?: Decibels);
+	constructor(options: Partial<EQ3Options>);
+	constructor() {
+		super(optionsFromArguments(EQ3.getDefaults(), arguments, ["low", "mid", "high"]));
+		const options = optionsFromArguments(EQ3.getDefaults(), arguments, ["low", "mid", "high"]);
+
+		this.input = this._multibandSplit = new MultibandSplit({
+			context: this.context,
+			highFrequency: options.highFrequency,
+			lowFrequency: options.lowFrequency,
+		});
+
+		this._lowGain = new Gain({
+			context: this.context,
+			gain: options.low,
+			units: "decibels",
+		});
+
+		this._midGain = new Gain({
+			context: this.context,
+			gain: options.mid,
+			units: "decibels",
+		});
+
+		this._highGain = new Gain({
+			context: this.context,
+			gain: options.high,
+			units: "decibels",
+		});
+
+		this.low = this._lowGain.gain;
+		this.mid = this._midGain.gain;
+		this.high = this._highGain.gain;
+		this.Q = this._multibandSplit.Q;
+		this.lowFrequency = this._multibandSplit.lowFrequency;
+		this.highFrequency	= this._multibandSplit.highFrequency;
+
+		// the frequency bands
+		this._multibandSplit.low.chain(this._lowGain, this.output);
+		this._multibandSplit.mid.chain(this._midGain, this.output);
+		this._multibandSplit.high.chain(this._highGain, this.output);
+
+		readOnly(this, ["low", "mid", "high", "lowFrequency", "highFrequency"]);
+		this._internalChannels = [this._multibandSplit];
+	}
+
+	static getDefaults(): EQ3Options {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			high: 0,
+			highFrequency: 2500,
+			low: 0,
+			lowFrequency: 400,
+			mid: 0,
+		});
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		writable(this, ["low", "mid", "high", "lowFrequency", "highFrequency"]);
+		this._multibandSplit.dispose();
+		this.lowFrequency.dispose();
+		this.highFrequency.dispose();
+		this._lowGain.dispose();
+		this._midGain.dispose();
+		this._highGain.dispose();
+		this.low.dispose();
+		this.mid.dispose();
+		this.high.dispose();
+		this.Q.dispose();
+		return this;
+	}
+
+}

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

@@ -0,0 +1,80 @@
+import { expect } from "chai";
+import { FeedbackCombFilter } from "./FeedbackCombFilter";
+import { BasicTests } from "test/helper/Basic";
+import { PassAudio } from "test/helper/PassAudio";
+import { Offline } from "test/helper/Offline";
+import { Signal } from "Tone/signal";
+
+describe("FeedbackCombFilter", () => {
+
+	BasicTests(FeedbackCombFilter);
+
+	context("Comb Filtering", () => {
+
+		it("can be constructed with an object", () => {
+			const fbcf = new FeedbackCombFilter({
+				delayTime: 0.2,
+				resonance: 0.3,
+			});
+			expect(fbcf.delayTime.value).to.be.closeTo(0.2, 0.001);
+			expect(fbcf.resonance.value).to.be.closeTo(0.3, 0.001);
+			fbcf.dispose();
+		});
+
+		it("can be get and set through object", () => {
+			const fbcf = new FeedbackCombFilter();
+			fbcf.set({
+				delayTime: 0.2,
+				resonance: 0.3,
+			});
+			const values = fbcf.get();
+			expect(values.delayTime).to.be.closeTo(0.2, 0.001);
+			expect(values.resonance).to.be.closeTo(0.3, 0.001);
+			fbcf.dispose();
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio(input => {
+				const fbcf = new FeedbackCombFilter({
+					delayTime: 0.0,
+					resonance: 0,
+				}).toDestination();
+				input.connect(fbcf);
+			});
+		});
+
+		it("can delay by the delayTime", () => {
+			return Offline(() => {
+				const fbcf = new FeedbackCombFilter({
+					delayTime: 0.1,
+					resonance: 0,
+				}).toDestination();
+				const sig = new Signal(0).connect(fbcf);
+				sig.setValueAtTime(1, 0);
+			}, 0.2).then(buffer => {
+				expect(buffer.getValueAtTime(0)).to.equal(0);
+				expect(buffer.getValueAtTime(0.999)).to.equal(0);
+				expect(buffer.getValueAtTime(0.101)).to.equal(1);
+				expect(buffer.getValueAtTime(0.15)).to.equal(1);
+			});
+		});
+
+		it("can delay with feedback", () => {
+			return Offline(() => {
+				const fbcf = new FeedbackCombFilter({
+					delayTime: 0.1,
+					resonance: 0.5,
+				}).toDestination();
+				const sig = new Signal(0).connect(fbcf);
+				sig.setValueAtTime(1, 0);
+				sig.setValueAtTime(0, 0.1);
+			}, 0.4).then(buffer => {
+				expect(buffer.getValueAtTime(0)).to.equal(0);
+				expect(buffer.getValueAtTime(0.101)).to.equal(1);
+				expect(buffer.getValueAtTime(0.201)).to.equal(0.5);
+				expect(buffer.getValueAtTime(0.301)).to.equal(0.25);
+			});
+		});
+	});
+});
+

package/Tone/component/filter/FeedbackCombFilter.ts

@@ -0,0 +1,105 @@
+import { Gain } from "../../core/context/Gain";
+import { Param } from "../../core/context/Param";
+import { connectSeries, ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { NormalRange, Time } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { readOnly, RecursivePartial } from "../../core/util/Interface";
+import { ToneAudioWorklet } from "../../core/worklet/ToneAudioWorklet";
+import { workletName } from "./FeedbackCombFilter.worklet";
+
+export interface FeedbackCombFilterOptions extends ToneAudioNodeOptions {
+	delayTime: Time;
+	resonance: NormalRange;
+}
+
+/**
+ * Comb filters are basic building blocks for physical modeling. Read more
+ * about comb filters on [CCRMA's website](https://ccrma.stanford.edu/~jos/pasp/Feedback_Comb_Filters.html).
+ * 
+ * This comb filter is implemented with the AudioWorkletNode which allows it to have feedback delays less than the 
+ * Web Audio processing block of 128 samples. There is a polyfill for browsers that don't yet support the 
+ * AudioWorkletNode, but it will add some latency and have slower performance than the AudioWorkletNode. 
+ * @category Component
+ */
+export class FeedbackCombFilter extends ToneAudioWorklet<FeedbackCombFilterOptions> {
+
+	readonly name = "FeedbackCombFilter";
+
+	/**
+	 * The amount of delay of the comb filter.
+	 */
+	readonly delayTime: Param<"time">;
+
+	/**
+	 * The amount of feedback of the delayed signal.
+	 */
+	readonly resonance: Param<"normalRange">;
+
+	readonly input: Gain;
+	readonly output: Gain;
+
+	/**
+	 * @param delayTime The delay time of the filter.
+	 * @param resonance The amount of feedback the filter has.
+	 */
+	constructor(delayTime?: Time, resonance?: NormalRange);
+	constructor(options?: RecursivePartial<FeedbackCombFilterOptions>);
+	constructor() {
+		super(optionsFromArguments(FeedbackCombFilter.getDefaults(), arguments, ["delayTime", "resonance"]));
+		const options = optionsFromArguments(FeedbackCombFilter.getDefaults(), arguments, ["delayTime", "resonance"]);
+
+		this.input = new Gain({ context: this.context });
+		this.output = new Gain({ context: this.context });
+
+		this.delayTime = new Param<"time">({
+			context: this.context,
+			value: options.delayTime,
+			units: "time",
+			minValue: 0,
+			maxValue: 1,
+			param: this._dummyParam,
+			swappable: true,
+		});
+
+		this.resonance = new Param<"normalRange">({
+			context: this.context,
+			value: options.resonance,
+			units: "normalRange",
+			param: this._dummyParam,
+			swappable: true,
+		});
+
+		readOnly(this, ["resonance", "delayTime"]);
+	}
+
+	protected _audioWorkletName(): string {
+		return workletName;
+	}
+
+	/**
+	 * The default parameters
+	 */
+	static getDefaults(): FeedbackCombFilterOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			delayTime: 0.1,
+			resonance: 0.5,
+		});
+	}
+
+	onReady(node: AudioWorkletNode) {
+		connectSeries(this.input, node, this.output);
+		const delayTime = node.parameters.get("delayTime") as AudioParam;;
+		this.delayTime.setParam(delayTime);
+		const feedback = node.parameters.get("feedback") as AudioParam;;
+		this.resonance.setParam(feedback);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.input.dispose();
+		this.output.dispose();
+		this.delayTime.dispose();
+		this.resonance.dispose();
+		return this;
+	}
+}

package/Tone/component/filter/FeedbackCombFilter.worklet.ts

@@ -0,0 +1,39 @@
+import "../../core/worklet/SingleIOProcessor.worklet";
+import "../../core/worklet/DelayLine.worklet";
+import { registerProcessor } from "../../core/worklet/WorkletGlobalScope";
+
+export const workletName = "feedback-comb-filter";
+
+const feedbackCombFilter = /* javascript */`
+	class FeedbackCombFilterWorklet extends SingleIOProcessor {
+
+		constructor(options) {
+			super(options);
+			this.delayLine = new DelayLine(this.sampleRate, options.channelCount || 2);
+		}
+
+		static get parameterDescriptors() {
+			return [{
+				name: "delayTime",
+				defaultValue: 0.1,
+				minValue: 0,
+				maxValue: 1,
+				automationRate: "k-rate"
+			}, {
+				name: "feedback",
+				defaultValue: 0.5,
+				minValue: 0,
+				maxValue: 0.9999,
+				automationRate: "k-rate"
+			}];
+		}
+
+		generate(input, channel, parameters) {
+			const delayedSample = this.delayLine.get(channel, parameters.delayTime * this.sampleRate);
+			this.delayLine.push(channel, input + delayedSample * parameters.feedback);
+			return delayedSample;
+		}
+	}
+`;
+
+registerProcessor(workletName, feedbackCombFilter);

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

@@ -0,0 +1,114 @@
+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 { Filter, FilterRollOff } from "./Filter";
+
+describe("Filter", () => {
+
+	BasicTests(Filter);
+
+	context("Filtering", () => {
+
+		it("can be constructed with a arguments", () => {
+			const filter = new Filter(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 Filter({
+				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 Filter();
+			const values = {
+				Q: 2,
+				frequency: 440,
+				gain: -6,
+				rolloff: -24 as FilterRollOff,
+				type: "highpass" as BiquadFilterType,
+			};
+			filter.set(values);
+			expect(filter.get()).to.include.keys(["type", "frequency", "rolloff", "Q", "gain"]);
+			expect(filter.type).to.equal(values.type);
+			expect(filter.frequency.value).to.equal(values.frequency);
+			expect(filter.rolloff).to.equal(values.rolloff);
+			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 Filter();
+			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 Filter().toDestination();
+				input.connect(filter);
+			});
+		});
+
+		it("only accepts filter values -12, -24, -48 and -96", () => {
+			const filter = new Filter();
+			filter.rolloff = -12;
+			expect(filter.rolloff).to.equal(-12);
+			// @ts-ignore
+			filter.rolloff = "-24";
+			expect(filter.rolloff).to.equal(-24);
+			filter.rolloff = -48;
+			expect(filter.rolloff).to.equal(-48);
+			filter.rolloff = -96;
+			expect(filter.rolloff).to.equal(-96);
+			expect(() => {
+				// @ts-ignore
+				filter.rolloff = -95;
+			}).to.throw(Error);
+			filter.dispose();
+		});
+
+		it("can set the basic filter types", () => {
+			const filter = new Filter();
+			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 Filter(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/Filter.ts

@@ -0,0 +1,202 @@
+import { Gain } from "../../core/context/Gain";
+import { connectSeries, ToneAudioNode } from "../../core/context/ToneAudioNode";
+import { Frequency } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { readOnly, writable } from "../../core/util/Interface";
+import { isNumber } from "../../core/util/TypeCheck";
+import { Signal } from "../../signal/Signal";
+import { assert } from "../../core/util/Debug";
+import { BiquadFilter, BiquadFilterOptions } from "./BiquadFilter";
+
+export type FilterRollOff = -12 | -24 | -48 | -96;
+
+export type FilterOptions = BiquadFilterOptions & {
+	rolloff: FilterRollOff;
+}
+
+/**
+ * Tone.Filter is a filter which allows for all of the same native methods
+ * as the [BiquadFilterNode](http://webaudio.github.io/web-audio-api/#the-biquadfilternode-interface).
+ * Tone.Filter has the added ability to set the filter rolloff at -12
+ * (default), -24 and -48.
+ * @example
+ * const filter = new Tone.Filter(1500, "highpass").toDestination();
+ * filter.frequency.rampTo(20000, 10);
+ * const noise = new Tone.Noise().connect(filter).start();
+ * @category Component
+ */
+export class Filter extends ToneAudioNode<FilterOptions> {
+
+	readonly name: string = "Filter";
+
+	readonly input = new Gain({ context: this.context });
+	readonly output = new Gain({ context: this.context });
+	private _filters: BiquadFilter[] = [];
+
+	/**
+	 * the rolloff value of the filter
+	 */
+	private _rolloff!: FilterRollOff;
+	private _type: BiquadFilterType;
+
+	/**
+	 * The Q or Quality of the filter
+	 */
+	readonly Q: Signal<"positive">;
+
+	/**
+	 * The cutoff frequency of the filter.
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The detune parameter
+	 */
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * The gain of the filter, only used in certain filter types
+	 */
+	readonly gain: Signal<"decibels">;
+
+	/**
+	 * @param frequency The cutoff frequency of the filter.
+	 * @param type The type of filter.
+	 * @param rolloff The drop in decibels per octave after the cutoff frequency
+	 */
+	constructor(frequency?: Frequency, type?: BiquadFilterType, rolloff?: FilterRollOff);
+	constructor(options?: Partial<FilterOptions>);
+	constructor() {
+		super(optionsFromArguments(Filter.getDefaults(), arguments, ["frequency", "type", "rolloff"]));
+		const options = optionsFromArguments(Filter.getDefaults(), arguments, ["frequency", "type", "rolloff"]);
+
+		this._filters = [];
+
+		this.Q = new Signal({
+			context: this.context,
+			units: "positive",
+			value: options.Q,
+		});
+		this.frequency = new Signal({
+			context: this.context,
+			units: "frequency",
+			value: options.frequency,
+		});
+		this.detune = new Signal({
+			context: this.context,
+			units: "cents",
+			value: options.detune,
+		});
+		this.gain = new Signal({
+			context: this.context,
+			units: "decibels",
+			convert: false,
+			value: options.gain,
+		});
+		this._type = options.type;
+		this.rolloff = options.rolloff;
+		readOnly(this, ["detune", "frequency", "gain", "Q"]);
+	}
+
+	static getDefaults(): FilterOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			Q: 1,
+			detune: 0,
+			frequency: 350,
+			gain: 0,
+			rolloff: -12 as FilterRollOff,
+			type: "lowpass" as BiquadFilterType,
+		});
+	}
+
+	/**
+	 * The type of the filter. Types: "lowpass", "highpass",
+	 * "bandpass", "lowshelf", "highshelf", "notch", "allpass", or "peaking".
+	 */
+	get type(): BiquadFilterType {
+		return this._type;
+	}
+	set type(type: BiquadFilterType) {
+		const types: BiquadFilterType[] = ["lowpass", "highpass", "bandpass",
+			"lowshelf", "highshelf", "notch", "allpass", "peaking"];
+		assert(types.indexOf(type) !== -1, `Invalid filter type: ${type}`);
+		this._type = type;
+		this._filters.forEach(filter => filter.type = type);
+	}
+
+	/**
+	 * The rolloff of the filter which is the drop in db
+	 * per octave. Implemented internally by cascading filters.
+	 * Only accepts the values -12, -24, -48 and -96.
+	 */
+	get rolloff(): FilterRollOff {
+		return this._rolloff;
+	}
+	set rolloff(rolloff) {
+		const rolloffNum = isNumber(rolloff) ? rolloff : parseInt(rolloff, 10) as FilterRollOff;
+		const possibilities = [-12, -24, -48, -96];
+		let cascadingCount = possibilities.indexOf(rolloffNum);
+		// check the rolloff is valid
+		assert(cascadingCount !== -1, `rolloff can only be ${possibilities.join(", ")}`);
+		cascadingCount += 1;
+
+		this._rolloff = rolloffNum;
+		this.input.disconnect();
+		this._filters.forEach(filter => filter.disconnect());
+
+		this._filters = new Array(cascadingCount);
+		for (let count = 0; count < cascadingCount; count++) {
+			const filter = new BiquadFilter({
+				context: this.context,
+			});
+			filter.type = this._type;
+			this.frequency.connect(filter.frequency);
+			this.detune.connect(filter.detune);
+			this.Q.connect(filter.Q);
+			this.gain.connect(filter.gain);
+			this._filters[count] = filter;
+		}
+		this._internalChannels = this._filters;
+		connectSeries(this.input, ...this._internalChannels, this.output);
+	}
+
+	/**
+	 * 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 filterClone = new BiquadFilter({
+			frequency: this.frequency.value,
+			gain: this.gain.value,
+			Q: this.Q.value,
+			type: this._type,
+			detune: this.detune.value,
+		});
+		// start with all 1s
+		const totalResponse = new Float32Array(len).map(() => 1);
+		this._filters.forEach(() => {
+			const response = filterClone.getFrequencyResponse(len);
+			response.forEach((val, i) => totalResponse[i] *= val);
+		});
+		filterClone.dispose();
+		return totalResponse;
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this._filters.forEach(filter => {
+			filter.dispose();
+		});
+		writable(this, ["detune", "frequency", "gain", "Q"]);
+		this.frequency.dispose();
+		this.Q.dispose();
+		this.detune.dispose();
+		this.gain.dispose();
+		return this;
+	}
+}