Tone.js/Tone/core/clock/TickSource.ts

import { ToneWithContext, ToneWithContextOptions } from "../context/ToneWithContext";
import { Seconds, Ticks, Time } from "../type/Units";
import { optionsFromArguments } from "../util/Defaults";
import { readOnly } from "../util/Interface";
import { PlaybackState, StateTimeline, StateTimelineEvent } from "../util/StateTimeline";
import { Timeline } from "../util/Timeline";
import { isDefined } from "../util/TypeCheck";
import { TickSignal } from "./TickSignal";
import { EQ } from "../util/Math";

interface TickSourceOptions extends ToneWithContextOptions {
	frequency: number;
	units: "bpm" | "hertz";
}

interface TickSourceOffsetEvent {
	ticks: number;
	time: number;
	seconds: number;
}

/**
 * Uses [TickSignal](TickSignal) to track elapsed ticks with complex automation curves.
 */
export class TickSource<TypeName extends "bpm" | "hertz"> extends ToneWithContext<TickSourceOptions> {

	readonly name: string = "TickSource";

	/**
	 * The frequency the callback function should be invoked.
	 */
	readonly frequency: TickSignal<TypeName>;

	/**
	 * The state timeline
	 */
	private _state: StateTimeline = new StateTimeline();

	/**
	 * The offset values of the ticks
	 */
	private _tickOffset: Timeline<TickSourceOffsetEvent> = new Timeline();

	/**
	 * @param frequency The initial frequency that the signal ticks at
	 */
	constructor(frequency?: number);
	constructor(options?: Partial<TickSourceOptions>);
	constructor() {
		super(optionsFromArguments(TickSource.getDefaults(), arguments, ["frequency"]));
		const options = optionsFromArguments(TickSource.getDefaults(), arguments, ["frequency"]);

		this.frequency = new TickSignal({
			context: this.context,
			units: options.units as TypeName,
			value: options.frequency,
		});
		readOnly(this, "frequency");

		// set the initial state
		this._state.setStateAtTime("stopped", 0);
		// add the first event
		this.setTicksAtTime(0, 0);
	}

	static getDefaults(): TickSourceOptions {
		return Object.assign({
			frequency: 1,
			units: "hertz" as "hertz",
		}, ToneWithContext.getDefaults());
	}

	/**
	 * Returns the playback state of the source, either "started", "stopped" or "paused".
	 */
	get state(): PlaybackState {
		return this.getStateAtTime(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 The number of ticks to start the source at
	 */
	start(time: Time, offset?: Ticks): this {
		const computedTime = this.toSeconds(time);
		if (this._state.getValueAtTime(computedTime) !== "started") {
			this._state.setStateAtTime("started", computedTime);
			if (isDefined(offset)) {
				this.setTicksAtTime(offset, computedTime);
			}
		}
		return this;
	}

	/**
	 * Stop the clock. Stopping the clock resets the tick counter to 0.
	 * @param time The time when the clock should stop.
	 */
	stop(time: Time): this {
		const computedTime = this.toSeconds(time);
		// cancel the previous stop
		if (this._state.getValueAtTime(computedTime) === "stopped") {
			const event = this._state.get(computedTime);
			if (event && event.time > 0) {
				this._tickOffset.cancel(event.time);
				this._state.cancel(event.time);
			}
		}
		this._state.cancel(computedTime);
		this._state.setStateAtTime("stopped", computedTime);
		this.setTicksAtTime(0, 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);
		}
		return this;
	}

	/**
	 * Cancel start/stop/pause and setTickAtTime events scheduled after the given time.
	 * @param time When to clear the events after
	 */
	cancel(time: Time): this {
		time = this.toSeconds(time);
		this._state.cancel(time);
		this._tickOffset.cancel(time);
		return this;
	}

	/**
	 * Get the elapsed ticks at the given time
	 * @param  time  When to get the tick value
	 * @return The number of ticks
	 */
	getTicksAtTime(time?: Time): Ticks {
		const computedTime = this.toSeconds(time);
		const stopEvent = this._state.getLastState("stopped", computedTime) as StateTimelineEvent;
		// this event allows forEachBetween to iterate until the current time
		const tmpEvent: StateTimelineEvent = { state: "paused", time: computedTime };
		this._state.add(tmpEvent);

		// keep track of the previous offset event
		let lastState = stopEvent;
		let elapsedTicks = 0;

		// iterate through all the events since the last stop
		this._state.forEachBetween(stopEvent.time, computedTime + this.sampleTime, e => {
			let periodStartTime = lastState.time;
			// if there is an offset event in this period use that
			const offsetEvent = this._tickOffset.get(e.time);
			if (offsetEvent && offsetEvent.time >= lastState.time) {
				elapsedTicks = offsetEvent.ticks;
				periodStartTime = offsetEvent.time;
			}
			if (lastState.state === "started" && e.state !== "started") {
				elapsedTicks += this.frequency.getTicksAtTime(e.time) - this.frequency.getTicksAtTime(periodStartTime);
			}
			lastState = e;
		});

		// remove the temporary event
		this._state.remove(tmpEvent);

		// return the ticks
		return elapsedTicks;
	}

	/**
	 * The number of times the callback was invoked. Starts counting at 0
	 * and increments after the callback was invoked. Returns -1 when stopped.
	 */
	get ticks(): Ticks {
		return this.getTicksAtTime(this.now());
	}
	set ticks(t: Ticks) {
		this.setTicksAtTime(t, this.now());
	}

	/**
	 * The time since ticks=0 that the TickSource has been running. Accounts
	 * for tempo curves
	 */
	get seconds(): Seconds {
		return this.getSecondsAtTime(this.now());
	}
	set seconds(s: Seconds) {
		const now = this.now();
		const ticks = this.frequency.timeToTicks(s, now);
		this.setTicksAtTime(ticks, now);
	}

	/**
	 * 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 {
		time = this.toSeconds(time);
		const stopEvent = this._state.getLastState("stopped", time) as StateTimelineEvent;
		// this event allows forEachBetween to iterate until the current time
		const tmpEvent: StateTimelineEvent = { state: "paused", time };
		this._state.add(tmpEvent);

		// keep track of the previous offset event
		let lastState = stopEvent;
		let elapsedSeconds = 0;

		// iterate through all the events since the last stop
		this._state.forEachBetween(stopEvent.time, time + this.sampleTime, e => {
			let periodStartTime = lastState.time;
			// if there is an offset event in this period use that
			const offsetEvent = this._tickOffset.get(e.time);
			if (offsetEvent && offsetEvent.time >= lastState.time) {
				elapsedSeconds = offsetEvent.seconds;
				periodStartTime = offsetEvent.time;
			}
			if (lastState.state === "started" && e.state !== "started") {
				elapsedSeconds += e.time - periodStartTime;
			}
			lastState = e;
		});

		// remove the temporary event
		this._state.remove(tmpEvent);

		// return the ticks
		return elapsedSeconds;
	}

	/**
	 * 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 {
		time = this.toSeconds(time);
		this._tickOffset.cancel(time);
		this._tickOffset.add({
			seconds: this.frequency.getDurationOfTicks(ticks, time),
			ticks,
			time,
		});
		return this;
	}

	/**
	 * Returns the scheduled state at the given time.
	 * @param  time  The time to query.
	 */
	getStateAtTime(time: Time): PlaybackState {
		time = this.toSeconds(time);
		return this._state.getValueAtTime(time);
	}

	/**
	 * 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 {
		const offset = this._tickOffset.get(before) as TickSourceOffsetEvent;
		const event = this._state.get(before) as StateTimelineEvent;
		const startTime = Math.max(offset.time, event.time);
		const absoluteTicks = this.frequency.getTicksAtTime(startTime) + tick - offset.ticks;
		return this.frequency.getTimeOfTick(absoluteTicks);
	}

	/**
	 * Invoke the callback event at all scheduled ticks between the
	 * start time and the end time
	 * @param  startTime  The beginning of the search range
	 * @param  endTime    The end of the search range
	 * @param  callback   The callback to invoke with each tick
	 */
	forEachTickBetween(startTime: number, endTime: number, callback: (when: Seconds, ticks: Ticks) => void): this {
		// only iterate through the sections where it is "started"
		let lastStateEvent = this._state.get(startTime);
		this._state.forEachBetween(startTime, endTime, event => {
			if (lastStateEvent && lastStateEvent.state === "started" && event.state !== "started") {
				this.forEachTickBetween(Math.max(lastStateEvent.time, startTime), event.time - this.sampleTime, callback);
			}
			lastStateEvent = event;
		});

		let error: Error | null = null;

		if (lastStateEvent && lastStateEvent.state === "started") {
			const maxStartTime = Math.max(lastStateEvent.time, startTime);
			// figure out the difference between the frequency ticks and the
			const startTicks = this.frequency.getTicksAtTime(maxStartTime);
			const ticksAtStart = this.frequency.getTicksAtTime(lastStateEvent.time);
			const diff = startTicks - ticksAtStart;
			let offset = Math.ceil(diff) - diff;
			// guard against floating point issues
			offset = EQ(offset, 1) ? 0 : offset;
			let nextTickTime = this.frequency.getTimeOfTick(startTicks + offset);
			while (nextTickTime < endTime) {
				try {
					callback(nextTickTime, Math.round(this.getTicksAtTime(nextTickTime)));
				} catch (e) {
					error = e;
					break;
				}
				nextTickTime += this.frequency.getDurationOfTicks(1, nextTickTime);
			}
		}

		if (error) {
			throw error;
		}

		return this;
	}

	/**
	 * Clean up
	 */
	dispose(): this {
		super.dispose();
		this._state.dispose();
		this._tickOffset.dispose();
		this.frequency.dispose();
		return this;
	}
}