tone 14.8.27

package/Tone/effect/StereoWidener.ts

@@ -0,0 +1,112 @@
+import { MidSideEffect, MidSideEffectOptions } from "../effect/MidSideEffect";
+import { Signal } from "../signal/Signal";
+import { Multiply } from "../signal/Multiply";
+import { Subtract } from "../signal/Subtract";
+import { NormalRange } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { readOnly } from "../core/util/Interface";
+import { connect } from "../core/context/ToneAudioNode";
+
+export interface StereoWidenerOptions extends MidSideEffectOptions {
+	width: NormalRange;
+}
+
+/**
+ * Applies a width factor to the mid/side seperation.
+ * 0 is all mid and 1 is all side.
+ * Algorithm found in [kvraudio forums](http://www.kvraudio.com/forum/viewtopic.php?t=212587).
+ * ```
+ * Mid *= 2*(1-width)<br>
+ * Side *= 2*width
+ * ```
+ * @category Effect
+ */
+export class StereoWidener extends MidSideEffect<StereoWidenerOptions> {
+
+	readonly name: string = "StereoWidener";
+
+	/**
+	 * The width control. 0 = 100% mid. 1 = 100% side. 0.5 = no change.
+	 */
+	readonly width: Signal<"normalRange">;
+	
+	/**
+	 * Two times the (1-width) for the mid channel
+	 */
+	private _twoTimesWidthMid: Multiply;
+	
+	/**
+	 * Two times the width for the side channel
+	 */
+	private _twoTimesWidthSide: Multiply;
+	
+	/**
+	 * Mid multiplier
+	 */
+	private _midMult: Multiply;
+	
+	/**
+	 * 1 - width
+	 */
+	private _oneMinusWidth: Subtract;
+	
+	/**
+	 * Side multiplier
+	 */
+	private _sideMult: Multiply;
+
+	/**
+	 * @param width The stereo width. A width of 0 is mono and 1 is stereo. 0.5 is no change.
+	 */
+	constructor(width?: NormalRange);
+	constructor(options?: Partial<StereoWidenerOptions>);
+	constructor() {
+
+		super(optionsFromArguments(StereoWidener.getDefaults(), arguments, ["width"]));
+		const options = optionsFromArguments(StereoWidener.getDefaults(), arguments, ["width"]);
+		this.width = new Signal({
+			context: this.context,
+			value: options.width,
+			units: "normalRange",
+		});
+		readOnly(this, ["width"]);
+		this._twoTimesWidthMid = new Multiply({
+			context: this.context,
+			value: 2,
+		});
+		this._twoTimesWidthSide = new Multiply({
+			context: this.context,
+			value: 2,
+		});
+		this._midMult = new Multiply({ context: this.context });
+		this._twoTimesWidthMid.connect(this._midMult.factor);
+		this.connectEffectMid(this._midMult);
+
+		this._oneMinusWidth = new Subtract({ context: this.context });
+		this._oneMinusWidth.connect(this._twoTimesWidthMid);
+		connect(this.context.getConstant(1), this._oneMinusWidth);
+		this.width.connect(this._oneMinusWidth.subtrahend);
+
+		this._sideMult = new Multiply({ context: this.context });
+		this.width.connect(this._twoTimesWidthSide);
+		this._twoTimesWidthSide.connect(this._sideMult.factor);
+		this.connectEffectSide(this._sideMult);
+	}
+
+	static getDefaults(): StereoWidenerOptions {
+		return Object.assign(MidSideEffect.getDefaults(), {
+			width: 0.5,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.width.dispose();
+		this._midMult.dispose();
+		this._sideMult.dispose();
+		this._twoTimesWidthMid.dispose();
+		this._twoTimesWidthSide.dispose();
+		this._oneMinusWidth.dispose();
+		return this;
+	}
+}

package/Tone/effect/StereoXFeedbackEffect.ts

@@ -0,0 +1,37 @@
+import { StereoFeedbackEffect, StereoFeedbackEffectOptions } from "./StereoFeedbackEffect";
+import { NormalRange } from "../core/type/Units";
+import { readOnly } from "../core/util/Interface";
+
+export interface StereoXFeedbackEffectOptions extends StereoFeedbackEffectOptions {
+	feedback: NormalRange;
+}
+
+/**
+ * Just like a [[StereoFeedbackEffect]], but the feedback is routed from left to right
+ * and right to left instead of on the same channel.
+ * ```
+ * +--------------------------------+ feedbackL <-----------------------------------+
+ * |                                                                                |
+ * +-->                          +----->        +---->                          +-----+
+ *      feedbackMerge +--> split        (EFFECT)       merge +--> feedbackSplit     | |
+ * +-->                          +----->        +---->                          +---+ |
+ * |                                                                                  |
+ * +--------------------------------+ feedbackR <-------------------------------------+
+ * ```
+ */
+export class StereoXFeedbackEffect<Options extends StereoXFeedbackEffectOptions> extends StereoFeedbackEffect<Options> {
+	
+	constructor(options: StereoXFeedbackEffectOptions) {
+
+		super(options);
+		// the left output connected to the right input
+		this._feedbackL.disconnect();
+		this._feedbackL.connect(this._feedbackMerge, 0, 1);
+
+		// the left output connected to the right input
+		this._feedbackR.disconnect();
+		this._feedbackR.connect(this._feedbackMerge, 0, 0);
+		
+		readOnly(this, ["feedback"]);
+	}
+}

package/Tone/effect/Tremolo.test.ts

@@ -0,0 +1,88 @@
+import { Tremolo } from "./Tremolo";
+import { BasicTests } from "test/helper/Basic";
+import { EffectTests } from "test/helper/EffectTests";
+import { Offline } from "test/helper/Offline";
+import { expect } from "chai";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Oscillator } from "Tone/source";
+
+describe("Tremolo", () => {
+	BasicTests(Tremolo);
+	EffectTests(Tremolo);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const tremolo = new Tremolo().toDestination().start(0.2);
+			const osc = new Oscillator().connect(tremolo).start();
+		}, "tremolo.wav", 0.05);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const tremolo = new Tremolo({
+				depth: 0.2,
+				type: "sawtooth",
+				spread: 160,
+			});
+			expect(tremolo.depth.value).to.be.closeTo(0.2, 0.001);
+			expect(tremolo.type).to.equal("sawtooth");
+			expect(tremolo.spread).to.equal(160);
+			tremolo.dispose();
+		});
+
+		it("can be started and stopped", () => {
+			const tremolo = new Tremolo();
+			tremolo.start().stop("+0.2");
+			tremolo.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const tremolo = new Tremolo();
+			tremolo.set({
+				frequency: 2.4,
+				type: "triangle"
+			});
+			expect(tremolo.get().frequency).to.be.closeTo(2.4, 0.01);
+			expect(tremolo.get().type).to.equal("triangle");
+			tremolo.dispose();
+		});
+
+		it("can set the frequency and depth", () => {
+			const tremolo = new Tremolo();
+			tremolo.depth.value = 0.4;
+			tremolo.frequency.value = 0.4;
+			expect(tremolo.depth.value).to.be.closeTo(0.4, 0.01);
+			expect(tremolo.frequency.value).to.be.closeTo(0.4, 0.01);
+			tremolo.dispose();
+		});
+
+		it("can sync the frequency to the transport", () => {
+
+			return Offline(({ transport }) => {
+				const tremolo = new Tremolo(2);
+				tremolo.sync();
+				tremolo.frequency.toDestination();
+				transport.bpm.setValueAtTime(transport.bpm.value * 2, 0.05);
+			}, 0.1).then((buffer) => {
+				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", () => {
+
+			return Offline(({ transport }) => {
+				const tremolo = new Tremolo(2);
+				tremolo.sync();
+				tremolo.frequency.toDestination();
+				transport.bpm.setValueAtTime(transport.bpm.value * 2, 0.05);
+				tremolo.unsync();
+			}, 0.1).then((buffer) => {
+				expect(buffer.getValueAtTime(0)).to.be.closeTo(2, 0.1);
+				expect(buffer.getValueAtTime(0.05)).to.be.closeTo(2, 0.1);
+			});
+		});
+	});
+});
+

package/Tone/effect/Tremolo.ts

@@ -0,0 +1,191 @@
+import { StereoEffect, StereoEffectOptions } from "./StereoEffect";
+import { LFO } from "../source/oscillator/LFO";
+import { Gain } from "../core/context/Gain";
+import { Signal } from "../signal/Signal";
+import { Degrees, Frequency, NormalRange, Time } from "../core/type/Units";
+import { ToneOscillatorType } from "../source/oscillator/OscillatorInterface";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { readOnly } from "../core/util/Interface";
+
+export interface TremoloOptions extends StereoEffectOptions {
+	frequency: Frequency;
+	type: ToneOscillatorType;
+	depth: NormalRange;
+	spread: Degrees;
+}
+
+/**
+ * Tremolo modulates the amplitude of an incoming signal using an [[LFO]].
+ * The effect is a stereo effect where the modulation phase is inverted in each channel.
+ *
+ * @example
+ * // create a tremolo and start it's LFO
+ * const tremolo = new Tone.Tremolo(9, 0.75).toDestination().start();
+ * // route an oscillator through the tremolo and start it
+ * const oscillator = new Tone.Oscillator().connect(tremolo).start();
+ * 
+ * @category Effect
+ */
+export class Tremolo extends StereoEffect<TremoloOptions> {
+
+	readonly name: string = "Tremolo";
+
+	/**
+	 * The tremolo LFO in the left channel
+	 */
+	private _lfoL: LFO;
+
+	/**
+	 * The tremolo LFO in the left channel
+	 */
+	private _lfoR: LFO;
+
+	/**
+	 * Where the gain is multiplied
+	 */
+	private _amplitudeL: Gain;
+
+	/**
+	 * Where the gain is multiplied
+	 */
+	private _amplitudeR: Gain;
+
+	/**
+	 * The frequency of the tremolo.
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The depth of the effect. A depth of 0, has no effect
+	 * on the amplitude, and a depth of 1 makes the amplitude
+	 * modulate fully between 0 and 1.
+	 */
+	readonly depth: Signal<"normalRange">;
+
+	/**
+	 * @param frequency The rate of the effect.
+	 * @param depth The depth of the effect.
+	 */
+	constructor(frequency?: Frequency, depth?: NormalRange);
+	constructor(options?: Partial<TremoloOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Tremolo.getDefaults(), arguments, ["frequency", "depth"]));
+		const options = optionsFromArguments(Tremolo.getDefaults(), arguments, ["frequency", "depth"]);
+
+		this._lfoL = new LFO({
+			context: this.context,
+			type: options.type,
+			min: 1,
+			max: 0,
+		});
+		this._lfoR = new LFO({
+			context: this.context,
+			type: options.type,
+			min: 1,
+			max: 0,
+		});
+		this._amplitudeL = new Gain({ context: this.context });
+		this._amplitudeR = new Gain({ context: this.context });
+		this.frequency = new Signal({
+			context: this.context,
+			value: options.frequency,
+			units: "frequency",
+		});
+		this.depth = new Signal({
+			context: this.context,
+			value: options.depth,
+			units: "normalRange",
+		});
+
+		readOnly(this, ["frequency", "depth"]);
+		this.connectEffectLeft(this._amplitudeL);
+		this.connectEffectRight(this._amplitudeR);
+		this._lfoL.connect(this._amplitudeL.gain);
+		this._lfoR.connect(this._amplitudeR.gain);
+		this.frequency.fan(this._lfoL.frequency, this._lfoR.frequency);
+		this.depth.fan(this._lfoR.amplitude, this._lfoL.amplitude);
+		this.spread = options.spread;
+	}
+
+	static getDefaults(): TremoloOptions {
+		return Object.assign(StereoEffect.getDefaults(), {
+			frequency: 10,
+			type: "sine" as "sine",
+			depth: 0.5,
+			spread: 180,
+		});
+	}
+
+	/**
+	 * 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;
+	}
+
+	/**
+	 * Amount of stereo spread. When set to 0, both LFO's will be panned centrally.
+	 * When set to 180, LFO's will be panned hard left and right respectively.
+	 */
+	get spread(): Degrees {
+		return this._lfoR.phase - this._lfoL.phase; // 180
+	}
+	set spread(spread) {
+		this._lfoL.phase = 90 - (spread / 2);
+		this._lfoR.phase = (spread / 2) + 90;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._lfoL.dispose();
+		this._lfoR.dispose();
+		this._amplitudeL.dispose();
+		this._amplitudeR.dispose();
+		this.frequency.dispose();
+		this.depth.dispose();
+		return this;
+	}
+}

package/Tone/effect/Vibrato.test.ts

@@ -0,0 +1,52 @@
+import { Vibrato } from "./Vibrato";
+import { BasicTests } from "test/helper/Basic";
+import { EffectTests } from "test/helper/EffectTests";
+import { expect } from "chai";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+
+describe("Vibrato", () => {
+	BasicTests(Vibrato);
+	EffectTests(Vibrato);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const vibrato = new Vibrato(4, 1).toDestination();
+			const osc = new Oscillator().connect(vibrato).start();
+		}, "vibrato.wav", 0.02);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const vibrato = new Vibrato({
+				maxDelay: 0.02,
+				depth: 0.25,
+				type: "sawtooth"
+			});
+			expect(vibrato.depth.value).to.be.closeTo(0.25, 0.001);
+			expect(vibrato.type).to.equal("sawtooth");
+			vibrato.dispose();
+		});
+		
+		it("can get/set the options", () => {
+			const vibrato = new Vibrato();
+			vibrato.set({
+				frequency: 2.4,
+				type: "triangle"
+			});
+			expect(vibrato.get().frequency).to.be.closeTo(2.4, 0.01);
+			expect(vibrato.get().type).to.equal("triangle");
+			vibrato.dispose();
+		});
+
+		it("can set the frequency and depth", () => {
+			const vibrato = new Vibrato();
+			vibrato.depth.value = 0.4;
+			vibrato.frequency.value = 0.4;
+			expect(vibrato.depth.value).to.be.closeTo(0.4, 0.01);
+			expect(vibrato.frequency.value).to.be.closeTo(0.4, 0.01);
+			vibrato.dispose();
+		});
+	});
+});

package/Tone/effect/Vibrato.ts

@@ -0,0 +1,104 @@
+import { Effect, EffectOptions } from "./Effect";
+import { ToneOscillatorType } from "../source/oscillator/OscillatorInterface";
+import { Frequency, NormalRange, Seconds } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { LFO } from "../source/oscillator/LFO";
+import { Delay } from "../core/context/Delay";
+import { Signal } from "../signal/Signal";
+import { Param } from "../core/context/Param";
+import { readOnly } from "../core/util/Interface";
+
+export interface VibratoOptions extends EffectOptions {
+	maxDelay: Seconds;
+	frequency: Frequency;
+	depth: NormalRange;
+	type: ToneOscillatorType;
+}
+/**
+ * A Vibrato effect composed of a Tone.Delay and a Tone.LFO. The LFO
+ * modulates the delayTime of the delay, causing the pitch to rise and fall. 
+ * @category Effect
+ */
+export class Vibrato extends Effect<VibratoOptions> {
+
+	readonly name: string = "Vibrato";
+	/**
+	 * The delay node used for the vibrato effect
+	 */
+	private _delayNode: Delay;
+	
+	/**
+	 * The LFO used to control the vibrato
+	 */
+	private _lfo: LFO;
+	
+	/**
+	 * The frequency of the vibrato
+	 */
+	readonly frequency: Signal<"frequency">;
+	
+	/**
+	 * The depth of the vibrato. 
+	 */
+	readonly depth: Param<"normalRange">;
+
+	/**
+	 * @param frequency The frequency of the vibrato.
+	 * @param depth The amount the pitch is modulated.
+	 */
+	constructor(frequency?: Frequency, depth?: NormalRange);
+	constructor(options?: Partial<VibratoOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Vibrato.getDefaults(), arguments, ["frequency", "depth"]));
+		const options = optionsFromArguments(Vibrato.getDefaults(), arguments, ["frequency", "depth"]);
+
+		this._delayNode = new Delay({
+			context: this.context,
+			delayTime: 0,
+			maxDelay: options.maxDelay,
+		});
+		this._lfo = new LFO({
+			context: this.context,
+			type: options.type,
+			min: 0,
+			max: options.maxDelay, 
+			frequency: options.frequency,
+			phase: -90 // offse the phase so the resting position is in the center
+		}).start().connect(this._delayNode.delayTime);
+		this.frequency = this._lfo.frequency;
+		this.depth = this._lfo.amplitude;
+
+		this.depth.value = options.depth;
+		readOnly(this, ["frequency", "depth"]);
+		this.effectSend.chain(this._delayNode, this.effectReturn);
+	}
+
+	static getDefaults(): VibratoOptions {
+		return Object.assign(Effect.getDefaults(), {
+			maxDelay: 0.005,
+			frequency: 5,
+			depth: 0.1,
+			type: "sine" as "sine"
+		});
+	}
+
+	/**
+	 * Type of oscillator attached to the Vibrato.
+	 */
+	get type(): ToneOscillatorType {
+		return this._lfo.type;
+	}
+	set type(type) {
+		this._lfo.type = type;
+	}
+	
+	dispose(): this {
+		super.dispose();
+		this._delayNode.dispose();
+		this._lfo.dispose();
+		this.frequency.dispose();
+		this.depth.dispose();
+		return this;
+	}
+}

package/Tone/effect/index.ts

@@ -0,0 +1,18 @@
+export * from "./AutoFilter";
+export * from "./AutoPanner";
+export * from "./AutoWah";
+export * from "./BitCrusher";
+export * from "./Chebyshev";
+export * from "./Chorus";
+export * from "./Distortion";
+export * from "./FeedbackDelay";
+export * from "./FrequencyShifter";
+export * from "./Freeverb";
+export * from "./JCReverb";
+export * from "./PingPongDelay";
+export * from "./PitchShift";
+export * from "./Phaser";
+export * from "./Reverb";
+export * from "./StereoWidener";
+export * from "./Tremolo";
+export * from "./Vibrato";