tone 14.8.27

package/Tone/core/clock/Clock.ts

@@ -0,0 +1,317 @@
+import { ToneWithContext, ToneWithContextOptions } from "../context/ToneWithContext";
+import { Frequency, Hertz, Seconds, Ticks, Time } from "../type/Units";
+import { optionsFromArguments } from "../util/Defaults";
+import { Emitter } from "../util/Emitter";
+import { noOp, readOnly } from "../util/Interface";
+import { PlaybackState, StateTimeline } from "../util/StateTimeline";
+import { TickSignal } from "./TickSignal";
+import { TickSource } from "./TickSource";
+import { assertContextRunning } from "../util/Debug";
+
+type ClockCallback = (time: Seconds, ticks?: Ticks) => void;
+
+interface ClockOptions extends ToneWithContextOptions {
+	frequency: Hertz;
+	callback: ClockCallback;
+	units: "hertz" | "bpm";
+}
+
+type ClockEvent = "start" | "stop" | "pause";
+
+/**
+ * A sample accurate clock which provides a callback at the given rate.
+ * While the callback is not sample-accurate (it is still susceptible to
+ * loose JS timing), the time passed in as the argument to the callback
+ * is precise. For most applications, it is better to use Tone.Transport
+ * instead of the Clock by itself since you can synchronize multiple callbacks.
+ * @example
+ * // the callback will be invoked approximately once a second
+ * // and will print the time exactly once a second apart.
+ * const clock = new Tone.Clock(time => {
+ * 	console.log(time);
+ * }, 1);
+ * clock.start();
+ * @category Core
+ */
+export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
+	extends ToneWithContext<ClockOptions> implements Emitter<ClockEvent> {
+
+	readonly name: string = "Clock";
+
+	/**
+	 * The callback function to invoke at the scheduled tick.
+	 */
+	callback: ClockCallback = noOp;
+
+	/**
+	 * The tick counter
+	 */
+	private _tickSource: TickSource<TypeName>;
+
+	/**
+	 * The last time the loop callback was invoked
+	 */
+	private _lastUpdate = 0;
+
+	/**
+	 * Keep track of the playback state
+	 */
+	private _state: StateTimeline = new StateTimeline("stopped");
+
+	/**
+	 * Context bound reference to the _loop method
+	 * This is necessary to remove the event in the end.
+	 */
+	private _boundLoop: () => void = this._loop.bind(this);
+
+	/**
+	 * The rate the callback function should be invoked.
+	 */
+	frequency: TickSignal<TypeName>;
+
+	/**
+	 * @param callback The callback to be invoked with the time of the audio event
+	 * @param frequency The rate of the callback
+	 */
+	constructor(callback?: ClockCallback, frequency?: Frequency);
+	constructor(options: Partial<ClockOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Clock.getDefaults(), arguments, ["callback", "frequency"]));
+		const options = optionsFromArguments(Clock.getDefaults(), arguments, ["callback", "frequency"]);
+
+		this.callback = options.callback;
+		this._tickSource = new TickSource({
+			context: this.context,
+			frequency: options.frequency,
+			units: options.units,
+		});
+		this._lastUpdate = 0;
+		this.frequency = this._tickSource.frequency;
+		readOnly(this, "frequency");
+
+		// add an initial state
+		this._state.setStateAtTime("stopped", 0);
+
+		// bind a callback to the worker thread
+		this.context.on("tick", this._boundLoop);
+	}
+
+	static getDefaults(): ClockOptions {
+		return Object.assign(ToneWithContext.getDefaults(), {
+			callback: noOp as ClockCallback,
+			frequency: 1,
+			units: "hertz",
+		}) as ClockOptions;
+	}
+
+	/**
+	 * Returns the playback state of the source, either "started", "stopped" or "paused".
+	 */
+	get state(): PlaybackState {
+		return this._state.getValueAtTime(this.now());
+	}
+
+	/**
+	 * Start the clock at the given time. Optionally pass in an offset
+	 * of where to start the tick counter from.
+	 * @param  time    The time the clock should start
+	 * @param offset  Where the tick counter starts counting from.
+	 */
+	start(time?: Time, offset?: Ticks): this {
+		// make sure the context is running
+		assertContextRunning(this.context);
+		// start the loop
+		const computedTime = this.toSeconds(time);
+		this.log("start", computedTime);
+		if (this._state.getValueAtTime(computedTime) !== "started") {
+			this._state.setStateAtTime("started", computedTime);
+			this._tickSource.start(computedTime, offset);
+			if (computedTime < this._lastUpdate) {
+				this.emit("start", computedTime, offset);
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * Stop the clock. Stopping the clock resets the tick counter to 0.
+	 * @param time The time when the clock should stop.
+	 * @example
+	 * const clock = new Tone.Clock(time => {
+	 * 	console.log(time);
+	 * }, 1);
+	 * clock.start();
+	 * // stop the clock after 10 seconds
+	 * clock.stop("+10");
+	 */
+	stop(time?: Time): this {
+		const computedTime = this.toSeconds(time);
+		this.log("stop", computedTime);
+		this._state.cancel(computedTime);
+		this._state.setStateAtTime("stopped", computedTime);
+		this._tickSource.stop(computedTime);
+		if (computedTime < this._lastUpdate) {
+			this.emit("stop", computedTime);
+		}
+		return this;
+	}
+
+	/**
+	 * Pause the clock. Pausing does not reset the tick counter.
+	 * @param time The time when the clock should stop.
+	 */
+	pause(time?: Time): this {
+		const computedTime = this.toSeconds(time);
+		if (this._state.getValueAtTime(computedTime) === "started") {
+			this._state.setStateAtTime("paused", computedTime);
+			this._tickSource.pause(computedTime);
+			if (computedTime < this._lastUpdate) {
+				this.emit("pause", computedTime);
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * The number of times the callback was invoked. Starts counting at 0
+	 * and increments after the callback was invoked.
+	 */
+	get ticks(): Ticks {
+		return Math.ceil(this.getTicksAtTime(this.now()));
+	}
+	set ticks(t: Ticks) {
+		this._tickSource.ticks = t;
+	}
+
+	/**
+	 * The time since ticks=0 that the Clock has been running. Accounts for tempo curves
+	 */
+	get seconds(): Seconds {
+		return this._tickSource.seconds;
+	}
+	set seconds(s: Seconds) {
+		this._tickSource.seconds = s;
+	}
+
+	/**
+	 * Return the elapsed seconds at the given time.
+	 * @param  time  When to get the elapsed seconds
+	 * @return  The number of elapsed seconds
+	 */
+	getSecondsAtTime(time: Time): Seconds {
+		return this._tickSource.getSecondsAtTime(time);
+	}
+
+	/**
+	 * Set the clock's ticks at the given time.
+	 * @param  ticks The tick value to set
+	 * @param  time  When to set the tick value
+	 */
+	setTicksAtTime(ticks: Ticks, time: Time): this {
+		this._tickSource.setTicksAtTime(ticks, time);
+		return this;
+	}
+
+	/**
+	 * Get the time of the given tick. The second argument
+	 * is when to test before. Since ticks can be set (with setTicksAtTime)
+	 * there may be multiple times for a given tick value.
+	 * @param  tick The tick number.
+	 * @param  before When to measure the tick value from.
+	 * @return The time of the tick
+	 */
+	getTimeOfTick(tick: Ticks, before = this.now()): Seconds {
+		return this._tickSource.getTimeOfTick(tick, before);
+	}
+
+	/**
+	 * Get the clock's ticks at the given time.
+	 * @param  time  When to get the tick value
+	 * @return The tick value at the given time.
+	 */
+	getTicksAtTime(time?: Time): Ticks {
+		return this._tickSource.getTicksAtTime(time);
+	}
+
+	/**
+	 * Get the time of the next tick
+	 * @param  offset The tick number.
+	 */
+	nextTickTime(offset: Ticks, when: Time): Seconds {
+		const computedTime = this.toSeconds(when);
+		const currentTick = this.getTicksAtTime(computedTime);
+		return this._tickSource.getTimeOfTick(currentTick + offset, computedTime);
+	}
+
+	/**
+	 * The scheduling loop.
+	 */
+	private _loop(): void {
+
+		const startTime = this._lastUpdate;
+		const endTime = this.now();
+		this._lastUpdate = endTime;
+		this.log("loop", startTime, endTime);
+
+		if (startTime !== endTime) {
+			// the state change events
+			this._state.forEachBetween(startTime, endTime, e => {
+				switch (e.state) {
+					case "started":
+						const offset = this._tickSource.getTicksAtTime(e.time);
+						this.emit("start", e.time, offset);
+						break;
+					case "stopped":
+						if (e.time !== 0) {
+							this.emit("stop", e.time);
+						}
+						break;
+					case "paused":
+						this.emit("pause", e.time);
+						break;
+				}
+			});
+			// the tick callbacks
+			this._tickSource.forEachTickBetween(startTime, endTime, (time, ticks) => {
+				this.callback(time, ticks);
+			});
+		}
+	}
+
+	/**
+	 * Returns the scheduled state at the given time.
+	 * @param  time  The time to query.
+	 * @return  The name of the state input in setStateAtTime.
+	 * @example
+	 * const clock = new Tone.Clock();
+	 * clock.start("+0.1");
+	 * clock.getStateAtTime("+0.1"); // returns "started"
+	 */
+	getStateAtTime(time: Time): PlaybackState {
+		const computedTime = this.toSeconds(time);
+		return this._state.getValueAtTime(computedTime);
+	}
+
+	/**
+	 * Clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		this.context.off("tick", this._boundLoop);
+		this._tickSource.dispose();
+		this._state.dispose();
+		return this;
+	}
+
+	//-------------------------------------
+	// EMITTER MIXIN TO SATISFY COMPILER
+	//-------------------------------------
+
+	on!: (event: ClockEvent, callback: (...args: any[]) => void) => this;
+	once!: (event: ClockEvent, callback: (...args: any[]) => void) => this;
+	off!: (event: ClockEvent, callback?: ((...args: any[]) => void) | undefined) => this;
+	emit!: (event: any, ...args: any[]) => this;
+}
+
+Emitter.mixin(Clock);

package/Tone/core/clock/TickParam.test.ts

@@ -0,0 +1,15 @@
+import { Compare, Plot } from "@tonejs/plot";
+import { expect } from "chai";
+import { BasicTests, testAudioContext } from "test/helper/Basic";
+// import { atTime, Offline } from "test/helper/Offline";
+import { TickParam } from "./TickParam";
+
+describe("TickParam", () => {
+
+	// sanity checks
+	BasicTests(TickParam, {
+		context: testAudioContext,
+		param: testAudioContext.createOscillator().frequency,
+	});
+
+});

package/Tone/core/clock/TickParam.ts

@@ -0,0 +1,271 @@
+import { AutomationEvent, Param, ParamOptions } from "../context/Param";
+import { Seconds, Ticks, Time, UnitMap, UnitName } from "../type/Units";
+import { optionsFromArguments } from "../util/Defaults";
+import { Timeline } from "../util/Timeline";
+import { isUndef } from "../util/TypeCheck";
+
+type TickAutomationEvent = AutomationEvent & {
+	ticks: number;
+};
+
+interface TickParamOptions<TypeName extends UnitName> extends ParamOptions<TypeName> {
+	multiplier: number;
+}
+
+/**
+ * A Param class just for computing ticks. Similar to the [[Param]] class,
+ * but offers conversion to BPM values as well as ability to compute tick
+ * duration and elapsed ticks
+ */
+export class TickParam<TypeName extends "hertz" | "bpm"> extends Param<TypeName> {
+
+	readonly name: string = "TickParam";
+
+	/**
+	 * The timeline which tracks all of the automations.
+	 */
+	protected _events: Timeline<TickAutomationEvent> = new Timeline(Infinity);
+
+	/**
+	 * The internal holder for the multiplier value
+	 */
+	private _multiplier = 1;
+
+	/**
+	 * @param param The AudioParam to wrap
+	 * @param units The unit name
+	 * @param convert Whether or not to convert the value to the target units
+	 */
+	/**
+	 * @param value The initial value of the signal
+	 */
+	constructor(value?: number);
+	constructor(options: Partial<TickParamOptions<TypeName>>);
+	constructor() {
+
+		super(optionsFromArguments(TickParam.getDefaults(), arguments, ["value"]));
+		const options = optionsFromArguments(TickParam.getDefaults(), arguments, ["value"]);
+
+		// set the multiplier
+		this._multiplier = options.multiplier;
+
+		// clear the ticks from the beginning
+		this._events.cancel(0);
+		// set an initial event
+		this._events.add({
+			ticks: 0,
+			time: 0,
+			type: "setValueAtTime",
+			value: this._fromType(options.value),
+		});
+		this.setValueAtTime(options.value, 0);
+	}
+
+	static getDefaults(): TickParamOptions<any> {
+		return Object.assign(Param.getDefaults(), {
+			multiplier: 1,
+			units: "hertz",
+			value: 1,
+		});
+	}
+
+	setTargetAtTime(value: UnitMap[TypeName], time: Time, constant: number): this {
+		// approximate it with multiple linear ramps
+		time = this.toSeconds(time);
+		this.setRampPoint(time);
+		const computedValue = this._fromType(value);
+
+		// start from previously scheduled value
+		const prevEvent = this._events.get(time) as TickAutomationEvent;
+		const segments = Math.round(Math.max(1 / constant, 1));
+		for (let i = 0; i <= segments; i++) {
+			const segTime = constant * i + time;
+			const rampVal = this._exponentialApproach(prevEvent.time, prevEvent.value, computedValue, constant, segTime);
+			this.linearRampToValueAtTime(this._toType(rampVal), segTime);
+		}
+		return this;
+	}
+
+	setValueAtTime(value: UnitMap[TypeName], time: Time): this {
+		const computedTime = this.toSeconds(time);
+		super.setValueAtTime(value, time);
+		const event = this._events.get(computedTime) as TickAutomationEvent;
+		const previousEvent = this._events.previousEvent(event);
+		const ticksUntilTime = this._getTicksUntilEvent(previousEvent, computedTime);
+		event.ticks = Math.max(ticksUntilTime, 0);
+		return this;
+	}
+
+	linearRampToValueAtTime(value: UnitMap[TypeName], time: Time): this {
+		const computedTime = this.toSeconds(time);
+		super.linearRampToValueAtTime(value, time);
+		const event = this._events.get(computedTime) as TickAutomationEvent;
+		const previousEvent = this._events.previousEvent(event);
+		const ticksUntilTime = this._getTicksUntilEvent(previousEvent, computedTime);
+		event.ticks = Math.max(ticksUntilTime, 0);
+		return this;
+	}
+
+	exponentialRampToValueAtTime(value: UnitMap[TypeName], time: Time): this {
+		// aproximate it with multiple linear ramps
+		time = this.toSeconds(time);
+		const computedVal = this._fromType(value);
+
+		// start from previously scheduled value
+		const prevEvent = this._events.get(time) as TickAutomationEvent;
+		// approx 10 segments per second
+		const segments = Math.round(Math.max((time - prevEvent.time) * 10, 1));
+		const segmentDur = ((time - prevEvent.time) / segments);
+		for (let i = 0; i <= segments; i++) {
+			const segTime = segmentDur * i + prevEvent.time;
+			const rampVal = this._exponentialInterpolate(prevEvent.time, prevEvent.value, time, computedVal, segTime);
+			this.linearRampToValueAtTime(this._toType(rampVal), segTime);
+		}
+		return this;
+	}
+
+	/**
+	 * Returns the tick value at the time. Takes into account
+	 * any automation curves scheduled on the signal.
+	 * @param  event The time to get the tick count at
+	 * @return The number of ticks which have elapsed at the time given any automations.
+	 */
+	private _getTicksUntilEvent(event: TickAutomationEvent | null, time: number): Ticks {
+		if (event === null) {
+			event = {
+				ticks: 0,
+				time: 0,
+				type: "setValueAtTime",
+				value: 0,
+			};
+		} else if (isUndef(event.ticks)) {
+			const previousEvent = this._events.previousEvent(event);
+			event.ticks = this._getTicksUntilEvent(previousEvent, event.time);
+		}
+		const val0 = this._fromType(this.getValueAtTime(event.time));
+		let val1 = this._fromType(this.getValueAtTime(time));
+		// if it's right on the line, take the previous value
+		const onTheLineEvent = this._events.get(time);
+		if (onTheLineEvent && onTheLineEvent.time === time && onTheLineEvent.type === "setValueAtTime") {
+			val1 = this._fromType(this.getValueAtTime(time - this.sampleTime));
+		}
+		return 0.5 * (time - event.time) * (val0 + val1) + event.ticks;
+	}
+
+	/**
+	 * Returns the tick value at the time. Takes into account
+	 * any automation curves scheduled on the signal.
+	 * @param  time The time to get the tick count at
+	 * @return The number of ticks which have elapsed at the time given any automations.
+	 */
+	getTicksAtTime(time: Time): Ticks {
+		const computedTime = this.toSeconds(time);
+		const event = this._events.get(computedTime);
+		return Math.max(this._getTicksUntilEvent(event, computedTime), 0);
+	}
+
+	/**
+	 * Return the elapsed time of the number of ticks from the given time
+	 * @param ticks The number of ticks to calculate
+	 * @param  time The time to get the next tick from
+	 * @return The duration of the number of ticks from the given time in seconds
+	 */
+	getDurationOfTicks(ticks: Ticks, time: Time): Seconds {
+		const computedTime = this.toSeconds(time);
+		const currentTick = this.getTicksAtTime(time);
+		return this.getTimeOfTick(currentTick + ticks) - computedTime;
+	}
+
+	/**
+	 * Given a tick, returns the time that tick occurs at.
+	 * @return The time that the tick occurs.
+	 */
+	getTimeOfTick(tick: Ticks): Seconds {
+		const before = this._events.get(tick, "ticks");
+		const after = this._events.getAfter(tick, "ticks");
+		if (before && before.ticks === tick) {
+			return before.time;
+		} else if (before && after &&
+			after.type === "linearRampToValueAtTime" &&
+			before.value !== after.value) {
+			const val0 = this._fromType(this.getValueAtTime(before.time));
+			const val1 = this._fromType(this.getValueAtTime(after.time));
+			const delta = (val1 - val0) / (after.time - before.time);
+			const k = Math.sqrt(Math.pow(val0, 2) - 2 * delta * (before.ticks - tick));
+			const sol1 = (-val0 + k) / delta;
+			const sol2 = (-val0 - k) / delta;
+			return (sol1 > 0 ? sol1 : sol2) + before.time;
+		} else if (before) {
+			if (before.value === 0) {
+				return Infinity;
+			} else {
+				return before.time + (tick - before.ticks) / before.value;
+			}
+		} else {
+			return tick / this._initialValue;
+		}
+	}
+
+	/**
+	 * Convert some number of ticks their the duration in seconds accounting
+	 * for any automation curves starting at the given time.
+	 * @param  ticks The number of ticks to convert to seconds.
+	 * @param  when  When along the automation timeline to convert the ticks.
+	 * @return The duration in seconds of the ticks.
+	 */
+	ticksToTime(ticks: Ticks, when: Time): Seconds {
+		return this.getDurationOfTicks(ticks, when);
+	}
+
+	/**
+	 * The inverse of [[ticksToTime]]. Convert a duration in
+	 * seconds to the corresponding number of ticks accounting for any
+	 * automation curves starting at the given time.
+	 * @param  duration The time interval to convert to ticks.
+	 * @param  when When along the automation timeline to convert the ticks.
+	 * @return The duration in ticks.
+	 */
+	timeToTicks(duration: Time, when: Time): Ticks {
+		const computedTime = this.toSeconds(when);
+		const computedDuration = this.toSeconds(duration);
+		const startTicks = this.getTicksAtTime(computedTime);
+		const endTicks = this.getTicksAtTime(computedTime + computedDuration);
+		return endTicks - startTicks;
+	}
+
+	/**
+	 * Convert from the type when the unit value is BPM
+	 */
+	protected _fromType(val: UnitMap[TypeName]): number {
+		if (this.units === "bpm" && this.multiplier) {
+			return 1 / (60 / val / this.multiplier);
+		} else {
+			return super._fromType(val);
+		}
+	}
+
+	/**
+	 * Special case of type conversion where the units === "bpm"
+	 */
+	protected _toType(val: number): UnitMap[TypeName] {
+		if (this.units === "bpm" && this.multiplier) {
+			return (val / this.multiplier) * 60 as UnitMap[TypeName];
+		} else {
+			return super._toType(val);
+		}
+	}
+	/**
+	 * A multiplier on the bpm value. Useful for setting a PPQ relative to the base frequency value.
+	 */
+	get multiplier(): number {
+		return this._multiplier;
+	}
+	set multiplier(m: number) {
+		// get and reset the current value with the new multiplier
+		// might be necessary to clear all the previous values
+		const currentVal = this.value;
+		this._multiplier = m;
+		this.cancelScheduledValues(0);
+		this.setValueAtTime(currentVal, 0);
+	}
+}