tone 14.8.27

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

@@ -0,0 +1,45 @@
+import { expect } from "chai";
+import { Offline } from "test/helper/Offline";
+import { Transport } from "./Transport";
+import { TransportEvent } from "./TransportEvent";
+
+describe("TransportEvent", () => {
+
+	it("can be created and disposed", () => {
+		return Offline((context) => {
+			const transport = new Transport({ context });
+			const event = new TransportEvent(transport, {
+				time: 0,
+			});
+			event.dispose();
+		});
+	});
+
+	it("has a unique id", () => {
+		return Offline((context) => {
+			const transport = new Transport({ context });
+			const event = new TransportEvent(transport, {
+				time: 0,
+			});
+			expect(event.id).to.be.a("number");
+			event.dispose();
+		});
+	});
+
+	it("can invoke the callback", () => {
+		let wasInvoked = false;
+		return Offline((context) => {
+			const transport = new Transport({ context });
+			const event = new TransportEvent(transport, {
+				callback: (time) => {
+					expect(time).to.equal(100);
+					wasInvoked = true;
+				},
+				time: 0,
+			});
+			event.invoke(100);
+		}).then(() => {
+			expect(wasInvoked).to.equal(true);
+		});
+	});
+});

package/Tone/core/clock/TransportEvent.ts

@@ -0,0 +1,105 @@
+import { Seconds, Ticks } from "../type/Units";
+import { noOp } from "../util/Interface";
+
+type Transport = import("../clock/Transport").Transport;
+
+export interface TransportEventOptions {
+	callback: (time: number) => void;
+	once: boolean;
+	time: Ticks;
+}
+
+/**
+ * TransportEvent is an internal class used by [[Transport]]
+ * to schedule events. Do no invoke this class directly, it is
+ * handled from within Tone.Transport.
+ */
+export class TransportEvent {
+
+	/**
+	 * Reference to the Transport that created it
+	 */
+	protected transport: Transport;
+
+	/**
+	 * The unique id of the event
+	 */
+	id: number = TransportEvent._eventId++;
+
+	/**
+	 * The time the event starts
+	 */
+	time: Ticks;
+
+	/**
+	 * The callback to invoke
+	 */
+	private callback?: (time: Seconds) => void;
+
+	/**
+	 * If the event should be removed after being invoked.
+	 */
+	private _once: boolean;
+
+	/**
+	 * The remaining value between the passed in time, and Math.floor(time).
+	 * This value is later added back when scheduling to get sub-tick precision. 
+	 */
+	protected _remainderTime = 0;
+
+	/**
+	 * @param transport The transport object which the event belongs to
+	 */
+	constructor(transport: Transport, opts: Partial<TransportEventOptions>) {
+
+		const options: TransportEventOptions = Object.assign(TransportEvent.getDefaults(), opts);
+
+		this.transport = transport;
+		this.callback = options.callback;
+		this._once = options.once;
+		this.time = Math.floor(options.time);
+		this._remainderTime = options.time - this.time;
+	}
+
+	static getDefaults(): TransportEventOptions {
+		return {
+			callback: noOp,
+			once: false,
+			time: 0,
+		};
+	}
+
+	/**
+	 * Current ID counter
+	 */
+	private static _eventId = 0;
+
+	/**
+	 * Get the time and remainder time.
+	 */
+	protected get floatTime(): number {
+		return this.time + this._remainderTime;
+	}
+
+	/**
+	 * Invoke the event callback.
+	 * @param  time  The AudioContext time in seconds of the event
+	 */
+	invoke(time: Seconds): void {
+		if (this.callback) {
+			const tickDuration = this.transport.bpm.getDurationOfTicks(1, time);
+			this.callback(time + this._remainderTime * tickDuration);
+			if (this._once) {
+				this.transport.clear(this.id);
+			}
+		}
+	}
+
+	/**
+	 * Clean up
+	 */
+	dispose(): this {
+		this.callback = undefined;
+		return this;
+	}
+}

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

@@ -0,0 +1,43 @@
+import { expect } from "chai";
+import { Offline } from "test/helper/Offline";
+import { Transport } from "./Transport";
+import { TransportRepeatEvent } from "./TransportRepeatEvent";
+
+describe("TransportRepeatEvent", () => {
+
+	it("can be created and disposed", () => {
+		return Offline((context) => {
+			const transport = new Transport({ context });
+			const event = new TransportRepeatEvent(transport, {
+				duration: 100,
+				interval: 4,
+				time: 0,
+			});
+			event.dispose();
+		});
+	});
+
+	it("generates a unique event ID", () => {
+		return Offline((context) => {
+			const transport = new Transport({ context });
+			const event = new TransportRepeatEvent(transport, {
+				time: 0,
+			});
+			expect(event.id).to.be.a("number");
+			event.dispose();
+		});
+	});
+
+	it("is removed from the Transport when disposed", () => {
+		return Offline((context) => {
+			const transport = new Transport({ context });
+			const event = new TransportRepeatEvent(transport, {
+				time: 0,
+			});
+			event.dispose();
+			// @ts-ignore
+			expect(transport._timeline.length).to.equal(0);
+		});
+	});
+
+});

package/Tone/core/clock/TransportRepeatEvent.ts

@@ -0,0 +1,150 @@
+import { BaseContext } from "../context/BaseContext";
+import { TicksClass } from "../type/Ticks";
+import { Seconds, Ticks, Time } from "../type/Units";
+import { TransportEvent, TransportEventOptions } from "./TransportEvent";
+import { GT, LT } from "../util/Math";
+
+type Transport = import("../clock/Transport").Transport;
+
+interface TransportRepeatEventOptions extends TransportEventOptions {
+	interval: Ticks;
+	duration: Ticks;
+}
+
+/**
+ * TransportRepeatEvent is an internal class used by Tone.Transport
+ * to schedule repeat events. This class should not be instantiated directly.
+ */
+export class TransportRepeatEvent extends TransportEvent {
+
+	/**
+	 * When the event should stop repeating
+	 */
+	private duration: Ticks;
+
+	/**
+	 * The interval of the repeated event
+	 */
+	private _interval: Ticks;
+
+	/**
+	 * The ID of the current timeline event
+	 */
+	private _currentId = -1;
+
+	/**
+	 * The ID of the next timeline event
+	 */
+	private _nextId = -1;
+
+	/**
+	 * The time of the next event
+	 */
+	private _nextTick = this.time;
+
+	/**
+	 * a reference to the bound start method
+	 */
+	private _boundRestart = this._restart.bind(this);
+
+	/**
+	 * The audio context belonging to this event
+	 */
+	protected context: BaseContext;
+
+	/**
+	 * @param transport The transport object which the event belongs to
+	 */
+	constructor(transport: Transport, opts: Partial<TransportRepeatEventOptions>) {
+
+		super(transport, opts);
+
+		const options = Object.assign(TransportRepeatEvent.getDefaults(), opts);
+
+		this.duration = options.duration;
+		this._interval = options.interval;
+		this._nextTick = options.time;
+		this.transport.on("start", this._boundRestart);
+		this.transport.on("loopStart", this._boundRestart);
+		this.transport.on("ticks", this._boundRestart);
+		this.context = this.transport.context;
+		this._restart();
+	}
+
+	static getDefaults(): TransportRepeatEventOptions {
+		return Object.assign({}, TransportEvent.getDefaults(), {
+			duration: Infinity,
+			interval: 1,
+			once: false,
+		});
+	}
+
+	/**
+	 * Invoke the callback. Returns the tick time which
+	 * the next event should be scheduled at.
+	 * @param  time  The AudioContext time in seconds of the event
+	 */
+	invoke(time: Seconds): void {
+		// create more events if necessary
+		this._createEvents(time);
+		// call the super class
+		super.invoke(time);
+	}
+
+	/**
+	 * Create an event on the transport on the nextTick
+	 */
+	private _createEvent(): number {
+		if (LT(this._nextTick, this.floatTime + this.duration)) {
+			return this.transport.scheduleOnce(this.invoke.bind(this),
+				new TicksClass(this.context, this._nextTick).toSeconds());
+		}
+		return -1;
+	}
+
+	/**
+	 * Push more events onto the timeline to keep up with the position of the timeline
+	 */
+	private _createEvents(time: Seconds): void {
+		// schedule the next event
+		// const ticks = this.transport.getTicksAtTime(time);
+		// if the next tick is within the bounds set by "duration"
+		if (LT(this._nextTick + this._interval, this.floatTime + this.duration)) {
+			this._nextTick += this._interval;
+			this._currentId = this._nextId;
+			this._nextId = this.transport.scheduleOnce(this.invoke.bind(this),
+				new TicksClass(this.context, this._nextTick).toSeconds());
+		}
+	}
+
+	/**
+	 * Re-compute the events when the transport time has changed from a start/ticks/loopStart event
+	 */
+	private _restart(time?: Time): void {
+		this.transport.clear(this._currentId);
+		this.transport.clear(this._nextId);
+		// start at the first event
+		this._nextTick = this.floatTime;
+		const ticks = this.transport.getTicksAtTime(time);
+		if (GT(ticks, this.time)) {
+			// the event is not being scheduled from the beginning and should be offset
+			this._nextTick = this.floatTime + Math.ceil((ticks - this.floatTime) / this._interval) * this._interval;
+		}
+		this._currentId = this._createEvent();
+		this._nextTick += this._interval;
+		this._nextId = this._createEvent();
+	}
+
+	/**
+	 * Clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		this.transport.clear(this._currentId);
+		this.transport.clear(this._nextId);
+		this.transport.off("start", this._boundRestart);
+		this.transport.off("loopStart", this._boundRestart);
+		this.transport.off("ticks", this._boundRestart);
+		return this;
+	}
+}

package/Tone/core/context/AbstractParam.ts

@@ -0,0 +1,260 @@
+import { Time, UnitMap, UnitName } from "../type/Units";
+
+/**
+ * Abstract base class for [[Param]] and [[Signal]]
+ */
+export abstract class AbstractParam<TypeName extends UnitName> {
+
+	/**
+	 * Schedules a parameter value change at the given time.
+	 * @param value The value to set the signal.
+	 * @param time The time when the change should occur.
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const osc = new Tone.Oscillator(20).toDestination().start();
+	 * 	// set the frequency to 40 at exactly 0.25 seconds
+	 * 	osc.frequency.setValueAtTime(40, 0.25);
+	 * }, 0.5, 1);
+	 */
+	abstract setValueAtTime(value: UnitMap[TypeName], time: Time): this;
+
+	/**
+	 * Get the signals value at the given time. Subsequent scheduling
+	 * may invalidate the returned value.
+	 * @param time When to get the value
+	 * @example
+	 * const signal = new Tone.Signal().toDestination();
+	 * // ramp up to '8' over 3 seconds
+	 * signal.rampTo(8, 3);
+	 * // ramp back down to '0' over 3 seconds
+	 * signal.rampTo(0, 3, "+3");
+	 * setInterval(() => {
+	 * 	// check the value every 100 ms
+	 * 	console.log(signal.getValueAtTime(Tone.now()));
+	 * }, 100);
+	 */
+	abstract getValueAtTime(time: Time): UnitMap[TypeName];
+
+	/**
+	 * Creates a schedule point with the current value at the current time.
+	 * Automation methods like [[linearRampToValueAtTime]] and [[exponentialRampToValueAtTime]]
+	 * require a starting automation value usually set by [[setValueAtTime]]. This method
+	 * is useful since it will do a `setValueAtTime` with whatever the currently computed
+	 * value at the given time is. 
+	 * @param time When to add a ramp point.
+	 * @example
+	 * const osc = new Tone.Oscillator().toDestination().start();
+	 * // set the frequency to "G4" in exactly 1 second from now.
+	 * osc.frequency.setRampPoint("+1");
+	 * osc.frequency.linearRampToValueAtTime("C1", "+2");
+	 */
+	abstract setRampPoint(time: Time): this;
+
+	/**
+	 * Schedules a linear continuous change in parameter value from the
+	 * previous scheduled parameter value to the given value.
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(0).toDestination();
+	 * 	// the ramp starts from the previously scheduled value
+	 * 	signal.setValueAtTime(0, 0.1);
+	 * 	signal.linearRampToValueAtTime(1, 0.4);
+	 * }, 0.5, 1);
+	 */
+	abstract linearRampToValueAtTime(value: UnitMap[TypeName], time: Time): this;
+
+	/**
+	 * Schedules an exponential continuous change in parameter value from
+	 * the previous scheduled parameter value to the given value.
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(1).toDestination();
+	 * 	// the ramp starts from the previously scheduled value, which must be positive
+	 * 	signal.setValueAtTime(1, 0.1);
+	 * 	signal.exponentialRampToValueAtTime(0, 0.4);
+	 * }, 0.5, 1);
+	 */
+	abstract exponentialRampToValueAtTime(value: UnitMap[TypeName], time: Time): this;
+
+	/**
+	 * Schedules an exponential continuous change in parameter value from
+	 * the current time and current value to the given value over the
+	 * duration of the rampTime.
+	 * @param value   The value to ramp to.
+	 * @param rampTime the time that it takes the
+	 *                             value to ramp from it's current value
+	 * @param startTime When the ramp should start.
+	 * @example
+	 * const delay = new Tone.FeedbackDelay(0.5, 0.98).toDestination();
+	 * // a short burst of noise through the feedback delay
+	 * const noise = new Tone.Noise().connect(delay).start().stop("+0.1");
+	 * // making the delay time shorter over time will also make the pitch rise
+	 * delay.delayTime.exponentialRampTo(0.01, 20);
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(.1).toDestination();
+	 * 	signal.exponentialRampTo(5, 0.3, 0.1);
+	 * }, 0.5, 1);
+	 */
+	abstract exponentialRampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: Time): this;
+
+	/**
+	 * Schedules an linear continuous change in parameter value from
+	 * the current time and current value to the given value over the
+	 * duration of the rampTime.
+	 *
+	 * @param  value   The value to ramp to.
+	 * @param  rampTime the time that it takes the
+	 *                              value to ramp from it's current value
+	 * @param startTime 	When the ramp should start.
+	 * @returns {Param} this
+	 * @example
+	 * const delay = new Tone.FeedbackDelay(0.5, 0.98).toDestination();
+	 * // a short burst of noise through the feedback delay
+	 * const noise = new Tone.Noise().connect(delay).start().stop("+0.1");
+	 * // making the delay time shorter over time will also make the pitch rise
+	 * delay.delayTime.linearRampTo(0.01, 20);
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(1).toDestination();
+	 * 	signal.linearRampTo(0, 0.3, 0.1);
+	 * }, 0.5, 1);
+	 */
+	abstract linearRampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: Time): this;
+
+	/**
+	 * Start exponentially approaching the target value at the given time. Since it
+	 * is an exponential approach it will continue approaching after the ramp duration. The
+	 * rampTime is the time that it takes to reach over 99% of the way towards the value.
+	 * @param  value   The value to ramp to.
+	 * @param  rampTime the time that it takes the
+	 *                              value to ramp from it's current value
+	 * @param startTime 	When the ramp should start.
+	 * @example
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(1).toDestination();
+	 * 	signal.targetRampTo(0, 0.3, 0.1);
+	 * }, 0.5, 1);
+	 */
+	abstract targetRampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: Time): this;
+
+	/**
+	 * Start exponentially approaching the target value at the given time. Since it
+	 * is an exponential approach it will continue approaching after the ramp duration. The
+	 * rampTime is the time that it takes to reach over 99% of the way towards the value. This methods
+	 * is similar to setTargetAtTime except the third argument is a time instead of a 'timeConstant'
+	 * @param  value   The value to ramp to.
+	 * @param time 	When the ramp should start.
+	 * @param  rampTime the time that it takes the value to ramp from it's current value
+	 * @example
+	 * const osc = new Tone.Oscillator().toDestination().start();
+	 * // exponential approach over 4 seconds starting in 1 second
+	 * osc.frequency.exponentialApproachValueAtTime("C4", "+1", 4);
+	 */
+	abstract exponentialApproachValueAtTime(value: UnitMap[TypeName], time: Time, rampTime: Time): this;
+
+	/**
+	 * Start exponentially approaching the target value at the given time with
+	 * a rate having the given time constant.
+	 * @param value
+	 * @param startTime
+	 * @param timeConstant
+	 */
+	abstract setTargetAtTime(value: UnitMap[TypeName], startTime: Time, timeConstant: number): this;
+
+	/**
+	 * Sets an array of arbitrary parameter values starting at the given time
+	 * for the given duration.
+	 *
+	 * @param values
+	 * @param startTime
+	 * @param duration
+	 * @param scaling If the values in the curve should be scaled by some value
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(1).toDestination();
+	 * 	signal.setValueCurveAtTime([1, 0.2, 0.8, 0.1, 0], 0.2, 0.3);
+	 * }, 0.5, 1);
+	 */
+	abstract setValueCurveAtTime(values: UnitMap[TypeName][], startTime: Time, duration: Time, scaling?: number): this;
+
+	/**
+	 * Cancels all scheduled parameter changes with times greater than or
+	 * equal to startTime.
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(0).toDestination();
+	 * 	signal.setValueAtTime(0.1, 0.1);
+	 * 	signal.setValueAtTime(0.2, 0.2);
+	 * 	signal.setValueAtTime(0.3, 0.3);
+	 * 	signal.setValueAtTime(0.4, 0.4);
+	 * 	// cancels the last two scheduled changes
+	 * 	signal.cancelScheduledValues(0.3);
+	 * }, 0.5, 1);
+	 */
+	abstract cancelScheduledValues(time: Time): this;
+
+	/**
+	 * This is similar to [[cancelScheduledValues]] except
+	 * it holds the automated value at time until the next automated event.
+	 * @example
+	 * return Tone.Offline(() => {
+	 * 	const signal = new Tone.Signal(0).toDestination();
+	 * 	signal.linearRampTo(1, 0.5, 0);
+	 * 	signal.cancelAndHoldAtTime(0.3);
+	 * }, 0.5, 1);
+	 */
+	abstract cancelAndHoldAtTime(time: Time): this;
+
+	/**
+	 * Ramps to the given value over the duration of the rampTime.
+	 * Automatically selects the best ramp type (exponential or linear)
+	 * depending on the `units` of the signal
+	 *
+	 * @param  value
+	 * @param  rampTime The time that it takes the value to ramp from it's current value
+	 * @param startTime When the ramp should start.
+	 * @example
+	 * const osc = new Tone.Oscillator().toDestination().start();
+	 * // schedule it to ramp either linearly or exponentially depending on the units
+	 * osc.frequency.rampTo("A2", 10);
+	 * @example
+	 * const osc = new Tone.Oscillator().toDestination().start();
+	 * // schedule it to ramp starting at a specific time
+	 * osc.frequency.rampTo("A2", 10, "+2");
+	 */
+	abstract rampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: Time): this;
+
+	/**
+	 * The current value of the parameter. Setting this value
+	 * is equivalent to setValueAtTime(value, context.currentTime)
+	 */
+	abstract value: UnitMap[TypeName];
+
+	/**
+	 * If the value should be converted or not
+	 */
+	abstract convert: boolean;
+
+	/**
+	 * The unit type
+	 */
+	abstract readonly units: UnitName;
+
+	/**
+	 * True if the signal value is being overridden by
+	 * a connected signal. Internal use only.
+	 */
+	abstract overridden: boolean;
+
+	/**
+	 * The minimum value of the output given the units
+	 */
+	abstract readonly minValue: number;
+
+	/**
+	 * The maximum value of the output given the units
+	 */
+	abstract readonly maxValue: number;
+}

package/Tone/core/context/AudioContext.ts

@@ -0,0 +1,60 @@
+import {
+	AudioContext as stdAudioContext,
+	AudioWorkletNode as stdAudioWorkletNode,
+	OfflineAudioContext as stdOfflineAudioContext
+} from "standardized-audio-context";
+import { assert } from "../util/Debug";
+import { isDefined } from "../util/TypeCheck";
+
+/**
+ * Create a new AudioContext
+ */
+export function createAudioContext(options?: AudioContextOptions): AudioContext {
+	return new stdAudioContext(options) as unknown as AudioContext;
+}
+
+/**
+ * Create a new OfflineAudioContext
+ */
+export function createOfflineAudioContext(channels: number, length: number, sampleRate: number): OfflineAudioContext {
+	return new stdOfflineAudioContext(channels, length, sampleRate) as unknown as OfflineAudioContext;
+}
+
+/**
+ * Either the online or offline audio context
+ */
+export type AnyAudioContext = AudioContext | OfflineAudioContext;
+
+/**
+ * Interface for things that Tone.js adds to the window
+ */
+interface ToneWindow extends Window {
+	TONE_SILENCE_LOGGING?: boolean;
+	TONE_DEBUG_CLASS?: string;
+}
+
+/**
+ * A reference to the window object
+ * @hidden
+ */
+export const theWindow: ToneWindow | null = typeof self === "object" ? self : null;
+
+/**
+ * If the browser has a window object which has an AudioContext
+ * @hidden
+ */
+export const hasAudioContext = theWindow &&
+	(theWindow.hasOwnProperty("AudioContext") || theWindow.hasOwnProperty("webkitAudioContext"));
+
+export function createAudioWorkletNode(context: AnyAudioContext, name: string, options?: Partial<AudioWorkletNodeOptions>): AudioWorkletNode {
+	assert(isDefined(stdAudioWorkletNode), "This node only works in a secure context (https or localhost)");
+	// @ts-ignore
+	return new stdAudioWorkletNode(context, name, options);
+}
+
+/**
+ * This promise resolves to a boolean which indicates if the 
+ * functionality is supported within the currently used browse. 
+ * Taken from [standardized-audio-context](https://github.com/chrisguttandin/standardized-audio-context#issupported)
+ */
+export { isSupported as supported } from "standardized-audio-context";