tone 14.8.27

package/Tone/effect/AutoWah.ts

@@ -0,0 +1,208 @@
+import { Effect, EffectOptions } from "./Effect";
+import { Filter } from "../component/filter/Filter";
+import { Follower } from "../component/analysis/Follower";
+import { Decibels, Frequency, GainFactor, Hertz, Positive, Time } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { Gain } from "../core/context/Gain";
+import { dbToGain, gainToDb } from "../core/type/Conversions";
+import { ScaleExp } from "../signal/ScaleExp";
+import { Signal } from "../signal/Signal";
+import { readOnly } from "../core/util/Interface";
+
+export interface AutoWahOptions extends EffectOptions {
+	baseFrequency: Frequency;
+	octaves: Positive;
+	sensitivity: Decibels;
+	Q: Positive;
+	gain: GainFactor;
+	follower: Time;
+}
+
+/**
+ * AutoWah connects a [[Follower]] to a [[Filter]]. 
+ * The frequency of the filter, follows the input amplitude curve. 
+ * Inspiration from [Tuna.js](https://github.com/Dinahmoe/tuna).
+ * 
+ * @example
+ * const autoWah = new Tone.AutoWah(50, 6, -30).toDestination();
+ * // initialize the synth and connect to autowah
+ * const synth = new Tone.Synth().connect(autoWah);
+ * // Q value influences the effect of the wah - default is 2
+ * autoWah.Q.value = 6;
+ * // more audible on higher notes
+ * synth.triggerAttackRelease("C4", "8n");
+ * @category Effect
+ */
+export class AutoWah extends Effect<AutoWahOptions> {
+
+	readonly name: string = "AutoWah";
+
+	/**
+	 * The envelope follower. Set the attack/release
+	 * timing to adjust how the envelope is followed.
+	 */
+	private _follower: Follower;
+
+	/**
+	 * scales the follower value to the frequency domain
+	 */
+	private _sweepRange: ScaleExp;
+
+	/**
+	 * Hold the base frequency value
+	 */
+	private _baseFrequency: Hertz;
+
+	/**
+	 * Private holder for the octave count
+	 */
+	private _octaves: Positive;
+
+	/**
+	 * the input gain to adjust the sensitivity
+	 */
+	private _inputBoost: Gain;
+
+	/**
+	 * Private holder for the filter
+	 */
+	private _bandpass: Filter;
+
+	/**
+	 * The peaking fitler
+	 */
+	private _peaking: Filter;
+
+	/**
+	 * The gain of the filter.
+	 */
+	readonly gain: Signal<"decibels">;
+
+	/**
+	 * The quality of the filter.
+	 */
+	readonly Q: Signal<"positive">;
+
+	/**
+	 * @param baseFrequency The frequency the filter is set to at the low point of the wah
+	 * @param octaves The number of octaves above the baseFrequency the filter will sweep to when fully open. 
+	 * @param sensitivity The decibel threshold sensitivity for the incoming signal. Normal range of -40 to 0.
+	 */
+	constructor(baseFrequency?: Frequency, octaves?: Positive, sensitivity?: Decibels);
+	constructor(options?: Partial<AutoWahOptions>);
+	constructor() {
+
+		super(optionsFromArguments(AutoWah.getDefaults(), arguments, ["baseFrequency", "octaves", "sensitivity"]));
+		const options = optionsFromArguments(AutoWah.getDefaults(), arguments, ["baseFrequency", "octaves", "sensitivity"]);
+
+		this._follower = new Follower({
+			context: this.context,
+			smoothing: options.follower,
+		});
+		this._sweepRange = new ScaleExp({
+			context: this.context,
+			min: 0,
+			max: 1,
+			exponent: 0.5,
+		});
+		this._baseFrequency = this.toFrequency(options.baseFrequency);
+		this._octaves = options.octaves;
+		this._inputBoost = new Gain({ context: this.context });
+		this._bandpass = new Filter({
+			context: this.context,
+			rolloff: -48,
+			frequency: 0,
+			Q: options.Q,
+		});
+		this._peaking = new Filter({
+			context: this.context,
+			type: "peaking"
+		});
+		this._peaking.gain.value = options.gain;
+		this.gain = this._peaking.gain;
+		this.Q = this._bandpass.Q;
+
+		// the control signal path
+		this.effectSend.chain(this._inputBoost, this._follower, this._sweepRange);
+		this._sweepRange.connect(this._bandpass.frequency);
+		this._sweepRange.connect(this._peaking.frequency);
+		// the filtered path
+		this.effectSend.chain(this._bandpass, this._peaking, this.effectReturn);
+		// set the initial value
+		this._setSweepRange();
+		this.sensitivity = options.sensitivity;
+
+		readOnly(this, ["gain", "Q"]);
+	}
+
+	static getDefaults(): AutoWahOptions {
+		return Object.assign(Effect.getDefaults(), {
+			baseFrequency: 100,
+			octaves: 6,
+			sensitivity: 0,
+			Q: 2,
+			gain: 2,
+			follower: 0.2,
+		});
+	}
+
+	/**
+	 * The number of octaves that the filter will sweep above the baseFrequency.
+	 */
+	get octaves() {
+		return this._octaves;
+	}
+	set octaves(octaves) {
+		this._octaves = octaves;
+		this._setSweepRange();
+	}
+
+	/**
+	 * The follower's smoothing time
+	 */
+	get follower(): Time {
+		return this._follower.smoothing;
+	}
+	set follower(follower) {
+		this._follower.smoothing = follower;
+	}
+
+	/**
+	 * The base frequency from which the sweep will start from.
+	 */
+	get baseFrequency(): Frequency {
+		return this._baseFrequency;
+	}
+	set baseFrequency(baseFreq) {
+		this._baseFrequency = this.toFrequency(baseFreq);
+		this._setSweepRange();
+	}
+
+	/**
+	 * The sensitivity to control how responsive to the input signal the filter is.
+	 */
+	get sensitivity(): Decibels {
+		return gainToDb(1 / this._inputBoost.gain.value);
+	}
+	set sensitivity(sensitivity) {
+		this._inputBoost.gain.value = 1 / dbToGain(sensitivity);
+	}
+
+	/**
+	 * sets the sweep range of the scaler
+	 */
+	private _setSweepRange() {
+		this._sweepRange.min = this._baseFrequency;
+		this._sweepRange.max = Math.min(this._baseFrequency * Math.pow(2, this._octaves), this.context.sampleRate / 2);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._follower.dispose();
+		this._sweepRange.dispose();
+		this._bandpass.dispose();
+		this._peaking.dispose();
+		this._inputBoost.dispose();
+		return this;
+	}
+}

package/Tone/effect/BitCrusher.test.ts

@@ -0,0 +1,42 @@
+import { BitCrusher } from "./BitCrusher";
+import { Oscillator } from "Tone/source/oscillator/Oscillator";
+import { BasicTests } from "test/helper/Basic";
+import { EffectTests } from "test/helper/EffectTests";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { expect } from "chai";
+
+describe("BitCrusher", () => {
+
+	BasicTests(BitCrusher);
+	EffectTests(BitCrusher);
+
+	context("API", () => {
+
+		it("matches a file", () => {
+			return CompareToFile(() => {
+				const crusher = new BitCrusher({ bits: 4 }).toDestination();
+				const osc = new Oscillator(110).connect(crusher);
+				osc.start(0);
+			}, "bitCrusher.wav", 0.01);
+		});
+
+		it("can pass in options in the constructor", () => {
+			const crusher = new BitCrusher({
+				bits: 3,
+			});
+			expect(crusher.bits.value).to.equal(3);
+			crusher.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const crusher = new BitCrusher(4);
+			expect(crusher.bits.value).to.equal(4);
+			crusher.set({
+				bits: 5,
+			});
+			expect(crusher.get().bits).to.equal(5);
+			crusher.dispose();
+		});
+	});
+});
+

package/Tone/effect/BitCrusher.ts

@@ -0,0 +1,129 @@
+import { ToneAudioWorklet, ToneAudioWorkletOptions } from "../core/worklet/ToneAudioWorklet";
+import { Effect, EffectOptions } from "./Effect";
+import { Positive } from "../core/type/Units";
+import { Gain } from "../core/context/Gain";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { connectSeries } from "../core/context/ToneAudioNode";
+import { Param } from "../core/context/Param";
+import { workletName } from "./BitCrusher.worklet";
+
+export interface BitCrusherOptions extends EffectOptions {
+	bits: Positive;
+}
+
+/**
+ * BitCrusher down-samples the incoming signal to a different bit depth.
+ * Lowering the bit depth of the signal creates distortion. Read more about BitCrushing
+ * on [Wikipedia](https://en.wikipedia.org/wiki/Bitcrusher).
+ * @example
+ * // initialize crusher and route a synth through it
+ * const crusher = new Tone.BitCrusher(4).toDestination();
+ * const synth = new Tone.Synth().connect(crusher);
+ * synth.triggerAttackRelease("C2", 2);
+ * 
+ * @category Effect
+ */
+export class BitCrusher extends Effect<BitCrusherOptions> {
+
+	readonly name: string = "BitCrusher";
+
+	/**
+	 * The bit depth of the effect
+	 * @min 1
+	 * @max 16
+	 */
+	readonly bits: Param<"positive">;
+
+	/**
+	 * The node which does the bit crushing effect. Runs in an AudioWorklet when possible.
+	 */
+	private _bitCrusherWorklet: BitCrusherWorklet;
+
+	constructor(bits?: Positive);
+	constructor(options?: Partial<BitCrusherWorkletOptions>);
+	constructor() {
+		super(optionsFromArguments(BitCrusher.getDefaults(), arguments, ["bits"]));
+		const options = optionsFromArguments(BitCrusher.getDefaults(), arguments, ["bits"]);
+
+		this._bitCrusherWorklet = new BitCrusherWorklet({
+			context: this.context,
+			bits: options.bits,
+		});
+		// connect it up
+		this.connectEffect(this._bitCrusherWorklet);
+
+		this.bits = this._bitCrusherWorklet.bits;
+	}
+
+	static getDefaults(): BitCrusherOptions {
+		return Object.assign(Effect.getDefaults(), {
+			bits: 4,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._bitCrusherWorklet.dispose();
+		return this;
+	}
+}
+
+interface BitCrusherWorkletOptions extends ToneAudioWorkletOptions {
+	bits: number;
+}
+
+/**
+ * Internal class which creates an AudioWorklet to do the bit crushing
+ */
+class BitCrusherWorklet extends ToneAudioWorklet<BitCrusherWorkletOptions> {
+
+	readonly name: string = "BitCrusherWorklet";
+
+	readonly input: Gain;
+	readonly output: Gain;
+
+	readonly bits: Param<"positive">;
+
+	constructor(options?: Partial<BitCrusherWorkletOptions>);
+	constructor() {
+		super(optionsFromArguments(BitCrusherWorklet.getDefaults(), arguments));
+		const options = optionsFromArguments(BitCrusherWorklet.getDefaults(), arguments);
+
+		this.input = new Gain({ context: this.context });
+		this.output = new Gain({ context: this.context });
+
+		this.bits = new Param<"positive">({
+			context: this.context,
+			value: options.bits,
+			units: "positive",
+			minValue: 1,
+			maxValue: 16,
+			param: this._dummyParam,
+			swappable: true,
+		});
+	}
+
+	static getDefaults(): BitCrusherWorkletOptions {
+		return Object.assign(ToneAudioWorklet.getDefaults(), {
+			bits: 12,
+		});
+	}
+
+	protected _audioWorkletName(): string {
+		return workletName;
+	}
+
+	onReady(node: AudioWorkletNode) {
+		connectSeries(this.input, node, this.output);
+		const bits = node.parameters.get("bits") as AudioParam;
+		this.bits.setParam(bits);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.input.dispose();
+		this.output.dispose();
+		this.bits.dispose();
+		return this;
+	}
+}

package/Tone/effect/BitCrusher.worklet.ts

@@ -0,0 +1,27 @@
+import "../core/worklet/SingleIOProcessor.worklet";
+import { registerProcessor } from "../core/worklet/WorkletGlobalScope";
+
+export const workletName = "bit-crusher";
+
+export const bitCrusherWorklet = /* javascript */`
+	class BitCrusherWorklet extends SingleIOProcessor {
+
+		static get parameterDescriptors() {
+			return [{
+				name: "bits",
+				defaultValue: 12,
+				minValue: 1,
+				maxValue: 16,
+				automationRate: 'k-rate'
+			}];
+		}
+
+		generate(input, _channel, parameters) {
+			const step = Math.pow(0.5, parameters.bits - 1);
+			const val = step * Math.floor(input / step + 0.5);
+			return val;
+		}
+	}
+`;
+
+registerProcessor(workletName, bitCrusherWorklet);

package/Tone/effect/Chebyshev.test.ts

@@ -0,0 +1,49 @@
+import { Chebyshev } from "./Chebyshev";
+import { BasicTests } from "test/helper/Basic";
+import { EffectTests } from "test/helper/EffectTests";
+import { expect } from "chai";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Synth } from "Tone/instrument";
+
+describe("Chebyshev", () => {
+
+	BasicTests(Chebyshev);
+	EffectTests(Chebyshev, 51);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const cheby = new Chebyshev(100).toDestination();
+			const synth = new Synth().connect(cheby);
+			synth.triggerAttackRelease("C2", 0.2);
+		}, "chebyshev.wav", 0.01);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const cheby = new Chebyshev({
+				order: 2,
+			});
+			expect(cheby.order).to.equal(2);
+			cheby.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const cheby = new Chebyshev();
+			cheby.set({
+				order: 40,
+			});
+			expect(cheby.get().order).to.equal(40);
+			cheby.dispose();
+		});
+
+		it("throws an error if order is not an integer", () => {
+			const cheby = new Chebyshev();
+			expect(() => {
+				cheby.order = 0.2;
+			}).to.throw(Error);
+			cheby.dispose();
+		});
+	});
+});
+

package/Tone/effect/Chebyshev.ts

@@ -0,0 +1,123 @@
+import { Effect, EffectOptions } from "./Effect";
+import { Positive } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { WaveShaper } from "../signal/WaveShaper";
+import { assert } from "../core/util/Debug";
+
+export interface ChebyshevOptions extends EffectOptions {
+	order: Positive;
+	oversample: OverSampleType;
+}
+
+/**
+ * Chebyshev is a waveshaper which is good 
+ * for making different types of distortion sounds.
+ * Note that odd orders sound very different from even ones, 
+ * and order = 1 is no change. 
+ * Read more at [music.columbia.edu](http://music.columbia.edu/cmc/musicandcomputers/chapter4/04_06.php).
+ * @example
+ * // create a new cheby
+ * const cheby = new Tone.Chebyshev(50).toDestination();
+ * // create a monosynth connected to our cheby
+ * const synth = new Tone.MonoSynth().connect(cheby);
+ * synth.triggerAttackRelease("C2", 0.4);
+ * @category Effect
+ */
+export class Chebyshev extends Effect<ChebyshevOptions> {
+
+	readonly name: string = "Chebyshev";
+
+	/**
+	 * The private waveshaper node
+	 */
+	private _shaper: WaveShaper;
+
+	/**
+	 * holds onto the order of the filter
+	 */
+	private _order: number;
+
+	/**
+	 * @param order The order of the chebyshev polynomial. Normal range between 1-100. 
+	 */
+	constructor(order?: Positive);
+	constructor(options?: Partial<ChebyshevOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Chebyshev.getDefaults(), arguments, ["order"]));
+		const options = optionsFromArguments(Chebyshev.getDefaults(), arguments, ["order"]);
+
+		this._shaper = new WaveShaper({
+			context: this.context,
+			length: 4096
+		});
+		this._order = options.order;
+
+		this.connectEffect(this._shaper);
+		this.order = options.order;
+		this.oversample = options.oversample;
+	}
+
+	static getDefaults(): ChebyshevOptions {
+		return Object.assign(Effect.getDefaults(), {
+			order: 1,
+			oversample: "none" as "none"
+		});
+	}
+
+	/**
+	 * get the coefficient for that degree
+	 * @param  x the x value
+	 * @param  degree 
+	 * @param  memo memoize the computed value. this speeds up computation greatly. 
+	 */
+	private _getCoefficient(x: number, degree: number, memo: Map<number, number>): number {
+		if (memo.has(degree)) {
+			return memo.get(degree) as number;
+		} else if (degree === 0) {
+			memo.set(degree, 0);
+		} else if (degree === 1) {
+			memo.set(degree, x);
+		} else {
+			memo.set(degree, 2 * x * this._getCoefficient(x, degree - 1, memo) - this._getCoefficient(x, degree - 2, memo));
+		}
+		return memo.get(degree) as number;
+	}
+
+	/**
+	 * The order of the Chebyshev polynomial which creates the equation which is applied to the incoming 
+	 * signal through a Tone.WaveShaper. Must be an integer. The equations are in the form:
+	 * ```
+	 * order 2: 2x^2 + 1
+	 * order 3: 4x^3 + 3x 
+	 * ```
+	 * @min 1
+	 * @max 100
+	 */
+	get order(): Positive {
+		return this._order;
+	}
+	set order(order) {
+		assert(Number.isInteger(order), "'order' must be an integer");
+		this._order = order;
+		this._shaper.setMap((x => {
+			return this._getCoefficient(x, order, new Map());
+		}));
+	}
+
+	/**
+	 * 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/Chorus.test.ts

@@ -0,0 +1,87 @@
+import { Chorus } from "./Chorus";
+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";
+import { Offline } from "test/helper/Offline";
+
+describe("Chorus", () => {
+
+	BasicTests(Chorus);
+	EffectTests(Chorus);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const chorus = new Chorus().toDestination().start();
+			const osc = new Oscillator(220, "sawtooth").connect(chorus).start();
+		}, "chorus.wav", 0.1);
+	});
+
+	context("API", () => {
+
+		it("can pass in options in the constructor", () => {
+			const chorus = new Chorus({
+				frequency: 2,
+				delayTime: 1,
+				depth: 0.4,
+				spread: 90
+			});
+			expect(chorus.frequency.value).to.be.closeTo(2, 0.01);
+			expect(chorus.delayTime).to.be.closeTo(1, 0.01);
+			expect(chorus.depth).to.be.closeTo(0.4, 0.01);
+			expect(chorus.spread).to.be.equal(90);
+			chorus.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const chorus = new Chorus();
+			chorus.set({
+				type: "square",
+			});
+			expect(chorus.get().type).to.equal("square");
+			chorus.dispose();
+		});
+
+		it("can get/set the delayTime", () => {
+			const chorus = new Chorus();
+			chorus.delayTime = 3;
+			expect(chorus.delayTime).to.equal(3);
+			chorus.dispose();
+		});
+
+		it("can be started and stopped", () => {
+			const chorus = new Chorus();
+			chorus.start().stop("+0.2");
+			chorus.dispose();
+		});
+
+		it("can sync the frequency to the transport", () => {
+			return Offline(({ transport }) => {
+				const chorus = new Chorus(2);
+				chorus.sync();
+				chorus.frequency.toDestination();
+				transport.bpm.setValueAtTime(transport.bpm.value * 2, 0.05);
+				// transport.start(0)
+			}, 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 chorus = new Chorus(2);
+				chorus.sync();
+				chorus.frequency.toDestination();
+				transport.bpm.setValueAtTime(transport.bpm.value * 2, 0.05);
+				chorus.unsync();
+				// transport.start(0)
+			}, 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);
+			});
+		});
+	});
+});
+