tone 14.8.27

package/Tone/core/type/Units.ts

@@ -0,0 +1,204 @@
+export * from "./NoteUnits";
+
+import { Note } from "./NoteUnits";
+
+/**
+ * A number representing a time in seconds
+ * @category Unit
+ */
+export type Seconds = number;
+
+/**
+ * A number used to measure the intensity of a sound on a logarithmic scale.
+ * @category Unit
+ */
+export type Decibels = number;
+
+/**
+ * A number that is between [0, 1]
+ * @category Unit
+ */
+export type NormalRange = number;
+
+/**
+ * A number that is between [-1, 1]
+ * @category Unit
+ */
+export type AudioRange = number;
+
+/**
+ * Half-step note increments, i.e. 12 is an octave above the root. and 1 is a half-step up.
+ * @category Unit
+ */
+export type Interval = number;
+
+/**
+ * A number representing the multiplication factor applied to a signal
+ * @category Unit
+ */
+export type GainFactor = number;
+
+/**
+ * A number greater than or equal to 0.
+ * @category Unit
+ */
+export type Positive = number;
+
+/**
+ * Represents a subdivision of a measure.
+ * The number represents the subdivision. "t" represents a triplet. A "." add a half.
+ * e.g. "4n" is a quarter note, "4t" is a quarter note triplet, and "4n." is a dotted quarter note.
+ * @category Unit
+ */
+export type Subdivision = "1m" | "1n" | "1n." | "2n" | "2n." | "2t" | "4n" | "4n." | "4t" | "8n" | "8n." | "8t" |
+"16n" | "16n." | "16t" | "32n" | "32n." | "32t" | "64n" | "64n." | "64t" | "128n" | "128n." | "128t" |
+"256n" | "256n." | "256t" | "0";
+
+/**
+ * A time object has a subdivision as the keys and a number as the values.
+ * @example
+ * Tone.Time({
+ * 	"2n": 1,
+ * 	"8n": 3
+ * }).valueOf(); // 2n + 8n * 3
+ * @category Unit
+ */
+export type TimeObject = {
+	[sub in Subdivision]?: number;
+};
+
+/**
+ * Time can be described in a number of ways. Read more [Time](https://github.com/Tonejs/Tone.js/wiki/Time).
+ * * Numbers, which will be taken literally as the time (in seconds).
+ * * Notation, ("4n", "8t") describes time in BPM and time signature relative values.
+ * * TransportTime, ("4:3:2") will also provide tempo and time signature relative times in the form BARS:QUARTERS:SIXTEENTHS.
+ * * Frequency, ("8hz") is converted to the length of the cycle in seconds.
+ * * Now-Relative, ("+1") prefix any of the above with "+" and it will be interpreted as "the current time plus whatever expression follows".
+ * * Object, ({"4n" : 3, "8t" : -1}). The resulting time is equal to the sum of all of the keys multiplied by the values in the object.
+ * * No Argument, for methods which accept time, no argument will be interpreted as "now" (i.e. the currentTime).
+ * @category Unit
+ */
+export type Time = string | Seconds | TimeObject | Subdivision;
+
+/**
+ * Frequency can be described similar to time, except ultimately the
+ * values are converted to frequency instead of seconds. A number
+ * is taken literally as the value in hertz. Additionally any of the
+ * Time encodings can be used. Note names in the form
+ * of NOTE OCTAVE (i.e. C4) are also accepted and converted to their
+ * frequency value.
+ * @category Unit
+ */
+export type Frequency = Subdivision | Note | string | Hertz;
+
+/**
+ *
+ * @category Unit
+ */
+export type TimeSignature = number | number[];
+
+/**
+ * TransportTime describes a position along the Transport's timeline. It is
+ * similar to Time in that it uses all the same encodings, but TransportTime specifically
+ * pertains to the Transport's timeline, which is startable, stoppable, loopable, and seekable.
+ * [Read more](https://github.com/Tonejs/Tone.js/wiki/TransportTime)
+ * @category Unit
+ */
+export type TransportTime = Time;
+
+/**
+ * Ticks are the basic subunit of the Transport. They are
+ * the smallest unit of time that the Transport supports.
+ * @category Unit
+ */
+export type Ticks = number;
+
+/**
+ * Beats per minute
+ * @category Unit
+ */
+export type BPM = number;
+
+/**
+ * Angle between 0 and 360.
+ * @category Unit
+ */
+export type Degrees = number;
+
+/**
+ * Angle between 0 and 2 * PI.
+ * @category Unit
+ */
+export type Radians = number;
+
+/**
+ * A colon-separated representation of time in the form of
+ * Bars:Beats:Sixteenths.
+ * @category Unit
+ */
+export type BarsBeatsSixteenths = string;
+/**
+ * Sampling is the reduction of a continuous signal to a discrete signal.
+ * Audio is typically sampled 44100 times per second.
+ * @category Unit
+ */
+export type Samples = number;
+
+/**
+ * Hertz are a frequency representation defined as one cycle per second.
+ * @category Unit
+ */
+export type Hertz = number;
+
+/**
+ * A Cent is 1/100th of a semitone.
+ * e.g. a value of 50 cents would be halfway between two intervals.
+ * @category Unit
+ */
+export type Cents = number;
+
+/**
+ * One millisecond is a thousandth of a second.
+ * @category Unit
+ */
+export type Milliseconds = number;
+
+/**
+ * A value which is a power of 2
+ * @category Unit
+ */
+export type PowerOfTwo = number;
+
+/**
+ * Map the unit name to a unit value
+ */
+export interface UnitMap {
+	number: number;
+	decibels: Decibels;
+	normalRange: NormalRange;
+	audioRange: AudioRange;
+	gain: GainFactor;
+	positive: Positive;
+	time: Time;
+	frequency: Frequency;
+	transportTime: TransportTime;
+	ticks: Ticks;
+	bpm: BPM;
+	degrees: Degrees;
+	radians: Radians;
+	samples: Samples;
+	hertz: Hertz;
+	cents: Cents;
+}
+
+/**
+ * All of the unit types
+ * @category Unit
+ */
+export type Unit = UnitMap[keyof UnitMap];
+
+/**
+ * All of the unit names
+ * @category Unit
+ */
+export type UnitName = keyof UnitMap;

package/Tone/core/util/AdvancedTypeCheck.ts

@@ -0,0 +1,40 @@
+import {
+	AudioBuffer, isAnyAudioContext,
+	isAnyAudioNode, isAnyAudioParam,
+	isAnyOfflineAudioContext
+} from "standardized-audio-context";
+
+/**
+ * Test if the given value is an instanceof AudioParam
+ */
+export function isAudioParam(arg: any): arg is AudioParam {
+	return isAnyAudioParam(arg);
+}
+
+/**
+ * Test if the given value is an instanceof AudioNode
+ */
+export function isAudioNode(arg: any): arg is AudioNode {
+	return isAnyAudioNode(arg);
+}
+
+/**
+ * Test if the arg is instanceof an OfflineAudioContext
+ */
+export function isOfflineAudioContext(arg: any): arg is OfflineAudioContext {
+	return isAnyOfflineAudioContext(arg);
+}
+
+/**
+ * Test if the arg is an instanceof AudioContext
+ */
+export function isAudioContext(arg: any): arg is AudioContext {
+	return isAnyAudioContext(arg);
+}
+
+/**
+ * Test if the arg is instanceof an AudioBuffer
+ */
+export function isAudioBuffer(arg: any): arg is AudioBuffer {
+	return arg instanceof AudioBuffer;
+}

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

@@ -0,0 +1,74 @@
+import { expect } from "chai";
+import { ToneOscillatorNode } from "../../source/oscillator/ToneOscillatorNode";
+import { assertRange, setLogger } from "./Debug";
+import { theWindow } from "../context/AudioContext";
+import { Oscillator } from "Tone/source";
+import { Context } from "../context/Context";
+
+describe("Debug", () => {
+
+	it("can log a class when that class is set to 'debug'", () => {
+		const osc = new ToneOscillatorNode();
+		osc.debug = true;
+		let loggerInvoked = false;
+		let warnInvoked = false;
+		setLogger({
+			log: () => loggerInvoked = true,
+			warn: () => warnInvoked = true
+		});
+		osc.start();
+		expect(loggerInvoked).to.be.true;
+		expect(warnInvoked).to.be.false;
+		osc.dispose();
+		setLogger(console);
+	});
+
+	it("can log a class when the window is set with that class name", () => {
+		// @ts-ignore
+		theWindow.TONE_DEBUG_CLASS = "ToneOscillatorNode";
+		const osc = new ToneOscillatorNode();
+		let loggerInvoked = false;
+		let warnInvoked = false;
+		setLogger({
+			log: () => loggerInvoked = true,
+			warn: () => warnInvoked = true
+		});
+		osc.start();
+		expect(loggerInvoked).to.be.true;
+		expect(warnInvoked).to.be.false;
+		setLogger(console);
+		// @ts-ignore
+		theWindow.TONE_DEBUG_CLASS = undefined;
+		osc.dispose();
+	});
+
+	it("can assert a range", () => {
+		expect(() => {
+			assertRange(-1, 0, 1);
+		}).to.throw(RangeError);
+
+		expect(() => {
+			assertRange(2, 0, 1);
+		}).to.throw(RangeError);
+		
+		expect(() => {
+			assertRange(0, 0);
+		}).to.not.throw(RangeError);
+	});
+
+	it("warns if console is not running", async () => {
+		const context = new Context();
+		await context.rawContext.suspend(0);
+		const osc = new Oscillator({ context });
+		let warnInvoked = false;
+		setLogger({
+			log: () => {},
+			warn: () => warnInvoked = true
+		});
+		osc.start();
+		expect(warnInvoked).to.be.true;
+		osc.dispose();
+		setLogger(console);
+		await context.close();
+	});
+});

package/Tone/core/util/Debug.ts

@@ -0,0 +1,63 @@
+/**
+ * Assert that the statement is true, otherwise invoke the error.
+ * @param statement
+ * @param error The message which is passed into an Error
+ */
+export function assert(statement: boolean, error: string): void {
+	if (!statement) {
+		throw new Error(error);
+	}
+}
+
+/**
+ * Make sure that the given value is within the range
+ */
+export function assertRange(value: number, gte: number, lte = Infinity): void {
+	if (!(gte <= value && value <= lte)) {
+		throw new RangeError(`Value must be within [${gte}, ${lte}], got: ${value}`);
+	}
+}
+
+/**
+ * Make sure that the given value is within the range
+ */
+export function assertContextRunning(context: import("../context/BaseContext").BaseContext): void {
+	// add a warning if the context is not started
+	if (!context.isOffline && context.state !== "running") {
+		warn("The AudioContext is \"suspended\". Invoke Tone.start() from a user action to start the audio.");
+	}
+}
+
+/**
+ * A basic logging interface
+ */
+interface Logger {
+	log: (args?: any[]) => void;
+	warn: (args?: any[]) => void;
+}
+
+/**
+ * The default logger is the console
+ */
+let defaultLogger: Logger = console;
+
+/**
+ * Set the logging interface
+ */
+export function setLogger(logger: Logger): void {
+	defaultLogger = logger;
+}
+
+/**
+ * Log anything
+ */
+export function log(...args: any[]): void {
+	defaultLogger.log(...args);
+}
+
+/**
+ * Warn anything
+ */
+export function warn(...args: any[]): void {
+	defaultLogger.warn(...args);
+}

package/Tone/core/util/Decorator.ts

@@ -0,0 +1,51 @@
+import { assertRange } from "./Debug";
+import { Time } from "../type/Units";
+
+/**
+ * Assert that the number is in the given range.
+ */
+export function range(min: number, max = Infinity) {
+	const valueMap: WeakMap<any, number> = new WeakMap();
+	return function(target: any, propertyKey: string | symbol) {
+		Reflect.defineProperty(
+			target,
+			propertyKey,
+			{
+				configurable: true,
+				enumerable: true,
+				get: function() {
+					return valueMap.get(this);
+				},
+				set: function(newValue: number) {
+					assertRange(newValue, min, max);
+					valueMap.set(this, newValue);
+				}
+			},
+		);
+	};
+}
+
+/**
+ * Convert the time to seconds and assert that the time is in between the two
+ * values when being set.
+ */
+export function timeRange(min: number, max = Infinity) {
+	const valueMap: WeakMap<any, Time> = new WeakMap();
+	return function(target: any, propertyKey: string) {
+		Reflect.defineProperty(
+			target,
+			propertyKey,
+			{
+				configurable: true,
+				enumerable: true,
+				get: function() {
+					return valueMap.get(this);
+				},
+				set: function(newValue: Time) {
+					assertRange(this.toSeconds(newValue), min, max);
+					valueMap.set(this, newValue);
+				}
+			},
+		);
+	};
+}

package/Tone/core/util/Defaults.ts

@@ -0,0 +1,123 @@
+import { isAudioBuffer, isAudioNode, isAudioParam } from "./AdvancedTypeCheck";
+import { isDefined, isObject, isUndef } from "./TypeCheck";
+
+type BaseToneOptions = import("../Tone").BaseToneOptions;
+
+/**
+ * Some objects should not be merged
+ */
+function noCopy(key: string, arg: any): boolean {
+	return key === "value" || isAudioParam(arg) || isAudioNode(arg) || isAudioBuffer(arg);
+}
+
+/**
+ * Recursively merge an object
+ * @param target the object to merge into
+ * @param sources the source objects to merge
+ */
+export function deepMerge<T>(target: T): T;
+export function deepMerge<T, U>(target: T, source1: U): T & U;
+export function deepMerge<T, U, V>(target: T, source1: U, source2: V): T & U & V;
+export function deepMerge<T, U, V, W>(target: T, source1: U, source2: V, source3: W): T & U & V & W;
+export function deepMerge(target: any, ...sources: any[]): any {
+	if (!sources.length) {
+		return target; 
+	}
+	const source = sources.shift();
+
+	if (isObject(target) && isObject(source)) {
+		for (const key in source) {
+			if (noCopy(key, source[key])) {
+				target[key] = source[key];
+			} else if (isObject(source[key])) {
+				if (!target[key]) {
+					Object.assign(target, { [key]: {} }); 
+				}
+				deepMerge(target[key], source[key] as any);
+			} else {
+				Object.assign(target, { [key]: source[key] as any });
+			}
+		}
+	}
+	// @ts-ignore
+	return deepMerge(target, ...sources);
+}
+
+/**
+ * Returns true if the two arrays have the same value for each of the elements
+ */
+export function deepEquals<T>(arrayA: T[], arrayB: T[]): boolean {
+	return arrayA.length === arrayB.length && arrayA.every((element, index) => arrayB[index] === element);
+}
+
+/**
+ * Convert an args array into an object.
+ */
+export function optionsFromArguments<T extends object>(
+	defaults: T,
+	argsArray: IArguments,
+	keys: Array<keyof T> = [],
+	objKey?: keyof T,
+): T {
+	const opts: Partial<T> = {};
+	const args = Array.from(argsArray);
+	// if the first argument is an object and has an object key
+	if (isObject(args[0]) && objKey && !Reflect.has(args[0], objKey)) {
+		// if it's not part of the defaults
+		const partOfDefaults = Object.keys(args[0]).some(key => Reflect.has(defaults, key));
+		if (!partOfDefaults) {
+			// merge that key
+			deepMerge(opts, { [objKey]: args[0] });
+			// remove the obj key from the keys
+			keys.splice(keys.indexOf(objKey), 1);
+			// shift the first argument off
+			args.shift();
+		}
+	}
+	if (args.length === 1 && isObject(args[0])) {
+		deepMerge(opts, args[0]);
+	} else {
+		for (let i = 0; i < keys.length; i++) {
+			if (isDefined(args[i])) {
+				opts[keys[i]] = args[i];
+			}
+		}
+	}
+	return deepMerge(defaults, opts);
+}
+
+/**
+ * Return this instances default values by calling Constructor.getDefaults()
+ */
+export function getDefaultsFromInstance<T>(instance: T): BaseToneOptions {
+	type ToneClass = {
+		constructor: ToneClass;
+		getDefaults: () => BaseToneOptions;
+	} & T;
+
+	return (instance as ToneClass).constructor.getDefaults();
+}
+
+/**
+ * Returns the fallback if the given object is undefined.
+ * Take an array of arguments and return a formatted options object.
+ */
+export function defaultArg<T>(given: T, fallback: T): T {
+	if (isUndef(given)) {
+		return fallback;
+	} else {
+		return given;
+	}
+}
+
+/**
+ * Remove all of the properties belonging to omit from obj.
+ */
+export function omitFromObject<T extends object, O extends string[]>(obj: T, omit: O): Omit<T, keyof O> {
+	omit.forEach(prop => {
+		if (Reflect.has(obj, prop)) {
+			delete obj[prop];
+		}
+	});
+	return obj;
+}

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

@@ -0,0 +1,72 @@
+import { expect } from "chai";
+import { ONLINE_TESTING } from "test/helper/Supports";
+import { Draw } from "./Draw";
+
+describe("Draw", () => {
+
+	if (ONLINE_TESTING) {
+
+		const draw = new Draw();
+
+		after(() => {
+			draw.dispose();
+		});
+
+		it("can schedule a callback at a AudioContext time", (done) => {
+			const scheduledTime = draw.now() + 0.2;
+			draw.schedule(() => {
+				expect(draw.context.currentTime).to.be.closeTo(scheduledTime, 0.05);
+				done();
+			}, scheduledTime);
+		});
+
+		it("can schedule multiple callbacks", (done) => {
+			let callbackCount = 0;
+			const firstEvent = draw.now() + 0.1;
+			draw.schedule(() => {
+				callbackCount++;
+				expect(draw.context.currentTime).to.be.closeTo(firstEvent, 0.05);
+			}, firstEvent);
+
+			const thirdEvent = draw.now() + 0.3;
+			draw.schedule(() => {
+				callbackCount++;
+				expect(draw.context.currentTime).to.be.closeTo(thirdEvent, 0.05);
+				expect(callbackCount).to.equal(3);
+				done();
+			}, thirdEvent);
+
+			const secondEvent = draw.now() + 0.2;
+			draw.schedule(() => {
+				callbackCount++;
+				expect(draw.context.currentTime).to.be.closeTo(secondEvent, 0.05);
+			}, secondEvent);
+		});
+
+		it("can cancel scheduled events", (done) => {
+			let callbackCount = 0;
+			draw.schedule(() => {
+				callbackCount++;
+			}, draw.now() + 0.1);
+
+			draw.schedule(() => {
+				throw new Error("should not call this method");
+			}, draw.now() + 0.2);
+
+			draw.schedule(() => {
+				throw new Error("should not call this method");
+			}, draw.now() + 0.25);
+
+			// cancel the second and third events
+			draw.cancel(draw.now() + 0.15);
+
+			// schedule another one after
+			draw.schedule(() => {
+				callbackCount++;
+				expect(callbackCount).to.equal(2);
+				done();
+			}, draw.now() + 0.3);
+
+		});
+	}
+});