tone 14.8.27

package/Tone/effect/Freeverb.test.ts

@@ -0,0 +1,45 @@
+import { Freeverb } from "./Freeverb";
+import { BasicTests } from "test/helper/Basic";
+import { EffectTests } from "test/helper/EffectTests";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { expect } from "chai";
+
+describe("Freeverb", () => {
+
+	BasicTests(Freeverb);
+	EffectTests(Freeverb);
+
+	it("matches a file basic", () => {
+		return CompareToFile(() => {
+			const reverb = new Freeverb(0.9).toDestination();
+			reverb.dampening = 7000;
+			const osc = new Oscillator().connect(reverb);
+			osc.start(0).stop(0.01);
+		}, "freeverb.wav", 0.3);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const reverb = new Freeverb({
+				dampening: 2000,
+				roomSize: 0.2,
+			});
+			expect(reverb.dampening).to.be.closeTo(2000, 0.01);
+			expect(reverb.roomSize.value).to.be.closeTo(0.2, 0.01);
+			reverb.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const reverb = new Freeverb(0.2, 2300);
+			reverb.set({
+				roomSize: 0.23,
+			});
+			expect(reverb.get().dampening).to.be.closeTo(2300, 0.01);
+			expect(reverb.get().roomSize).to.be.closeTo(0.23, 0.01);
+			reverb.dispose();
+		});
+	});
+});
+

package/Tone/effect/Freeverb.ts

@@ -0,0 +1,137 @@
+import { StereoEffect, StereoEffectOptions } from "./StereoEffect";
+import { Frequency, NormalRange } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { readOnly } from "../core/util/Interface";
+import { Signal } from "../signal/Signal";
+import { LowpassCombFilter } from "../component/filter/LowpassCombFilter";
+
+export interface FreeverbOptions extends StereoEffectOptions {
+	dampening: Frequency;
+	roomSize: NormalRange;
+}
+
+/**
+ * An array of comb filter delay values from Freeverb implementation
+ */
+const combFilterTunings = [1557 / 44100, 1617 / 44100, 1491 / 44100, 1422 / 44100, 1277 / 44100, 1356 / 44100, 1188 / 44100, 1116 / 44100];
+
+/**
+ * An array of allpass filter frequency values from Freeverb implementation
+ */
+const allpassFilterFrequencies = [225, 556, 441, 341];
+
+/**
+ * Freeverb is a reverb based on [Freeverb](https://ccrma.stanford.edu/~jos/pasp/Freeverb.html).
+ * Read more on reverb on [Sound On Sound](https://web.archive.org/web/20160404083902/http://www.soundonsound.com:80/sos/feb01/articles/synthsecrets.asp).
+ * Freeverb is now implemented with an AudioWorkletNode which may result on performance degradation on some platforms. Consider using [[Reverb]].
+ * @example
+ * const freeverb = new Tone.Freeverb().toDestination();
+ * freeverb.dampening = 1000;
+ * // routing synth through the reverb
+ * const synth = new Tone.NoiseSynth().connect(freeverb);
+ * synth.triggerAttackRelease(0.05);
+ * @category Effect
+ */
+export class Freeverb extends StereoEffect<FreeverbOptions> {
+
+	readonly name: string = "Freeverb";
+
+	/**
+	 * The roomSize value between 0 and 1. A larger roomSize will result in a longer decay.
+	 */
+	readonly roomSize: Signal<"normalRange">;
+
+	/**
+	 * the comb filters
+	 */
+	private _combFilters: LowpassCombFilter[] = [];
+
+	/**
+	 * the allpass filters on the left
+	 */
+	private _allpassFiltersL: BiquadFilterNode[] = [];
+
+	/**
+	 * the allpass filters on the right
+	 */
+	private _allpassFiltersR: BiquadFilterNode[] = [];
+
+	/**
+	 * @param roomSize Correlated to the decay time.
+	 * @param dampening The cutoff frequency of a lowpass filter as part of the reverb.
+	 */
+	constructor(roomSize?: NormalRange, dampening?: Frequency);
+	constructor(options?: Partial<FreeverbOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Freeverb.getDefaults(), arguments, ["roomSize", "dampening"]));
+		const options = optionsFromArguments(Freeverb.getDefaults(), arguments, ["roomSize", "dampening"]);
+
+		this.roomSize = new Signal({
+			context: this.context,
+			value: options.roomSize,
+			units: "normalRange",
+		});
+
+		// make the allpass filters on the right
+		this._allpassFiltersL = allpassFilterFrequencies.map(freq => {
+			const allpassL = this.context.createBiquadFilter();
+			allpassL.type = "allpass";
+			allpassL.frequency.value = freq;
+			return allpassL;
+		});
+
+		// make the allpass filters on the left
+		this._allpassFiltersR = allpassFilterFrequencies.map(freq => {
+			const allpassR = this.context.createBiquadFilter();
+			allpassR.type = "allpass";
+			allpassR.frequency.value = freq;
+			return allpassR;
+		});
+
+		// make the comb filters
+		this._combFilters = combFilterTunings.map((delayTime, index) => {
+			const lfpf = new LowpassCombFilter({
+				context: this.context,
+				dampening: options.dampening,
+				delayTime,
+			});
+			if (index < combFilterTunings.length / 2) {
+				this.connectEffectLeft(lfpf, ...this._allpassFiltersL);
+			} else {
+				this.connectEffectRight(lfpf, ...this._allpassFiltersR);
+			}
+			this.roomSize.connect(lfpf.resonance);
+			return lfpf;
+		});
+
+		readOnly(this, ["roomSize"]);
+	}
+
+	static getDefaults(): FreeverbOptions {
+		return Object.assign(StereoEffect.getDefaults(), {
+			roomSize: 0.7,
+			dampening: 3000
+		});
+	}
+
+	/**
+	 * The amount of dampening of the reverberant signal.
+	 */
+
+	get dampening(): Frequency {
+		return this._combFilters[0].dampening;
+	}
+	set dampening(d) {
+		this._combFilters.forEach(c => c.dampening = d);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._allpassFiltersL.forEach(al => al.disconnect());
+		this._allpassFiltersR.forEach(ar => ar.disconnect());
+		this._combFilters.forEach(cf => cf.dispose());
+		this.roomSize.dispose();
+		return this;
+	}
+}

package/Tone/effect/FrequencyShifter.test.ts

@@ -0,0 +1,55 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { EffectTests } from "test/helper/EffectTests";
+import { Offline } from "test/helper/Offline";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { FrequencyShifter } from "./FrequencyShifter";
+
+describe("FrequencyShifter", () => {
+
+	BasicTests(FrequencyShifter);
+	EffectTests(FrequencyShifter);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const shifter = new FrequencyShifter().toDestination();
+			shifter.frequency.value = -60;
+			const osc = new Oscillator().connect(shifter);
+			osc.start(0);
+		}, "frequencyShifter.wav", 0.1);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const shifter = new FrequencyShifter({
+				frequency: -20,
+			});
+			expect(shifter.frequency.value).to.be.closeTo(-20, 0.001);
+			shifter.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const shifter = new FrequencyShifter();
+			shifter.set({
+				frequency: 40,
+			});
+			expect(shifter.get().frequency).to.be.closeTo(40, 0.001);
+			shifter.dispose();
+		});
+
+		it("passes audio from input to output", () => {
+			return Offline(() => {
+				const osc = new Oscillator();
+				osc.start(0).stop(0.1);
+				const shifter = new FrequencyShifter(0.2).toDestination();
+				osc.connect(shifter);
+			}, 0.3).then((buffer) => {
+				expect(buffer.getRmsAtTime(0.05)).to.be.greaterThan(0);
+				expect(buffer.getRmsAtTime(0.1)).to.be.greaterThan(0);
+				expect(buffer.getRmsAtTime(0.2)).to.be.greaterThan(0);
+			});
+		});
+	});
+});

package/Tone/effect/FrequencyShifter.ts

@@ -0,0 +1,155 @@
+import { PhaseShiftAllpass } from "../component/filter/PhaseShiftAllpass";
+import { Frequency } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { Effect, EffectOptions } from "../effect/Effect";
+import { Add } from "../signal/Add";
+import { Multiply } from "../signal/Multiply";
+import { Negate } from "../signal/Negate";
+import { Signal } from "../signal/Signal";
+import { Oscillator } from "../source/oscillator/Oscillator";
+import { ToneOscillatorNode } from "../source/oscillator/ToneOscillatorNode";
+
+interface FrequencyShifterOptions extends EffectOptions {
+	frequency: Frequency;
+}
+
+/**
+ * FrequencyShifter can be used to shift all frequencies of a signal by a fixed amount.
+ * The amount can be changed at audio rate and the effect is applied in real time.
+ * The frequency shifting is implemented with a technique called single side band modulation using a ring modulator.
+ * Note: Contrary to pitch shifting, all frequencies are shifted by the same amount,
+ * destroying the harmonic relationship between them. This leads to the classic ring modulator timbre distortion.
+ * The algorithm will produces some aliasing towards the high end, especially if your source material
+ * contains a lot of high frequencies. Unfortunatelly the webaudio API does not support resampling
+ * buffers in real time, so it is not possible to fix it properly. Depending on the use case it might
+ * be an option to low pass filter your input before frequency shifting it to get ride of the aliasing.
+ * You can find a very detailed description of the algorithm here: https://larzeitlin.github.io/RMFS/
+ *
+ * @example
+ * const input = new Tone.Oscillator(230, "sawtooth").start();
+ * const shift = new Tone.FrequencyShifter(42).toDestination();
+ * input.connect(shift);
+ * @category Effect
+ */
+export class FrequencyShifter extends Effect<FrequencyShifterOptions> {
+
+	readonly name: string = "FrequencyShifter";
+
+	/**
+	 * The ring modulators carrier frequency. This frequency determines
+	 * by how many Hertz the input signal will be shifted up or down. Default is 0.
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The ring modulators sine carrier
+	 */
+	private _sine: ToneOscillatorNode;
+
+	/**
+	 * The ring modulators cosine carrier
+	 */
+	private _cosine: Oscillator;
+
+	/**
+	 * The sine multiply operator
+	 */
+	private _sineMultiply: Multiply;
+
+	/**
+	 * The cosine multiply operator
+	 */
+	private _cosineMultiply: Multiply;
+
+	/**
+	 * The negate operator
+	 */
+	private _negate: Negate;
+
+	/**
+	 * The final add operator
+	 */
+	private _add: Add;
+
+	/**
+	 * The phase shifter to create the initial 90° phase offset
+	 */
+	private _phaseShifter: PhaseShiftAllpass;
+
+	/**
+	 * @param frequency The incoming signal is shifted by this frequency value.
+	 */
+	constructor(frequency?: Frequency);
+	constructor(options?: Partial<FrequencyShifterOptions>);
+	constructor() {
+
+		super(optionsFromArguments(FrequencyShifter.getDefaults(), arguments, ["frequency"]));
+		const options = optionsFromArguments(FrequencyShifter.getDefaults(), arguments, ["frequency"]);
+
+		this.frequency = new Signal({
+			context: this.context,
+			units: "frequency",
+			value: options.frequency,
+			minValue: -this.context.sampleRate / 2,
+			maxValue: this.context.sampleRate / 2,
+		});
+
+		this._sine = new ToneOscillatorNode({
+			context: this.context,
+			type: "sine",
+		});
+
+		this._cosine = new Oscillator({
+			context: this.context,
+			phase: -90,
+			type: "sine",
+		});
+
+		this._sineMultiply = new Multiply({ context: this.context });
+		this._cosineMultiply = new Multiply({ context: this.context });
+		this._negate = new Negate({ context: this.context });
+		this._add = new Add({ context: this.context });
+
+		this._phaseShifter = new PhaseShiftAllpass({ context: this.context });
+		this.effectSend.connect(this._phaseShifter);
+
+		// connect the carrier frequency signal to the two oscillators
+		this.frequency.fan(this._sine.frequency, this._cosine.frequency);
+
+		this._phaseShifter.offset90.connect(this._cosineMultiply);
+		this._cosine.connect(this._cosineMultiply.factor);
+
+		this._phaseShifter.connect(this._sineMultiply);
+		this._sine.connect(this._sineMultiply.factor);
+		this._sineMultiply.connect(this._negate);
+
+		this._cosineMultiply.connect(this._add);
+		this._negate.connect(this._add.addend);
+
+		this._add.connect(this.effectReturn);
+
+		// start the oscillators at the same time
+		const now = this.immediate();
+		this._sine.start(now);
+		this._cosine.start(now);
+	}
+
+	static getDefaults(): FrequencyShifterOptions {
+		return Object.assign(Effect.getDefaults(), {
+			frequency: 0,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.frequency.dispose();
+		this._add.dispose();
+		this._cosine.dispose();
+		this._cosineMultiply.dispose();
+		this._negate.dispose();
+		this._phaseShifter.dispose();
+		this._sine.dispose();
+		this._sineMultiply.dispose();
+		return this;
+	}
+}

package/Tone/effect/JCReverb.test.ts

@@ -0,0 +1,41 @@
+import { JCReverb } from "./JCReverb";
+import { BasicTests } from "test/helper/Basic";
+import { EffectTests } from "test/helper/EffectTests";
+import { expect } from "chai";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Noise } from "Tone/source/Noise";
+
+describe("JCReverb", () => {
+
+	BasicTests(JCReverb);
+	EffectTests(JCReverb);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const reverb = new JCReverb().toDestination();
+			const noise = new Noise().connect(reverb);
+			noise.start(0).stop(0.1);
+		}, "jcReverb.wav", 0.2);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const reverb = new JCReverb({
+				roomSize: 0.2,
+			});
+			expect(reverb.roomSize.value).to.be.closeTo(0.2, 0.01);
+			reverb.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const reverb = new JCReverb();
+			reverb.set({
+				roomSize: 0.23,
+			});
+			expect(reverb.get().roomSize).to.be.closeTo(0.23, 0.01);
+			reverb.dispose();
+		});
+	});
+});
+

package/Tone/effect/JCReverb.ts

@@ -0,0 +1,130 @@
+import { NormalRange } from "../core/type/Units";
+import { StereoEffect, StereoEffectOptions } from "./StereoEffect";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { Scale } from "../signal/Scale";
+import { Signal } from "../signal/Signal";
+import { FeedbackCombFilter } from "../component/filter/FeedbackCombFilter";
+import { readOnly } from "../core/util/Interface";
+
+export interface JCReverbOptions extends StereoEffectOptions {
+	roomSize: NormalRange;
+}
+
+/**
+ * an array of the comb filter delay time values
+ */
+const combFilterDelayTimes = [1687 / 25000, 1601 / 25000, 2053 / 25000, 2251 / 25000];
+
+/**
+ * the resonances of each of the comb filters
+ */
+const combFilterResonances = [0.773, 0.802, 0.753, 0.733];
+
+/**
+ * the allpass filter frequencies
+ */
+const allpassFilterFreqs = [347, 113, 37];
+
+/**
+ * JCReverb is a simple [Schroeder Reverberator](https://ccrma.stanford.edu/~jos/pasp/Schroeder_Reverberators.html)
+ * tuned by John Chowning in 1970.
+ * It is made up of three allpass filters and four [[FeedbackCombFilter]].
+ * JCReverb is now implemented with an AudioWorkletNode which may result on performance degradation on some platforms. Consider using [[Reverb]].
+ * @example
+ * const reverb = new Tone.JCReverb(0.4).toDestination();
+ * const delay = new Tone.FeedbackDelay(0.5);
+ * // connecting the synth to reverb through delay
+ * const synth = new Tone.DuoSynth().chain(delay, reverb);
+ * synth.triggerAttackRelease("A4", "8n");
+ * 
+ * @category Effect
+ */
+export class JCReverb extends StereoEffect<JCReverbOptions> {
+
+	readonly name: string = "JCReverb";
+
+	/**
+	 * Room size control values. 
+	 */
+	readonly roomSize: Signal<"normalRange">
+
+	/**
+	 * Scale the room size
+	 */
+	private _scaleRoomSize: Scale;
+
+	/**
+	 * a series of allpass filters
+	 */
+	private _allpassFilters: BiquadFilterNode[] = [];
+
+	/**
+	 * parallel feedback comb filters
+	 */
+	private _feedbackCombFilters: FeedbackCombFilter[] = [];
+
+	/**
+	 * @param roomSize Correlated to the decay time.
+	 */
+	constructor(roomSize?: NormalRange);
+	constructor(options?: Partial<JCReverbOptions>);
+	constructor() {
+
+		super(optionsFromArguments(JCReverb.getDefaults(), arguments, ["roomSize"]));
+		const options = optionsFromArguments(JCReverb.getDefaults(), arguments, ["roomSize"]);
+
+		this.roomSize = new Signal({
+			context: this.context,
+			value: options.roomSize,
+			units: "normalRange",
+		});
+		this._scaleRoomSize = new Scale({
+			context: this.context,
+			min: -0.733,
+			max: 0.197,
+		});
+
+		// make the allpass filters
+		this._allpassFilters = allpassFilterFreqs.map(freq => {
+			const allpass = this.context.createBiquadFilter();
+			allpass.type = "allpass";
+			allpass.frequency.value = freq;
+			return allpass;
+		});
+
+		// and the comb filters
+		this._feedbackCombFilters = combFilterDelayTimes.map((delayTime, index) => {
+			const fbcf = new FeedbackCombFilter({
+				context: this.context,
+				delayTime,
+			});
+			this._scaleRoomSize.connect(fbcf.resonance);
+			fbcf.resonance.value = combFilterResonances[index];
+			if (index < combFilterDelayTimes.length / 2) {
+				this.connectEffectLeft(...this._allpassFilters, fbcf);
+			} else {
+				this.connectEffectRight(...this._allpassFilters, fbcf);
+			}
+			return fbcf;
+		});
+
+		// chain the allpass filters together
+		this.roomSize.connect(this._scaleRoomSize);
+		readOnly(this, ["roomSize"]);
+	}
+
+	static getDefaults(): JCReverbOptions {
+		return Object.assign(StereoEffect.getDefaults(), {
+			roomSize: 0.5,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._allpassFilters.forEach(apf => apf.disconnect());
+		this._feedbackCombFilters.forEach(fbcf => fbcf.dispose());
+		this.roomSize.dispose();
+		this._scaleRoomSize.dispose();
+		return this;
+	}
+}

package/Tone/effect/LFOEffect.ts

@@ -0,0 +1,115 @@
+import { Effect, EffectOptions } from "../effect/Effect";
+import { Frequency, NormalRange, Time } from "../core/type/Units";
+import { LFO } from "../source/oscillator/LFO";
+import { ToneOscillatorType } from "../source/oscillator/OscillatorInterface";
+import { Signal } from "../signal/Signal";
+import { readOnly } from "../core/util/Interface";
+import { Param } from "../core/context/Param";
+
+export interface LFOEffectOptions extends EffectOptions {
+	frequency: Frequency;
+	type: ToneOscillatorType;
+	depth: NormalRange;
+}
+
+/**
+ * Base class for LFO-based effects.
+ */
+export abstract class LFOEffect<Options extends LFOEffectOptions> extends Effect<Options> {
+
+	readonly name: string = "LFOEffect";
+
+	/**
+	 * the lfo which drives the filter cutoff
+	 */
+	protected _lfo: LFO;
+
+	/**
+	 * The range of the filter modulating between the min and max frequency. 
+	 * 0 = no modulation. 1 = full modulation.
+	 */
+	readonly depth: Param<"normalRange">;
+
+	/**
+	 * How fast the filter modulates between min and max. 
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	constructor(options: LFOEffectOptions) {
+
+		super(options);
+
+		this._lfo = new LFO({
+			context: this.context,
+			frequency: options.frequency,
+			amplitude: options.depth,
+		});
+		this.depth = this._lfo.amplitude;
+		this.frequency = this._lfo.frequency;
+
+		this.type = options.type;
+		readOnly(this, ["frequency", "depth"]);
+	}
+
+	static getDefaults(): LFOEffectOptions {
+		return Object.assign(Effect.getDefaults(), {
+			frequency: 1,
+			type: "sine" as ToneOscillatorType,
+			depth: 1,
+		});
+	}
+
+	/**
+	 * Start the effect.
+	 */
+	start(time?: Time): this {
+		this._lfo.start(time);
+		return this;
+	}
+
+	/**
+	 * Stop the lfo
+	 */
+	stop(time?: Time): this {
+		this._lfo.stop(time);
+		return this;
+	}
+
+	/**
+	 * Sync the filter to the transport. See [[LFO.sync]]
+	 */
+	sync(): this {
+		this._lfo.sync();
+		return this;
+	}
+
+	/**
+	 * Unsync the filter from the transport.
+	 */
+	unsync(): this {
+		this._lfo.unsync();
+		return this;
+	}
+
+	/**
+	 * The type of the LFO's oscillator: See [[Oscillator.type]]
+	 * @example
+	 * const autoFilter = new Tone.AutoFilter().start().toDestination();
+	 * const noise = new Tone.Noise().start().connect(autoFilter);
+	 * autoFilter.type = "square";
+	 */
+	get type() {
+		return this._lfo.type;
+	}
+	set type(type) {
+		this._lfo.type = type;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._lfo.dispose();
+		this.frequency.dispose();
+		this.depth.dispose();
+		return this;
+	}
+}