tone 14.8.27

package/Tone/effect/Chorus.ts

@@ -0,0 +1,225 @@
+import { StereoFeedbackEffect, StereoFeedbackEffectOptions } from "../effect/StereoFeedbackEffect";
+import { Degrees, Frequency, Milliseconds, NormalRange, Seconds, Time } from "../core/type/Units";
+import { ToneOscillatorType } from "../source/oscillator/OscillatorInterface";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { LFO } from "../source/oscillator/LFO";
+import { Delay } from "../core/context/Delay";
+import { Signal } from "../signal/Signal";
+import { readOnly } from "../core/util/Interface";
+
+export interface ChorusOptions extends StereoFeedbackEffectOptions {
+	frequency: Frequency;
+	delayTime: Milliseconds;
+	depth: NormalRange;
+	type: ToneOscillatorType;
+	spread: Degrees;
+}
+
+/**
+ * Chorus is a stereo chorus effect composed of a left and right delay with an [[LFO]] applied to the delayTime of each channel.
+ * When [[feedback]] is set to a value larger than 0, you also get Flanger-type effects. 
+ * Inspiration from [Tuna.js](https://github.com/Dinahmoe/tuna/blob/master/tuna.js).
+ * Read more on the chorus effect on [SoundOnSound](http://www.soundonsound.com/sos/jun04/articles/synthsecrets.htm).
+ *
+ * @example
+ * const chorus = new Tone.Chorus(4, 2.5, 0.5).toDestination().start();
+ * const synth = new Tone.PolySynth().connect(chorus);
+ * synth.triggerAttackRelease(["C3", "E3", "G3"], "8n");
+ * 
+ * @category Effect
+ */
+export class Chorus extends StereoFeedbackEffect<ChorusOptions> {
+
+	readonly name: string = "Chorus";
+
+	/**
+	 * the depth of the chorus
+	 */
+	private _depth: NormalRange;
+
+	/**
+	 * the delayTime in seconds.
+	 */
+	private _delayTime: Seconds;
+
+	/**
+	 * the lfo which controls the delayTime
+	 */
+	private _lfoL: LFO
+
+	/**
+	 * another LFO for the right side with a 180 degree phase diff
+	 */
+	private _lfoR: LFO
+
+	/**
+	 * delay for left
+	 */
+	private _delayNodeL: Delay;
+
+	/**
+	 * delay for right
+	 */
+	private _delayNodeR: Delay;
+
+	/**
+	 * The frequency of the LFO which modulates the delayTime.
+	 */
+	readonly frequency: Signal<"frequency">
+
+	/**
+	 * @param frequency The frequency of the LFO.
+	 * @param delayTime The delay of the chorus effect in ms.
+	 * @param depth The depth of the chorus.
+	 */
+	constructor(frequency?: Frequency, delayTime?: Milliseconds, depth?: NormalRange);
+	constructor(options?: Partial<ChorusOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Chorus.getDefaults(), arguments, ["frequency", "delayTime", "depth"]));
+		const options = optionsFromArguments(Chorus.getDefaults(), arguments, ["frequency", "delayTime", "depth"]);
+
+		this._depth = options.depth;
+		this._delayTime = options.delayTime / 1000;
+		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._delayNodeL = new Delay({ context: this.context });
+		this._delayNodeR = new Delay({ context: this.context });
+		this.frequency = this._lfoL.frequency;
+		readOnly(this, ["frequency"]);
+		// have one LFO frequency control the other
+		this._lfoL.frequency.connect(this._lfoR.frequency);
+
+		// connections
+		this.connectEffectLeft(this._delayNodeL);
+		this.connectEffectRight(this._delayNodeR);
+		// lfo setup
+		this._lfoL.connect(this._delayNodeL.delayTime);
+		this._lfoR.connect(this._delayNodeR.delayTime);
+		// set the initial values
+		this.depth = this._depth;
+		this.type = options.type;
+		this.spread = options.spread;
+	}
+
+	static getDefaults(): ChorusOptions {
+		return Object.assign(StereoFeedbackEffect.getDefaults(), {
+			frequency: 1.5,
+			delayTime: 3.5,
+			depth: 0.7,
+			type: "sine" as "sine",
+			spread: 180,
+			feedback: 0,
+			wet: 0.5,
+		});
+	}
+
+	/**
+	 * The depth of the effect. A depth of 1 makes the delayTime
+	 * modulate between 0 and 2*delayTime (centered around the delayTime).
+	 */
+	get depth(): NormalRange {
+		return this._depth;
+	}
+	set depth(depth) {
+		this._depth = depth;
+		const deviation = this._delayTime * depth;
+		this._lfoL.min = Math.max(this._delayTime - deviation, 0);
+		this._lfoL.max = this._delayTime + deviation;
+		this._lfoR.min = Math.max(this._delayTime - deviation, 0);
+		this._lfoR.max = this._delayTime + deviation;
+	}
+
+	/**
+	 * The delayTime in milliseconds of the chorus. A larger delayTime
+	 * will give a more pronounced effect. Nominal range a delayTime
+	 * is between 2 and 20ms.
+	 */
+	get delayTime(): Milliseconds {
+		return this._delayTime * 1000;
+	}
+	set delayTime(delayTime) {
+		this._delayTime = delayTime / 1000;
+		this.depth = this._depth;
+	}
+
+	/**
+	 * The oscillator type of the LFO.
+	 */
+	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;
+	}
+	set spread(spread) {
+		this._lfoL.phase = 90 - (spread / 2);
+		this._lfoR.phase = (spread / 2) + 90;
+	}
+
+	/**
+	 * Start the effect.
+	 */
+	start(time?: Time): this {
+		this._lfoL.start(time);
+		this._lfoR.start(time);
+		return this;
+	}
+
+	/**
+	 * Stop the lfo
+	 */
+	stop(time?: Time): this {
+		this._lfoL.stop(time);
+		this._lfoR.stop(time);
+		return this;
+	}
+
+	/**
+	 * Sync the filter to the transport. See [[LFO.sync]]
+	 */
+	sync(): this {
+		this._lfoL.sync();
+		this._lfoR.sync();
+		return this;
+	}
+
+	/**
+	 * Unsync the filter from the transport.
+	 */
+	unsync(): this {
+		this._lfoL.unsync();
+		this._lfoR.unsync();
+		return this;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._lfoL.dispose();
+		this._lfoR.dispose();
+		this._delayNodeL.dispose();
+		this._delayNodeR.dispose();
+		this.frequency.dispose();
+		return this;
+	}
+}

package/Tone/effect/Distortion.test.ts

@@ -0,0 +1,41 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { EffectTests } from "test/helper/EffectTests";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { Distortion } from "./Distortion";
+
+describe("Distortion", () => {
+
+	BasicTests(Distortion);
+	EffectTests(Distortion);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const dist = new Distortion(0.8).toDestination();
+			const osc = new Oscillator().connect(dist);
+			osc.type = "square";
+			osc.start(0).stop(0.4);
+		}, "distortion.wav", 0.01);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const dist = new Distortion({
+				distortion: 0.2,
+			});
+			expect(dist.distortion).to.be.closeTo(0.2, 0.01);
+			dist.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const dist = new Distortion();
+			dist.set({
+				oversample: "4x",
+			});
+			expect(dist.get().oversample).to.equal("4x");
+			dist.dispose();
+		});
+	});
+});

package/Tone/effect/Distortion.ts

@@ -0,0 +1,98 @@
+import { optionsFromArguments } from "../core/util/Defaults";
+import { WaveShaper } from "../signal/WaveShaper";
+import { Effect, EffectOptions } from "./Effect";
+
+export interface DistortionOptions extends EffectOptions {
+	distortion: number;
+	oversample: OverSampleType;
+}
+
+/**
+ * A simple distortion effect using Tone.WaveShaper.
+ * Algorithm from [this stackoverflow answer](http://stackoverflow.com/a/22313408).
+ *
+ * @example
+ * const dist = new Tone.Distortion(0.8).toDestination();
+ * const fm = new Tone.FMSynth().connect(dist);
+ * fm.triggerAttackRelease("A1", "8n");
+ * @category Effect
+ */
+export class Distortion extends Effect<DistortionOptions> {
+
+	readonly name: string = "Distortion";
+
+	/**
+	 * The waveshaper which does the distortion
+	 */
+	private _shaper: WaveShaper;
+
+	/**
+	 * Stores the distortion value
+	 */
+	private _distortion: number;
+
+	/**
+	 * @param distortion The amount of distortion (nominal range of 0-1)
+	 */
+	constructor(distortion?: number);
+	constructor(options?: Partial<DistortionOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Distortion.getDefaults(), arguments, ["distortion"]));
+		const options = optionsFromArguments(Distortion.getDefaults(), arguments, ["distortion"]);
+
+		this._shaper = new WaveShaper({
+			context: this.context,
+			length: 4096,
+		});
+
+		this._distortion = options.distortion;
+
+		this.connectEffect(this._shaper);
+		this.distortion = options.distortion;
+		this.oversample = options.oversample;
+	}
+
+	static getDefaults(): DistortionOptions {
+		return Object.assign(Effect.getDefaults(), {
+			distortion: 0.4,
+			oversample: "none" as OverSampleType,
+		});
+	}
+
+	/**
+	 * The amount of distortion. Nominal range is between 0 and 1.
+	 */
+	get distortion(): number {
+		return this._distortion;
+	}
+	set distortion(amount) {
+		this._distortion = amount;
+		const k = amount * 100;
+		const deg = Math.PI / 180;
+		this._shaper.setMap((x) => {
+			if (Math.abs(x) < 0.001) {
+				// should output 0 when input is 0
+				return 0;
+			} else {
+				return (3 + k) * x * 20 * deg / (Math.PI + k * Math.abs(x));
+			}
+		});
+	}
+
+	/**
+	 * The oversampling of the effect. Can either be "none", "2x" or "4x".
+	 */
+	get oversample(): OverSampleType {
+		return this._shaper.oversample;
+	}
+	set oversample(oversampling) {
+		this._shaper.oversample = oversampling;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._shaper.dispose();
+		return this;
+	}
+}

package/Tone/effect/Effect.ts

@@ -0,0 +1,88 @@
+import { CrossFade } from "../component/channel/CrossFade";
+import { Gain } from "../core/context/Gain";
+import { ToneAudioNode, ToneAudioNodeOptions } from "../core/context/ToneAudioNode";
+import { NormalRange } from "../core/type/Units";
+import { readOnly } from "../core/util/Interface";
+import { Signal } from "../signal/Signal";
+
+export interface EffectOptions extends ToneAudioNodeOptions {
+	wet: NormalRange;
+}
+/**
+ * Effect is the base class for effects. Connect the effect between
+ * the effectSend and effectReturn GainNodes, then control the amount of
+ * effect which goes to the output using the wet control.
+ */
+export abstract class Effect<Options extends EffectOptions>
+	extends ToneAudioNode<Options> {
+
+	readonly name: string = "Effect";
+
+	/**
+	 * the drywet knob to control the amount of effect
+	 */
+	private _dryWet: CrossFade = new CrossFade({ context: this.context });
+
+	/**
+	 * The wet control is how much of the effected
+	 * will pass through to the output. 1 = 100% effected
+	 * signal, 0 = 100% dry signal.
+	 */
+	wet: Signal<"normalRange"> = this._dryWet.fade;
+
+	/**
+	 * connect the effectSend to the input of hte effect
+	 */
+	protected effectSend: Gain = new Gain({ context: this.context });
+
+	/**
+	 * connect the output of the effect to the effectReturn
+	 */
+	protected effectReturn: Gain = new Gain({ context: this.context });
+
+	/**
+	 * The effect input node
+	 */
+	input: Gain = new Gain({ context: this.context });
+
+	/**
+	 * The effect output
+	 */
+	output = this._dryWet;
+
+	constructor(options: EffectOptions) {
+		super(options);
+
+		// connections
+		this.input.fan(this._dryWet.a, this.effectSend);
+		this.effectReturn.connect(this._dryWet.b);
+		this.wet.setValueAtTime(options.wet, 0);
+		this._internalChannels = [this.effectReturn, this.effectSend];
+		readOnly(this, "wet");
+	}
+
+	static getDefaults(): EffectOptions {
+		return Object.assign(ToneAudioNode.getDefaults(), {
+			wet: 1,
+		});
+	}
+
+	/**
+	 * chains the effect in between the effectSend and effectReturn
+	 */
+	protected connectEffect(effect: ToneAudioNode | AudioNode): this {
+		// add it to the internal channels
+		this._internalChannels.push(effect);
+		this.effectSend.chain(effect, this.effectReturn);
+		return this;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._dryWet.dispose();
+		this.effectSend.dispose();
+		this.effectReturn.dispose();
+		this.wet.dispose();
+		return this;
+	}
+}

package/Tone/effect/FeedbackDelay.test.ts

@@ -0,0 +1,75 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { EffectTests } from "test/helper/EffectTests";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { FeedbackDelay } from "./FeedbackDelay";
+import { FeedbackEffect } from "./FeedbackEffect";
+
+describe("FeedbackDelay", () => {
+
+	BasicTests(FeedbackDelay);
+	EffectTests(FeedbackDelay, 0.01);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const delay = new FeedbackDelay(0.1, 0.6).toDestination();
+			const osc = new Oscillator().connect(delay);
+			osc.type = "square";
+			osc.start(0).stop(0.01);
+		}, "feedbackDelay.wav", 0.05);
+	});
+
+	context("API", () => {
+
+		it("extends FeedbackEffect", () => {
+			const feedbackDelay = new FeedbackDelay(0.2, 0.3);
+			expect(feedbackDelay).to.be.instanceOf(FeedbackEffect);
+			feedbackDelay.dispose();
+		});
+
+		it("parses constructor arguments correctly", () => {
+			const feedbackDelay = new FeedbackDelay(0.1, 0.4);
+			expect(feedbackDelay.delayTime.value).to.be.closeTo(0.1, 0.01);
+			expect(feedbackDelay.feedback.value).to.be.closeTo(0.4, 0.01);
+			feedbackDelay.dispose();
+		});
+
+		it("can pass in options in the constructor", () => {
+			const feedbackDelay = new FeedbackDelay({
+				delayTime: 0.2,
+				feedback: 0.3,
+			});
+			expect(feedbackDelay.delayTime.value).to.be.closeTo(0.2, 0.01);
+			expect(feedbackDelay.feedback.value).to.be.closeTo(0.3, 0.01);
+			feedbackDelay.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const feedbackDelay = new FeedbackDelay();
+			feedbackDelay.set({
+				feedback: 0.4,
+			});
+			expect(feedbackDelay.get().feedback).to.be.closeTo(0.4, 0.01);
+			feedbackDelay.dispose();
+		});
+
+		it("can set the delayTime", () => {
+			const feedbackDelay = new FeedbackDelay();
+			feedbackDelay.delayTime.value = "4n";
+			expect(feedbackDelay.delayTime.value).to.be.closeTo(0.5, 0.001);
+			feedbackDelay.delayTime.value = 0.22;
+			expect(feedbackDelay.delayTime.value).to.be.closeTo(0.22, 0.001);
+			feedbackDelay.dispose();
+		});
+
+		it("can set the feedback amount", () => {
+			const feedbackDelay = new FeedbackDelay();
+			feedbackDelay.feedback.value = 1;
+			expect(feedbackDelay.feedback.value).to.be.closeTo(1, 0.001);
+			feedbackDelay.feedback.value = 0.22;
+			expect(feedbackDelay.feedback.value).to.be.closeTo(0.22, 0.001);
+			feedbackDelay.dispose();
+		});
+	});
+});

package/Tone/effect/FeedbackDelay.ts

@@ -0,0 +1,73 @@
+import { Delay } from "../core/context/Delay";
+import { Param } from "../core/context/Param";
+import { NormalRange, Time } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { readOnly } from "../core/util/Interface";
+import { FeedbackEffect, FeedbackEffectOptions } from "./FeedbackEffect";
+
+interface FeedbackDelayOptions extends FeedbackEffectOptions {
+	delayTime: Time;
+	maxDelay: Time;
+}
+
+/**
+ * FeedbackDelay is a DelayNode in which part of output signal is fed back into the delay.
+ *
+ * @param delayTime The delay applied to the incoming signal.
+ * @param feedback The amount of the effected signal which is fed back through the delay.
+ * @example
+ * const feedbackDelay = new Tone.FeedbackDelay("8n", 0.5).toDestination();
+ * const tom = new Tone.MembraneSynth({
+ * 	octaves: 4,
+ * 	pitchDecay: 0.1
+ * }).connect(feedbackDelay);
+ * tom.triggerAttackRelease("A2", "32n");
+ * @category Effect
+ */
+export class FeedbackDelay extends FeedbackEffect<FeedbackDelayOptions> {
+
+	readonly name: string = "FeedbackDelay";
+
+	/**
+	 * the delay node
+	 */
+	private _delayNode: Delay;
+
+	/**
+	 * The delayTime of the FeedbackDelay.
+	 */
+	readonly delayTime: Param<"time">;
+
+	constructor(delayTime?: Time, feedback?: NormalRange);
+	constructor(options?: Partial<FeedbackDelayOptions>);
+	constructor() {
+
+		super(optionsFromArguments(FeedbackDelay.getDefaults(), arguments, ["delayTime", "feedback"]));
+		const options = optionsFromArguments(FeedbackDelay.getDefaults(), arguments, ["delayTime", "feedback"]);
+
+		this._delayNode = new Delay({
+			context: this.context,
+			delayTime: options.delayTime,
+			maxDelay: options.maxDelay,
+		});
+		this.delayTime = this._delayNode.delayTime;
+
+		// connect it up
+		this.connectEffect(this._delayNode);
+		readOnly(this, "delayTime");
+	}
+
+	static getDefaults(): FeedbackDelayOptions {
+		return Object.assign(FeedbackEffect.getDefaults(), {
+			delayTime: 0.25,
+			maxDelay: 1,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._delayNode.dispose();
+		this.delayTime.dispose();
+		return this;
+	}
+}

package/Tone/effect/FeedbackEffect.ts

@@ -0,0 +1,68 @@
+import { Gain } from "../core/context/Gain";
+import { Param } from "../core/context/Param";
+import { NormalRange } from "../core/type/Units";
+import { readOnly } from "../core/util/Interface";
+import { Effect, EffectOptions } from "./Effect";
+
+export interface FeedbackEffectOptions extends EffectOptions {
+	/**
+	 * The feedback from the output back to the input
+	 * ```
+	 * +---<--------<---+
+	 * |                |
+	 * |  +----------+  |
+	 * +--> feedback +>-+
+	 *    +----------+
+	 * ```
+	 */
+	feedback: NormalRange;
+}
+
+/**
+ * FeedbackEffect provides a loop between an audio source and its own output.
+ * This is a base-class for feedback effects.
+ */
+export abstract class FeedbackEffect<Options extends FeedbackEffectOptions> extends Effect<Options> {
+
+	readonly name: string = "FeedbackEffect";
+
+	/**
+	 * the gain which controls the feedback
+	 */
+	private _feedbackGain: Gain<"normalRange">;
+
+	/**
+	 * The amount of signal which is fed back into the effect input.
+	 */
+	feedback: Param<"normalRange">;
+
+	constructor(options: FeedbackEffectOptions) {
+
+		super(options);
+
+		this._feedbackGain = new Gain({
+			context: this.context,
+			gain: options.feedback,
+			units: "normalRange",
+		});
+
+		this.feedback = this._feedbackGain.gain;
+		readOnly(this, "feedback");
+
+		// the feedback loop
+		this.effectReturn.chain(this._feedbackGain, this.effectSend);
+	}
+
+	static getDefaults(): FeedbackEffectOptions {
+		return Object.assign(Effect.getDefaults(), {
+			feedback: 0.125,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._feedbackGain.dispose();
+		this.feedback.dispose();
+		return this;
+	}
+}