tone 14.8.27

package/Tone/core/util/Timeline.ts

@@ -0,0 +1,399 @@
+import { Tone } from "../Tone";
+import { Seconds } from "../type/Units";
+import { optionsFromArguments } from "./Defaults";
+import { assert } from "./Debug";
+import { EQ, GT, GTE, LT } from "./Math";
+
+type TimelineSearchParam = "ticks" | "time";
+
+/**
+ * The options object for Timeline
+ */
+interface TimelineOptions {
+	memory: number;
+	increasing: boolean;
+}
+
+/**
+ * An event must have a time number
+ */
+export interface TimelineEvent {
+	time: number;
+}
+
+/**
+ * A Timeline class for scheduling and maintaining state
+ * along a timeline. All events must have a "time" property.
+ * Internally, events are stored in time order for fast
+ * retrieval.
+ */
+export class Timeline<GenericEvent extends TimelineEvent> extends Tone {
+
+	readonly name: string = "Timeline";
+
+	/**
+	 * The memory of the timeline, i.e.
+	 * how many events in the past it will retain
+	 */
+	memory: number;
+
+	/**
+	 * The array of scheduled timeline events
+	 */
+	protected _timeline: GenericEvent[] = [];
+
+	/**
+	 * If the time value must always be greater than or equal to the last 
+	 * element on the list. 
+	 */
+	increasing: boolean;
+
+	/**
+	 * @param memory The number of previous events that are retained.
+	 */
+	constructor(memory?: number);
+	constructor(options?: Partial<TimelineOptions>);
+	constructor() {
+		super();
+		const options = optionsFromArguments(Timeline.getDefaults(), arguments, ["memory"]);
+
+		this.memory = options.memory;
+		this.increasing = options.increasing;
+	}
+
+	static getDefaults(): TimelineOptions {
+		return {
+			memory: Infinity,
+			increasing: false,
+		};
+	}
+
+	/**
+	 * The number of items in the timeline.
+	 */
+	get length(): number {
+		return this._timeline.length;
+	}
+
+	/**
+	 * Insert an event object onto the timeline. Events must have a "time" attribute.
+	 * @param event  The event object to insert into the timeline.
+	 */
+	add(event: GenericEvent): this {
+		// the event needs to have a time attribute
+		assert(Reflect.has(event, "time"), "Timeline: events must have a time attribute");
+		event.time = event.time.valueOf();
+		if (this.increasing && this.length) {
+			const lastValue = this._timeline[this.length - 1] as GenericEvent;
+			assert(GTE(event.time, lastValue.time), "The time must be greater than or equal to the last scheduled time");
+			this._timeline.push(event);
+		} else {
+			const index = this._search(event.time);
+			this._timeline.splice(index + 1, 0, event);
+		}
+		// if the length is more than the memory, remove the previous ones
+		if (this.length > this.memory) {
+			const diff = this.length - this.memory;
+			this._timeline.splice(0, diff);
+		}
+		return this;
+	}
+
+	/**
+	 * Remove an event from the timeline.
+	 * @param  {Object}  event  The event object to remove from the list.
+	 * @returns {Timeline} this
+	 */
+	remove(event: GenericEvent): this {
+		const index = this._timeline.indexOf(event);
+		if (index !== -1) {
+			this._timeline.splice(index, 1);
+		}
+		return this;
+	}
+
+	/**
+	 * Get the nearest event whose time is less than or equal to the given time.
+	 * @param  time  The time to query.
+	 */
+	get(time: number, param: TimelineSearchParam = "time"): GenericEvent | null {
+		const index = this._search(time, param);
+		if (index !== -1) {
+			return this._timeline[index];
+		} else {
+			return null;
+		}
+	}
+
+	/**
+	 * Return the first event in the timeline without removing it
+	 * @returns {Object} The first event object
+	 */
+	peek(): GenericEvent | undefined {
+		return this._timeline[0];
+	}
+
+	/**
+	 * Return the first event in the timeline and remove it
+	 */
+	shift(): GenericEvent | undefined {
+		return this._timeline.shift();
+	}
+
+	/**
+	 * Get the event which is scheduled after the given time.
+	 * @param  time  The time to query.
+	 */
+	getAfter(time: number, param: TimelineSearchParam = "time"): GenericEvent | null {
+		const index = this._search(time, param);
+		if (index + 1 < this._timeline.length) {
+			return this._timeline[index + 1];
+		} else {
+			return null;
+		}
+	}
+
+	/**
+	 * Get the event before the event at the given time.
+	 * @param  time  The time to query.
+	 */
+	getBefore(time: number): GenericEvent | null {
+		const len = this._timeline.length;
+		// if it's after the last item, return the last item
+		if (len > 0 && this._timeline[len - 1].time < time) {
+			return this._timeline[len - 1];
+		}
+		const index = this._search(time);
+		if (index - 1 >= 0) {
+			return this._timeline[index - 1];
+		} else {
+			return null;
+		}
+	}
+
+	/**
+	 * Cancel events at and after the given time
+	 * @param  after  The time to query.
+	 */
+	cancel(after: number): this {
+		if (this._timeline.length > 1) {
+			let index = this._search(after);
+			if (index >= 0) {
+				if (EQ(this._timeline[index].time, after)) {
+					// get the first item with that time
+					for (let i = index; i >= 0; i--) {
+						if (EQ(this._timeline[i].time, after)) {
+							index = i;
+						} else {
+							break;
+						}
+					}
+					this._timeline = this._timeline.slice(0, index);
+				} else {
+					this._timeline = this._timeline.slice(0, index + 1);
+				}
+			} else {
+				this._timeline = [];
+			}
+		} else if (this._timeline.length === 1) {
+			// the first item's time
+			if (GTE(this._timeline[0].time, after)) {
+				this._timeline = [];
+			}
+		}
+		return this;
+	}
+
+	/**
+	 * Cancel events before or equal to the given time.
+	 * @param  time  The time to cancel before.
+	 */
+	cancelBefore(time: number): this {
+		const index = this._search(time);
+		if (index >= 0) {
+			this._timeline = this._timeline.slice(index + 1);
+		}
+		return this;
+	}
+
+	/**
+	 * Returns the previous event if there is one. null otherwise
+	 * @param  event The event to find the previous one of
+	 * @return The event right before the given event
+	 */
+	previousEvent(event: GenericEvent): GenericEvent | null {
+		const index = this._timeline.indexOf(event);
+		if (index > 0) {
+			return this._timeline[index - 1];
+		} else {
+			return null;
+		}
+	}
+
+	/**
+	 * Does a binary search on the timeline array and returns the
+	 * nearest event index whose time is after or equal to the given time.
+	 * If a time is searched before the first index in the timeline, -1 is returned.
+	 * If the time is after the end, the index of the last item is returned.
+	 */
+	protected _search(time: number, param: TimelineSearchParam = "time"): number {
+		if (this._timeline.length === 0) {
+			return -1;
+		}
+		let beginning = 0;
+		const len = this._timeline.length;
+		let end = len;
+		if (len > 0 && this._timeline[len - 1][param] <= time) {
+			return len - 1;
+		}
+		while (beginning < end) {
+			// calculate the midpoint for roughly equal partition
+			let midPoint = Math.floor(beginning + (end - beginning) / 2);
+			const event = this._timeline[midPoint];
+			const nextEvent = this._timeline[midPoint + 1];
+			if (EQ(event[param], time)) {
+				// choose the last one that has the same time
+				for (let i = midPoint; i < this._timeline.length; i++) {
+					const testEvent = this._timeline[i];
+					if (EQ(testEvent[param], time)) {
+						midPoint = i;
+					} else {
+						break;
+					}
+				}
+				return midPoint;
+			} else if (LT(event[param], time) && GT(nextEvent[param], time)) {
+				return midPoint;
+			} else if (GT(event[param], time)) {
+				// search lower
+				end = midPoint;
+			} else {
+				// search upper
+				beginning = midPoint + 1;
+			}
+		}
+		return -1;
+	}
+
+	/**
+	 * Internal iterator. Applies extra safety checks for
+	 * removing items from the array.
+	 */
+	private _iterate(
+		callback: (event: GenericEvent) => void,
+		lowerBound = 0, upperBound = this._timeline.length - 1,
+	): void {
+		this._timeline.slice(lowerBound, upperBound + 1).forEach(callback);
+	}
+
+	/**
+	 * Iterate over everything in the array
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEach(callback: (event: GenericEvent) => void): this {
+		this._iterate(callback);
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array at or before the given time.
+	 * @param  time The time to check if items are before
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEachBefore(time: Seconds, callback: (event: GenericEvent) => void): this {
+		// iterate over the items in reverse so that removing an item doesn't break things
+		const upperBound = this._search(time);
+		if (upperBound !== -1) {
+			this._iterate(callback, 0, upperBound);
+		}
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array after the given time.
+	 * @param  time The time to check if items are before
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEachAfter(time: Seconds, callback: (event: GenericEvent) => void): this {
+		// iterate over the items in reverse so that removing an item doesn't break things
+		const lowerBound = this._search(time);
+		this._iterate(callback, lowerBound + 1);
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array between the startTime and endTime.
+	 * The timerange is inclusive of the startTime, but exclusive of the endTime.
+	 * range = [startTime, endTime).
+	 * @param  startTime The time to check if items are before
+	 * @param  endTime The end of the test interval.
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEachBetween(startTime: number, endTime: number, callback: (event: GenericEvent) => void): this {
+		let lowerBound = this._search(startTime);
+		let upperBound = this._search(endTime);
+		if (lowerBound !== -1 && upperBound !== -1) {
+			if (this._timeline[lowerBound].time !== startTime) {
+				lowerBound += 1;
+			}
+			// exclusive of the end time
+			if (this._timeline[upperBound].time === endTime) {
+				upperBound -= 1;
+			}
+			this._iterate(callback, lowerBound, upperBound);
+		} else if (lowerBound === -1) {
+			this._iterate(callback, 0, upperBound);
+		}
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array at or after the given time. Similar to
+	 * forEachAfter, but includes the item(s) at 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: (event: GenericEvent) => void): this {
+		// iterate over the items in reverse so that removing an item doesn't break things
+		let lowerBound = this._search(time);
+		// work backwards until the event time is less than time
+		while (lowerBound >= 0 && this._timeline[lowerBound].time >= time) {
+			lowerBound--;
+		}
+		this._iterate(callback, lowerBound + 1);
+		return this;
+	}
+
+	/**
+	 * Iterate over everything in the array at the given time
+	 * @param  time The time to check if items are before
+	 * @param  callback The callback to invoke with every item
+	 */
+	forEachAtTime(time: number, callback: (event: GenericEvent) => void): this {
+		// iterate over the items in reverse so that removing an item doesn't break things
+		const upperBound = this._search(time);
+		if (upperBound !== -1 && EQ(this._timeline[upperBound].time, time)) {
+			let lowerBound = upperBound;
+			for (let i = upperBound; i >= 0; i--) {
+				if (EQ(this._timeline[i].time, time)) {
+					lowerBound = i;
+				} else {
+					break;
+				}
+			}
+			this._iterate(event => {
+				callback(event);
+			}, lowerBound, upperBound);
+		}
+		return this;
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this._timeline = [];
+		return this;
+	}
+}

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

@@ -0,0 +1,29 @@
+import { expect } from "chai";
+import { TimelineValue } from "./TimelineValue";
+
+describe("TimelineValue", () => {
+
+	it("can be created and disposed", () => {
+		const sched = new TimelineValue(0);
+		sched.dispose();
+	});
+
+	it("can add events to the timeline", () => {
+		const sched = new TimelineValue(10);
+		sched.set(11, 1);		
+		sched.set(1, 12);		
+		sched.set(3, 4);
+		expect(sched.get(0)).to.equal(10);
+		expect(sched.get(1)).to.equal(11);
+		expect(sched.get(2)).to.equal(11);
+		expect(sched.get(4)).to.equal(3);
+		expect(sched.get(12)).to.equal(1);
+		sched.dispose();
+	});
+
+	it("returns the initial value if there is nothing scheduled", () => {
+		const sched = new TimelineValue(10);
+		expect(sched.get(0)).to.equal(10);
+		sched.dispose();
+	});
+});

package/Tone/core/util/TimelineValue.ts

@@ -0,0 +1,56 @@
+import { Timeline, TimelineEvent } from "./Timeline";
+import { Tone } from "../Tone";
+import { Seconds } from "../type/Units";
+
+interface TimelineValueEvent<T> extends TimelineEvent {
+	value: T;
+}
+
+/**
+ * Represents a single value which is gettable and settable in a timed way
+ */
+export class TimelineValue<Type> extends Tone {
+
+	readonly name: string = "TimelineValue";
+
+	/**
+	 * The timeline which stores the values
+	 */
+	private _timeline: Timeline<TimelineValueEvent<Type>> = new Timeline({ memory: 10 })
+
+	/**
+	 * Hold the value to return if there is no scheduled values
+	 */
+	private _initialValue: Type;
+
+	/**
+	 * @param initialValue The value to return if there is no scheduled values
+	 */
+	constructor(initialValue: Type) {
+
+		super();
+		this._initialValue = initialValue;
+	}
+
+	/**
+	 * Set the value at the given time
+	 */
+	set(value: Type, time: Seconds): this {
+		this._timeline.add({
+			value, time
+		});
+		return this;
+	}
+	
+	/**
+	 * Get the value at the given time
+	 */
+	get(time: Seconds): Type {
+		const event = this._timeline.get(time);
+		if (event) {
+			return event.value;
+		} else {
+			return this._initialValue;
+		}
+	}
+}

package/Tone/core/util/TypeCheck.ts

@@ -0,0 +1,65 @@
+import { Note } from "../type/Units";
+
+/**
+ * Test if the arg is undefined
+ */
+export function isUndef(arg: any): arg is undefined {
+	return typeof arg === "undefined";
+}
+
+/**
+ * Test if the arg is not undefined
+ */
+export function isDefined<T>(arg: T | undefined): arg is T {
+	return !isUndef(arg);
+}
+
+/**
+ * Test if the arg is a function
+ */
+export function isFunction(arg: any): arg is (a: any) => any {
+	return typeof arg === "function";
+}
+
+/**
+ * Test if the argument is a number.
+ */
+export function isNumber(arg: any): arg is number {
+	return (typeof arg === "number");
+}
+
+/**
+ * Test if the given argument is an object literal (i.e. `{}`);
+ */
+export function isObject(arg: any): arg is object {
+	return (Object.prototype.toString.call(arg) === "[object Object]" && arg.constructor === Object);
+}
+
+/**
+ * Test if the argument is a boolean.
+ */
+export function isBoolean(arg: any): arg is boolean {
+	return (typeof arg === "boolean");
+}
+
+/**
+ * Test if the argument is an Array
+ */
+export function isArray(arg: any): arg is any[] {
+	return (Array.isArray(arg));
+}
+
+/**
+ * Test if the argument is a string.
+ */
+export function isString(arg: any): arg is string {
+	return (typeof arg === "string");
+}
+
+/**
+ * Test if the argument is in the form of a note in scientific pitch notation.
+ * e.g. "C4"
+ */
+export function isNote(arg: any): arg is Note {
+	return isString(arg) && /^([a-g]{1}(?:b|#|x|bb)?)(-?[0-9]+)/i.test(arg);
+}

package/Tone/core/util/global.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Replace the default lib.dom.d.ts interface to reflect the fact
+ * that the AudioParamMap extends Map
+ */
+interface AudioParamMap extends Map<string, AudioParam> {
+	forEach(callbackfn: (value: AudioParam, key: string, parent: AudioParamMap) => void, thisArg?: any): void;
+}

package/Tone/core/worklet/DelayLine.worklet.ts

@@ -0,0 +1,49 @@
+import { addToWorklet } from "./WorkletGlobalScope";
+
+const delayLine = /* javascript */ `
+	/**
+	 * A multichannel buffer for use within an AudioWorkletProcessor as a delay line
+	 */
+	class DelayLine {
+		
+		constructor(size, channels) {
+			this.buffer = [];
+			this.writeHead = []
+			this.size = size;
+
+			// create the empty channels
+			for (let i = 0; i < channels; i++) {
+				this.buffer[i] = new Float32Array(this.size);
+				this.writeHead[i] = 0;
+			}
+		}
+
+		/**
+		 * Push a value onto the end
+		 * @param channel number
+		 * @param value number
+		 */
+		push(channel, value) {
+			this.writeHead[channel] += 1;
+			if (this.writeHead[channel] > this.size) {
+				this.writeHead[channel] = 0;
+			}
+			this.buffer[channel][this.writeHead[channel]] = value;
+		}
+
+		/**
+		 * Get the recorded value of the channel given the delay
+		 * @param channel number
+		 * @param delay number delay samples
+		 */
+		get(channel, delay) {
+			let readHead = this.writeHead[channel] - Math.floor(delay);
+			if (readHead < 0) {
+				readHead += this.size;
+			}
+			return this.buffer[channel][readHead];
+		}
+	}
+`;
+
+addToWorklet(delayLine);

package/Tone/core/worklet/SingleIOProcessor.worklet.ts

@@ -0,0 +1,73 @@
+import "./ToneAudioWorkletProcessor.worklet";
+import { addToWorklet } from "./WorkletGlobalScope";
+
+export const singleIOProcess = /* javascript */ `
+	/**
+	 * Abstract class for a single input/output processor. 
+	 * has a 'generate' function which processes one sample at a time
+	 */
+	class SingleIOProcessor extends ToneAudioWorkletProcessor {
+
+		constructor(options) {
+			super(Object.assign(options, {
+				numberOfInputs: 1,
+				numberOfOutputs: 1
+			}));
+			/**
+			 * Holds the name of the parameter and a single value of that
+			 * parameter at the current sample
+			 * @type { [name: string]: number }
+			 */
+			this.params = {}
+		}
+
+		/**
+		 * Generate an output sample from the input sample and parameters
+		 * @abstract
+		 * @param input number
+		 * @param channel number
+		 * @param parameters { [name: string]: number }
+		 * @returns number
+		 */
+		generate(){}
+
+		/**
+		 * Update the private params object with the 
+		 * values of the parameters at the given index
+		 * @param parameters { [name: string]: Float32Array },
+		 * @param index number
+		 */
+		updateParams(parameters, index) {
+			for (const paramName in parameters) {
+				const param = parameters[paramName];
+				if (param.length > 1) {
+					this.params[paramName] = parameters[paramName][index];
+				} else {
+					this.params[paramName] = parameters[paramName][0];
+				}
+			}
+		}
+
+		/**
+		 * Process a single frame of the audio
+		 * @param inputs Float32Array[][]
+		 * @param outputs Float32Array[][]
+		 */
+		process(inputs, outputs, parameters) {
+			const input = inputs[0];
+			const output = outputs[0];
+			// get the parameter values
+			const channelCount = Math.max(input && input.length || 0, output.length);
+			for (let sample = 0; sample < this.blockSize; sample++) {
+				this.updateParams(parameters, sample);
+				for (let channel = 0; channel < channelCount; channel++) {
+					const inputSample = input && input.length ? input[channel][sample] : 0;
+					output[channel][sample] = this.generate(inputSample, channel, this.params);
+				}
+			}
+			return !this.disposed;
+		}
+	};
+`;
+
+addToWorklet(singleIOProcess);