tone 14.8.27

package/Tone/instrument/AMSynth.test.ts

@@ -0,0 +1,79 @@
+import { AMSynth } from "./AMSynth";
+import { BasicTests } from "test/helper/Basic";
+import { InstrumentTest } from "test/helper/InstrumentTests";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { expect } from "chai";
+import { Offline } from "test/helper/Offline";
+
+describe("AMSynth", () => {
+
+	BasicTests(AMSynth);
+	InstrumentTest(AMSynth, "C4");
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const synth = new AMSynth().toDestination();
+			synth.triggerAttackRelease("C5", 0.1, 0.1);
+		}, "amSynth.wav", 0.15);
+	});
+
+	context("API", () => {
+
+		it("invokes the onsilence callback", (done) => {
+			Offline(() => {
+				const amSynth = new AMSynth({
+					onsilence: () => done()
+				});
+				amSynth.triggerAttackRelease("C3", 0.2, 0);
+			}, 2);
+		});
+
+		it("can get and set carrier attributes", () => {
+			const amSynth = new AMSynth();
+			amSynth.oscillator.type = "triangle";
+			expect(amSynth.oscillator.type).to.equal("triangle");
+			amSynth.dispose();
+		});
+
+		it("can get and set modulator attributes", () => {
+			const amSynth = new AMSynth();
+			amSynth.envelope.attack = 0.24;
+			expect(amSynth.envelope.attack).to.equal(0.24);
+			amSynth.dispose();
+		});
+
+		it("can get and set harmonicity", () => {
+			const amSynth = new AMSynth();
+			amSynth.harmonicity.value = 2;
+			expect(amSynth.harmonicity.value).to.equal(2);
+			amSynth.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const amSynth = new AMSynth({
+				oscillator: {
+					type: "square"
+				},
+				modulationEnvelope: {
+					attack: 0.3
+				}
+			});
+			expect(amSynth.modulationEnvelope.attack).to.equal(0.3);
+			expect(amSynth.oscillator.type).to.equal("square");
+			amSynth.dispose();
+		});
+
+		it("can get/set attributes", () => {
+			const amSynth = new AMSynth();
+			amSynth.set({
+				harmonicity: 1.5,
+				detune: 1200
+			});
+			expect(amSynth.get().harmonicity).to.equal(1.5);
+			expect(amSynth.get().detune).to.be.closeTo(1200, 1);
+			amSynth.dispose();
+		});
+
+	});
+});
+

package/Tone/instrument/AMSynth.ts

@@ -0,0 +1,51 @@
+import { AudioToGain } from "../signal/AudioToGain";
+import { RecursivePartial } from "../core/util/Interface";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { ModulationSynth, ModulationSynthOptions } from "./ModulationSynth";
+
+export type AMSynthOptions = ModulationSynthOptions;
+
+/**
+ * AMSynth uses the output of one Tone.Synth to modulate the
+ * amplitude of another Tone.Synth. The harmonicity (the ratio between
+ * the two signals) affects the timbre of the output signal greatly.
+ * Read more about Amplitude Modulation Synthesis on
+ * [SoundOnSound](https://web.archive.org/web/20160404103653/http://www.soundonsound.com:80/sos/mar00/articles/synthsecrets.htm).
+ *
+ * @example
+ * const synth = new Tone.AMSynth().toDestination();
+ * synth.triggerAttackRelease("C4", "4n");
+ * 
+ * @category Instrument
+ */
+export class AMSynth extends ModulationSynth<AMSynthOptions> {
+
+	readonly name: string = "AMSynth";
+
+	/**
+	 * Scale the oscillator from -1,1 to 0-1
+	 */
+	private _modulationScale: AudioToGain;
+
+	constructor(options?: RecursivePartial<AMSynthOptions>);
+	constructor() {
+		super(optionsFromArguments(AMSynth.getDefaults(), arguments));
+
+		this._modulationScale = new AudioToGain({
+			context: this.context,
+		});
+
+		// control the two voices frequency
+		this.frequency.connect(this._carrier.frequency);
+		this.frequency.chain(this.harmonicity, this._modulator.frequency);
+		this.detune.fan(this._carrier.detune, this._modulator.detune);
+		this._modulator.chain(this._modulationScale, this._modulationNode.gain);
+		this._carrier.chain(this._modulationNode, this.output);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._modulationScale.dispose();
+		return this;
+	}
+}

package/Tone/instrument/DuoSynth.test.ts

@@ -0,0 +1,95 @@
+import { BasicTests } from "test/helper/Basic";
+import { InstrumentTest } from "test/helper/InstrumentTests";
+import { DuoSynth } from "./DuoSynth";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { expect } from "chai";
+import { MonophonicTest } from "test/helper/MonophonicTests";
+
+describe("DuoSynth", () => {
+
+	BasicTests(DuoSynth);
+	MonophonicTest(DuoSynth, "C4");
+	InstrumentTest(DuoSynth, "C4", {
+		voice0: {
+			oscillator: {
+				type: "square"
+			},
+			envelope: {
+				decay: 0.1,
+				sustain: 0.5,
+				release: 0.2
+			}
+		},
+		voice1: {
+			oscillator: {
+				type: "square"
+			},
+			envelope: {
+				decay: 0.1,
+				sustain: 0.5,
+				release: 0.3
+			}
+		}
+	});
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const synth = new DuoSynth().toDestination();
+			synth.triggerAttackRelease("C5", 0.1, 0.1);
+		}, "duoSynth.wav", 0.05);
+	});
+
+	context("API", () => {
+
+		it("can get and set voice0 attributes", () => {
+			const duoSynth = new DuoSynth();
+			duoSynth.voice0.oscillator.type = "triangle";
+			expect(duoSynth.voice0.oscillator.type).to.equal("triangle");
+			duoSynth.dispose();
+		});
+
+		it("can get and set voice1 attributes", () => {
+			const duoSynth = new DuoSynth();
+			duoSynth.voice1.envelope.attack = 0.24;
+			expect(duoSynth.voice1.envelope.attack).to.equal(0.24);
+			duoSynth.dispose();
+		});
+
+		it("can get and set harmonicity", () => {
+			const duoSynth = new DuoSynth();
+			duoSynth.harmonicity.value = 2;
+			expect(duoSynth.harmonicity.value).to.equal(2);
+			duoSynth.dispose();
+		});
+
+		it("can get and set vibratoRate", () => {
+			const duoSynth = new DuoSynth();
+			duoSynth.vibratoRate.value = 2;
+			expect(duoSynth.vibratoRate.value).to.equal(2);
+			duoSynth.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const duoSynth = new DuoSynth({
+				voice0: {
+					filter: {
+						rolloff: -24
+					}
+				}
+			});
+			expect(duoSynth.voice0.filter.rolloff).to.equal(-24);
+			duoSynth.dispose();
+		});
+
+		it("can get/set attributes", () => {
+			const duoSynth = new DuoSynth();
+			duoSynth.set({
+				harmonicity: 1.5
+			});
+			expect(duoSynth.get().harmonicity).to.equal(1.5);
+			duoSynth.dispose();
+		});
+
+	});
+});
+

package/Tone/instrument/DuoSynth.ts

@@ -0,0 +1,216 @@
+import { Monophonic, MonophonicOptions } from "./Monophonic";
+import { MonoSynth, MonoSynthOptions } from "./MonoSynth";
+import { Signal } from "../signal/Signal";
+import { readOnly, RecursivePartial } from "../core/util/Interface";
+import { LFO } from "../source/oscillator/LFO";
+import { Gain, } from "../core/context/Gain";
+import { Multiply } from "../signal/Multiply";
+import { Frequency, NormalRange, Positive, Seconds, Time } from "../core/type/Units";
+import { deepMerge, omitFromObject, optionsFromArguments } from "../core/util/Defaults";
+import { Param } from "../core/context/Param";
+
+export interface DuoSynthOptions extends MonophonicOptions {
+	voice0: Omit<MonoSynthOptions, keyof MonophonicOptions>;
+	voice1: Omit<MonoSynthOptions, keyof MonophonicOptions>;
+	harmonicity: Positive;
+	vibratoRate: Frequency;
+	vibratoAmount: Positive;
+}
+
+/**
+ * DuoSynth is a monophonic synth composed of two [[MonoSynths]] run in parallel with control over the
+ * frequency ratio between the two voices and vibrato effect.
+ * @example
+ * const duoSynth = new Tone.DuoSynth().toDestination();
+ * duoSynth.triggerAttackRelease("C4", "2n");
+ * @category Instrument
+ */
+export class DuoSynth extends Monophonic<DuoSynthOptions> {
+
+	readonly name: string = "DuoSynth";
+
+	readonly frequency: Signal<"frequency">;
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * the first voice
+	 */
+	readonly voice0: MonoSynth;
+
+	/**
+	 * the second voice
+	 */
+	readonly voice1: MonoSynth;
+
+	/**
+	 * The amount of vibrato
+	 */
+	public vibratoAmount: Param<"normalRange">;
+
+	/**
+	 * the vibrato frequency
+	 */
+	public vibratoRate: Signal<"frequency">;
+
+	/**
+	 * Harmonicity is the ratio between the two voices. A harmonicity of
+	 * 1 is no change. Harmonicity = 2 means a change of an octave.
+	 * @example
+	 * const duoSynth = new Tone.DuoSynth().toDestination();
+	 * duoSynth.triggerAttackRelease("C4", "2n");
+	 * // pitch voice1 an octave below voice0
+	 * duoSynth.harmonicity.value = 0.5;
+	 */
+	public harmonicity: Signal<"positive">;
+
+	/**
+	 * The vibrato LFO.
+	 */
+	private _vibrato: LFO;
+
+	/**
+	 * the vibrato gain
+	 */
+	private _vibratoGain: Gain<"normalRange">;
+
+	constructor(options?: RecursivePartial<DuoSynthOptions>);
+	constructor() {
+		super(optionsFromArguments(DuoSynth.getDefaults(), arguments));
+		const options = optionsFromArguments(DuoSynth.getDefaults(), arguments);
+
+		this.voice0 = new MonoSynth(Object.assign(options.voice0, {
+			context: this.context,
+			onsilence: () => this.onsilence(this)
+		}));
+		this.voice1 = new MonoSynth(Object.assign(options.voice1, {
+			context: this.context,
+		}));
+
+		this.harmonicity = new Multiply({
+			context: this.context,
+			units: "positive",
+			value: options.harmonicity,
+		});
+
+		this._vibrato = new LFO({
+			frequency: options.vibratoRate,
+			context: this.context,
+			min: -50,
+			max: 50
+		});
+		// start the vibrato immediately
+		this._vibrato.start();
+		this.vibratoRate = this._vibrato.frequency;
+		this._vibratoGain = new Gain({
+			context: this.context,
+			units: "normalRange",
+			gain: options.vibratoAmount
+		});
+		this.vibratoAmount = this._vibratoGain.gain;
+
+		this.frequency = new Signal({
+			context: this.context,
+			units: "frequency",
+			value: 440
+		});
+		this.detune = new Signal({
+			context: this.context,
+			units: "cents",
+			value: options.detune
+		});
+
+		// control the two voices frequency
+		this.frequency.connect(this.voice0.frequency);
+		this.frequency.chain(this.harmonicity, this.voice1.frequency);
+
+		this._vibrato.connect(this._vibratoGain);
+		this._vibratoGain.fan(this.voice0.detune, this.voice1.detune);
+
+		this.detune.fan(this.voice0.detune, this.voice1.detune);
+
+		this.voice0.connect(this.output);
+		this.voice1.connect(this.output);
+
+		readOnly(this, ["voice0", "voice1", "frequency", "vibratoAmount", "vibratoRate"]);
+	}
+
+	getLevelAtTime(time: Time): NormalRange {
+		time = this.toSeconds(time);
+		return this.voice0.envelope.getValueAtTime(time) + this.voice1.envelope.getValueAtTime(time);
+	}
+
+	static getDefaults(): DuoSynthOptions {
+		return deepMerge(Monophonic.getDefaults(), {
+			vibratoAmount: 0.5,
+			vibratoRate: 5,
+			harmonicity: 1.5,
+			voice0: deepMerge(
+				omitFromObject(MonoSynth.getDefaults(), Object.keys(Monophonic.getDefaults())),
+				{
+					filterEnvelope: {
+						attack: 0.01,
+						decay: 0.0,
+						sustain: 1,
+						release: 0.5
+					},
+					envelope: {
+						attack: 0.01,
+						decay: 0.0,
+						sustain: 1,
+						release: 0.5
+					}
+				}),
+			voice1: deepMerge(
+				omitFromObject(MonoSynth.getDefaults(), Object.keys(Monophonic.getDefaults())),
+				{
+
+					filterEnvelope: {
+						attack: 0.01,
+						decay: 0.0,
+						sustain: 1,
+						release: 0.5
+					},
+					envelope: {
+						attack: 0.01,
+						decay: 0.0,
+						sustain: 1,
+						release: 0.5
+					}
+				}),
+		}) as DuoSynthOptions;
+	}
+	/**
+	 * Trigger the attack portion of the note
+	 */
+	protected _triggerEnvelopeAttack(time: Seconds, velocity: number): void {
+		// @ts-ignore
+		this.voice0._triggerEnvelopeAttack(time, velocity);
+		// @ts-ignore
+		this.voice1._triggerEnvelopeAttack(time, velocity);
+	}
+
+	/**
+	 * Trigger the release portion of the note
+	 */
+	protected _triggerEnvelopeRelease(time: Seconds) {
+		// @ts-ignore
+		this.voice0._triggerEnvelopeRelease(time);
+		// @ts-ignore
+		this.voice1._triggerEnvelopeRelease(time);
+		return this;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.voice0.dispose();
+		this.voice1.dispose();
+		this.frequency.dispose();
+		this.detune.dispose();
+		this._vibrato.dispose();
+		this.vibratoRate.dispose();
+		this._vibratoGain.dispose();
+		this.harmonicity.dispose();
+		return this;
+	}
+}
+

package/Tone/instrument/FMSynth.test.ts

@@ -0,0 +1,72 @@
+import { expect } from "chai";
+import { FMSynth } from "./FMSynth";
+import { BasicTests } from "test/helper/Basic";
+import { InstrumentTest } from "test/helper/InstrumentTests";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Offline } from "test/helper/Offline";
+
+describe("FMSynth", () => {
+
+	BasicTests(FMSynth);
+	InstrumentTest(FMSynth, "C4");
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const synth = new FMSynth().toDestination();
+			synth.triggerAttackRelease("G4", 0.1, 0.05);
+		}, "fmSynth.wav", 0.06);
+	});
+
+	context("API", () => {
+		it("can get and set carrier attributes", () => {
+			const fmSynth = new FMSynth();
+			fmSynth.oscillator.type = "triangle";
+			expect(fmSynth.oscillator.type).to.equal("triangle");
+			fmSynth.dispose();
+		});
+
+		it("invokes the onsilence callback", (done) => {
+			Offline(() => {
+				const synth = new FMSynth({
+					onsilence: () => done()
+				});
+				synth.triggerAttackRelease("C3", 0.2, 0);
+			}, 2);
+		});
+
+		it("can get and set modulator attributes", () => {
+			const fmSynth = new FMSynth();
+			fmSynth.modulationEnvelope.attack = 0.24;
+			expect(fmSynth.modulationEnvelope.attack).to.equal(0.24);
+			fmSynth.dispose();
+		});
+
+		it("can get and set harmonicity", () => {
+			const fmSynth = new FMSynth();
+			fmSynth.harmonicity.value = 2;
+			expect(fmSynth.harmonicity.value).to.equal(2);
+			fmSynth.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const fmSynth = new FMSynth({
+				envelope: {
+					release: 0.3
+				}
+			});
+			expect(fmSynth.envelope.release).to.equal(0.3);
+			fmSynth.dispose();
+		});
+
+		it("can get/set attributes", () => {
+			const fmSynth = new FMSynth();
+			fmSynth.set({
+				harmonicity: 1.5,
+				detune: 1200
+			});
+			expect(fmSynth.get().harmonicity).to.equal(1.5);
+			expect(fmSynth.get().detune).to.be.closeTo(1200, 1);
+			fmSynth.dispose();
+		});
+	});
+});

package/Tone/instrument/FMSynth.ts

@@ -0,0 +1,65 @@
+import { Positive } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { RecursivePartial } from "../core/util/Interface";
+import { Multiply } from "../signal/Multiply";
+import { ModulationSynth, ModulationSynthOptions } from "./ModulationSynth";
+
+export interface FMSynthOptions extends ModulationSynthOptions {
+	modulationIndex: Positive;
+}
+
+/**
+ * FMSynth is composed of two Tone.Synths where one Tone.Synth modulates
+ * the frequency of a second Tone.Synth. A lot of spectral content
+ * can be explored using the modulationIndex parameter. Read more about
+ * frequency modulation synthesis on Sound On Sound: [Part 1](https://web.archive.org/web/20160403123704/http://www.soundonsound.com/sos/apr00/articles/synthsecrets.htm), [Part 2](https://web.archive.org/web/20160403115835/http://www.soundonsound.com/sos/may00/articles/synth.htm).
+ *
+ * @example
+ * const fmSynth = new Tone.FMSynth().toDestination();
+ * fmSynth.triggerAttackRelease("C5", "4n");
+ * 
+ * @category Instrument
+ */
+
+export class FMSynth extends ModulationSynth<FMSynthOptions> {
+	readonly name: string = "FMSynth";
+
+	/**
+	 * The modulation index which essentially the depth or amount of the modulation. It is the
+	 * ratio of the frequency of the modulating signal (mf) to the amplitude of the
+	 * modulating signal (ma) -- as in ma/mf.
+	 */
+	readonly modulationIndex: Multiply;
+
+	constructor(options?: RecursivePartial<FMSynthOptions>);
+	constructor() {
+		super(optionsFromArguments(FMSynth.getDefaults(), arguments));
+		const options = optionsFromArguments(FMSynth.getDefaults(), arguments);
+
+		this.modulationIndex = new Multiply({
+			context: this.context,
+			value: options.modulationIndex,
+		});
+
+		// control the two voices frequency
+		this.frequency.connect(this._carrier.frequency);
+		this.frequency.chain(this.harmonicity, this._modulator.frequency);
+		this.frequency.chain(this.modulationIndex, this._modulationNode);
+		this.detune.fan(this._carrier.detune, this._modulator.detune);
+		this._modulator.connect(this._modulationNode.gain);
+		this._modulationNode.connect(this._carrier.frequency);
+		this._carrier.connect(this.output);
+	}
+
+	static getDefaults(): FMSynthOptions {
+		return Object.assign(ModulationSynth.getDefaults(), {
+			modulationIndex: 10,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.modulationIndex.dispose();
+		return this;
+	}
+}