tone 14.8.27

package/Tone/core/util/IntervalTimeline.ts

@@ -0,0 +1,569 @@
+import { Tone } from "../Tone";
+import { isDefined } from "./TypeCheck";
+import { assert } from "./Debug";
+
+/**
+ * An IntervalTimeline event must have a time and duration
+ */
+export interface IntervalTimelineEvent {
+	time: number;
+	duration: number;
+	[propName: string]: any;
+}
+
+type IteratorCallback = (event: IntervalTimelineEvent) => void;
+
+/**
+ * Similar to Tone.Timeline, but all events represent
+ * intervals with both "time" and "duration" times. The
+ * events are placed in a tree structure optimized
+ * for querying an intersection point with the timeline
+ * events. Internally uses an [Interval Tree](https://en.wikipedia.org/wiki/Interval_tree)
+ * to represent the data.
+ */
+export class IntervalTimeline extends Tone {
+
+	readonly name: string = "IntervalTimeline";
+
+	/**
+	 * The root node of the inteval tree
+	 */
+	private _root: IntervalNode | null = null;
+
+	/**
+	 * Keep track of the length of the timeline.
+	 */
+	private _length = 0;
+
+	/**
+	 * The event to add to the timeline. All events must
+	 * have a time and duration value
+	 * @param  event  The event to add to the timeline
+	 */
+	add(event: IntervalTimelineEvent): this {
+		assert(isDefined(event.time), "Events must have a time property");
+		assert(isDefined(event.duration), "Events must have a duration parameter");
+
+		event.time = event.time.valueOf();
+		let node: IntervalNode | null = new IntervalNode(event.time, event.time + event.duration, event);
+		if (this._root === null) {
+			this._root = node;
+		} else {
+			this._root.insert(node);
+		}
+		this._length++;
+		// Restructure tree to be balanced
+		while (node !== null) {
+			node.updateHeight();
+			node.updateMax();
+			this._rebalance(node);
+			node = node.parent;
+		}
+		return this;
+	}
+
+	/**
+	 * Remove an event from the timeline.
+	 * @param  event  The event to remove from the timeline
+	 */
+	remove(event: IntervalTimelineEvent): this {
+		if (this._root !== null) {
+			const results: IntervalNode[] = [];
+			this._root.search(event.time, results);
+			for (const node of results) {
+				if (node.event === event) {
+					this._removeNode(node);
+					this._length--;
+					break;
+				}
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * The number of items in the timeline.
+	 * @readOnly
+	 */
+	get length(): number {
+		return this._length;
+	}
+
+	/**
+	 * Remove events whose time time is after the given time
+	 * @param  after  The time to query.
+	 */
+	cancel(after: number): this {
+		this.forEachFrom(after, event => this.remove(event));
+		return this;
+	}
+
+	/**
+	 * Set the root node as the given node
+	 */
+	private _setRoot(node: IntervalNode | null): void {
+		this._root = node;
+		if (this._root !== null) {
+			this._root.parent = null;
+		}
+	}
+
+	/**
+	 * Replace the references to the node in the node's parent
+	 * with the replacement node.
+	 */
+	private _replaceNodeInParent(node: IntervalNode, replacement: IntervalNode | null): void {
+		if (node.parent !== null) {
+			if (node.isLeftChild()) {
+				node.parent.left = replacement;
+			} else {
+				node.parent.right = replacement;
+			}
+			this._rebalance(node.parent);
+		} else {
+			this._setRoot(replacement);
+		}
+	}
+
+	/**
+	 * Remove the node from the tree and replace it with
+	 * a successor which follows the schema.
+	 */
+	private _removeNode(node: IntervalNode): void {
+		if (node.left === null && node.right === null) {
+			this._replaceNodeInParent(node, null);
+		} else if (node.right === null) {
+			this._replaceNodeInParent(node, node.left);
+		} else if (node.left === null) {
+			this._replaceNodeInParent(node, node.right);
+		} else {
+			const balance = node.getBalance();
+			let replacement: IntervalNode;
+			let temp: IntervalNode | null = null;
+			if (balance > 0) {
+				if (node.left.right === null) {
+					replacement = node.left;
+					replacement.right = node.right;
+					temp = replacement;
+				} else {
+					replacement = node.left.right;
+					while (replacement.right !== null) {
+						replacement = replacement.right;
+					}
+					if (replacement.parent) {
+						replacement.parent.right = replacement.left;
+						temp = replacement.parent;
+						replacement.left = node.left;
+						replacement.right = node.right;
+					}
+				}
+			} else if (node.right.left === null) {
+				replacement = node.right;
+				replacement.left = node.left;
+				temp = replacement;
+			} else {
+				replacement = node.right.left;
+				while (replacement.left !== null) {
+					replacement = replacement.left;
+				}
+				if (replacement.parent) {
+					replacement.parent.left = replacement.right;
+					temp = replacement.parent;
+					replacement.left = node.left;
+					replacement.right = node.right;
+				}
+			}
+			if (node.parent !== null) {
+				if (node.isLeftChild()) {
+					node.parent.left = replacement;
+				} else {
+					node.parent.right = replacement;
+				}
+			} else {
+				this._setRoot(replacement);
+			}
+			if (temp) {
+				this._rebalance(temp);
+			}
+		}
+		node.dispose();
+	}
+
+	/**
+	 * Rotate the tree to the left
+	 */
+	private _rotateLeft(node: IntervalNode): void {
+		const parent = node.parent;
+		const isLeftChild = node.isLeftChild();
+
+		// Make node.right the new root of this sub tree (instead of node)
+		const pivotNode = node.right;
+		if (pivotNode) {
+			node.right = pivotNode.left;
+			pivotNode.left = node;
+		}
+
+		if (parent !== null) {
+			if (isLeftChild) {
+				parent.left = pivotNode;
+			} else {
+				parent.right = pivotNode;
+			}
+		} else {
+			this._setRoot(pivotNode);
+		}
+	}
+
+	/**
+	 * Rotate the tree to the right
+	 */
+	private _rotateRight(node: IntervalNode): void {
+		const parent = node.parent;
+		const isLeftChild = node.isLeftChild();
+
+		// Make node.left the new root of this sub tree (instead of node)
+		const pivotNode = node.left;
+		if (pivotNode) {
+			node.left = pivotNode.right;
+			pivotNode.right = node;
+		}
+
+		if (parent !== null) {
+			if (isLeftChild) {
+				parent.left = pivotNode;
+			} else {
+				parent.right = pivotNode;
+			}
+		} else {
+			this._setRoot(pivotNode);
+		}
+	}
+
+	/**
+	 * Balance the BST
+	 */
+	private _rebalance(node: IntervalNode): void {
+		const balance = node.getBalance();
+		if (balance > 1 && node.left) {
+			if (node.left.getBalance() < 0) {
+				this._rotateLeft(node.left);
+			} else {
+				this._rotateRight(node);
+			}
+		} else if (balance < -1 && node.right) {
+			if (node.right.getBalance() > 0) {
+				this._rotateRight(node.right);
+			} else {
+				this._rotateLeft(node);
+			}
+		}
+	}
+
+	/**
+	 * Get an event whose time and duration span the give time. Will
+	 * return the match whose "time" value is closest to the given time.
+	 * @return  The event which spans the desired time
+	 */
+	get(time: number): IntervalTimelineEvent | null {
+		if (this._root !== null) {
+			const results: IntervalNode[] = [];
+			this._root.search(time, results);
+			if (results.length > 0) {
+				let max = results[0];
+				for (let i = 1; i < results.length; i++) {
+					if (results[i].low > max.low) {
+						max = results[i];
+					}
+				}
+				return max.event;
+			}
+		}
+		return null;
+	}
+
+	/**
+	 * Iterate over everything in the timeline.
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEach(callback: IteratorCallback): this {
+		if (this._root !== null) {
+			const allNodes: IntervalNode[] = [];
+			this._root.traverse(node => allNodes.push(node));
+			allNodes.forEach(node => {
+				if (node.event) {
+					callback(node.event);
+				}
+			});
+		}
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array in which the given time
+	 * overlaps with the time and duration time of the event.
+	 * @param  time The time to check if items are overlapping
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEachAtTime(time: number, callback: IteratorCallback): this {
+		if (this._root !== null) {
+			const results: IntervalNode[] = [];
+			this._root.search(time, results);
+			results.forEach(node => {
+				if (node.event) {
+					callback(node.event);
+				}
+			});
+		}
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array in which the time is greater
+	 * than or equal to the given time.
+	 * @param  time The time to check if items are before
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEachFrom(time: number, callback: IteratorCallback): this {
+		if (this._root !== null) {
+			const results: IntervalNode[] = [];
+			this._root.searchAfter(time, results);
+			results.forEach(node => {
+				if (node.event) {
+					callback(node.event);
+				}
+			});
+		}
+		return this;
+	}
+
+	/**
+	 * Clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		if (this._root !== null) {
+			this._root.traverse(node => node.dispose());
+		}
+		this._root = null;
+		return this;
+	}
+}
+
+//-------------------------------------
+// 	INTERVAL NODE HELPER
+//-------------------------------------
+
+/**
+ * Represents a node in the binary search tree, with the addition
+ * of a "high" value which keeps track of the highest value of
+ * its children.
+ * References:
+ * https://brooknovak.wordpress.com/2013/12/07/augmented-interval-tree-in-c/
+ * http://www.mif.vu.lt/~valdas/ALGORITMAI/LITERATURA/Cormen/Cormen.pdf
+ * @param low
+ * @param high
+ */
+class IntervalNode {
+
+	// the event container
+	event: IntervalTimelineEvent | null;
+	// the low value
+	low: number;
+	// the high value
+	high: number;
+	// the high value for this and all child nodes
+	max: number;
+	// the nodes to the left
+	private _left: IntervalNode | null = null;
+	// the nodes to the right
+	private _right: IntervalNode | null = null;
+	// the parent node
+	parent: IntervalNode | null = null;
+	// the number of child nodes
+	height = 0;
+
+	constructor(low: number, high: number, event: IntervalTimelineEvent) {
+		this.event = event;
+		// the low value
+		this.low = low;
+		// the high value
+		this.high = high;
+		// the high value for this and all child nodes
+		this.max = this.high;
+	}
+
+	/**
+	 * Insert a node into the correct spot in the tree
+	 */
+	insert(node: IntervalNode): void {
+		if (node.low <= this.low) {
+			if (this.left === null) {
+				this.left = node;
+			} else {
+				this.left.insert(node);
+			}
+		} else if (this.right === null) {
+			this.right = node;
+		} else {
+			this.right.insert(node);
+		}
+	}
+
+	/**
+	 * Search the tree for nodes which overlap
+	 * with the given point
+	 * @param  point  The point to query
+	 * @param  results  The array to put the results
+	 */
+	search(point: number, results: IntervalNode[]): void {
+		// If p is to the right of the rightmost point of any interval
+		// in this node and all children, there won't be any matches.
+		if (point > this.max) {
+			return;
+		}
+		// Search left children
+		if (this.left !== null) {
+			this.left.search(point, results);
+		}
+		// Check this node
+		if (this.low <= point && this.high > point) {
+			results.push(this);
+		}
+		// If p is to the left of the time of this interval,
+		// then it can't be in any child to the right.
+		if (this.low > point) {
+			return;
+		}
+		// Search right children
+		if (this.right !== null) {
+			this.right.search(point, results);
+		}
+	}
+
+	/**
+	 * Search the tree for nodes which are less
+	 * than the given point
+	 * @param  point  The point to query
+	 * @param  results  The array to put the results
+	 */
+	searchAfter(point: number, results: IntervalNode[]): void {
+		// Check this node
+		if (this.low >= point) {
+			results.push(this);
+			if (this.left !== null) {
+				this.left.searchAfter(point, results);
+			}
+		}
+		// search the right side
+		if (this.right !== null) {
+			this.right.searchAfter(point, results);
+		}
+	}
+
+	/**
+	 * Invoke the callback on this element and both it's branches
+	 * @param  {Function}  callback
+	 */
+	traverse(callback: (self: IntervalNode) => void): void {
+		callback(this);
+		if (this.left !== null) {
+			this.left.traverse(callback);
+		}
+		if (this.right !== null) {
+			this.right.traverse(callback);
+		}
+	}
+
+	/**
+	 * Update the height of the node
+	 */
+	updateHeight(): void {
+		if (this.left !== null && this.right !== null) {
+			this.height = Math.max(this.left.height, this.right.height) + 1;
+		} else if (this.right !== null) {
+			this.height = this.right.height + 1;
+		} else if (this.left !== null) {
+			this.height = this.left.height + 1;
+		} else {
+			this.height = 0;
+		}
+	}
+
+	/**
+	 * Update the height of the node
+	 */
+	updateMax(): void {
+		this.max = this.high;
+		if (this.left !== null) {
+			this.max = Math.max(this.max, this.left.max);
+		}
+		if (this.right !== null) {
+			this.max = Math.max(this.max, this.right.max);
+		}
+	}
+
+	/**
+	 * The balance is how the leafs are distributed on the node
+	 * @return  Negative numbers are balanced to the right
+	 */
+	getBalance(): number {
+		let balance = 0;
+		if (this.left !== null && this.right !== null) {
+			balance = this.left.height - this.right.height;
+		} else if (this.left !== null) {
+			balance = this.left.height + 1;
+		} else if (this.right !== null) {
+			balance = -(this.right.height + 1);
+		}
+		return balance;
+	}
+
+	/**
+	 * @returns true if this node is the left child of its parent
+	 */
+	isLeftChild(): boolean {
+		return this.parent !== null && this.parent.left === this;
+	}
+
+	/**
+	 * get/set the left node
+	 */
+	get left(): IntervalNode | null {
+		return this._left;
+	}
+
+	set left(node: IntervalNode | null) {
+		this._left = node;
+		if (node !== null) {
+			node.parent = this;
+		}
+		this.updateHeight();
+		this.updateMax();
+	}
+
+	/**
+	 * get/set the right node
+	 */
+	get right(): IntervalNode | null {
+		return this._right;
+	}
+
+	set right(node: IntervalNode | null) {
+		this._right = node;
+		if (node !== null) {
+			node.parent = this;
+		}
+		this.updateHeight();
+		this.updateMax();
+	}
+
+	/**
+	 * null out references.
+	 */
+	dispose(): void {
+		this.parent = null;
+		this._left = null;
+		this._right = null;
+		this.event = null;
+	}
+}

package/Tone/core/util/Math.ts

@@ -0,0 +1,40 @@
+/**
+ * The threshold for correctness for operators. Less than one sample even 
+ * at very high sampling rates (e.g. `1e-6 < 1 / 192000`).
+ */
+const EPSILON = 1e-6;
+
+/**
+ * Test if A is greater than B
+ */
+export function GT(a: number, b: number): boolean {
+	return a > b + EPSILON;
+}
+
+/**
+ * Test if A is greater than or equal to B
+ */
+export function GTE(a: number, b: number): boolean {
+	return GT(a, b) || EQ(a, b);
+}
+
+/**
+ * Test if A is less than B
+ */
+export function LT(a: number, b: number): boolean {
+	return a + EPSILON < b;
+}
+
+/**
+ * Test if A is less than B
+ */
+export function EQ(a: number, b: number): boolean {
+	return Math.abs(a - b) < EPSILON;
+}
+
+/**
+ * Clamp the value within the given range
+ */
+export function clamp(value: number, min: number, max: number): number {
+	return Math.max(Math.min(value, max), min);
+}

package/Tone/core/util/StateTimeline.test.ts

@@ -0,0 +1,103 @@
+import { expect } from "chai";
+import { StateTimeline } from "./StateTimeline";
+
+describe("StateTimeline", () => {
+
+	it("can be created and disposed", () => {
+		const sched = new StateTimeline();
+		sched.dispose();
+	});
+
+	it("can schedule a state at a given time", () => {
+		const sched = new StateTimeline();
+		sched.setStateAtTime("started", 0);
+		sched.setStateAtTime("stopped", 1);
+		sched.setStateAtTime("started", 1);
+		sched.dispose();
+	});
+
+	it("can get a state at a given time", () => {
+		const sched = new StateTimeline();
+		sched.setStateAtTime("started", 0);
+		sched.setStateAtTime("stopped", 1);
+		sched.setStateAtTime("started", 2);
+		expect(sched.getValueAtTime(1)).to.equal("stopped");
+		expect(sched.getValueAtTime(0.999)).to.equal("started");
+		sched.dispose();
+	});
+
+	it("returns initial state if it's before any scheduled states", () => {
+		const sched = new StateTimeline();
+		sched.setStateAtTime("started", 0);
+		sched.setStateAtTime("stopped", 1);
+		sched.setStateAtTime("started", 2);
+		expect(sched.getValueAtTime(-11)).to.equal("stopped");
+		sched.dispose();
+	});
+
+	it("returns the last event inserted if the timing is very close", () => {
+		const sched = new StateTimeline();
+		sched.setStateAtTime("stopped", 1 + 1e-7);
+		sched.setStateAtTime("started", 1 - 1e-7);
+		expect(sched.getValueAtTime(1 - 1e-7)).to.equal("started");
+		sched.dispose();
+	});
+
+	it("returns initial state if defined and query time is before any scheduled states", () => {
+		const sched = new StateTimeline("started");
+		sched.setStateAtTime("started", 20);
+		sched.setStateAtTime("stopped", 21);
+		sched.setStateAtTime("started", 22);
+		expect(sched.getValueAtTime(0)).is.equal("started");
+		sched.dispose();
+	});
+
+	it("gets the last occurance of the state at or before the given time", () => {
+		const sched = new StateTimeline();
+		sched.setStateAtTime("started", 0);
+		sched.setStateAtTime("stopped", 1);
+		sched.setStateAtTime("started", 2);
+		sched.setStateAtTime("stopped", 3);
+		expect(sched.getLastState("stopped", 1)).to.exist;
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 1).state).is.equal("stopped");
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 2)).to.exist;
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 2).state).is.equal("stopped");
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 2).time).is.equal(1);
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 0.9).time).to.equal(0);
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 4).state).is.equal("stopped");
+		// @ts-ignore
+		expect(sched.getLastState("stopped", 4).time).is.equal(3);
+		sched.dispose();
+	});
+
+	it("gets the next occurance of the state at or before the given time", () => {
+		const sched = new StateTimeline();
+		sched.setStateAtTime("started", 0);
+		sched.setStateAtTime("stopped", 1);
+		sched.setStateAtTime("started", 2);
+		sched.setStateAtTime("stopped", 3);
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 1)).to.exist;
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 1).state).is.equal("stopped");
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 2)).to.exist;
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 2).state).is.equal("stopped");
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 2).time).is.equal(3);
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 0.9)).to.exist;
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 0.9).state).is.equal("stopped");
+		// @ts-ignore
+		expect(sched.getNextState("stopped", 0.9).time).is.equal(1);
+		sched.dispose();
+	});
+});