tone 14.8.27

package/Tone/core/type/Time.ts

@@ -0,0 +1,156 @@
+import { getContext } from "../Global";
+import { ftom } from "./Conversions";
+import { TimeBaseClass, TimeBaseUnit, TimeExpression, TimeValue } from "./TimeBase";
+import { BarsBeatsSixteenths, MidiNote, Seconds, Subdivision, Ticks, Time } from "./Units";
+
+/**
+ * TimeClass is a primitive type for encoding and decoding Time values.
+ * TimeClass can be passed into the parameter of any method which takes time as an argument.
+ * @param  val    The time value.
+ * @param  units  The units of the value.
+ * @example
+ * const time = Tone.Time("4n"); // a quarter note
+ * @category Unit
+ */
+export class TimeClass<Type extends Seconds | Ticks = Seconds, Unit extends string = TimeBaseUnit>
+	extends TimeBaseClass<Type, Unit> {
+
+	readonly name: string = "TimeClass";
+
+	protected _getExpressions(): TimeExpression<Type> {
+		return Object.assign(super._getExpressions(), {
+			now: {
+				method: (capture: string): Type => {
+					return this._now() + new (this.constructor as typeof TimeClass)(this.context, capture).valueOf() as Type;
+				},
+				regexp: /^\+(.+)/,
+			},
+			quantize: {
+				method: (capture: string): Type => {
+					const quantTo = new TimeClass(this.context, capture).valueOf();
+					return this._secondsToUnits(this.context.transport.nextSubdivision(quantTo));
+				},
+				regexp: /^@(.+)/,
+			},
+		});
+	}
+
+	/**
+	 * Quantize the time by the given subdivision. Optionally add a
+	 * percentage which will move the time value towards the ideal
+	 * quantized value by that percentage.
+	 * @param  subdiv    The subdivision to quantize to
+	 * @param  percent  Move the time value towards the quantized value by a percentage.
+	 * @example
+	 * Tone.Time(21).quantize(2); // returns 22
+	 * Tone.Time(0.6).quantize("4n", 0.5); // returns 0.55
+	 */
+	quantize(subdiv: Time, percent = 1): Type {
+		const subdivision = new (this.constructor as typeof TimeClass)(this.context, subdiv).valueOf();
+		const value = this.valueOf();
+		const multiple = Math.round(value / subdivision);
+		const ideal = multiple * subdivision;
+		const diff = ideal - value;
+		return value + diff * percent as Type;
+	}
+
+	//-------------------------------------
+	// CONVERSIONS
+	//-------------------------------------
+	/**
+	 * Convert a Time to Notation. The notation values are will be the
+	 * closest representation between 1m to 128th note.
+	 * @return {Notation}
+	 * @example
+	 * // if the Transport is at 120bpm:
+	 * Tone.Time(2).toNotation(); // returns "1m"
+	 */
+	toNotation(): Subdivision {
+		const time = this.toSeconds();
+		const testNotations: Subdivision[] = ["1m"];
+		for (let power = 1; power < 9; power++) {
+			const subdiv = Math.pow(2, power);
+			testNotations.push(subdiv + "n." as Subdivision);
+			testNotations.push(subdiv + "n" as Subdivision);
+			testNotations.push(subdiv + "t" as Subdivision);
+		}
+		testNotations.push("0");
+		// find the closets notation representation
+		let closest = testNotations[0];
+		let closestSeconds = new TimeClass(this.context, testNotations[0]).toSeconds();
+		testNotations.forEach(notation => {
+			const notationSeconds = new TimeClass(this.context, notation).toSeconds();
+			if (Math.abs(notationSeconds - time) < Math.abs(closestSeconds - time)) {
+				closest = notation;
+				closestSeconds = notationSeconds;
+			}
+		});
+		return closest;
+	}
+
+	/**
+	 * Return the time encoded as Bars:Beats:Sixteenths.
+	 */
+	toBarsBeatsSixteenths(): BarsBeatsSixteenths {
+		const quarterTime = this._beatsToUnits(1);
+		let quarters = this.valueOf() / quarterTime;
+		quarters = parseFloat(quarters.toFixed(4));
+		const measures = Math.floor(quarters / this._getTimeSignature());
+		let sixteenths = (quarters % 1) * 4;
+		quarters = Math.floor(quarters) % this._getTimeSignature();
+		const sixteenthString = sixteenths.toString();
+		if (sixteenthString.length > 3) {
+			// the additional parseFloat removes insignificant trailing zeroes
+			sixteenths = parseFloat(parseFloat(sixteenthString).toFixed(3));
+		}
+		const progress = [measures, quarters, sixteenths];
+		return progress.join(":");
+	}
+
+	/**
+	 * Return the time in ticks.
+	 */
+	toTicks(): Ticks {
+		const quarterTime = this._beatsToUnits(1);
+		const quarters = this.valueOf() / quarterTime;
+		return quarters * this._getPPQ();
+	}
+
+	/**
+	 * Return the time in seconds.
+	 */
+	toSeconds(): Seconds {
+		return this.valueOf();
+	}
+
+	/**
+	 * Return the value as a midi note.
+	 */
+	toMidi(): MidiNote {
+		return ftom(this.toFrequency());
+	}
+
+	protected _now(): Type {
+		return this.context.now() as Type;
+	}
+}
+
+/**
+ * Create a TimeClass from a time string or number. The time is computed against the 
+ * global Tone.Context. To use a specific context, use [[TimeClass]]
+ * @param value A value which represents time
+ * @param units The value's units if they can't be inferred by the value.
+ * @category Unit
+ * @example
+ * const time = Tone.Time("4n").toSeconds();
+ * console.log(time);
+ * @example
+ * const note = Tone.Time(1).toNotation();
+ * console.log(note);
+ * @example
+ * const freq = Tone.Time(0.5).toFrequency();
+ * console.log(freq);
+ */
+export function Time(value?: TimeValue, units?: TimeBaseUnit): TimeClass<Seconds> {
+	return new TimeClass(getContext(), value, units);
+}

package/Tone/core/type/TimeBase.ts

@@ -0,0 +1,324 @@
+import { BaseContext } from "../context/BaseContext";
+import { Tone } from "../Tone";
+import { isDefined, isObject, isString, isUndef } from "../util/TypeCheck";
+import { BPM, Hertz, MidiNote, Milliseconds, Samples, Seconds, Ticks, Time } from "./Units";
+
+export type TimeValue = Time | TimeBaseClass<any, any>;
+
+/**
+ * The units that the TimeBase can accept. extended by other classes
+ */
+export type TimeBaseUnit = "s" | "n" | "t" | "m" | "i" | "hz" | "tr" | "samples" | "number";
+
+export interface TypeFunction {
+	regexp: RegExp;
+	method: (value: string, ...args: string[]) => number;
+}
+
+export interface TimeExpression<Type extends number> {
+	[key: string]: {
+		regexp: RegExp;
+		method: (value: string, ...args: string[]) => Type;
+	};
+}
+
+/**
+ * TimeBase is a flexible encoding of time which can be evaluated to and from a string.
+ */
+export abstract class TimeBaseClass<Type extends number, Unit extends string> extends Tone {
+
+	readonly context: BaseContext;
+
+	/**
+	 * The value of the units
+	 */
+	protected _val?: TimeValue;
+
+	/**
+	 * The units of time
+	 */
+	protected _units?: Unit;
+
+	/**
+	 * All of the conversion expressions
+	 */
+	protected _expressions: TimeExpression<Type>;
+
+	/**
+	 * The default units
+	 */
+	readonly defaultUnits: Unit = "s" as Unit;
+
+	/**
+	 * @param context The context associated with the time value. Used to compute
+	 * Transport and context-relative timing.
+	 * @param  value  The time value as a number, string or object
+	 * @param  units  Unit values
+	 */
+	constructor(context: BaseContext, value?: TimeValue, units?: Unit) {
+		super();
+
+		this._val = value;
+		this._units = units;
+		this.context = context;
+		this._expressions = this._getExpressions();
+	}
+
+	/**
+	 * All of the time encoding expressions
+	 */
+	protected _getExpressions(): TimeExpression<Type> {
+		return {
+			hz: {
+				method: (value) => {
+					return this._frequencyToUnits(parseFloat(value));
+				},
+				regexp: /^(\d+(?:\.\d+)?)hz$/i,
+			},
+			i: {
+				method: (value) => {
+					return this._ticksToUnits(parseInt(value, 10));
+				},
+				regexp: /^(\d+)i$/i,
+			},
+			m: {
+				method: (value) => {
+					return this._beatsToUnits(parseInt(value, 10) * this._getTimeSignature());
+				},
+				regexp: /^(\d+)m$/i,
+			},
+			n: {
+				method: (value, dot) => {
+					const numericValue = parseInt(value, 10);
+					const scalar = dot === "." ? 1.5 : 1;
+					if (numericValue === 1) {
+						return this._beatsToUnits(this._getTimeSignature()) * scalar as Type;
+					} else {
+						return this._beatsToUnits(4 / numericValue) * scalar as Type;
+					}
+				},
+				regexp: /^(\d+)n(\.?)$/i,
+			},
+			number: {
+				method: (value) => {
+					return this._expressions[this.defaultUnits].method.call(this, value);
+				},
+				regexp: /^(\d+(?:\.\d+)?)$/,
+			},
+			s: {
+				method: (value): Type => {
+					return this._secondsToUnits(parseFloat(value));
+				},
+				regexp: /^(\d+(?:\.\d+)?)s$/,
+			},
+			samples: {
+				method: (value) => {
+					return parseInt(value, 10) / this.context.sampleRate as Type;
+				},
+				regexp: /^(\d+)samples$/,
+			},
+			t: {
+				method: (value) => {
+					const numericValue = parseInt(value, 10);
+					return this._beatsToUnits(8 / (Math.floor(numericValue) * 3));
+				},
+				regexp: /^(\d+)t$/i,
+			},
+			tr: {
+				method: (m, q, s) => {
+					let total = 0;
+					if (m && m !== "0") {
+						total += this._beatsToUnits(this._getTimeSignature() * parseFloat(m));
+					}
+					if (q && q !== "0") {
+						total += this._beatsToUnits(parseFloat(q));
+					}
+					if (s && s !== "0") {
+						total += this._beatsToUnits(parseFloat(s) / 4);
+					}
+					return total as Type;
+				},
+				regexp: /^(\d+(?:\.\d+)?):(\d+(?:\.\d+)?):?(\d+(?:\.\d+)?)?$/,
+			},
+		};
+	}
+
+	//-------------------------------------
+	// 	VALUE OF
+	//-------------------------------------
+
+	/**
+	 * Evaluate the time value. Returns the time in seconds.
+	 */
+	valueOf(): Type {
+		if (this._val instanceof TimeBaseClass) {
+			this.fromType(this._val);
+		}
+		if (isUndef(this._val)) {
+			return this._noArg();
+		} else if (isString(this._val) && isUndef(this._units)) {
+			for (const units in this._expressions) {
+				if (this._expressions[units].regexp.test(this._val.trim())) {
+					this._units = units as Unit;
+					break;
+				}
+			}
+		} else if (isObject(this._val)) {
+			let total = 0;
+			for (const typeName in this._val) {
+				if (isDefined(this._val[typeName])) {
+					const quantity = this._val[typeName];
+					// @ts-ignore
+					const time = (new this.constructor(this.context, typeName)).valueOf() * quantity;
+					total += time;
+				}
+			}
+			return total as Type;
+		}
+		if (isDefined(this._units)) {
+			const expr = this._expressions[this._units];
+			const matching = this._val.toString().trim().match(expr.regexp);
+			if (matching) {
+				return expr.method.apply(this, matching.slice(1));
+			} else {
+				return expr.method.call(this, this._val);
+			}
+		} else if (isString(this._val)) {
+			return parseFloat(this._val) as Type;
+		} else {
+			return this._val as Type;
+		}
+	}
+
+	//-------------------------------------
+	// 	UNIT CONVERSIONS
+	//-------------------------------------
+
+	/**
+	 * Returns the value of a frequency in the current units
+	 */
+	protected _frequencyToUnits(freq: Hertz): Type {
+		return 1 / freq as Type;
+	}
+
+	/**
+	 * Return the value of the beats in the current units
+	 */
+	protected _beatsToUnits(beats: number): Type {
+		return (60 / this._getBpm()) * beats as Type;
+	}
+
+	/**
+	 * Returns the value of a second in the current units
+	 */
+	protected _secondsToUnits(seconds: Seconds): Type {
+		return seconds as Type;
+	}
+
+	/**
+	 * Returns the value of a tick in the current time units
+	 */
+	protected _ticksToUnits(ticks: Ticks): Type {
+		return (ticks * (this._beatsToUnits(1)) / this._getPPQ()) as Type;
+	}
+
+	/**
+	 * With no arguments, return 'now'
+	 */
+	protected _noArg(): Type {
+		return this._now();
+	}
+
+	//-------------------------------------
+	// 	TEMPO CONVERSIONS
+	//-------------------------------------
+
+	/**
+	 * Return the bpm
+	 */
+	protected _getBpm(): BPM {
+		return this.context.transport.bpm.value;
+	}
+
+	/**
+	 * Return the timeSignature
+	 */
+	protected _getTimeSignature(): number {
+		return this.context.transport.timeSignature as number;
+	}
+
+	/**
+	 * Return the PPQ or 192 if Transport is not available
+	 */
+	protected _getPPQ(): number {
+		return this.context.transport.PPQ;
+	}
+
+	/**
+	 * Return the current time in whichever context is relevant
+	 */
+	protected abstract _now(): Type;
+
+	//-------------------------------------
+	// 	CONVERSION INTERFACE
+	//-------------------------------------
+
+	/**
+	 * Coerce a time type into this units type.
+	 * @param type Any time type units
+	 */
+	fromType(type: TimeBaseClass<any, any>): this {
+		this._units = undefined;
+		switch (this.defaultUnits) {
+			case "s":
+				this._val = type.toSeconds();
+				break;
+			case "i":
+				this._val = type.toTicks();
+				break;
+			case "hz":
+				this._val = type.toFrequency();
+				break;
+			case "midi":
+				this._val = type.toMidi();
+				break;
+		}
+		return this;
+	}
+
+	/**
+	 * Return the value in seconds
+	 */
+	abstract toSeconds(): Seconds;
+
+	/**
+	 * Return the value as a Midi note
+	 */
+	abstract toMidi(): MidiNote;
+
+	/**
+	 * Convert the value into ticks
+	 */
+	abstract toTicks(): Ticks;
+
+	/**
+	 * Return the value in hertz
+	 */
+	toFrequency(): Hertz {
+		return 1 / this.toSeconds();
+	}
+
+	/**
+	 * Return the time in samples
+	 */
+	toSamples(): Samples {
+		return this.toSeconds() * this.context.sampleRate;
+	}
+
+	/**
+	 * Return the time in milliseconds.
+	 */
+	toMilliseconds(): Milliseconds {
+		return this.toSeconds() * 1000;
+	}
+}

package/Tone/core/type/TransportTime.test.ts

@@ -0,0 +1,184 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { atTime, Offline } from "test/helper/Offline";
+import { getContext } from "../Global";
+import { Frequency } from "./Frequency";
+import { Ticks } from "./Ticks";
+import { Time } from "./Time";
+import { TransportTime, TransportTimeClass } from "./TransportTime";
+
+describe("TransportTimeClass", () => {
+
+	BasicTests(TransportTime);
+
+	context("Constructor", () => {
+
+		it("can be made with or without 'new'", () => {
+			const t0 = TransportTime();
+			expect(t0).to.be.instanceOf(TransportTimeClass);
+			t0.dispose();
+			const t1 = new TransportTimeClass(getContext());
+			expect(t1).to.be.instanceOf(TransportTimeClass);
+			t1.dispose();
+		});
+
+		it("can pass in a number in the constructor", () => {
+			return Offline(() => {
+				const time = TransportTime(1);
+				expect(time).to.be.instanceOf(TransportTimeClass);
+				expect(time.valueOf()).to.equal(1);
+				time.dispose();
+			});
+		});
+
+		it("can pass in a string in the constructor", () => {
+			return Offline((context) => {
+				const time = TransportTime("1");
+				expect(time).to.be.instanceOf(TransportTimeClass);
+				expect(time.valueOf()).to.equal(1);
+				time.dispose();
+			});
+		});
+
+		it("can pass in a value and a type", () => {
+			return Offline((context) => {
+				expect(TransportTime(4, "m").valueOf()).to.equal(8);
+			});
+		});
+
+		it("with no arguments evaluates to 0 when the transport is stopped", () => {
+			return Offline(() => {
+				expect(TransportTime().valueOf()).to.equal(0);
+			});
+		});
+
+		it("with no arguments evaluates to the current ticks when the transport is started", () => {
+			return Offline((context) => {
+				const transport = context.transport;
+				transport.start();
+				return atTime(0.29, () => {
+					expect(new TransportTimeClass(context).valueOf()).to.equal(transport.seconds);
+					transport.stop();
+				});
+			}, 0.3);
+		});
+
+		it("is evaluated in equations and comparisons using valueOf", () => {
+			// @ts-ignore
+			expect(TransportTime("1") + 1).to.equal(2);
+			// @ts-ignore
+			expect(TransportTime("1") + TransportTime("1")).to.equal(2);
+			expect(TransportTime("1") > TransportTime(0)).to.be.true;
+			expect(+TransportTime("1")).to.equal(1);
+		});
+
+		it("can convert from Time", () => {
+			expect(TransportTime(Time(2)).valueOf()).to.equal(2);
+			expect(TransportTime(Time("4n")).valueOf()).to.equal(0.5);
+		});
+
+		it("can convert from Frequency", () => {
+			expect(TransportTime(Frequency(2)).valueOf()).to.equal(0.5);
+			expect(TransportTime(Frequency("4n")).valueOf()).to.equal(0.5);
+		});
+
+		it("can convert from TransportTime", () => {
+			expect(TransportTime(TransportTime(2)).valueOf()).to.equal(2);
+			expect(TransportTime(TransportTime("4n")).valueOf()).to.equal(0.5);
+		});
+
+		it("can convert from Ticks", () => {
+			return Offline((context) => {
+				const transport = context.transport;
+				expect(TransportTime(Ticks(transport.PPQ)).valueOf()).to.equal(0.5);
+				expect(TransportTime(Ticks("4n")).valueOf()).to.equal(0.5);
+			});
+		});
+
+		it("can convert from an Object", () => {
+			return Offline(() => {
+				expect(TransportTime({ "4n": 2 }).valueOf()).to.equal(1);
+				expect(TransportTime({ "1n": 1, "8t": 2 }).valueOf()).to.be.closeTo(2.333, 0.01);
+			});
+		});
+	});
+
+	context("Quantizes values", () => {
+
+		it("can quantize values", () => {
+			return Offline((context) => {
+				expect(TransportTime("4t").quantize("4n").valueOf()).to.be.closeTo(0.5, 0.01);
+			});
+		});
+
+		it("can get the next subdivison when the transport is started", () => {
+			return Offline((context) => {
+				const transport = context.transport;
+				transport.start();
+				return atTime(0.59, () => {
+					expect(new TransportTimeClass(context, "@1m").valueOf()).to.be.closeTo(2, 0.01);
+					expect(new TransportTimeClass(context, "@4n").valueOf()).to.be.closeTo(1, 0.01);
+				});
+			}, 0.6);
+		});
+	});
+
+	context("Operators", () => {
+
+		it("can add the current time", () => {
+			return Offline((context) => {
+				const transport = context.transport;
+				transport.start();
+				return atTime(0.59, () => {
+					const now = transport.seconds;
+					const quarterNote = 60 / transport.bpm.value;
+					expect(new TransportTimeClass(context, "+4i").valueOf()).to.be.closeTo(4 / transport.PPQ + now, 0.1);
+					expect(new TransportTimeClass(context, "+2n").valueOf()).to.be.closeTo(quarterNote * 2 + now, 0.1);
+					transport.stop();
+				});
+			}, 0.6);
+		});
+
+	});
+
+	context("Conversions", () => {
+
+		it("converts time into notation", () => {
+			return Offline((context) => {
+				const transport = context.transport;
+				transport.bpm.value = 120;
+				transport.timeSignature = 4;
+				expect(TransportTime("4n").toNotation()).to.equal("4n");
+				expect(TransportTime(1.5).toNotation()).to.equal("2n.");
+				expect(TransportTime(0).toNotation()).to.equal("0");
+				expect(TransportTime("1:0:0").toNotation()).to.equal("1m");
+			});
+		});
+
+		it("converts time into samples", () => {
+			return Offline((context) => {
+				expect(TransportTime(2).toSamples()).to.equal(2 * context.sampleRate);
+			});
+		});
+
+		it("converts time into frequency", () => {
+			return Offline(() => {
+				expect(TransportTime(2).toFrequency()).to.equal(0.5);
+			});
+		});
+
+		it("converts time into seconds", () => {
+			return Offline(() => {
+				expect(TransportTime("2n").toSeconds()).to.equal(1);
+			});
+		});
+
+		it("converts time into BarsBeatsSixteenths", () => {
+			return Offline(() => {
+				expect(TransportTime("3:1:3").toBarsBeatsSixteenths()).to.equal("3:1:3");
+				expect(TransportTime(2).toBarsBeatsSixteenths()).to.equal("1:0:0");
+			});
+		});
+
+	});
+});

package/Tone/core/type/TransportTime.ts

@@ -0,0 +1,34 @@
+import { getContext } from "../Global";
+import { Seconds, Ticks } from "../type/Units";
+import { TimeClass } from "./Time";
+import { TimeBaseUnit, TimeValue } from "./TimeBase";
+
+/**
+ * TransportTime is a the time along the Transport's
+ * timeline. It is similar to Tone.Time, but instead of evaluating
+ * against the AudioContext's clock, it is evaluated against
+ * the Transport's position. See [TransportTime wiki](https://github.com/Tonejs/Tone.js/wiki/TransportTime).
+ * @category Unit
+ */
+export class TransportTimeClass<Type extends Seconds | Ticks = Seconds> extends TimeClass<Type> {
+
+	readonly name: string = "TransportTime";
+
+	/**
+	 * Return the current time in whichever context is relevant
+	 */
+	protected _now(): Type {
+		return this.context.transport.seconds as Type;
+	}
+}
+
+/**
+ * TransportTime is a the time along the Transport's
+ * timeline. It is similar to [[Time]], but instead of evaluating
+ * against the AudioContext's clock, it is evaluated against
+ * the Transport's position. See [TransportTime wiki](https://github.com/Tonejs/Tone.js/wiki/TransportTime).
+ * @category Unit
+ */
+export function TransportTime(value?: TimeValue, units?: TimeBaseUnit): TransportTimeClass {
+	return new TransportTimeClass(getContext(), value, units);
+}