tone 14.8.27

package/Tone/instrument/ModulationSynth.ts

@@ -0,0 +1,217 @@
+import { Signal } from "../signal/Signal";
+import { Multiply } from "../signal/Multiply";
+import { Gain } from "../core/context/Gain";
+import { NormalRange, Positive, Seconds, Time } from "../core/type/Units";
+import { Envelope, EnvelopeOptions } from "../component/envelope/Envelope";
+import { ToneAudioNode, ToneAudioNodeOptions } from "../core/context/ToneAudioNode";
+import { Monophonic } from "./Monophonic";
+import { OmniOscillator } from "../source/oscillator/OmniOscillator";
+import { OmniOscillatorSynthOptions } from "../source/oscillator/OscillatorInterface";
+import { Source } from "../source/Source";
+import { Synth, SynthOptions } from "./Synth";
+import { AmplitudeEnvelope } from "../component/envelope/AmplitudeEnvelope";
+import { readOnly, RecursivePartial } from "../core/util/Interface";
+import { omitFromObject, optionsFromArguments } from "../core/util/Defaults";
+
+export interface ModulationSynthOptions extends SynthOptions {
+	harmonicity: Positive;
+	modulationEnvelope: Omit<EnvelopeOptions, keyof ToneAudioNodeOptions>;
+	modulation: OmniOscillatorSynthOptions;
+}
+/**
+ * Base class for both AM and FM synths
+ */
+export abstract class ModulationSynth<Options extends ModulationSynthOptions> extends Monophonic<Options> {
+
+	readonly name: string = "ModulationSynth";
+
+	/**
+	 * The carrier voice.
+	 */
+	protected _carrier: Synth;
+
+	/**
+	 * The modulator voice.
+	 */
+
+	protected _modulator: Synth;
+
+	/**
+	 * The carrier's oscillator
+	 */
+	readonly oscillator: OmniOscillator<any>;
+
+	/**
+	 * The carrier's envelope
+	 */
+	readonly envelope: AmplitudeEnvelope;
+
+	/**
+	 * The modulator's oscillator which is applied to the amplitude of the oscillator
+	 */
+	readonly modulation: OmniOscillator<any>;
+
+	/**
+	 * The modulator's envelope
+	 */
+	readonly modulationEnvelope: AmplitudeEnvelope;
+
+	/**
+	 * The frequency control
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The detune in cents
+	 */
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * 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 amSynth = new Tone.AMSynth().toDestination();
+	 * // pitch the modulator an octave below oscillator
+	 * amSynth.harmonicity.value = 0.5;
+	 * amSynth.triggerAttackRelease("C5", "4n");
+	 */
+	readonly harmonicity: Multiply;
+
+	/**
+	 * The node where the modulation happens
+	 */
+	protected _modulationNode: Gain;
+
+	constructor(options?: RecursivePartial<ModulationSynthOptions>);
+	constructor() {
+		super(optionsFromArguments(ModulationSynth.getDefaults(), arguments));
+		const options = optionsFromArguments(ModulationSynth.getDefaults(), arguments);
+
+		this._carrier = new Synth({
+			context: this.context,
+			oscillator: options.oscillator,
+			envelope: options.envelope,
+			onsilence: () => this.onsilence(this),
+			volume: -10,
+		});
+		this._modulator = new Synth({
+			context: this.context,
+			oscillator: options.modulation,
+			envelope: options.modulationEnvelope,
+			volume: -10,
+		});
+
+		this.oscillator = this._carrier.oscillator;
+		this.envelope = this._carrier.envelope;
+		this.modulation = this._modulator.oscillator;
+		this.modulationEnvelope = this._modulator.envelope;
+
+		this.frequency = new Signal({
+			context: this.context,
+			units: "frequency",
+		});
+		this.detune = new Signal({
+			context: this.context,
+			value: options.detune,
+			units: "cents"
+		});
+		this.harmonicity = new Multiply({
+			context: this.context,
+			value: options.harmonicity,
+			minValue: 0,
+		});
+		this._modulationNode = new Gain({
+			context: this.context,
+			gain: 0,
+		});
+
+		readOnly(this, ["frequency", "harmonicity", "oscillator", "envelope", "modulation", "modulationEnvelope", "detune"]);
+	}
+
+	static getDefaults(): ModulationSynthOptions {
+		return Object.assign(Monophonic.getDefaults(), {
+			harmonicity: 3,
+			oscillator: Object.assign(
+				omitFromObject(OmniOscillator.getDefaults(), [
+					...Object.keys(Source.getDefaults()),
+					"frequency",
+					"detune"
+				]),
+				{
+					type: "sine"
+				}
+			) as OmniOscillatorSynthOptions,
+			envelope: Object.assign(
+				omitFromObject(
+					Envelope.getDefaults(),
+					Object.keys(ToneAudioNode.getDefaults())
+				),
+				{
+					attack: 0.01,
+					decay: 0.01,
+					sustain: 1,
+					release: 0.5
+				}
+			),
+			modulation: Object.assign(
+				omitFromObject(OmniOscillator.getDefaults(), [
+					...Object.keys(Source.getDefaults()),
+					"frequency",
+					"detune"
+				]),
+				{
+					type: "square"
+				}
+			) as OmniOscillatorSynthOptions,
+			modulationEnvelope: Object.assign(
+				omitFromObject(
+					Envelope.getDefaults(),
+					Object.keys(ToneAudioNode.getDefaults())
+				),
+				{
+					attack: 0.5,
+					decay: 0.0,
+					sustain: 1,
+					release: 0.5
+				}
+			)
+		});
+	}
+
+	/**
+	 * Trigger the attack portion of the note
+	 */
+	protected _triggerEnvelopeAttack(time: Seconds, velocity: number): void {
+		// @ts-ignore
+		this._carrier._triggerEnvelopeAttack(time, velocity);
+		// @ts-ignore
+		this._modulator._triggerEnvelopeAttack(time, velocity);
+	}
+
+	/**
+	 * Trigger the release portion of the note
+	 */
+	protected _triggerEnvelopeRelease(time: Seconds) {
+		// @ts-ignore
+		this._carrier._triggerEnvelopeRelease(time);
+		// @ts-ignore
+		this._modulator._triggerEnvelopeRelease(time);
+		return this;
+	}
+
+	getLevelAtTime(time: Time): NormalRange {
+		time = this.toSeconds(time);
+		return this.envelope.getValueAtTime(time);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._carrier.dispose();
+		this._modulator.dispose();
+		this.frequency.dispose();
+		this.detune.dispose();
+		this.harmonicity.dispose();
+		this._modulationNode.dispose();
+		return this;
+	}
+}

package/Tone/instrument/MonoSynth.test.ts

@@ -0,0 +1,88 @@
+import { BasicTests } from "test/helper/Basic";
+import { MonoSynth } from "./MonoSynth";
+import { InstrumentTest } from "test/helper/InstrumentTests";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { expect } from "chai";
+import { Offline } from "test/helper/Offline";
+
+describe("MonoSynth", () => {
+
+	BasicTests(MonoSynth);
+	InstrumentTest(MonoSynth, "C4");
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const synth = new MonoSynth().toDestination();
+			synth.triggerAttackRelease("C4", 0.1, 0.05);
+		}, "monoSynth.wav", 0.01);
+	});
+
+	context("API", () => {
+
+		it("can get and set oscillator attributes", () => {
+			const monoSynth = new MonoSynth();
+			monoSynth.oscillator.type = "triangle";
+			expect(monoSynth.oscillator.type).to.equal("triangle");
+			monoSynth.dispose();
+		});
+
+		it("can get and set envelope attributes", () => {
+			const monoSynth = new MonoSynth();
+			monoSynth.envelope.attack = 0.24;
+			expect(monoSynth.envelope.attack).to.equal(0.24);
+			monoSynth.dispose();
+		});
+
+		it("can get and set filter attributes", () => {
+			const monoSynth = new MonoSynth();
+			monoSynth.filter.Q.value = 0.4;
+			expect(monoSynth.filter.Q.value).to.be.closeTo(0.4, 0.001);
+			monoSynth.dispose();
+		});
+
+		it("can get and set filterEnvelope attributes", () => {
+			const monoSynth = new MonoSynth();
+			monoSynth.filterEnvelope.baseFrequency = 400;
+			expect(monoSynth.filterEnvelope.baseFrequency).to.equal(400);
+			monoSynth.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const monoSynth = new MonoSynth({
+				envelope: {
+					sustain: 0.3
+				}
+			});
+			expect(monoSynth.envelope.sustain).to.equal(0.3);
+			monoSynth.dispose();
+		});
+
+		it("can get/set attributes", () => {
+			const monoSynth = new MonoSynth();
+			monoSynth.set({
+				envelope: {
+					decay: 0.24
+				}
+			});
+			expect(monoSynth.get().envelope.decay).to.equal(0.24);
+			monoSynth.dispose();
+		});
+
+		it("is silent after triggerAttack if sustain is 0", async () => {
+			return await Offline(() => {
+				const synth = new MonoSynth({
+					envelope: {
+						attack: 0.1,
+						decay: 0.1,
+						sustain: 0,
+					}
+				}).toDestination();
+				synth.triggerAttack("C4", 0);
+			}, 0.5).then((buffer) => {
+				expect(buffer.getTimeOfLastSound()).to.be.closeTo(0.2, 0.01);
+			});
+		});
+
+	});
+});
+

package/Tone/instrument/MonoSynth.ts

@@ -0,0 +1,177 @@
+import { AmplitudeEnvelope } from "../component/envelope/AmplitudeEnvelope";
+import { Envelope, EnvelopeOptions } from "../component/envelope/Envelope";
+import { Filter, FilterOptions } from "../component/filter/Filter";
+import { omitFromObject, optionsFromArguments } from "../core/util/Defaults";
+import { readOnly, RecursivePartial } from "../core/util/Interface";
+import { Monophonic, MonophonicOptions } from "../instrument/Monophonic";
+import { OmniOscillator } from "../source/oscillator/OmniOscillator";
+import { Source } from "../source/Source";
+import { FrequencyEnvelope, FrequencyEnvelopeOptions } from "../component/envelope/FrequencyEnvelope";
+import { NormalRange, Seconds, Time } from "../core/type/Units";
+import { Signal } from "../signal/Signal";
+import { ToneAudioNode, ToneAudioNodeOptions } from "../core/context/ToneAudioNode";
+import { OmniOscillatorSynthOptions } from "../source/oscillator/OscillatorInterface";
+
+export interface MonoSynthOptions extends MonophonicOptions {
+	oscillator: OmniOscillatorSynthOptions;
+	envelope: Omit<EnvelopeOptions, keyof ToneAudioNodeOptions>;
+	filterEnvelope: Omit<FrequencyEnvelopeOptions, keyof ToneAudioNodeOptions>;
+	filter: Omit<FilterOptions, keyof ToneAudioNodeOptions>;
+}
+
+/**
+ * MonoSynth is composed of one `oscillator`, one `filter`, and two `envelopes`.
+ * The amplitude of the Oscillator and the cutoff frequency of the
+ * Filter are controlled by Envelopes.
+ * <img src="https://docs.google.com/drawings/d/1gaY1DF9_Hzkodqf8JI1Cg2VZfwSElpFQfI94IQwad38/pub?w=924&h=240">
+ * @example
+ * const synth = new Tone.MonoSynth({
+ * 	oscillator: {
+ * 		type: "square"
+ * 	},
+ * 	envelope: {
+ * 		attack: 0.1
+ * 	}
+ * }).toDestination();
+ * synth.triggerAttackRelease("C4", "8n");
+ * @category Instrument
+ */
+export class MonoSynth extends Monophonic<MonoSynthOptions> {
+
+	readonly name = "MonoSynth";
+
+	/**
+	 * The oscillator.
+	 */
+	readonly oscillator: OmniOscillator<any>;
+
+	/**
+	 * The frequency control.
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The detune control.
+	 */
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * The filter.
+	 */
+	readonly filter: Filter;
+
+	/**
+	 * The filter envelope.
+	 */
+	readonly filterEnvelope: FrequencyEnvelope;
+
+	/**
+	 * The amplitude envelope.
+	 */
+	readonly envelope: AmplitudeEnvelope;
+
+	constructor(options?: RecursivePartial<MonoSynthOptions>);
+	constructor() {
+		super(optionsFromArguments(MonoSynth.getDefaults(), arguments));
+		const options = optionsFromArguments(MonoSynth.getDefaults(), arguments);
+
+		this.oscillator = new OmniOscillator(Object.assign(options.oscillator, {
+			context: this.context,
+			detune: options.detune,
+			onstop: () => this.onsilence(this),
+		}));
+		this.frequency = this.oscillator.frequency;
+		this.detune = this.oscillator.detune;
+		this.filter = new Filter(Object.assign(options.filter, { context: this.context }));
+		this.filterEnvelope = new FrequencyEnvelope(Object.assign(options.filterEnvelope, { context: this.context }));
+		this.envelope = new AmplitudeEnvelope(Object.assign(options.envelope, { context: this.context }));
+
+		// connect the oscillators to the output
+		this.oscillator.chain(this.filter, this.envelope, this.output);
+
+		// connect the filter envelope
+		this.filterEnvelope.connect(this.filter.frequency);
+
+		readOnly(this, ["oscillator", "frequency", "detune", "filter", "filterEnvelope", "envelope"]);
+	}
+
+	static getDefaults(): MonoSynthOptions {
+		return Object.assign(Monophonic.getDefaults(), {
+			envelope: Object.assign(
+				omitFromObject(Envelope.getDefaults(), Object.keys(ToneAudioNode.getDefaults())),
+				{
+					attack: 0.005,
+					decay: 0.1,
+					release: 1,
+					sustain: 0.9,
+				},
+			),
+			filter: Object.assign(
+				omitFromObject(Filter.getDefaults(), Object.keys(ToneAudioNode.getDefaults())),
+				{
+					Q: 1,
+					rolloff: -12,
+					type: "lowpass",
+				},
+			),
+			filterEnvelope: Object.assign(
+				omitFromObject(FrequencyEnvelope.getDefaults(), Object.keys(ToneAudioNode.getDefaults())),
+				{
+					attack: 0.6,
+					baseFrequency: 200,
+					decay: 0.2,
+					exponent: 2,
+					octaves: 3,
+					release: 2,
+					sustain: 0.5,
+				}
+			),
+			oscillator: Object.assign(
+				omitFromObject(OmniOscillator.getDefaults(), Object.keys(Source.getDefaults())),
+				{
+					type: "sawtooth",
+				},
+			) as OmniOscillatorSynthOptions,
+		});
+	}
+
+	/**
+	 * start the attack portion of the envelope
+	 * @param time the time the attack should start
+	 * @param velocity the velocity of the note (0-1)
+	 */
+	protected _triggerEnvelopeAttack(time: Seconds, velocity = 1): void {
+		this.envelope.triggerAttack(time, velocity);
+		this.filterEnvelope.triggerAttack(time);
+		this.oscillator.start(time);
+		if (this.envelope.sustain === 0) {
+			const computedAttack = this.toSeconds(this.envelope.attack);
+			const computedDecay = this.toSeconds(this.envelope.decay);
+			this.oscillator.stop(time + computedAttack + computedDecay);
+		}
+	}
+
+	/**
+	 * start the release portion of the envelope
+	 * @param time the time the release should start
+	 */
+	protected _triggerEnvelopeRelease(time: Seconds): void {
+		this.envelope.triggerRelease(time);
+		this.filterEnvelope.triggerRelease(time);
+		this.oscillator.stop(time + this.toSeconds(this.envelope.release));
+	}
+
+	getLevelAtTime(time: Time): NormalRange {
+		time = this.toSeconds(time);
+		return this.envelope.getValueAtTime(time);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.oscillator.dispose();
+		this.envelope.dispose();
+		this.filterEnvelope.dispose();
+		this.filter.dispose();
+		return this;
+	}
+}

package/Tone/instrument/Monophonic.ts

@@ -0,0 +1,135 @@
+import { FrequencyClass } from "../core/type/Frequency";
+import { Cents, Frequency, NormalRange, Seconds, Time } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { noOp } from "../core/util/Interface";
+import { Instrument, InstrumentOptions } from "../instrument/Instrument";
+import { Signal } from "../signal/Signal";
+import { timeRange } from "../core/util/Decorator";
+
+type onSilenceCallback = (instrument: Monophonic<any>) => void;
+
+export interface MonophonicOptions extends InstrumentOptions {
+	portamento: Seconds;
+	onsilence: onSilenceCallback;
+	detune: Cents;
+}
+
+/**
+ * Abstract base class for other monophonic instruments to extend.
+ */
+export abstract class Monophonic<Options extends MonophonicOptions> extends Instrument<Options> {
+
+	/**
+	 * The glide time between notes.
+	 */
+	@timeRange(0)
+	portamento: Seconds;
+
+	/**
+	 * Invoked when the release has finished and the output is silent.
+	 */
+	onsilence: onSilenceCallback;
+
+	/**
+	 * The instrument's frequency signal.
+	 */
+	abstract readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The instrument's detune control signal.
+	 */
+	abstract readonly detune: Signal<"cents">;
+
+	constructor(options?: Partial<MonophonicOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Monophonic.getDefaults(), arguments));
+		const options = optionsFromArguments(Monophonic.getDefaults(), arguments);
+
+		this.portamento = options.portamento;
+		this.onsilence = options.onsilence;
+	}
+
+	static getDefaults(): MonophonicOptions {
+		return Object.assign(Instrument.getDefaults(), {
+			detune: 0,
+			onsilence: noOp,
+			portamento: 0,
+		});
+	}
+
+	/**
+	 * Trigger the attack of the note optionally with a given velocity.
+	 * @param  note The note to trigger.
+	 * @param  time When the note should start.
+	 * @param  velocity The velocity determines how "loud" the note will be.
+	 * @example
+	 * const synth = new Tone.Synth().toDestination();
+	 * // trigger the note a half second from now at half velocity
+	 * synth.triggerAttack("C4", "+0.5", 0.5);
+	 */
+	triggerAttack(note: Frequency | FrequencyClass, time?: Time, velocity: NormalRange = 1): this {
+		this.log("triggerAttack", note, time, velocity);
+		const seconds = this.toSeconds(time);
+		this._triggerEnvelopeAttack(seconds, velocity);
+		this.setNote(note, seconds);
+		return this;
+	}
+
+	/**
+	 * Trigger the release portion of the envelope.
+	 * @param  time If no time is given, the release happens immediately.
+	 * @example
+	 * const synth = new Tone.Synth().toDestination();
+	 * synth.triggerAttack("C4");
+	 * // trigger the release a second from now
+	 * synth.triggerRelease("+1");
+	 */
+	triggerRelease(time?: Time): this {
+		this.log("triggerRelease", time);
+		const seconds = this.toSeconds(time);
+		this._triggerEnvelopeRelease(seconds);
+		return this;
+	}
+
+	/**
+	 * Internal method which starts the envelope attack
+	 */
+	protected abstract _triggerEnvelopeAttack(time: Seconds, velocity: NormalRange): void;
+
+	/**
+	 * Internal method which starts the envelope release
+	 */
+	protected abstract _triggerEnvelopeRelease(time: Seconds): void;
+
+	/**
+	 * Get the level of the output at the given time. Measures
+	 * the envelope(s) value at the time.
+	 * @param time The time to query the envelope value
+	 * @return The output level between 0-1
+	 */
+	abstract getLevelAtTime(time: Time): NormalRange;
+
+	/**
+	 * Set the note at the given time. If no time is given, the note
+	 * will set immediately.
+	 * @param note The note to change to.
+	 * @param  time The time when the note should be set.
+	 * @example
+	 * const synth = new Tone.Synth().toDestination();
+	 * synth.triggerAttack("C4");
+	 * // change to F#6 in one quarter note from now.
+	 * synth.setNote("F#6", "+4n");
+	 */
+	setNote(note: Frequency | FrequencyClass, time?: Time): this {
+		const computedTime = this.toSeconds(time);
+		const computedFrequency = note instanceof FrequencyClass ? note.toFrequency() : note;
+		if (this.portamento > 0 && this.getLevelAtTime(computedTime) > 0.05) {
+			const portTime = this.toSeconds(this.portamento);
+			this.frequency.exponentialRampTo(computedFrequency, portTime, computedTime);
+		} else {
+			this.frequency.setValueAtTime(computedFrequency, computedTime);
+		}
+		return this;
+	}
+}

package/Tone/instrument/NoiseSynth.test.ts

@@ -0,0 +1,82 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { InstrumentTest } from "test/helper/InstrumentTests";
+import { NoiseSynth } from "./NoiseSynth";
+
+describe("NoiseSynth", () => {
+
+	BasicTests(NoiseSynth);
+
+	InstrumentTest(NoiseSynth, undefined, {
+		envelope: {
+			decay: 0.1,
+			release: 0.2,
+			sustain: 0.5,
+		},
+	});
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const synth = new NoiseSynth({
+				envelope: {
+					attack: 0.01,
+					decay: 0.4,
+				},
+			}).toDestination();
+			synth.triggerAttack(0);
+			synth.triggerAttack(0.3);
+		}, "noiseSynth.wav", 4);
+	});
+
+	it("matches another file", () => {
+		return CompareToFile(() => {
+			const synth = new NoiseSynth({
+				envelope: {
+					attack: 0.01,
+					decay: 0.4,
+				},
+			}).toDestination();
+			synth.triggerAttackRelease(0.1, 0);
+		}, "noiseSynthRelease.wav", 4);
+	});
+
+	context("API", () => {
+
+		it("can get and set noise type", () => {
+			const noiseSynth = new NoiseSynth();
+			noiseSynth.noise.type = "pink";
+			expect(noiseSynth.noise.type).to.equal("pink");
+			noiseSynth.dispose();
+		});
+
+		it("can get and set envelope attributes", () => {
+			const noiseSynth = new NoiseSynth();
+			noiseSynth.envelope.attack = 0.24;
+			expect(noiseSynth.envelope.attack).to.equal(0.24);
+			noiseSynth.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const noiseSynth = new NoiseSynth({
+				envelope: {
+					sustain: 0.3,
+				},
+			});
+			expect(noiseSynth.envelope.sustain).to.equal(0.3);
+			noiseSynth.dispose();
+		});
+
+		it("can get/set attributes", () => {
+			const noiseSynth = new NoiseSynth();
+			noiseSynth.set({
+				envelope: {
+					decay: 0.24,
+				},
+			});
+			expect(noiseSynth.get().envelope.decay).to.equal(0.24);
+			noiseSynth.dispose();
+		});
+
+	});
+});