tone 15.2.13 → 15.3.0

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

@@ -427,6 +427,31 @@ describe("Player", () => {
 			expect(buff.isSilent()).to.be.true;
 		});
 
+		it("seeking updates stopped state", async () => {
+			await Offline(() => {
+				const player = new Player(buffer).toDestination();
+				player.start(0);
+				player.seek(buffer.duration * 0.75, 0.5);
+
+				return (time) => {
+					whenBetween(time, 0, 0.5, () => {
+						expect(player.state).to.equal("started");
+					});
+					whenBetween(time, 0.5, 0.5 + buffer.duration * 0.25, () => {
+						expect(player.state).to.equal("started");
+					});
+					whenBetween(
+						time,
+						0.5 + buffer.duration * 0.25,
+						Infinity,
+						() => {
+							expect(player.state).to.equal("stopped");
+						}
+					);
+				};
+			}, buffer.duration);
+		});
+
 		it("can seek to a position at the given time", async () => {
 			const buff = await Offline(() => {
 				const ramp = new Float32Array(
@@ -708,4 +733,215 @@ describe("Player", () => {
 			});
 		});
 	});
+
+	context("progress", () => {
+		it("can get the progress of the player", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.start(0);
+				return (time) => {
+					whenBetween(time, 0, buffer.duration, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					whenBetween(time, buffer.duration, Infinity, () => {
+						expect(player.progress).to.equal(0);
+					});
+				};
+			}, buffer.duration * 1.1);
+		});
+
+		it("progress goes back to 0 when the player loops", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.loop = true;
+				player.start(0);
+				return (time) => {
+					whenBetween(time, 0, buffer.duration, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					whenBetween(
+						time,
+						buffer.duration,
+						buffer.duration * 2,
+						() => {
+							expect(player.progress).to.be.closeTo(
+								time - buffer.duration,
+								0.01
+							);
+						}
+					);
+				};
+			}, buffer.duration * 2);
+		});
+
+		it("loops between loopStart and loopEnd", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.loop = true;
+				player.loopStart = 0.1;
+				player.loopEnd = 0.9;
+				player.start(0);
+				return (time) => {
+					whenBetween(time, 0, 0.8, () => {
+						expect(player.progress).to.be.closeTo(time + 0.1, 0.01);
+					});
+					whenBetween(time, 0.8, 1.6, () => {
+						expect(player.progress).to.be.closeTo(time - 0.7, 0.01);
+					});
+					whenBetween(time, 1.6, 2.4, () => {
+						expect(player.progress).to.be.closeTo(time - 1.5, 0.01);
+					});
+				};
+			}, 2.4);
+		});
+
+		it("progress updates at the rate of the playbackRate", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.playbackRate = 2;
+				player.start(0);
+				return (time) => {
+					whenBetween(time, 0, buffer.duration / 2, () => {
+						expect(player.progress).to.be.closeTo(time * 2, 0.01);
+					});
+					whenBetween(time, buffer.duration / 2, Infinity, () => {
+						expect(player.progress).to.be.equal(0);
+					});
+				};
+			}, buffer.duration);
+		});
+
+		it("playbackRate can be changed after start", async () => {
+			let playbackRateChanged = false;
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.start(0);
+				return (time) => {
+					whenBetween(time, 0, buffer.duration * 0.5, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					if (!playbackRateChanged && time > buffer.duration * 0.5) {
+						playbackRateChanged = true;
+						player.playbackRate = 2;
+					}
+					// after the playbackRate is changed, the progress should move half as fast
+					whenBetween(
+						time,
+						buffer.duration * 0.5,
+						buffer.duration * 0.75,
+						() => {
+							const timeAfterHalf = time - buffer.duration * 0.5;
+							expect(player.progress).to.be.closeTo(
+								buffer.duration * 0.5 + timeAfterHalf * 2,
+								0.01
+							);
+						}
+					);
+
+					whenBetween(time, buffer.duration * 0.75, Infinity, () => {
+						expect(player.progress).to.be.equal(0);
+					});
+				};
+			}, buffer.duration);
+		});
+
+		it("can start at an offset", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.start(0, buffer.duration / 2);
+				return (time) => {
+					whenBetween(time, 0.01, buffer.duration / 2, () => {
+						expect(player.progress).to.be.closeTo(
+							time + buffer.duration / 2,
+							0.01
+						);
+					});
+					whenBetween(time, buffer.duration / 2, Infinity, () => {
+						expect(player.progress).to.be.equal(0);
+					});
+				};
+			}, buffer.duration);
+		});
+
+		it("can seek to a new position", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.start(0);
+				player.seek(0, buffer.duration / 2);
+				return (time) => {
+					whenBetween(time, 0, buffer.duration * 0.5, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					whenBetween(
+						time,
+						buffer.duration * 0.5,
+						buffer.duration * 1.5,
+						() => {
+							expect(player.progress).to.be.closeTo(
+								time - buffer.duration * 0.5,
+								0.01
+							);
+						}
+					);
+					whenBetween(time, buffer.duration * 1.5, Infinity, () => {
+						expect(player.progress).to.be.equal(0);
+					});
+				};
+			}, buffer.duration * 2);
+		});
+
+		it("can start and stop multiple times", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.start(0);
+				player.stop(0.1);
+				player.start(0.2, buffer.duration / 2);
+				player.stop(0.3);
+				return (time) => {
+					whenBetween(time, 0, 0.1, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					whenBetween(time, 0.1, 0.2, () => {
+						expect(player.progress).to.equal(0);
+					});
+					whenBetween(time, 0.2, 0.3, () => {
+						expect(player.progress).to.be.closeTo(
+							time - 0.2 + buffer.duration / 2,
+							0.01
+						);
+					});
+					whenBetween(time, 0.3, 0.4, () => {
+						expect(player.progress).to.equal(0);
+					});
+				};
+			}, 0.4);
+		});
+
+		it("can seek multiple times", async () => {
+			await Offline(() => {
+				const player = new Player(buffer);
+				player.start(0);
+				player.seek(1, 0.5);
+				player.seek(0, 1);
+				player.seek(1.5, 1.5);
+				return (time) => {
+					whenBetween(time, 0, 0.5, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					whenBetween(time, 0.5, 1, () => {
+						expect(player.progress).to.be.closeTo(time + 0.5, 0.01);
+					});
+					whenBetween(time, 1, 1.5, () => {
+						expect(player.progress).to.be.closeTo(time - 1, 0.01);
+					});
+					whenBetween(time, 1.5, buffer.duration, () => {
+						expect(player.progress).to.be.closeTo(time, 0.01);
+					});
+					whenBetween(time, buffer.duration, Infinity, () => {
+						expect(player.progress).to.equal(0);
+					});
+				};
+			}, 3);
+		});
+	});
 });

package/Tone/source/buffer/Player.ts

@@ -1,10 +1,13 @@
+import { TickParam } from "../../core/clock/TickParam.js";
 import { ToneAudioBuffer } from "../../core/context/ToneAudioBuffer.js";
 import { Positive, Seconds, Time } from "../../core/type/Units.js";
 import { assertRange } from "../../core/util/Debug.js";
 import { timeRange } from "../../core/util/Decorator.js";
 import { defaultArg, optionsFromArguments } from "../../core/util/Defaults.js";
 import { noOp } from "../../core/util/Interface.js";
+import { Timeline } from "../../core/util/Timeline.js";
 import { isUndef } from "../../core/util/TypeCheck.js";
+import { ToneConstantSource } from "../../signal/ToneConstantSource.js";
 import { Source, SourceOptions } from "../Source.js";
 import { ToneBufferSource } from "./ToneBufferSource.js";
 
@@ -69,6 +72,33 @@ export class Player extends Source<PlayerOptions> {
 	 */
 	private _activeSources: Set<ToneBufferSource> = new Set();
 
+	/**
+	 * Used as the source of the TickParam, but not started or used for anything else.
+	 */
+	private _constantSource = new ToneConstantSource({
+		context: this.context,
+		units: "hertz",
+		offset: 0,
+	});
+
+	/**
+	 * Used to track the progress of the player.
+	 */
+	private _progressTracker = new TickParam({
+		context: this.context,
+		units: "hertz",
+		value: 0,
+		param: this._constantSource.offset,
+	});
+
+	/**
+	 * Combined with the _progressTracker param to track the progress of the player in seconds.
+	 */
+	private _progressOffset = new Timeline<{
+		time: Seconds;
+		seek: Seconds;
+	}>(Infinity);
+
 	/**
 	 * The fadeIn time of the amplitude envelope.
 	 */
@@ -142,6 +172,52 @@ export class Player extends Source<PlayerOptions> {
 		return this;
 	}
 
+	/**
+	 * Internal method to get the progress at a specific time.
+	 * @param time The time to evaluate the progress at.
+	 */
+	private _getProgressAtTime(time: Seconds): Seconds {
+		const state = this._state.getValueAtTime(time);
+		if (state === "stopped") {
+			return 0;
+		}
+		const startTime = this._state.getLastState("started", time)!;
+
+		// sum all of the offsets between the start time and the time
+		let seeksSinceStart = 0;
+		this._progressOffset.forEachBetween(startTime.time, time, (event) => {
+			seeksSinceStart += event.seek;
+		});
+		const progress =
+			this._progressTracker.getTicksAtTime(time) + seeksSinceStart;
+		if (this._loop) {
+			const loopEnd =
+				this.loopEnd === 0
+					? this.buffer.duration
+					: this.toSeconds(this.loopEnd);
+			const loopStart = this.toSeconds(this.loopStart);
+			const duration = loopEnd - loopStart;
+			return (progress % duration) + loopStart;
+		}
+
+		return progress;
+	}
+
+	/**
+	 * Displays the elapsed seconds since the player was started, taking into account playbackRate changes.
+	 * @example
+	 * const player = new Tone.Player("https://tonejs.github.io/audio/berklee/gong_1.mp3", () => {
+	 * 	player.start();
+	 * 	setInterval(() => {
+	 * 		console.log(player.progress);
+	 * 	}, 100);
+	 * }).toDestination();
+	 */
+	get progress(): Seconds {
+		const now = this.now();
+		return this._getProgressAtTime(now);
+	}
+
 	/**
 	 * Internal callback when the buffer is loaded.
 	 */
@@ -228,7 +304,7 @@ export class Player extends Source<PlayerOptions> {
 			playbackRate: this._playbackRate,
 		}).connect(this.output);
 
-		// set the looping properties
+		// schedule the "stopped" state
 		if (!this._loop && !this._synced) {
 			// cancel the previous stop
 			this._state.cancel(startTime + computedDuration);
@@ -245,6 +321,14 @@ export class Player extends Source<PlayerOptions> {
 		// add it to the array of active sources
 		this._activeSources.add(source);
 
+		// used to track the progress of the player
+		const seekDelta = computedOffset - this._getProgressAtTime(startTime);
+		this._progressOffset.add({
+			time: startTime,
+			seek: seekDelta,
+		});
+		this._progressTracker.setValueAtTime(this._playbackRate, startTime);
+
 		// start it
 		if (this._loop && isUndef(origDuration)) {
 			source.start(startTime, computedOffset);
@@ -264,6 +348,7 @@ export class Player extends Source<PlayerOptions> {
 	protected _stop(time?: Time): void {
 		const computedTime = this.toSeconds(time);
 		this._activeSources.forEach((source) => source.stop(computedTime));
+		this._progressTracker.setValueAtTime(0, computedTime);
 	}
 
 	/**
@@ -301,6 +386,8 @@ export class Player extends Source<PlayerOptions> {
 			const computedOffset = this.toSeconds(offset);
 			// if it's currently playing, stop it
 			this._stop(computedTime);
+			// remove the stop event
+			this._state.cancel(computedTime);
 			// restart it at the given time
 			this._start(computedTime, computedOffset);
 		}
@@ -412,12 +499,21 @@ export class Player extends Source<PlayerOptions> {
 	set playbackRate(rate) {
 		this._playbackRate = rate;
 		const now = this.now();
+		this._progressTracker.setValueAtTime(rate, now);
 
 		// cancel the stop event since it's at a different time now
 		const stopEvent = this._state.getNextState("stopped", now);
 		if (stopEvent && stopEvent.implicitEnd) {
 			this._state.cancel(stopEvent.time);
 			this._activeSources.forEach((source) => source.cancelStop());
+
+			const progress = this._getProgressAtTime(now);
+			const remainingTime = this._buffer.duration - progress;
+			const newStopTime = now + remainingTime / rate;
+			// reschedule the implicit stop event
+			this._state.setStateAtTime("stopped", newStopTime, {
+				implicitEnd: true,
+			});
 		}
 
 		// set all the sources
@@ -454,6 +550,9 @@ export class Player extends Source<PlayerOptions> {
 		this._activeSources.forEach((source) => source.dispose());
 		this._activeSources.clear();
 		this._buffer.dispose();
+		this._constantSource.dispose();
+		this._progressTracker.dispose();
+		this._progressOffset.dispose();
 		return this;
 	}
 }

package/Tone/version.ts

@@ -1 +1 @@
-export const version: string = "15.2.13";
+export const version: string = "15.3.0";