tone 14.8.27

package/Tone/component/analysis/Analyser.test.ts

@@ -0,0 +1,78 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { Noise } from "../../source/Noise";
+import { Analyser } from "./Analyser";
+
+describe("Analyser", () => {
+
+	BasicTests(Analyser);
+
+	it("can get and set properties", () => {
+		const anl = new Analyser();
+		anl.set({
+			size: 32,
+			smoothing: 0.2,
+		});
+		const values = anl.get();
+		expect(values.size).to.equal(32);
+		expect(values.smoothing).to.equal(0.2);
+		anl.dispose();
+	});
+
+	it("can correctly set the size", () => {
+		const anl = new Analyser("fft", 512);
+		expect(anl.size).to.equal(512);
+		anl.size = 1024;
+		expect(anl.size).to.equal(1024);
+		anl.dispose();
+	});
+
+	it("can run fft analysis", () => {
+		const anl = new Analyser("fft", 512);
+		const analysis = anl.getValue();
+		expect(analysis.length).to.equal(512);
+		analysis.forEach(val => {
+			expect(val).is.lessThan(0);
+		});
+		anl.dispose();
+	});
+
+	it("can run waveform analysis", (done) => {
+		const noise = new Noise();
+		const anl = new Analyser("waveform", 256);
+		noise.connect(anl);
+		noise.start();
+
+		setTimeout(() => {
+			const analysis = anl.getValue();
+			expect(analysis.length).to.equal(256);
+			analysis.forEach(val => {
+				expect(val).is.within(-1, 1);
+			});
+			anl.dispose();
+			noise.dispose();
+			done();
+		}, 300);
+	});
+
+	it("throws an error if an invalid type is set", () => {
+		const anl = new Analyser("fft", 512);
+		expect(() => {
+			// @ts-ignore
+			anl.type = "invalid";
+		}).to.throw(Error);
+		anl.dispose();
+	});
+
+	it("can do multichannel analysis", () => {
+		const anl = new Analyser({
+			type: "waveform",
+			channels: 2,
+			size: 512,
+		});
+		expect(anl.getValue().length).to.equal(2);
+		expect((anl.getValue()[0] as Float32Array).length).to.equal(512);
+		anl.dispose();
+	});
+
+});

package/Tone/component/analysis/Analyser.ts

@@ -0,0 +1,168 @@
+import { InputNode, OutputNode, ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { NormalRange, PowerOfTwo } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { Split } from "../channel/Split";
+import { Gain } from "../../core/context/Gain";
+import { assert, assertRange } from "../../core/util/Debug";
+
+export type AnalyserType = "fft" | "waveform";
+
+export interface AnalyserOptions extends ToneAudioNodeOptions {
+	size: PowerOfTwo;
+	type: AnalyserType;
+	smoothing: NormalRange;
+	channels: number;
+}
+
+/**
+ * Wrapper around the native Web Audio's [AnalyserNode](http://webaudio.github.io/web-audio-api/#idl-def-AnalyserNode).
+ * Extracts FFT or Waveform data from the incoming signal.
+ * @category Component
+ */
+export class Analyser extends ToneAudioNode<AnalyserOptions> {
+
+	readonly name: string = "Analyser";
+
+	readonly input: InputNode;
+	readonly output: OutputNode;
+
+	/**
+	 * The analyser node.
+	 */
+	private _analysers: AnalyserNode[] = [];
+
+	/**
+	 * Input and output are a gain node
+	 */
+	private _gain: Gain;
+
+	/**
+	 * The channel splitter node
+	 */
+	private _split: Split;
+
+	/**
+	 * The analysis type
+	 */
+	private _type!: AnalyserType;
+
+	/**
+	 * The buffer that the FFT data is written to
+	 */
+	private _buffers: Float32Array[] = [];
+
+	/**
+	 * @param type The return type of the analysis, either "fft", or "waveform".
+	 * @param size The size of the FFT. This must be a power of two in the range 16 to 16384.
+	 */
+	constructor(type?: AnalyserType, size?: number);
+	constructor(options?: Partial<AnalyserOptions>);
+	constructor() {
+		super(optionsFromArguments(Analyser.getDefaults(), arguments, ["type", "size"]));
+		const options = optionsFromArguments(Analyser.getDefaults(), arguments, ["type", "size"]);
+
+		this.input = this.output = this._gain = new Gain({ context: this.context });
+		this._split = new Split({
+			context: this.context,
+			channels: options.channels,
+		});
+		this.input.connect(this._split);
+		
+		assertRange(options.channels, 1);
+		
+		// create the analysers
+		for (let channel = 0; channel < options.channels; channel++) {
+			this._analysers[channel] = this.context.createAnalyser();
+			this._split.connect(this._analysers[channel], channel, 0);
+		}
+
+		// set the values initially
+		this.size = options.size;
+		this.type = options.type;
+		this.smoothing = options.smoothing;
+	}
+
+	static getDefaults(): AnalyserOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			size: 1024,
+			smoothing: 0.8,
+			type: "fft" as AnalyserType,
+			channels: 1,
+		});
+	}
+
+	/**
+	 * Run the analysis given the current settings. If [[channels]] = 1,
+	 * it will return a Float32Array. If [[channels]] > 1, it will
+	 * return an array of Float32Arrays where each index in the array
+	 * represents the analysis done on a channel.
+	 */
+	getValue(): Float32Array | Float32Array[] {
+		this._analysers.forEach((analyser, index) => {
+			const buffer = this._buffers[index];
+			if (this._type === "fft") {
+				analyser.getFloatFrequencyData(buffer);
+			} else if (this._type === "waveform") {
+				analyser.getFloatTimeDomainData(buffer);
+			}
+		});
+		if (this.channels === 1) {
+			return this._buffers[0];
+		} else {
+			return this._buffers;
+		}
+	}
+
+	/**
+	 * The size of analysis. This must be a power of two in the range 16 to 16384.
+	 */
+	get size(): PowerOfTwo {
+		return this._analysers[0].frequencyBinCount;
+	}
+	set size(size: PowerOfTwo) {
+		this._analysers.forEach((analyser, index) => {
+			analyser.fftSize = size * 2;
+			this._buffers[index] = new Float32Array(size);
+		});
+	}
+
+	/**
+	 * The number of channels the analyser does the analysis on. Channel
+	 * separation is done using [[Split]]
+	 */
+	get channels(): number {
+		return this._analysers.length;
+	}
+
+	/**
+	 * The analysis function returned by analyser.getValue(), either "fft" or "waveform".
+	 */
+	get type(): AnalyserType {
+		return this._type;
+	}
+	set type(type: AnalyserType) {
+		assert(type === "waveform" || type === "fft", `Analyser: invalid type: ${type}`);
+		this._type = type;
+	}
+
+	/**
+	 * 0 represents no time averaging with the last analysis frame.
+	 */
+	get smoothing(): NormalRange {
+		return this._analysers[0].smoothingTimeConstant;
+	}
+	set smoothing(val: NormalRange) {
+		this._analysers.forEach(a => a.smoothingTimeConstant = val);
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this._analysers.forEach(a => a.disconnect());
+		this._split.dispose();
+		this._gain.dispose();
+		return this;
+	}
+}

package/Tone/component/analysis/DCMeter.test.ts

@@ -0,0 +1,34 @@
+import { expect } from "chai";
+import { BasicTests, warns } from "test/helper/Basic";
+import { PassAudio } from "test/helper/PassAudio";
+import { ONLINE_TESTING } from "test/helper/Supports";
+import { Signal } from "Tone/signal/Signal";
+import { DCMeter } from "./DCMeter";
+
+describe("DCMeter", () => {
+
+	BasicTests(DCMeter);
+
+	context("DCMetering", () => {
+
+		it("passes the audio through", () => {
+			return PassAudio((input) => {
+				const meter = new DCMeter().toDestination();
+				input.connect(meter);
+			});
+		});
+
+		if (ONLINE_TESTING) {
+			it("can get the rms level of the incoming signal", (done) => {
+				const meter = new DCMeter();
+				const osc = new Signal(2).connect(meter);
+				setTimeout(() => {
+					expect(meter.getValue()).to.be.closeTo(2, 0.1);
+					meter.dispose();
+					osc.dispose();
+					done();
+				}, 400);
+			});
+		}
+	});
+});

package/Tone/component/analysis/DCMeter.ts

@@ -0,0 +1,38 @@
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { MeterBase, MeterBaseOptions } from "./MeterBase";
+
+export type DCMeterOptions = MeterBaseOptions;
+
+/**
+ * DCMeter gets the raw value of the input signal at the current time.
+ *
+ * @example
+ * const meter = new Tone.DCMeter();
+ * const mic = new Tone.UserMedia();
+ * mic.open();
+ * // connect mic to the meter
+ * mic.connect(meter);
+ * // the current level of the mic
+ * const level = meter.getValue();
+ * @category Component
+ */
+export class DCMeter extends MeterBase<DCMeterOptions> {
+
+	readonly name: string = "DCMeter";
+
+	constructor(options?: Partial<DCMeterOptions>);
+	constructor() {
+		super(optionsFromArguments(DCMeter.getDefaults(), arguments));
+
+		this._analyser.type = "waveform";
+		this._analyser.size = 256;
+	}
+
+	/**
+	 * Get the signal value of the incoming signal
+	 */
+	getValue(): number {
+		const value = this._analyser.getValue() as Float32Array;
+		return value[0];
+	}
+}

package/Tone/component/analysis/FFT.test.ts

@@ -0,0 +1,83 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { ONLINE_TESTING } from "test/helper/Supports";
+import { Noise } from "Tone/source/Noise";
+import { FFT } from "./FFT";
+
+describe("FFT", () => {
+
+	BasicTests(FFT);
+
+	it("can get and set properties", () => {
+		const fft = new FFT();
+		fft.set({
+			size: 128,
+			smoothing: 0.4,
+		});
+		const values = fft.get();
+		expect(values.size).to.equal(128);
+		expect(values.smoothing).to.equal(0.4);
+		fft.dispose();
+	});
+
+	it("can correctly set the size", () => {
+		const fft = new FFT(512);
+		expect(fft.size).to.equal(512);
+		fft.size = 1024;
+		expect(fft.size).to.equal(1024);
+		fft.dispose();
+	});
+
+	it("can set the smoothing", () => {
+		const fft = new FFT(512);
+		fft.smoothing = 0.2;
+		expect(fft.smoothing).to.equal(0.2);
+		fft.dispose();
+	});
+
+	it("can get the frequency values of each index of the return array", () => {
+		const fft = new FFT(32);
+		expect(fft.getFrequencyOfIndex(0)).to.be.closeTo(0, 1);
+		expect(fft.getFrequencyOfIndex(16)).to.be.closeTo(fft.context.sampleRate / 4, 1);
+		fft.dispose();
+	});
+
+	it("can run waveform analysis", (done) => {
+		const noise = new Noise();
+		const fft = new FFT(256);
+		noise.connect(fft);
+		noise.start();
+
+		setTimeout(() => {
+			const analysis = fft.getValue();
+			expect(analysis.length).to.equal(256);
+			analysis.forEach(value => {
+				expect(value).is.within(-Infinity, 0);
+			});
+			fft.dispose();
+			noise.dispose();
+			done();
+		}, 300);
+	});
+
+	if (ONLINE_TESTING) {
+		it("outputs a normal range", (done) => {
+			const noise = new Noise();
+			const fft = new FFT({
+				normalRange: true,
+			});
+			noise.connect(fft);
+			noise.start();
+
+			setTimeout(() => {
+				const analysis = fft.getValue();
+				analysis.forEach(value => {
+					expect(value).is.within(0, 1);
+				});
+				fft.dispose();
+				noise.dispose();
+				done();
+			}, 300);
+		});
+	}
+});

package/Tone/component/analysis/FFT.ts

@@ -0,0 +1,92 @@
+import { ToneAudioNode } from "../../core/context/ToneAudioNode";
+import { dbToGain } from "../../core/type/Conversions";
+import { Hertz, NormalRange, PowerOfTwo } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { MeterBase, MeterBaseOptions } from "./MeterBase";
+import { assert } from "../../core/util/Debug";
+
+export interface FFTOptions extends MeterBaseOptions {
+	size: PowerOfTwo;
+	smoothing: NormalRange;
+	normalRange: boolean;
+}
+
+/**
+ * Get the current frequency data of the connected audio source using a fast Fourier transform.
+ * @category Component
+ */
+export class FFT extends MeterBase<FFTOptions> {
+
+	readonly name: string = "FFT";
+
+	/**
+	 * If the output should be in decibels or normal range between 0-1. If `normalRange` is false,
+	 * the output range will be the measured decibel value, otherwise the decibel value will be converted to
+	 * the range of 0-1
+	 */
+	normalRange: boolean;
+
+	/**
+	 * @param size The size of the FFT. Value must be a power of two in the range 16 to 16384.
+	 */
+	constructor(size?: PowerOfTwo);
+	constructor(options?: Partial<FFTOptions>);
+	constructor() {
+		super(optionsFromArguments(FFT.getDefaults(), arguments, ["size"]));
+		const options = optionsFromArguments(FFT.getDefaults(), arguments, ["size"]);
+
+		this.normalRange = options.normalRange;
+		this._analyser.type = "fft";
+		this.size = options.size;
+	}
+
+	static getDefaults(): FFTOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			normalRange: false,
+			size: 1024,
+			smoothing: 0.8,
+		});
+	}
+
+	/**
+	 * Gets the current frequency data from the connected audio source.
+	 * Returns the frequency data of length [[size]] as a Float32Array of decibel values.
+	 */
+	getValue(): Float32Array {
+		const values = this._analyser.getValue() as Float32Array;
+		return values.map(v => this.normalRange ? dbToGain(v) : v);
+	}
+
+	/**
+	 * The size of analysis. This must be a power of two in the range 16 to 16384.
+	 * Determines the size of the array returned by [[getValue]] (i.e. the number of
+	 * frequency bins). Large FFT sizes may be costly to compute.
+	 */
+	get size(): PowerOfTwo {
+		return this._analyser.size;
+	}
+	set size(size) {
+		this._analyser.size = size;
+	}
+
+	/**
+	 * 0 represents no time averaging with the last analysis frame.
+	 */
+	get smoothing(): NormalRange {
+		return this._analyser.smoothing;
+	}
+	set smoothing(val) {
+		this._analyser.smoothing = val;
+	}
+
+	/**
+	 * Returns the frequency value in hertz of each of the indices of the FFT's [[getValue]] response.
+	 * @example
+	 * const fft = new Tone.FFT(32);
+	 * console.log([0, 1, 2, 3, 4].map(index => fft.getFrequencyOfIndex(index)));
+	 */
+	getFrequencyOfIndex(index: number): Hertz {
+		assert(0 <= index && index < this.size, `index must be greater than or equal to 0 and less than ${this.size}`);
+		return index * this.context.sampleRate / (this.size * 2);
+	}
+}

package/Tone/component/analysis/Follower.test.ts

@@ -0,0 +1,111 @@
+import { Follower } from "./Follower";
+import { BasicTests } from "test/helper/Basic";
+import { Offline } from "test/helper/Offline";
+import { Signal } from "Tone/signal/Signal";
+import { PassAudio } from "test/helper/PassAudio";
+import { expect } from "chai";
+
+describe("Follower", () => {
+
+	BasicTests(Follower);
+
+	context("Envelope Following", () => {
+
+		it("handles getter/setter as Object", () => {
+			const foll = new Follower();
+			const values = {
+				smoothing: 0.2,
+			};
+			foll.set(values);
+			expect(foll.get()).to.have.keys(["smoothing"]);
+			expect(foll.get().smoothing).to.be.closeTo(0.2, 0.001);
+			foll.dispose();
+		});
+
+		it("can be constructed with an object", () => {
+			const follower = new Follower({
+				smoothing: 0.5,
+			});
+			expect(follower.smoothing).to.be.closeTo(0.5, 0.001);
+			follower.dispose();
+		});
+
+		it("smooths the incoming signal at 0.1", () => {
+			return Offline(() => {
+				const foll = new Follower(0.1).toDestination();
+				const sig = new Signal(0);
+				sig.connect(foll);
+				sig.setValueAtTime(1, 0.1);
+				sig.setValueAtTime(0, 0.3);
+			}, 0.41).then((buffer) => {
+				expect(buffer.getValueAtTime(0)).to.be.closeTo(0, 0.01);
+				expect(buffer.getValueAtTime(0.1)).to.be.closeTo(0.0, 0.01);
+				expect(buffer.getValueAtTime(0.15)).to.be.closeTo(0.95, 0.05);
+				expect(buffer.getValueAtTime(0.2)).to.be.closeTo(1, 0.01);
+				expect(buffer.getValueAtTime(0.3)).to.be.closeTo(1, 0.01);
+				expect(buffer.getValueAtTime(0.35)).to.be.closeTo(0.05, 0.05);
+				expect(buffer.getValueAtTime(0.4)).to.be.closeTo(0, 0.01);
+			});
+		});
+
+		it("smooths the incoming signal at 0.05", () => {
+			return Offline(() => {
+				const foll = new Follower(0.05).toDestination();
+				const sig = new Signal(0);
+				sig.connect(foll);
+				sig.setValueAtTime(1, 0.1);
+				sig.setValueAtTime(0, 0.3);
+			}, 0.41).then((buffer) => {
+				expect(buffer.getValueAtTime(0)).to.be.closeTo(0, 0.01);
+				expect(buffer.getValueAtTime(0.1)).to.be.closeTo(0.0, 0.01);
+				expect(buffer.getValueAtTime(0.125)).to.be.closeTo(0.95, 0.05);
+				expect(buffer.getValueAtTime(0.15)).to.be.closeTo(1, 0.01);
+				expect(buffer.getValueAtTime(0.3)).to.be.closeTo(1, 0.01);
+				expect(buffer.getValueAtTime(0.325)).to.be.closeTo(0.05, 0.05);
+				expect(buffer.getValueAtTime(0.35)).to.be.closeTo(0, 0.01);
+			});
+		});
+
+		it("smooths the incoming signal at 0.2", () => {
+			return Offline(() => {
+				const foll = new Follower(0.2).toDestination();
+				const sig = new Signal(0);
+				sig.connect(foll);
+				sig.setValueAtTime(1, 0.1);
+				sig.setValueAtTime(0, 0.3);
+			}, 0.51).then((buffer) => {
+				expect(buffer.getValueAtTime(0)).to.be.closeTo(0, 0.01);
+				expect(buffer.getValueAtTime(0.1)).to.be.closeTo(0.0, 0.01);
+				expect(buffer.getValueAtTime(0.2)).to.be.closeTo(0.95, 0.05);
+				expect(buffer.getValueAtTime(0.3)).to.be.closeTo(1, 0.01);
+				expect(buffer.getValueAtTime(0.4)).to.be.closeTo(0.05, 0.05);
+				expect(buffer.getValueAtTime(0.5)).to.be.closeTo(0, 0.01);
+			});
+		});
+
+		it("smooths the incoming signal at 0.5", () => {
+			return Offline(() => {
+				const foll = new Follower(0.5).toDestination();
+				const sig = new Signal(0);
+				sig.connect(foll);
+				sig.setValueAtTime(1, 0.1);
+				sig.setValueAtTime(0, 0.6);
+			}, 1.11).then((buffer) => {
+				expect(buffer.getValueAtTime(0)).to.be.closeTo(0, 0.01);
+				expect(buffer.getValueAtTime(0.1)).to.be.closeTo(0.0, 0.01);
+				expect(buffer.getValueAtTime(0.35)).to.be.closeTo(0.95, 0.05);
+				expect(buffer.getValueAtTime(0.6)).to.be.closeTo(1, 0.01);
+				expect(buffer.getValueAtTime(0.85)).to.be.closeTo(0.05, 0.05);
+				expect(buffer.getValueAtTime(1.1)).to.be.closeTo(0, 0.01);
+			});
+		});
+
+		it("passes the incoming signal through", () => {
+			return PassAudio((input) => {
+				const follower = new Follower().toDestination();
+				input.connect(follower);
+			});
+		});
+	});
+});
+

package/Tone/component/analysis/Follower.ts

@@ -0,0 +1,85 @@
+import { Time } from "../../core/type/Units";
+import { InputNode, OutputNode, ToneAudioNode, ToneAudioNodeOptions } from "../../core/context/ToneAudioNode";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { OnePoleFilter } from "../filter/OnePoleFilter";
+import { Abs } from "../../signal/Abs";
+
+export interface FollowerOptions extends ToneAudioNodeOptions {
+	smoothing: Time;
+}
+
+/**
+ * Follower is a simple envelope follower. 
+ * It's implemented by applying a lowpass filter to the absolute value of the incoming signal. 
+ * ```
+ *          +-----+    +---------------+
+ * Input +--> Abs +----> OnePoleFilter +--> Output
+ *          +-----+    +---------------+
+ * ```
+ * @category Component
+ */
+export class Follower extends ToneAudioNode<FollowerOptions> {
+
+	readonly name: string = "Follower";
+
+	readonly input: InputNode;
+	readonly output: OutputNode;
+
+	/**
+	 * Private reference to the smoothing parameter
+	 */
+	private _smoothing: Time;
+
+	/**
+	 * The lowpass filter
+	 */
+	private _lowpass: OnePoleFilter;
+
+	/**
+	 * The absolute value
+	 */
+	private _abs: Abs;
+
+	/**
+	 * @param smoothing The rate of change of the follower.
+	 */
+	constructor(smoothing?: Time);
+	constructor(options?: Partial<FollowerOptions>);
+	constructor() {
+		super(optionsFromArguments(Follower.getDefaults(), arguments, ["smoothing"]));
+		const options = optionsFromArguments(Follower.getDefaults(), arguments, ["smoothing"]);
+
+		this._abs = this.input = new Abs({ context: this.context });
+		this._lowpass = this.output = new OnePoleFilter({
+			context: this.context,
+			frequency: 1 / this.toSeconds(options.smoothing),
+			type: "lowpass"
+		});
+		this._abs.connect(this._lowpass);
+		this._smoothing = options.smoothing;
+	}
+
+	static getDefaults(): FollowerOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			smoothing: 0.05
+		});
+	}
+
+	/**
+	 * The amount of time it takes a value change to arrive at the updated value. 
+	 */
+	get smoothing(): Time {
+		return this._smoothing;
+	}
+	set smoothing(smoothing) {
+		this._smoothing = smoothing;
+		this._lowpass.frequency = 1 / this.toSeconds(this.smoothing);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._abs.dispose();
+		this._lowpass.dispose();
+		return this;
+	}
+}