tone 15.5.1 → 15.5.3

package/Tone/core/context/OnRunning.test.ts

@@ -0,0 +1,63 @@
+import { expect } from "chai";
+
+import { Context } from "./Context.js";
+import { OfflineContext } from "./OfflineContext.js";
+import { onContextRunning } from "./OnRunning.js";
+
+context("onContextRunning", () => {
+	it("callback is invoked immediately when offline context is used", () => {
+		const ctx = new OfflineContext(1, 0.1, 44100);
+		let wasInvoked = false;
+
+		onContextRunning(ctx, () => {
+			wasInvoked = true;
+		});
+
+		expect(wasInvoked).to.be.true;
+		ctx.dispose();
+	});
+
+	it("callback is invoked immediately when context is already running", async () => {
+		const ctx = new Context();
+		await ctx.resume();
+		let wasInvoked = false;
+
+		onContextRunning(ctx, () => {
+			wasInvoked = true;
+		});
+
+		expect(wasInvoked).to.be.true;
+		ctx.dispose();
+	});
+
+	it("callback is invoked when the context starts running", async () => {
+		const ctx = new Context();
+		let wasInvoked = false;
+
+		onContextRunning(ctx, () => {
+			wasInvoked = true;
+		});
+
+		expect(wasInvoked).to.be.false;
+
+		await ctx.resume();
+		expect(wasInvoked).to.be.true;
+
+		ctx.dispose();
+	});
+
+	it("can remove the callback with the returned function", async () => {
+		const ctx = new Context();
+		let wasInvoked = false;
+		const remove = onContextRunning(ctx, () => {
+			wasInvoked = true;
+		});
+		expect(wasInvoked).to.be.false;
+		remove();
+
+		await ctx.resume();
+
+		expect(wasInvoked).to.be.false;
+		ctx.dispose();
+	});
+});

package/Tone/core/context/OnRunning.ts

@@ -0,0 +1,26 @@
+import { BaseContext } from "./BaseContext.js";
+
+/**
+ * Invoked when the context is started. The callback is invoked immediately
+ * if the context is already started or when the context is an OfflineContext.
+ * Returns a function which can be called to remove the listener.
+ * @internal Used to trigger certain events when the context has been started.
+ */
+export function onContextRunning(
+	context: BaseContext,
+	callback: () => void
+): () => void {
+	const listener = (state: AudioContextState) => {
+		if (state === "running") {
+			callback();
+			context.off("statechange", listener);
+		}
+	};
+	if (context.isOffline || context.state === "running") {
+		callback();
+		return () => {};
+	}
+
+	context.on("statechange", listener);
+	return () => context.off("statechange", listener);
+}

package/Tone/core/context/ToneWithContext.test.ts

@@ -0,0 +1,82 @@
+import { expect } from "chai";
+
+import { Offline } from "../../../test/helper/Offline.js";
+import { getContext } from "../Global.js";
+import { Gain } from "./Gain.js";
+import { ToneWithContext } from "./ToneWithContext.js";
+
+describe("ToneWithContext", () => {
+	context("get", () => {
+		it("returns an object with all the default properties", () => {
+			const gain = new Gain();
+			const values = gain.get();
+			expect(values).to.be.an("object");
+			expect(values).to.have.property("gain");
+			gain.dispose();
+		});
+
+		it("reflects the current value of properties", () => {
+			const gain = new Gain(0.3);
+			const values = gain.get();
+			expect(values.gain).to.be.closeTo(0.3, 0.001);
+			gain.dispose();
+		});
+	});
+
+	context("set", () => {
+		it("sets properties with an object", () => {
+			const gain = new Gain();
+			gain.set({ gain: 0.5 });
+			expect(gain.gain.value).to.be.closeTo(0.5, 0.001);
+			gain.dispose();
+		});
+
+		it("returns the instance for chaining", () => {
+			const gain = new Gain();
+			const returned = gain.set({ gain: 0.5 });
+			expect(returned).to.equal(gain);
+			gain.dispose();
+		});
+
+		it("does not set a value if it is the same", () => {
+			const gain = new Gain(0.7);
+			gain.set({ gain: 0.7 });
+			expect(gain.gain.value).to.be.closeTo(0.7, 0.001);
+			gain.dispose();
+		});
+	});
+
+	context("getDefaults", () => {
+		it("returns defaults with a context", () => {
+			const defaults = ToneWithContext.getDefaults();
+			expect(defaults).to.have.property("context");
+			expect(defaults.context).to.equal(getContext());
+		});
+	});
+
+	context("_onContextRunning", () => {
+		it("invokes the callback immediately for an offline context", () => {
+			return Offline(() => {
+				let callbackInvoked = false;
+				const gain = new Gain();
+				// Access protected method via subclass trick
+				(gain as any)._onContextRunning(() => {
+					callbackInvoked = true;
+				});
+				expect(callbackInvoked).to.equal(true);
+				gain.dispose();
+			});
+		});
+
+		it("cleans up the listener on dispose", () => {
+			return Offline(() => {
+				const gain = new Gain();
+				(gain as any)._onContextRunning(() => {
+					// no-op
+				});
+				// Should not throw when disposing
+				gain.dispose();
+			});
+		});
+	});
+});

package/Tone/core/context/ToneWithContext.ts

@@ -19,6 +19,7 @@ import {
 	isUndef,
 } from "../util/TypeCheck.js";
 import { BaseContext } from "./BaseContext.js";
+import { onContextRunning } from "./OnRunning.js";
 
 /**
  * A unit which process audio
@@ -232,4 +233,27 @@ export abstract class ToneWithContext<
 		});
 		return this;
 	}
+
+	/**
+	 * Internal method which removes the onContextRunning callback.
+	 */
+	private _removeOnContextRunning?: () => void;
+
+	/**
+	 * Internal method which is called the first time the context is resumed.
+	 * Useful for setting up AudioNodes which should be running as soon
+	 * as the context is running, but should not be started until then.
+	 */
+	protected _onContextRunning(callback: () => void): void {
+		this._removeOnContextRunning = onContextRunning(this.context, callback);
+	}
+
+	/**
+	 * Dispose and disconnect
+	 */
+	dispose(): this {
+		super.dispose();
+		this._removeOnContextRunning?.();
+		return this;
+	}
 }

package/Tone/core/util/Interface.ts

@@ -6,7 +6,10 @@ export type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
 /**
  * Make the property not writable using `defineProperty`. Internal use only.
  */
-export function readOnly(target: object, property: string | string[]): void {
+export function readOnly<T extends object>(
+	target: T,
+	property: keyof T | (keyof T)[]
+): void {
 	if (isArray(property)) {
 		property.forEach((str) => readOnly(target, str));
 	} else {
@@ -20,7 +23,10 @@ export function readOnly(target: object, property: string | string[]): void {
 /**
  * Make an attribute writeable. Internal use only.
  */
-export function writable(target: object, property: string | string[]): void {
+export function writable<T extends object>(
+	target: T,
+	property: keyof T | (keyof T)[]
+): void {
 	if (isArray(property)) {
 		property.forEach((str) => writable(target, str));
 	} else {

package/Tone/core/util/TypeCheck.ts

@@ -3,7 +3,7 @@ import { Note } from "../type/Units.js";
 /**
  * Test if the arg is undefined
  */
-export function isUndef(arg: any): arg is undefined {
+export function isUndef(arg: unknown): arg is undefined {
 	return arg === undefined;
 }
 
@@ -17,45 +17,45 @@ export function isDefined<T>(arg: T | undefined): arg is T {
 /**
  * Test if the arg is a function
  */
-export function isFunction(arg: any): arg is (a: any) => any {
+export function isFunction(arg: unknown): arg is (a: any) => any {
 	return typeof arg === "function";
 }
 
 /**
  * Test if the argument is a number.
  */
-export function isNumber(arg: any): arg is number {
+export function isNumber(arg: unknown): 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 {
+export function isObject(arg: unknown): arg is object {
 	return (
 		Object.prototype.toString.call(arg) === "[object Object]" &&
-		arg.constructor === Object
+		(arg as object).constructor === Object
 	);
 }
 
 /**
  * Test if the argument is a boolean.
  */
-export function isBoolean(arg: any): arg is boolean {
+export function isBoolean(arg: unknown): arg is boolean {
 	return typeof arg === "boolean";
 }
 
 /**
  * Test if the argument is an Array
  */
-export function isArray(arg: any): arg is any[] {
+export function isArray(arg: unknown): arg is any[] {
 	return Array.isArray(arg);
 }
 
 /**
  * Test if the argument is a string.
  */
-export function isString(arg: any): arg is string {
+export function isString(arg: unknown): arg is string {
 	return typeof arg === "string";
 }
 
@@ -63,6 +63,6 @@ export function isString(arg: any): arg is 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 {
+export function isNote(arg: unknown): arg is Note {
 	return isString(arg) && /^([a-g]{1}(?:b|#|x|bb)?)(-?[0-9]+)/i.test(arg);
 }

package/Tone/effect/FrequencyShifter.ts

@@ -131,9 +131,11 @@ export class FrequencyShifter extends Effect<FrequencyShifterOptions> {
 		this._add.connect(this.effectReturn);
 
 		// start the oscillators at the same time
-		const now = this.immediate();
-		this._sine.start(now);
-		this._cosine.start(now);
+		this._onContextRunning(() => {
+			const now = this.immediate();
+			this._sine.start(now);
+			this._cosine.start(now);
+		});
 	}
 
 	static getDefaults(): FrequencyShifterOptions {

package/Tone/effect/LFOStereoEffect.test.ts

@@ -0,0 +1,85 @@
+import { expect } from "chai";
+
+import { BasicTests } from "../../test/helper/Basic.js";
+import { Offline } from "../../test/helper/Offline.js";
+import { LFOStereoEffect, LFOStereoEffectOptions } from "./LFOStereoEffect.js";
+
+describe("LFOStereoEffect", () => {
+	class LFOStereoEffectTest extends LFOStereoEffect<LFOStereoEffectOptions> {
+		getLfoState() {
+			return this._lfoL.state;
+		}
+	}
+
+	BasicTests(LFOStereoEffectTest);
+
+	context("API", () => {
+		it("can pass in options in the constructor", () => {
+			const stereoEffect = new LFOStereoEffectTest({
+				frequency: 0.2,
+			});
+			expect(stereoEffect.frequency.value).to.be.closeTo(0.2, 0.01);
+			stereoEffect.dispose();
+		});
+
+		it("can be started and stopped", () => {
+			const stereoEffect = new LFOStereoEffectTest();
+			stereoEffect.start().stop("+0.2");
+			stereoEffect.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const stereoEffect = new LFOStereoEffectTest();
+			stereoEffect.set({
+				frequency: 2.4,
+			});
+			expect(stereoEffect.get().frequency).to.be.closeTo(2.4, 0.01);
+			stereoEffect.dispose();
+		});
+
+		it("can set the frequency and depth", () => {
+			const stereoEffect = new LFOStereoEffectTest();
+			stereoEffect.frequency.value = 0.4;
+			expect(stereoEffect.frequency.value).to.be.closeTo(0.4, 0.01);
+			stereoEffect.dispose();
+		});
+
+		it("can sync the frequency to the transport", async () => {
+			const buffer = await Offline(({ transport }) => {
+				const stereoEffect = new LFOStereoEffectTest({
+					frequency: 2,
+				});
+				stereoEffect.sync();
+				stereoEffect.frequency.toDestination();
+				transport.bpm.setValueAtTime(transport.bpm.value * 2, 0.05);
+			}, 0.1);
+			expect(buffer.getValueAtTime(0)).to.be.closeTo(2, 0.1);
+			expect(buffer.getValueAtTime(0.05)).to.be.closeTo(4, 0.1);
+		});
+
+		it("can unsync the frequency to the transport", async () => {
+			const buffer = await Offline(({ transport }) => {
+				const stereoEffect = new LFOStereoEffectTest({
+					frequency: 2,
+				});
+				stereoEffect.sync();
+				stereoEffect.frequency.toDestination();
+				transport.bpm.setValueAtTime(transport.bpm.value * 2, 0.05);
+				stereoEffect.unsync();
+			}, 0.1);
+			expect(buffer.getValueAtTime(0)).to.be.closeTo(2, 0.1);
+			expect(buffer.getValueAtTime(0.05)).to.be.closeTo(2, 0.1);
+		});
+
+		it("autostart the LFO", () => {
+			const stereoEffect = new LFOStereoEffectTest({
+				frequency: 0.2,
+				autostart: true,
+			});
+			expect(stereoEffect.frequency.value).to.be.closeTo(0.2, 0.01);
+
+			expect(stereoEffect.getLfoState()).to.equal("started");
+			stereoEffect.dispose();
+		});
+	});
+});

package/Tone/effect/LFOStereoEffect.ts

@@ -0,0 +1,136 @@
+import { Frequency, Time } from "../core/type/Units.js";
+import { optionsFromArguments } from "../core/util/Defaults.js";
+import { readOnly } from "../core/util/Interface.js";
+import { Signal } from "../signal/Signal.js";
+import { LFO } from "../source/oscillator/LFO.js";
+import { ToneOscillatorType } from "../source/oscillator/OscillatorInterface.js";
+import { StereoEffect, StereoEffectOptions } from "./StereoEffect.js";
+
+export interface LFOStereoEffectOptions extends StereoEffectOptions {
+	frequency: Frequency;
+	autostart: boolean;
+}
+
+/**
+ * Base class for stereo effects which modulate the incoming signal with an LFO.
+ *
+ * @category Effect
+ */
+export abstract class LFOStereoEffect<
+	Options extends LFOStereoEffectOptions,
+> extends StereoEffect<Options> {
+	readonly name: string = "LFOStereoEffect";
+
+	/**
+	 * The LFO in the left channel
+	 */
+	protected _lfoL: LFO;
+
+	/**
+	 * The LFO in the right channel
+	 */
+	protected _lfoR: LFO;
+
+	/**
+	 * The frequency of the tremolo.
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	constructor(options?: Partial<LFOStereoEffectOptions>);
+	constructor() {
+		const options = optionsFromArguments(
+			LFOStereoEffect.getDefaults(),
+			arguments
+		);
+		super(options);
+
+		this._lfoL = new LFO({
+			context: this.context,
+			min: 0,
+			max: 1,
+		});
+		this._lfoR = new LFO({
+			context: this.context,
+			min: 0,
+			max: 1,
+		});
+
+		// control the frequency with a single signal
+		this.frequency = new Signal({
+			context: this.context,
+			value: options.frequency,
+			units: "frequency",
+		});
+		this.frequency.fan(this._lfoL.frequency, this._lfoR.frequency);
+
+		readOnly(this, ["frequency"]);
+
+		if (options.autostart) {
+			this._onContextRunning(() => this.start(this.immediate()));
+		}
+	}
+
+	static getDefaults(): LFOStereoEffectOptions {
+		return Object.assign(StereoEffect.getDefaults(), {
+			frequency: 10,
+			autostart: false,
+		});
+	}
+
+	/**
+	 * Start the tremolo.
+	 */
+	start(time?: Time): this {
+		this._lfoL.start(time);
+		this._lfoR.start(time);
+		return this;
+	}
+
+	/**
+	 * Stop the tremolo.
+	 */
+	stop(time?: Time): this {
+		this._lfoL.stop(time);
+		this._lfoR.stop(time);
+		return this;
+	}
+
+	/**
+	 * Sync the effect to the transport.
+	 */
+	sync(): this {
+		this._lfoL.sync();
+		this._lfoR.sync();
+		this.context.transport.syncSignal(this.frequency);
+		return this;
+	}
+
+	/**
+	 * Unsync the filter from the transport
+	 */
+	unsync(): this {
+		this._lfoL.unsync();
+		this._lfoR.unsync();
+		this.context.transport.unsyncSignal(this.frequency);
+		return this;
+	}
+
+	/**
+	 * The oscillator type.
+	 */
+	get type(): ToneOscillatorType {
+		return this._lfoL.type;
+	}
+	set type(type) {
+		this._lfoL.type = type;
+		this._lfoR.type = type;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._lfoL.dispose();
+		this._lfoR.dispose();
+		this.frequency.dispose();
+		return this;
+	}
+}

package/Tone/effect/Phaser.ts

@@ -3,10 +3,9 @@ import { optionsFromArguments } from "../core/util/Defaults.js";
 import { readOnly } from "../core/util/Interface.js";
 import { Signal } from "../signal/Signal.js";
 import { LFO } from "../source/oscillator/LFO.js";
-import { StereoEffect, StereoEffectOptions } from "./StereoEffect.js";
+import { LFOStereoEffect, LFOStereoEffectOptions } from "./LFOStereoEffect.js";
 
-export interface PhaserOptions extends StereoEffectOptions {
-	frequency: Frequency;
+export interface PhaserOptions extends LFOStereoEffectOptions {
 	octaves: Positive;
 	stages: Positive;
 	Q: Positive;
@@ -28,19 +27,9 @@ export interface PhaserOptions extends StereoEffectOptions {
  * synth.triggerAttackRelease("E3", "2n");
  * @category Effect
  */
-export class Phaser extends StereoEffect<PhaserOptions> {
+export class Phaser extends LFOStereoEffect<PhaserOptions> {
 	readonly name: string = "Phaser";
 
-	/**
-	 * the lfo which controls the frequency on the left side
-	 */
-	private _lfoL: LFO;
-
-	/**
-	 * the lfo which controls the frequency on the right side
-	 */
-	private _lfoR: LFO;
-
 	/**
 	 * the base modulation frequency
 	 */
@@ -66,11 +55,6 @@ export class Phaser extends StereoEffect<PhaserOptions> {
 	 */
 	private _filtersR: BiquadFilterNode[];
 
-	/**
-	 * the frequency of the effect
-	 */
-	readonly frequency: Signal<"frequency">;
-
 	/**
 	 * @param frequency The speed of the phasing.
 	 * @param octaves The octaves of the effect.
@@ -90,19 +74,8 @@ export class Phaser extends StereoEffect<PhaserOptions> {
 		]);
 		super(options);
 
-		this._lfoL = new LFO({
-			context: this.context,
-			frequency: options.frequency,
-			min: 0,
-			max: 1,
-		});
-		this._lfoR = new LFO({
-			context: this.context,
-			frequency: options.frequency,
-			min: 0,
-			max: 1,
-			phase: 180,
-		});
+		this._lfoR.phase = 180;
+
 		this._baseFrequency = this.toFrequency(options.baseFrequency);
 		this._octaves = options.octaves;
 		this.Q = new Signal({
@@ -113,30 +86,24 @@ export class Phaser extends StereoEffect<PhaserOptions> {
 		this._filtersL = this._makeFilters(options.stages, this._lfoL);
 		this._filtersR = this._makeFilters(options.stages, this._lfoR);
 
-		this.frequency = this._lfoL.frequency;
-		this.frequency.value = options.frequency;
-
 		// connect them up
 		this.connectEffectLeft(...this._filtersL);
 		this.connectEffectRight(...this._filtersR);
-		// control the frequency with one LFO
-		this._lfoL.frequency.connect(this._lfoR.frequency);
+
 		// set the options
 		this.baseFrequency = options.baseFrequency;
 		this.octaves = options.octaves;
-		// start the lfo
-		this._lfoL.start();
-		this._lfoR.start();
-		readOnly(this, ["frequency", "Q"]);
+		readOnly(this, ["Q"]);
 	}
 
 	static getDefaults(): PhaserOptions {
-		return Object.assign(StereoEffect.getDefaults(), {
+		return Object.assign(LFOStereoEffect.getDefaults(), {
 			frequency: 0.5,
 			octaves: 3,
 			stages: 10,
 			Q: 10,
 			baseFrequency: 350,
+			autostart: true,
 		});
 	}
 
@@ -185,11 +152,8 @@ export class Phaser extends StereoEffect<PhaserOptions> {
 	dispose(): this {
 		super.dispose();
 		this.Q.dispose();
-		this._lfoL.dispose();
-		this._lfoR.dispose();
 		this._filtersL.forEach((f) => f.disconnect());
 		this._filtersR.forEach((f) => f.disconnect());
-		this.frequency.dispose();
 		return this;
 	}
 }

package/Tone/effect/PitchShift.ts

@@ -147,13 +147,16 @@ export class PitchShift extends FeedbackEffect<PitchShiftOptions> {
 		// route the input
 		this.effectSend.fan(this._delayA, this._delayB);
 		this._crossFade.chain(this._feedbackDelay, this.effectReturn);
-		// start the LFOs at the same time
-		const now = this.now();
-		this._lfoA.start(now);
-		this._lfoB.start(now);
-		this._crossFadeLFO.start(now);
 		// set the initial value
 		this.windowSize = this._windowSize;
+
+		// start the LFOs at the same time
+		this._onContextRunning(() => {
+			const now = this.immediate();
+			this._lfoA.start(now);
+			this._lfoB.start(now);
+			this._crossFadeLFO.start(now);
+		});
 	}
 
 	static getDefaults(): PitchShiftOptions {