tone 14.8.27

package/Tone/source/buffer/Players.test.ts

@@ -0,0 +1,288 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { Offline } from "test/helper/Offline";
+import { OutputAudio } from "test/helper/OutputAudio";
+import "test/helper/ToneAudioBuffer";
+import { ToneAudioBuffer } from "Tone/core/context/ToneAudioBuffer";
+import { getContext } from "Tone/core/Global";
+import { Player } from "./Player";
+import { Players } from "./Players";
+
+describe("Players", () => {
+
+	const buffer = new ToneAudioBuffer();
+
+	beforeEach(() => {
+		return buffer.load("./audio/sine.wav");
+	});
+
+	BasicTests(Players, { test: buffer });
+
+	context("Constructor", () => {
+
+		it("can be constructed with an object containing a ToneAudioBuffer", () => {
+			const players = new Players({
+				test: buffer,
+			});
+			expect(players.player("test").buffer.get()).to.equal(buffer.get());
+			players.dispose();
+		});
+
+		it("can be constructed with an AudioBuffer", () => {
+			const players = new Players({
+				test: buffer.get() as AudioBuffer,
+			});
+			expect(players.player("test").buffer.get()).to.equal(buffer.get());
+			players.dispose();
+		});
+
+		it("can be constructed with a url", (done) => {
+			const players = new Players({
+				test0: "./audio/sine.wav",
+				test1: "./audio/sine.wav",
+			}, () => {
+				expect(players.player("test0")).to.be.instanceOf(Player);
+				expect(players.player("test0").buffer.loaded).to.be.true;
+				expect(players.player("test1")).to.be.instanceOf(Player);
+				expect(players.player("test1").buffer.loaded).to.be.true;
+				expect(players.loaded).to.be.true;
+				players.dispose();
+				done();
+			});
+		});
+
+		it("can pass in additional args in the second parameters", (done) => {
+			const players = new Players({
+				test: "./audio/sine.wav",
+			}, {
+				onload: () => {
+					expect(players.player("test").buffer.loaded).to.be.true;
+					expect(players.volume.value).to.be.closeTo(-12, 0.1);
+					players.dispose();
+					done();
+				},
+				volume: -12,
+			});
+		});
+
+		it("invokes onerror if no url", (done) => {
+			const source = new Players({
+				urls: {
+					test: "./nosuchfile.wav"
+				}, 
+				onerror() {
+					source.dispose();
+					done();
+				}
+			});
+		});
+
+		it("can get and set fadeIn/Out", () => {
+			const players = new Players({
+				test: "./audio/sine.wav",
+			}, {
+				fadeIn: 0.1,
+				fadeOut: 0.2,
+			});
+			expect(players.fadeIn).to.equal(0.1);
+			expect(players.fadeOut).to.equal(0.2);
+			expect(players.player("test").fadeIn).to.equal(0.1);
+			players.fadeIn = 0.2;
+			players.fadeOut = 0.3;
+			expect(players.fadeIn).to.equal(0.2);
+			expect(players.fadeOut).to.equal(0.3);
+			expect(players.player("test").fadeOut).to.equal(0.3);
+			players.dispose();
+		});
+	});
+
+	context("get/has/add buffers", () => {
+
+		it("says it 'has' a sample", () => {
+			const players = new Players({
+				test: buffer,
+			});
+			expect(players.has("test")).to.be.true;
+			expect(players.has("nope")).to.be.false;
+			players.dispose();
+		});
+
+		it("can get a sample", () => {
+			const players = new Players({
+				test: buffer,
+			});
+			expect(players.player("test")).to.be.instanceOf(Player);
+			players.dispose();
+		});
+
+		it("throws an error if it tries to get a sample which is not there", () => {
+			const players = new Players({
+				test: buffer,
+			});
+			expect(() => {
+				players.player("nope");
+			}).to.throw(Error);
+			players.dispose();
+		});
+
+		it("can add a player with a buffer", () => {
+			const players = new Players();
+			expect(players.has("test")).to.be.false;
+			players.add("test", buffer);
+			expect(players.has("test")).to.be.true;
+			players.dispose();
+		});
+
+		it("can add a player with a url", (done) => {
+			const players = new Players();
+			expect(players.has("test")).to.be.false;
+			players.add("test", "./audio/sine.wav", () => {
+				expect(players.has("test")).to.be.true;
+				players.dispose();
+				done();
+			});
+		});
+
+		it("can add a player with an unloaded ToneAudioBuffer", (done) => {
+			const players = new Players();
+			const buffer2 = new ToneAudioBuffer("./audio/sine.wav");
+			players.add("test", buffer2, () => {
+				expect(players.has("test")).to.be.true;
+				expect(players.player("test").loaded).to.be.true;
+				players.dispose();
+				done();
+			});
+		});
+	});
+
+	context("start/stop players", () => {
+
+		it("makes a sound", () => {
+			return OutputAudio(() => {
+				const players = new Players({
+					test: buffer,
+				}).toDestination();
+				players.player("test").start(0);
+			});
+		});
+
+		it("can be muted", () => {
+			return Offline(() => {
+				const players = new Players({
+					test: buffer,
+				}).toDestination();
+				players.player("test").start(0);
+				players.mute = true;
+				expect(players.mute).to.be.true;
+			}, 0.3).then((buffer2) => {
+				expect(buffer2.isSilent()).to.be.true;
+			});
+		});
+
+		it("be scheduled to start in the future", () => {
+			return Offline(() => {
+				const players = new Players({
+					test: buffer,
+				}).toDestination();
+				players.player("test").start(0.1);
+			}, 0.3).then((buffer2) => {
+				buffer2.forEach((sample, time) => {
+					if (sample > 0) {
+						expect(time).to.be.at.least(0.099);
+					}
+				});
+			});
+		});
+
+		it("be scheduled to stop in the future", () => {
+			return Offline(() => {
+				const players = new Players({
+					test: buffer,
+				}).toDestination();
+				players.player("test").start(0).stop(0.2);
+			}, 0.3).then((buffer2) => {
+				buffer2.forEach((sample, time) => {
+					if (time > 0.2) {
+						expect(sample).to.equal(0);
+					}
+				});
+			});
+		});
+
+		it("if any of the players are playing, reports state as 'started'", () => {
+			return Offline(() => {
+				const players = new Players({
+					test0: buffer,
+					test1: buffer,
+				}).toDestination();
+				players.player("test0").start(0).stop(0.05);
+				players.player("test1").start(0).stop(0.1);
+				return (time) => {
+					if (time <= 0.1) {
+						expect(players.state).to.equal("started");
+					} else {
+						expect(players.state).to.equal("stopped");
+					}
+				};
+			}, 0.2);
+		});
+
+		it("can start multiple samples", () => {
+			return OutputAudio(() => {
+				const players = new Players({
+					test0: buffer,
+					test1: buffer,
+				}).toDestination();
+				players.player("test0").start(0).stop(0.01);
+				players.player("test1").start(0);
+			});
+		});
+
+		it("can stop all of the samples in the future", () => {
+			return Offline(() => {
+				const players = new Players({
+					test0: buffer,
+					test1: buffer,
+				}).toDestination();
+				players.player("test0").start(0);
+				players.player("test1").start(0);
+				players.stopAll(0.2);
+			}, 0.3).then((buffer2) => {
+				buffer2.forEach((sample, time) => {
+					if (time > 0.2) {
+						expect(sample).to.equal(0);
+					}
+				});
+			});
+		});
+
+		it("fades in and out correctly", () => {
+			return Offline(() => {
+				const onesArray = new Float32Array(getContext().sampleRate * 0.5);
+				onesArray.forEach((sample, index) => {
+					onesArray[index] = 1;
+				});
+				const onesBuffer = ToneAudioBuffer.fromArray(onesArray);
+				const players = new Players({
+					test: onesBuffer,
+				}, {
+					fadeIn: 0.1,
+					fadeOut: 0.1,
+				}).toDestination();
+				players.player("test").start(0);
+			}, 0.6).then((buffer2) => {
+				buffer2.forEach((sample, time) => {
+					if (time < 0.1) {
+						expect(sample).to.be.within(0, 1);
+					} else if (time < 0.4) {
+						expect(sample).to.equal(1);
+					} else if (time < 0.5) {
+						expect(sample).to.be.within(0, 1);
+					} else {
+						expect(sample).to.equal(0);
+					}
+				});
+			});
+		});
+	});
+});

package/Tone/source/buffer/Players.ts

@@ -0,0 +1,235 @@
+import { Volume } from "../../component/channel/Volume";
+import { Param } from "../../core/context/Param";
+import { ToneAudioBuffer } from "../../core/context/ToneAudioBuffer";
+import { ToneAudioBuffers, ToneAudioBuffersUrlMap } from "../../core/context/ToneAudioBuffers";
+import { OutputNode, ToneAudioNode } from "../../core/context/ToneAudioNode";
+import { Decibels, Time } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { assert } from "../../core/util/Debug";
+import { noOp, readOnly } from "../../core/util/Interface";
+import { BasicPlaybackState } from "../../core/util/StateTimeline";
+import { Source, SourceOptions } from "../Source";
+import { Player } from "./Player";
+
+export interface PlayersOptions extends SourceOptions {
+	urls: ToneAudioBuffersUrlMap;
+	volume: Decibels;
+	mute: boolean;
+	onload: () => void;
+	onerror: (error: Error) => void;
+	baseUrl: string;
+	fadeIn: Time;
+	fadeOut: Time;
+}
+
+/**
+ * Players combines multiple [[Player]] objects.
+ * @category Source
+ */
+export class Players extends ToneAudioNode<PlayersOptions> {
+
+	readonly name: string = "Players";
+
+	/**
+	 * The output volume node
+	 */
+	private _volume: Volume;
+
+	/**
+	 * The volume of the output in decibels.
+	 */
+	readonly volume: Param<"decibels">;
+
+	/**
+	 * The combined output of all of the players
+	 */
+	readonly output: OutputNode;
+
+	/**
+	 * Players has no input.
+	 */
+	readonly input = undefined;
+
+	/**
+	 * The container of all of the players
+	 */
+	private _players: Map<string, Player> = new Map();
+
+	/**
+	 * The container of all the buffers
+	 */
+	private _buffers: ToneAudioBuffers;
+
+	/**
+	 * private holder of the fadeIn time
+	 */
+	private _fadeIn: Time;
+
+	/**
+	 * private holder of the fadeOut time
+	 */
+	private _fadeOut: Time;
+
+	/**
+	 * @param urls An object mapping a name to a url.
+	 * @param onload The function to invoke when all buffers are loaded.
+	 */
+	constructor(urls?: ToneAudioBuffersUrlMap, onload?: () => void);
+	/**
+	 * @param urls An object mapping a name to a url.
+	 * @param options The remaining options associated with the players
+	 */
+	constructor(urls?: ToneAudioBuffersUrlMap, options?: Partial<Omit<PlayersOptions, "urls">>);
+	constructor(options?: Partial<PlayersOptions>);
+	constructor() {
+		super(optionsFromArguments(Players.getDefaults(), arguments, ["urls", "onload"], "urls"));
+		const options = optionsFromArguments(Players.getDefaults(), arguments, ["urls", "onload"], "urls");
+
+		/**
+		 * The output volume node
+		 */
+		this._volume = this.output = new Volume({
+			context: this.context,
+			volume: options.volume,
+		});
+
+		this.volume = this._volume.volume;
+		readOnly(this, "volume");
+		this._buffers = new ToneAudioBuffers({
+			urls: options.urls, 
+			onload: options.onload, 
+			baseUrl: options.baseUrl,
+			onerror: options.onerror
+		});
+		// mute initially
+		this.mute = options.mute;
+		this._fadeIn = options.fadeIn;
+		this._fadeOut = options.fadeOut;
+	}
+
+	static getDefaults(): PlayersOptions {
+		return Object.assign(Source.getDefaults(), {
+			baseUrl: "",
+			fadeIn: 0,
+			fadeOut: 0,
+			mute: false,
+			onload: noOp,
+			onerror: noOp,
+			urls: {},
+			volume: 0,
+		});
+	}
+
+	/**
+	 * Mute the output.
+	 */
+	get mute(): boolean {
+		return this._volume.mute;
+	}
+	set mute(mute) {
+		this._volume.mute = mute;
+	}
+
+	/**
+	 * The fadeIn time of the envelope applied to the source.
+	 */
+	get fadeIn(): Time {
+		return this._fadeIn;
+	}
+	set fadeIn(fadeIn) {
+		this._fadeIn = fadeIn;
+		this._players.forEach(player => {
+			player.fadeIn = fadeIn;
+		});
+	}
+
+	/**
+	 * The fadeOut time of the each of the sources.
+	 */
+	get fadeOut(): Time {
+		return this._fadeOut;
+	}
+	set fadeOut(fadeOut) {
+		this._fadeOut = fadeOut;
+		this._players.forEach(player => {
+			player.fadeOut = fadeOut;
+		});
+	}
+
+	/**
+	 * The state of the players object. Returns "started" if any of the players are playing.
+	 */
+	get state(): BasicPlaybackState {
+		const playing = Array.from(this._players).some(([_, player]) => player.state === "started");
+		return playing ? "started" : "stopped";
+	}
+
+	/**
+	 * True if the buffers object has a buffer by that name.
+	 * @param name  The key or index of the buffer.
+	 */
+	has(name: string): boolean {
+		return this._buffers.has(name);
+	}
+
+	/**
+	 * Get a player by name.
+	 * @param  name  The players name as defined in the constructor object or `add` method.
+	 */
+	player(name: string): Player {
+		assert(this.has(name), `No Player with the name ${name} exists on this object`);
+		if (!this._players.has(name)) {
+			const player = new Player({
+				context: this.context,
+				fadeIn: this._fadeIn,
+				fadeOut: this._fadeOut,
+				url: this._buffers.get(name),
+			}).connect(this.output);
+			this._players.set(name, player);
+		}
+		return this._players.get(name) as Player;
+	}
+
+	/**
+	 * If all the buffers are loaded or not
+	 */
+	get loaded(): boolean {
+		return this._buffers.loaded;
+	}
+
+	/**
+	 * Add a player by name and url to the Players
+	 * @param  name A unique name to give the player
+	 * @param  url  Either the url of the bufer or a buffer which will be added with the given name.
+	 * @param callback  The callback to invoke when the url is loaded.
+	 * @example
+	 * const players = new Tone.Players();
+	 * players.add("gong", "https://tonejs.github.io/audio/berklee/gong_1.mp3", () => {
+	 * 	console.log("gong loaded");
+	 * 	players.get("gong").start();
+	 * });
+	 */
+	add(name: string, url: string | ToneAudioBuffer | AudioBuffer, callback?: () => void): this {
+		assert(!this._buffers.has(name), "A buffer with that name already exists on this object");
+		this._buffers.add(name, url, callback);
+		return this;
+	}
+
+	/**
+	 * Stop all of the players at the given time
+	 * @param time The time to stop all of the players.
+	 */
+	stopAll(time?: Time): this {
+		this._players.forEach(player => player.stop(time));
+		return this;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._volume.dispose();
+		this.volume.dispose();
+		this._players.forEach(player => player.dispose());
+		this._buffers.dispose();
+		return this;
+	}
+}