tone 14.8.27

package/Tone/source/OneShotSource.ts

@@ -0,0 +1,260 @@
+import { Gain } from "../core/context/Gain";
+import {
+	ToneAudioNode,
+	ToneAudioNodeOptions,
+} from "../core/context/ToneAudioNode";
+import { GainFactor, Seconds, Time } from "../core/type/Units";
+import { noOp } from "../core/util/Interface";
+import { assert } from "../core/util/Debug";
+import { BasicPlaybackState } from "../core/util/StateTimeline";
+
+export type OneShotSourceCurve = "linear" | "exponential";
+
+type onEndedCallback = (source: OneShotSource<any>) => void;
+
+export interface OneShotSourceOptions extends ToneAudioNodeOptions {
+	onended: onEndedCallback;
+	fadeIn: Time;
+	fadeOut: Time;
+	curve: OneShotSourceCurve;
+}
+
+/**
+ * Base class for fire-and-forget nodes
+ */
+export abstract class OneShotSource<
+	Options extends ToneAudioNodeOptions
+> extends ToneAudioNode<Options> {
+	/**
+	 * The callback to invoke after the
+	 * source is done playing.
+	 */
+	onended: onEndedCallback = noOp;
+
+	/**
+	 * Sources do not have input nodes
+	 */
+	input: undefined;
+
+	/**
+	 * The start time
+	 */
+	protected _startTime = -1;
+
+	/**
+	 * The stop time
+	 */
+	protected _stopTime = -1;
+
+	/**
+	 * The id of the timeout
+	 */
+	private _timeout = -1;
+
+	/**
+	 * The public output node
+	 */
+	output: Gain = new Gain({
+		context: this.context,
+		gain: 0,
+	});
+
+	/**
+	 * The output gain node.
+	 */
+	protected _gainNode = this.output;
+
+	/**
+	 * The fadeIn time of the amplitude envelope.
+	 */
+	protected _fadeIn: Time;
+
+	/**
+	 * The fadeOut time of the amplitude envelope.
+	 */
+	protected _fadeOut: Time;
+
+	/**
+	 * The curve applied to the fades, either "linear" or "exponential"
+	 */
+	protected _curve: OneShotSourceCurve;
+
+	constructor(options: OneShotSourceOptions) {
+		super(options);
+
+		this._fadeIn = options.fadeIn;
+		this._fadeOut = options.fadeOut;
+		this._curve = options.curve;
+		this.onended = options.onended;
+	}
+
+	static getDefaults(): OneShotSourceOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			curve: "linear" as OneShotSourceCurve,
+			fadeIn: 0,
+			fadeOut: 0,
+			onended: noOp,
+		});
+	}
+
+	/**
+	 * Stop the source node
+	 */
+	protected abstract _stopSource(time: Seconds): void;
+
+	/**
+	 * Start the source node at the given time
+	 * @param  time When to start the node
+	 */
+	protected abstract start(time?: Time): this;
+	/**
+	 * Start the source at the given time
+	 * @param  time When to start the source
+	 */
+	protected _startGain(time: Seconds, gain: GainFactor = 1): this {
+		assert(
+			this._startTime === -1,
+			"Source cannot be started more than once"
+		);
+		// apply a fade in envelope
+		const fadeInTime = this.toSeconds(this._fadeIn);
+
+		// record the start time
+		this._startTime = time + fadeInTime;
+		this._startTime = Math.max(this._startTime, this.context.currentTime);
+
+		// schedule the envelope
+		if (fadeInTime > 0) {
+			this._gainNode.gain.setValueAtTime(0, time);
+			if (this._curve === "linear") {
+				this._gainNode.gain.linearRampToValueAtTime(
+					gain,
+					time + fadeInTime
+				);
+			} else {
+				this._gainNode.gain.exponentialApproachValueAtTime(
+					gain,
+					time,
+					fadeInTime
+				);
+			}
+		} else {
+			this._gainNode.gain.setValueAtTime(gain, time);
+		}
+		return this;
+	}
+
+	/**
+	 * Stop the source node at the given time.
+	 * @param time When to stop the source
+	 */
+	stop(time?: Time): this {
+		this.log("stop", time);
+		this._stopGain(this.toSeconds(time));
+		return this;
+	}
+
+	/**
+	 * Stop the source at the given time
+	 * @param  time When to stop the source
+	 */
+	protected _stopGain(time: Seconds): this {
+		assert(this._startTime !== -1, "'start' must be called before 'stop'");
+		// cancel the previous stop
+		this.cancelStop();
+
+		// the fadeOut time
+		const fadeOutTime = this.toSeconds(this._fadeOut);
+
+		// schedule the stop callback
+		this._stopTime = this.toSeconds(time) + fadeOutTime;
+		this._stopTime = Math.max(this._stopTime, this.context.currentTime);
+		if (fadeOutTime > 0) {
+			// start the fade out curve at the given time
+			if (this._curve === "linear") {
+				this._gainNode.gain.linearRampTo(0, fadeOutTime, time);
+			} else {
+				this._gainNode.gain.targetRampTo(0, fadeOutTime, time);
+			}
+		} else {
+			// stop any ongoing ramps, and set the value to 0
+			this._gainNode.gain.cancelAndHoldAtTime(time);
+			this._gainNode.gain.setValueAtTime(0, time);
+		}
+		this.context.clearTimeout(this._timeout);
+		this._timeout = this.context.setTimeout(() => {
+			// allow additional time for the exponential curve to fully decay
+			const additionalTail =
+				this._curve === "exponential" ? fadeOutTime * 2 : 0;
+			this._stopSource(this.now() + additionalTail);
+			this._onended();
+		}, this._stopTime - this.context.currentTime);
+		return this;
+	}
+
+	/**
+	 * Invoke the onended callback
+	 */
+	protected _onended(): void {
+		if (this.onended !== noOp) {
+			this.onended(this);
+			// overwrite onended to make sure it only is called once
+			this.onended = noOp;
+			// dispose when it's ended to free up for garbage collection only in the online context
+			if (!this.context.isOffline) {
+				const disposeCallback = () => this.dispose();
+				// @ts-ignore
+				if (typeof window.requestIdleCallback !== "undefined") {
+					// @ts-ignore
+					window.requestIdleCallback(disposeCallback);
+				} else {
+					setTimeout(disposeCallback, 1000);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Get the playback state at the given time
+	 */
+	getStateAtTime = function(time: Time): BasicPlaybackState {
+		const computedTime = this.toSeconds(time);
+		if (
+			this._startTime !== -1 &&
+			computedTime >= this._startTime &&
+			(this._stopTime === -1 || computedTime <= this._stopTime)
+		) {
+			return "started";
+		} else {
+			return "stopped";
+		}
+	};
+
+	/**
+	 * Get the playback state at the current time
+	 */
+	get state(): BasicPlaybackState {
+		return this.getStateAtTime(this.now());
+	}
+
+	/**
+	 * Cancel a scheduled stop event
+	 */
+	cancelStop(): this {
+		this.log("cancelStop");
+		assert(this._startTime !== -1, "Source is not started");
+		// cancel the stop envelope
+		this._gainNode.gain.cancelScheduledValues(
+			this._startTime + this.sampleTime
+		);
+		this.context.clearTimeout(this._timeout);
+		this._stopTime = -1;
+		return this;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._gainNode.disconnect();
+		return this;
+	}
+}

package/Tone/source/Source.test.ts

@@ -0,0 +1,408 @@
+import { expect } from "chai";
+import { atTime, Offline } from "test/helper/Offline";
+import { ONLINE_TESTING } from "test/helper/Supports";
+import { ToneAudioBuffer } from "Tone/core";
+import { getContext } from "Tone/core/Global";
+import { Player } from "./buffer/Player";
+import { Oscillator } from "./oscillator/Oscillator";
+
+describe("Source", () => {
+
+	it("can be started and stopped", () => {
+		const source = new Oscillator();
+		source.start(0);
+		source.stop(1);
+		source.dispose();
+	});
+
+	it("can be constructed with an options object", () => {
+		const source = new Oscillator({
+			volume: -20,
+		});
+		expect(source.volume.value).to.be.closeTo(-20, 0.1);
+		source.dispose();
+	});
+
+	it("can be muted in the constructor options", () => {
+		const source = new Oscillator({
+			mute: true,
+		});
+		expect(source.mute).to.be.true;
+		source.dispose();
+	});
+
+	it("can set the volume", () => {
+		const source = new Oscillator();
+		source.volume.value = -8;
+		expect(source.volume.value).to.be.closeTo(-8, 0.1);
+		source.dispose();
+	});
+
+	it("can mute and unmute the source", () => {
+		const source = new Oscillator();
+		source.volume.value = -8;
+		source.mute = true;
+		expect(source.mute).to.be.true;
+		expect(source.volume.value).to.equal(-Infinity);
+		source.mute = false;
+		// returns the volume to what it was
+		expect(source.volume.value).to.be.closeTo(-8, 0.1);
+		source.dispose();
+	});
+
+	it("can get and set values with an object", () => {
+		const source = new Oscillator();
+		source.set({ volume: -10 });
+		expect(source.get().volume).to.be.closeTo(-10, 0.1);
+		source.dispose();
+	});
+
+	it("is initally stopped", () => {
+		const source = new Oscillator();
+		expect(source.state).to.equal("stopped");
+		source.dispose();
+	});
+
+	it("cannot be scheduled to stop/start twice in a row", () => {
+		return Offline(() => {
+			const source = new Oscillator();
+			source.start(0).start(1);
+			source.stop(2).stop(3);
+			source.dispose();
+		});
+	});
+
+	it("can be scheduled with multiple starts/stops", () => {
+		return Offline(() => {
+			const source = new Oscillator();
+			source.start(0).stop(0.5).start(0.75).stop(1).start(1.25).stop(1.5);
+			return [
+				atTime(0.1, () => {
+					expect(source.state).to.equal("started");
+				}),
+				atTime(0.5, () => {
+					expect(source.state).to.equal("stopped");
+				}),
+				atTime(0.8, () => {
+					expect(source.state).to.equal("started");
+				}),
+				atTime(1, () => {
+					expect(source.state).to.equal("stopped");
+				}),
+				atTime(1.25, () => {
+					expect(source.state).to.equal("started");
+				}),
+				atTime(1.6, () => {
+					expect(source.state).to.equal("stopped");
+				}),
+			];
+		}, 2);
+	});
+
+	if (ONLINE_TESTING) {
+
+		it("clamps start time to the currentTime", (done) => {
+			const source = new Oscillator();
+			expect(source.state).to.equal("stopped");
+			source.start(0);
+			setTimeout(() => {
+				expect(source.state).to.equal("started");
+				source.dispose();
+				done();
+			}, 10);
+		});
+
+		it("clamps stop time to the currentTime", (done) => {
+			const source = new Oscillator();
+			expect(source.state).to.equal("stopped");
+			source.start(0);
+			setTimeout(() => {
+				expect(source.state).to.equal("started");
+				source.stop(0);
+				setTimeout(() => {
+					expect(source.state).to.equal("stopped");
+					source.dispose();
+					done();
+				}, 10);
+			}, 10);
+		});
+	}
+
+	it("correctly returns the scheduled play state", () => {
+		return Offline(() => {
+			const source = new Oscillator();
+			expect(source.state).to.equal("stopped");
+			source.start(0).stop(0.5);
+
+			return (time) => {
+				if (time >= 0 && time < 0.5) {
+					expect(source.state).to.equal("started");
+				} else if (time > 0.5) {
+					expect(source.state).to.equal("stopped");
+				}
+			};
+		}, 0.6);
+	});
+
+	it("start needs to be greater than the previous start time", () => {
+		return Offline(() => {
+			const source = new Oscillator();
+			source.start(0);
+			expect(() => {
+				source.start(0);
+			}).to.throw(Error);
+			source.dispose();
+		});
+	});
+
+	context("sync", () => {
+
+		const ramp = new Float32Array(getContext().sampleRate);
+		ramp.forEach((val, index) => {
+			ramp[index] = index / getContext().sampleRate;
+		});
+		const rampBuffer = ToneAudioBuffer.fromArray(ramp);
+
+		it("can sync its start to the transport", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0);
+				expect(source.state).to.equal("stopped");
+				transport.start(source.now());
+				expect(source.state).to.equal("started");
+				source.dispose();
+				transport.stop();
+			});
+		});
+
+		it("calling sync multiple times has no affect", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().sync().start(0);
+				expect(source.state).to.equal("stopped");
+				transport.start(source.now());
+				expect(source.state).to.equal("started");
+				source.dispose();
+				transport.stop();
+			});
+		});
+
+		it("can unsync after it was synced", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0);
+				source.unsync();
+				transport.start();
+				expect(source.state).to.equal("stopped");
+			});
+		});
+
+		it("calling unsync multiple times has no affect", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0);
+				source.unsync().unsync();
+				transport.start();
+				expect(source.state).to.equal("stopped");
+			});
+		});
+
+		it("can sync its stop to the transport", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0);
+				expect(source.state).to.equal("stopped");
+				transport.start(0).stop(0.4);
+				expect(source.state).to.equal("started");
+
+				return (time) => {
+					if (time > 0.4) {
+						expect(source.state).to.equal("stopped");
+					}
+				};
+			}, 0.5);
+		});
+
+		it("can schedule multiple starts/stops", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0.1).stop(0.2).start(0.3);
+				transport.start(0).stop(0.4);
+				expect(source.state).to.equal("stopped");
+
+				return (time) => {
+					if (time > 0.1 && time < 0.19) {
+						expect(source.state).to.equal("started");
+					} else if (time > 0.2 && time < 0.29) {
+						expect(source.state).to.equal("stopped");
+					} else if (time > 0.3 && time < 0.39) {
+						expect(source.state).to.equal("started");
+					} else if (time > 0.4) {
+						expect(source.state).to.equal("stopped");
+					}
+				};
+			}, 0.6);
+		});
+
+		it.skip("can sync schedule multiple starts", () => {
+			return Offline(({ transport }) => {
+				const buff = ToneAudioBuffer.fromArray(new Float32Array(1024).map(v => 1));
+				const source = new Player(buff);
+				source.sync().start(0.1).start(0.3);
+				transport.start(0);
+				expect(source.state).to.equal("stopped");
+
+				return [
+					atTime(0.11, () => {
+						expect(source.state).to.equal("started");
+					}),
+					atTime(0.31, () => {
+						expect(source.state).to.equal("started");
+					}),
+				];
+			}, 0.6);
+		});
+
+		it("has correct offset when the transport is started with an offset", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0.3).stop(0.4);
+				transport.start(0, 0.1);
+				expect(source.state).to.equal("stopped");
+
+				return time => {
+					if (time > 0.21 && time < 0.29) {
+						expect(source.state).to.equal("started");
+					} else if (time > 0.31) {
+						expect(source.state).to.equal("stopped");
+					}
+				};
+			}, 0.5);
+		});
+
+		it("can start with an offset after the start time of the source", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0);
+				transport.start(0, 0.1);
+				expect(source.state).to.equal("started");
+				source.dispose();
+			}, 0.1);
+		});
+
+		it("can sync its start to the transport after a delay", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0.3);
+				transport.start(0).stop(0.4);
+				expect(source.state).to.equal("stopped");
+
+				return (time) => {
+					if (time > 0.3 && time < 0.39) {
+						expect(source.state).to.equal("started");
+					} else if (time > 0.4) {
+						expect(source.state).to.equal("stopped");
+					}
+				};
+			}, 0.6);
+		});
+
+		it("correct state when the transport position is changed", () => {
+			return Offline(({ transport }) => {
+				const source = new Oscillator();
+				source.sync().start(0.3).stop(0.4);
+				transport.start(0).stop(0.4);
+				expect(source.state).to.equal("stopped");
+				transport.seconds = 0.305;
+				expect(source.state).to.equal("started");
+				transport.seconds = 0.405;
+				return atTime(0.01, () => {
+					expect(source.state).to.equal("stopped");
+				});
+			}, 0.1);
+		});
+
+		it("gives the correct offset on time on start/stop events", () => {
+			return Offline(({ transport }) => {
+				const source = new Player(rampBuffer).toDestination();
+				source.sync().start(0.2, 0.1).stop(0.3);
+				transport.start(0.2);
+			}, 0.7).then(output => {
+				expect(output.getValueAtTime(0.41)).to.be.closeTo(0.1, 0.01);
+				expect(output.getValueAtTime(0.45)).to.be.closeTo(0.15, 0.001);
+				expect(output.getValueAtTime(0.5)).to.be.equal(0);
+			});
+		});
+
+		it("gives the correct offset on time on start/stop events when started with an offset", () => {
+			return Offline(({ transport }) => {
+				const source = new Player(rampBuffer).toDestination();
+				source.sync().start(0.2, 0.1).stop(0.4);
+				transport.start(0.2, 0.1);
+			}, 0.7).then(output => {
+				expect(output.getValueAtTime(0.21)).to.be.closeTo(0.0, 0.01);
+				expect(output.getValueAtTime(0.31)).to.be.closeTo(0.1, 0.01);
+				expect(output.getValueAtTime(0.41)).to.be.closeTo(0.2, 0.01);
+				expect(output.getValueAtTime(0.45)).to.be.closeTo(0.25, 0.01);
+				expect(output.getValueAtTime(0.51)).to.be.equal(0);
+			});
+		});
+
+		it("gives the correct offset on time on start/stop events invoked with an transport offset that's in the middle of the event", () => {
+			return Offline(({ transport }) => {
+				const source = new Player(rampBuffer).toDestination();
+				source.sync().start(0.2, 0.1).stop(0.4);
+				transport.start(0, 0.3);
+			}, 0.7).then(output => {
+				expect(output.getValueAtTime(0.01)).to.be.closeTo(0.2, 0.01);
+				expect(output.getValueAtTime(0.05)).to.be.closeTo(0.25, 0.01);
+				expect(output.getValueAtTime(0.11)).to.be.equal(0);
+			});
+		});
+
+		it("gives the correct duration when invoked with an transport offset that's in the middle of the event", () => {
+			return Offline(({ transport }) => {
+				const source = new Player(rampBuffer).toDestination();
+				source.sync().start(0.2, 0.1, 0.3);
+				transport.start(0, 0.3);
+			}, 0.7).then(output => {
+				expect(output.getValueAtTime(0.01)).to.be.closeTo(0.2, 0.01);
+				expect(output.getValueAtTime(0.1)).to.be.closeTo(0.3, 0.01);
+				expect(output.getValueAtTime(0.199)).to.be.closeTo(0.4, 0.01);
+				expect(output.getValueAtTime(0.31)).to.be.equal(0);
+			});
+		});
+
+		it("stops at the right time when transport.stop is invoked before the scheduled stop", () => {
+			return Offline(({ transport }) => {
+				const source = new Player(rampBuffer).toDestination();
+				source.sync().start(0.2).stop(0.4);
+				transport.start(0).stop(0.3);
+			}, 0.7).then(output => {
+				expect(output.getValueAtTime(0.2)).to.be.closeTo(0.0, 0.01);
+				expect(output.getValueAtTime(0.25)).to.be.closeTo(0.05, 0.01);
+				expect(output.getValueAtTime(0.31)).to.be.equal(0);
+			});
+		});
+
+		it("invokes the right methods and offsets when the transport is seeked", () => {
+			return Offline(({ transport }) => {
+				const source = new Player(rampBuffer).toDestination();
+				source.sync().start(0.2);
+				transport.start(0, 0.3);
+
+				return atTime(0.1, () => {
+					// seek forward in time
+					transport.seconds = 0.1;
+				});
+			}, 0.7).then((output) => {
+				expect(output.getValueAtTime(0.01)).to.be.closeTo(0.1, 0.01);
+				expect(output.getValueAtTime(0.05)).to.be.closeTo(0.15, 0.01);
+				expect(output.getValueAtTime(0.11)).to.be.closeTo(0.0, 0.01);
+				expect(output.getValueAtTime(0.21)).to.be.closeTo(0.0, 0.01);
+				expect(output.getValueAtTime(0.25)).to.be.closeTo(0.05, 0.01);
+				expect(output.getValueAtTime(0.3)).to.be.closeTo(0.1, 0.01);
+			});
+		});
+	});
+});