tone 14.8.27

package/Tone/core/context/Gain.test.ts

@@ -0,0 +1,75 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { connectFrom, connectTo } from "test/helper/Connect";
+import { PassAudio } from "test/helper/PassAudio";
+import { Gain } from "./Gain";
+
+describe("Gain", () => {
+
+	BasicTests(Gain);
+
+	it("can be created and disposed", () => {
+		const gainNode = new Gain();
+		gainNode.dispose();
+	});
+
+	it("handles input and output connections", () => {
+		const gainNode = new Gain();
+		gainNode.connect(connectTo());
+		connectFrom().connect(gainNode);
+		connectFrom().connect(gainNode.gain);
+		gainNode.dispose();
+	});
+
+	it("can set the gain value", () => {
+		const gainNode = new Gain();
+		expect(gainNode.gain.value).to.be.closeTo(1, 0.001);
+		gainNode.gain.value = 0.2;
+		expect(gainNode.gain.value).to.be.closeTo(0.2, 0.001);
+		gainNode.dispose();
+	});
+
+	it("can be constructed with options object", () => {
+		const gainNode = new Gain({
+			gain: 0.4,
+		});
+		expect(gainNode.gain.value).to.be.closeTo(0.4, 0.001);
+		gainNode.dispose();
+	});
+
+	it("can be constructed with an initial value", () => {
+		const gainNode = new Gain(3);
+		expect(gainNode.gain.value).to.be.closeTo(3, 0.001);
+		gainNode.dispose();
+	});
+
+	it("can set the units", () => {
+		const gainNode = new Gain(0, "decibels");
+		expect(gainNode.gain.value).to.be.closeTo(0, 0.001);
+		expect(gainNode.gain.units).to.equal("decibels");
+		gainNode.dispose();
+	});
+
+	it("can get the value using 'get'", () => {
+		const gainNode = new Gain(5);
+		const value = gainNode.get();
+		expect(value.gain).to.be.closeTo(5, 0.001);
+		gainNode.dispose();
+	});
+
+	it("can set the value using 'set'", () => {
+		const gainNode = new Gain(5);
+		gainNode.set({
+			gain: 4,
+		});
+		expect(gainNode.gain.value).to.be.closeTo(4, 0.001);
+		gainNode.dispose();
+	});
+
+	it("passes audio through", () => {
+		return PassAudio((input) => {
+			const gainNode = new Gain().toDestination();
+			input.connect(gainNode);
+		});
+	});
+});

package/Tone/core/context/Gain.ts

@@ -0,0 +1,90 @@
+import { Param } from "../context/Param";
+import { UnitMap, UnitName } from "../type/Units";
+import { optionsFromArguments } from "../util/Defaults";
+import { readOnly } from "../util/Interface";
+import { ToneAudioNode, ToneAudioNodeOptions } from "./ToneAudioNode";
+
+interface GainOptions<TypeName extends UnitName> extends ToneAudioNodeOptions {
+	gain: UnitMap[TypeName];
+	units: TypeName;
+	convert: boolean;
+	minValue?: number;
+	maxValue?: number;
+}
+
+/**
+ * A thin wrapper around the Native Web Audio GainNode.
+ * The GainNode is a basic building block of the Web Audio
+ * API and is useful for routing audio and adjusting gains.
+ * @category Core
+ * @example
+ * return Tone.Offline(() => {
+ * 	const gainNode = new Tone.Gain(0).toDestination();
+ * 	const osc = new Tone.Oscillator(30).connect(gainNode).start();
+ * 	gainNode.gain.rampTo(1, 0.1);
+ * 	gainNode.gain.rampTo(0, 0.4, 0.2);
+ * }, 0.7, 1);
+ */
+export class Gain<TypeName extends "gain" | "decibels" | "normalRange" = "gain"> extends ToneAudioNode<GainOptions<TypeName>> {
+
+	readonly name: string = "Gain";
+
+	/**
+	 * The gain parameter of the gain node.
+	 * @example
+	 * const gainNode = new Tone.Gain(0).toDestination();
+	 * const osc = new Tone.Oscillator().connect(gainNode).start();
+	 * gainNode.gain.rampTo(1, 0.1);
+	 * gainNode.gain.rampTo(0, 2, "+0.5");
+	 */
+	readonly gain: Param<TypeName>;
+
+	/**
+	 * The wrapped GainNode.
+	 */
+	private _gainNode: GainNode = this.context.createGain();
+
+	// input = output
+	readonly input: GainNode = this._gainNode;
+	readonly output: GainNode = this._gainNode;
+
+	/**
+	 * @param  gain The initial gain of the GainNode
+	 * @param units The units of the gain parameter.
+	 */
+	constructor(gain?: UnitMap[TypeName], units?: TypeName);
+	constructor(options?: Partial<GainOptions<TypeName>>);
+	constructor() {
+		super(optionsFromArguments(Gain.getDefaults(), arguments, ["gain", "units"]));
+		const options = optionsFromArguments(Gain.getDefaults(), arguments, ["gain", "units"]);
+
+		this.gain = new Param({
+			context: this.context,
+			convert: options.convert,
+			param: this._gainNode.gain,
+			units: options.units,
+			value: options.gain,
+			minValue: options.minValue,
+			maxValue: options.maxValue,
+		});
+		readOnly(this, "gain");
+	}
+
+	static getDefaults(): GainOptions<any> {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			convert: true,
+			gain: 1,
+			units: "gain",
+		});
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this._gainNode.disconnect();
+		this.gain.dispose();
+		return this;
+	}
+}

package/Tone/core/context/Listener.test.ts

@@ -0,0 +1,22 @@
+import { expect } from "chai";
+import { Offline } from "test/helper/Offline";
+import { getContext } from "../Global";
+import { Listener } from "./Listener";
+
+describe("Listener", () => {
+
+	it("creates itself on the context", () => {
+		expect(getContext().listener).instanceOf(Listener);
+	});
+
+	it("can get and set values as an object", () => {
+		// can get and set some values
+		Offline(({ listener }) => {
+			expect(listener.get()).to.have.property("positionX");
+			expect(listener.get()).to.have.property("positionY");
+			expect(listener.get()).to.have.property("positionZ");
+			expect(listener.get()).to.have.property("forwardZ");
+			expect(listener.get()).to.have.property("upY");
+		});
+	});
+});

package/Tone/core/context/Listener.ts

@@ -0,0 +1,117 @@
+import { ToneAudioNode, ToneAudioNodeOptions } from "./ToneAudioNode";
+import { Param } from "./Param";
+import { onContextClose, onContextInit } from "./ContextInitialization";
+
+export interface ListenerOptions extends ToneAudioNodeOptions{
+	positionX: number;
+	positionY: number;
+	positionZ: number;
+	forwardX: number;
+	forwardY: number;
+	forwardZ: number;
+	upX: number;
+	upY: number;
+	upZ: number;
+}
+
+/**
+ * Tone.Listener is a thin wrapper around the AudioListener. Listener combined
+ * with [[Panner3D]] makes up the Web Audio API's 3D panning system. Panner3D allows you 
+ * to place sounds in 3D and Listener allows you to navigate the 3D sound environment from
+ * a first-person perspective. There is only one listener per audio context. 
+ */
+export class Listener extends ToneAudioNode<ListenerOptions> {
+
+	readonly name: string = "Listener";
+
+	/**
+	 * The listener has no inputs or outputs. 
+	 */
+	output: undefined; 
+	input: undefined; 
+
+	readonly positionX: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.positionX,
+	})
+
+	readonly positionY: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.positionY,
+	})
+
+	readonly positionZ: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.positionZ,
+	})
+
+	readonly forwardX: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.forwardX,
+	})
+
+	readonly forwardY: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.forwardY,
+	})
+
+	readonly forwardZ: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.forwardZ,
+	})
+
+	readonly upX: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.upX,
+	})
+
+	readonly upY: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.upY,
+	})
+
+	readonly upZ: Param = new Param({
+		context: this.context,
+		param: this.context.rawContext.listener.upZ,
+	})
+
+	static getDefaults(): ListenerOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			positionX: 0,
+			positionY: 0,
+			positionZ: 0,
+			forwardX: 0,
+			forwardY: 0,
+			forwardZ: -1,
+			upX: 0,
+			upY: 1,
+			upZ: 0,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.positionX.dispose();
+		this.positionY.dispose();
+		this.positionZ.dispose();
+		this.forwardX.dispose();
+		this.forwardY.dispose();
+		this.forwardZ.dispose();
+		this.upX.dispose();
+		this.upY.dispose();
+		this.upZ.dispose();
+		return this;
+	}
+}
+
+//-------------------------------------
+// 	INITIALIZATION
+//-------------------------------------
+
+onContextInit(context => {
+	context.listener = new Listener({ context });
+});
+
+onContextClose(context => {
+	context.listener.dispose();
+});

package/Tone/core/context/Offline.test.ts

@@ -0,0 +1,79 @@
+import { TestAudioBuffer } from "@tonejs/plot";
+import { expect } from "chai";
+import { ToneOscillatorNode } from "Tone/source/oscillator/ToneOscillatorNode";
+import { noOp } from "../util/Interface";
+import { Offline } from "./Offline";
+import { ToneAudioBuffer } from "./ToneAudioBuffer";
+
+describe("Offline", () => {
+
+	it("accepts a callback and a duration", () => {
+		return Offline(noOp, 0.01);
+	});
+
+	it("returns a promise", () => {
+		const ret = Offline(noOp, 0.01);
+		expect(ret).to.have.property("then");
+		return ret;
+	});
+
+	it("generates a buffer", () => {
+		return Offline(noOp, 0.01).then((buffer) => {
+			expect(buffer).to.be.instanceOf(ToneAudioBuffer);
+		});
+	});
+
+	it("silent by default", () => {
+		return Offline(noOp, 0.01, 1).then((buffer) => {
+			const isSilent = buffer.toArray().every(sample => sample === 0);
+			expect(isSilent).to.equal(true);
+		});
+	});
+
+	it("records the master output", () => {
+		return Offline(() => {
+			new ToneOscillatorNode().toDestination().start();
+		}, 0.01).then((buffer) => {
+			const testBuff = new TestAudioBuffer(buffer.get() as AudioBuffer);
+			expect(testBuff.isSilent()).is.equal(false);
+		});
+	});
+
+	it("returning a promise defers the rendering till the promise resolves", () => {
+		let wasInvoked = false;
+		return Offline(() => {
+			new ToneOscillatorNode().toDestination().start();
+			return new Promise((done) => {
+				setTimeout(done, 100);
+			}).then(() => {
+				wasInvoked = true;
+			});
+		}, 0.01).then((buffer) => {
+			const testBuff = new TestAudioBuffer(buffer.get() as AudioBuffer);
+			expect(wasInvoked).is.equal(true);
+			expect(testBuff.isSilent()).to.equal(false);
+		});
+	});
+
+	it("can schedule specific timing outputs", () => {
+		return Offline(() => {
+			new ToneOscillatorNode().toDestination().start(0.05);
+		}, 0.1).then((buffer) => {
+			const testBuff = new TestAudioBuffer(buffer.get() as AudioBuffer);
+			expect(testBuff.getTimeOfFirstSound()).to.be.closeTo(0.05, 0.0001);
+		});
+	});
+
+	// it("can schedule Transport events", () => {
+	// 	return Offline(function (Transport) {
+	// 		var osc = new Oscillator().toDestination();
+	// 		Transport.schedule(function (time) {
+	// 			osc.start(time);
+	// 		}, 0.05);
+	// 		Transport.start(0);
+	// 	}, 0.1).then((buffer) => {
+	// 		BufferTest(buffer);
+	// 		expect(buffer.getFirstSoundTime()).to.be.closeTo(0.05, 0.001);
+	// 	});
+	// });
+});

package/Tone/core/context/Offline.ts

@@ -0,0 +1,65 @@
+import { getContext, setContext } from "../Global";
+import { Seconds } from "../type/Units";
+import { OfflineContext } from "./OfflineContext";
+import { ToneAudioBuffer } from "./ToneAudioBuffer";
+
+/**
+ * Generate a buffer by rendering all of the Tone.js code within the callback using the OfflineAudioContext.
+ * The OfflineAudioContext is capable of rendering much faster than real time in many cases.
+ * The callback function also passes in an offline instance of [[Context]] which can be used
+ * to schedule events along the Transport. 
+ * @param  callback  All Tone.js nodes which are created and scheduled within this callback are recorded into the output Buffer.
+ * @param  duration     the amount of time to record for.
+ * @return  The promise which is invoked with the ToneAudioBuffer of the recorded output.
+ * @example
+ * // render 2 seconds of the oscillator
+ * Tone.Offline(() => {
+ * 	// only nodes created in this callback will be recorded
+ * 	const oscillator = new Tone.Oscillator().toDestination().start(0);
+ * }, 2).then((buffer) => {
+ * 	// do something with the output buffer
+ * 	console.log(buffer);
+ * });
+ * @example
+ * // can also schedule events along the Transport
+ * // using the passed in Offline Transport
+ * Tone.Offline(({ transport }) => {
+ * 	const osc = new Tone.Oscillator().toDestination();
+ * 	transport.schedule(time => {
+ * 		osc.start(time).stop(time + 0.1);
+ * 	}, 1);
+ * 	// make sure to start the transport
+ * 	transport.start(0.2);
+ * }, 4).then((buffer) => {
+ * 	// do something with the output buffer
+ * 	console.log(buffer);
+ * });
+ * @category Core
+ */
+export async function Offline(
+	callback: (context: OfflineContext) => Promise<void> | void,
+	duration: Seconds,
+	channels = 2,
+	sampleRate: number = getContext().sampleRate,
+): Promise<ToneAudioBuffer> {
+	// set the OfflineAudioContext based on the current context
+	const originalContext = getContext();
+
+	const context = new OfflineContext(channels, duration, sampleRate);
+	setContext(context);
+
+	// invoke the callback/scheduling
+	await callback(context);
+
+	// then render the audio
+	const bufferPromise = context.render();
+
+	// return the original AudioContext
+	setContext(originalContext);
+
+	// await the rendering
+	const buffer = await bufferPromise;
+
+	// return the audio
+	return new ToneAudioBuffer(buffer);
+}

package/Tone/core/context/OfflineContext.test.ts

@@ -0,0 +1,64 @@
+import { expect } from "chai";
+import { OfflineContext } from "./OfflineContext";
+
+context("OfflineContext", () => {
+
+	it("can be created an disposed", () => {
+		const ctx = new OfflineContext(1, 0.1, 44100);
+		ctx.dispose();
+	});
+
+	it("is setup with 0 lookAhead and offline clockSource", () => {
+		const ctx = new OfflineContext(1, 0.1, 44100);
+		expect(ctx.lookAhead).to.equal(0);
+		expect(ctx.clockSource).to.equal("offline");
+		return ctx.dispose();
+	});
+
+	it("now = currentTime", () => {
+		const ctx = new OfflineContext(1, 0.1, 44100);
+		expect(ctx.currentTime).to.equal(ctx.now());
+		return ctx.dispose();
+	});
+
+	it("closing shouldn't do anything", () => {
+		const ctx = new OfflineContext(1, 0.1, 44100);
+		return ctx.close();
+	});
+
+	it("can render audio", () => {
+		const ctx = new OfflineContext(1, 0.2, 44100);
+		const osc = ctx.createOscillator();
+		osc.connect(ctx.rawContext.destination);
+		osc.start(0.1);
+		return ctx.render().then(buffer => {
+			expect(buffer).to.have.property("length");
+			expect(buffer).to.have.property("sampleRate");
+			const array = buffer.getChannelData(0);
+			for (let i = 0; i < array.length; i++) {
+				if (array[i] !== 0) {
+					expect(i / array.length).to.be.closeTo(0.5, 0.01);
+					break;
+				}
+			}
+		});
+	});
+
+	it("can render audio not async", () => {
+		const ctx = new OfflineContext(1, 0.2, 44100);
+		const osc = ctx.createOscillator();
+		osc.connect(ctx.rawContext.destination);
+		osc.start(0.1);
+		return ctx.render(false).then(buffer => {
+			expect(buffer).to.have.property("length");
+			expect(buffer).to.have.property("sampleRate");
+			const array = buffer.getChannelData(0);
+			for (let i = 0; i < array.length; i++) {
+				if (array[i] !== 0) {
+					expect(i / array.length).to.be.closeTo(0.5, 0.01);
+					break;
+				}
+			}
+		});
+	});
+});

package/Tone/core/context/OfflineContext.ts

@@ -0,0 +1,118 @@
+import { createOfflineAudioContext } from "../context/AudioContext";
+import { Context } from "../context/Context";
+import { Seconds } from "../type/Units";
+import { isOfflineAudioContext } from "../util/AdvancedTypeCheck";
+import { ToneAudioBuffer } from "./ToneAudioBuffer";
+
+/**
+ * Wrapper around the OfflineAudioContext
+ * @category Core
+ * @example
+ * // generate a single channel, 0.5 second buffer
+ * const context = new Tone.OfflineContext(1, 0.5, 44100);
+ * const osc = new Tone.Oscillator({ context });
+ * context.render().then(buffer => {
+ * 	console.log(buffer.numberOfChannels, buffer.duration);
+ * });
+ */
+export class OfflineContext extends Context {
+
+	readonly name: string = "OfflineContext";
+
+	/**
+	 * A private reference to the duration
+	 */
+	private readonly _duration: Seconds;
+
+	/**
+	 * An artificial clock source
+	 */
+	private _currentTime: Seconds = 0;
+
+	/**
+	 * Private reference to the OfflineAudioContext.
+	 */
+	protected _context!: OfflineAudioContext;
+
+	readonly isOffline: boolean = true;
+
+	/**
+	 * @param  channels  The number of channels to render
+	 * @param  duration  The duration to render in seconds
+	 * @param sampleRate the sample rate to render at
+	 */
+	constructor(
+		channels: number,
+		duration: Seconds, 
+		sampleRate: number,
+	);
+	constructor(context: OfflineAudioContext);
+	constructor() {
+
+		super({
+			clockSource: "offline",
+			context: isOfflineAudioContext(arguments[0]) ?
+				arguments[0] : createOfflineAudioContext(arguments[0], arguments[1] * arguments[2], arguments[2]),
+			lookAhead: 0,
+			updateInterval: isOfflineAudioContext(arguments[0]) ?
+				128 / arguments[0].sampleRate : 128 / arguments[2],
+		});
+
+		this._duration = isOfflineAudioContext(arguments[0]) ?
+			arguments[0].length / arguments[0].sampleRate : arguments[1];
+	}
+
+	/**
+	 * Override the now method to point to the internal clock time
+	 */
+	now(): Seconds {
+		return this._currentTime;
+	}
+
+	/**
+	 * Same as this.now()
+	 */
+	get currentTime(): Seconds {
+		return this._currentTime;
+	}
+
+	/**
+	 * Render just the clock portion of the audio context.
+	 */
+	private async _renderClock(asynchronous: boolean): Promise<void> {
+		let index = 0;
+		while (this._duration - this._currentTime >= 0) {
+
+			// invoke all the callbacks on that time
+			this.emit("tick");
+
+			// increment the clock in block-sized chunks
+			this._currentTime += 128 / this.sampleRate;
+
+			// yield once a second of audio
+			index++;
+			const yieldEvery = Math.floor(this.sampleRate / 128);
+			if (asynchronous && index % yieldEvery === 0) {
+				await new Promise(done => setTimeout(done, 1));
+			}
+		}
+	}
+
+	/**
+	 * Render the output of the OfflineContext
+	 * @param asynchronous If the clock should be rendered asynchronously, which will not block the main thread, but be slightly slower.
+	 */
+	async render(asynchronous = true): Promise<ToneAudioBuffer> {
+		await this.workletsAreReady();
+		await this._renderClock(asynchronous);
+		const buffer = await this._context.startRendering();
+		return new ToneAudioBuffer(buffer);
+	}
+
+	/**
+	 * Close the context
+	 */
+	close(): Promise<void> {
+		return Promise.resolve();
+	}
+}