tone 14.8.27

package/Tone/instrument/Sampler.ts

@@ -0,0 +1,329 @@
+import { ToneAudioBuffer } from "../core/context/ToneAudioBuffer";
+import { ToneAudioBuffers } from "../core/context/ToneAudioBuffers";
+import { ftomf, intervalToFrequencyRatio } from "../core/type/Conversions";
+import { FrequencyClass } from "../core/type/Frequency";
+import { Frequency, Interval, MidiNote, NormalRange, Note, Time } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { noOp } from "../core/util/Interface";
+import { isArray, isNote, isNumber } from "../core/util/TypeCheck";
+import { Instrument, InstrumentOptions } from "../instrument/Instrument";
+import { ToneBufferSource, ToneBufferSourceCurve } from "../source/buffer/ToneBufferSource";
+import { timeRange } from "../core/util/Decorator";
+import { assert } from "../core/util/Debug";
+
+interface SamplesMap {
+	[note: string]: ToneAudioBuffer | AudioBuffer | string;
+	[midi: number]: ToneAudioBuffer | AudioBuffer | string;
+}
+
+export interface SamplerOptions extends InstrumentOptions {
+	attack: Time;
+	release: Time;
+	onload: () => void;
+	onerror: (error: Error) => void;
+	baseUrl: string;
+	curve: ToneBufferSourceCurve;
+	urls: SamplesMap;
+}
+
+/**
+ * Pass in an object which maps the note's pitch or midi value to the url,
+ * then you can trigger the attack and release of that note like other instruments.
+ * By automatically repitching the samples, it is possible to play pitches which
+ * were not explicitly included which can save loading time.
+ *
+ * For sample or buffer playback where repitching is not necessary,
+ * use [[Player]].
+ * @example
+ * const sampler = new Tone.Sampler({
+ * 	urls: {
+ * 		A1: "A1.mp3",
+ * 		A2: "A2.mp3",
+ * 	},
+ * 	baseUrl: "https://tonejs.github.io/audio/casio/",
+ * 	onload: () => {
+ * 		sampler.triggerAttackRelease(["C1", "E1", "G1", "B1"], 0.5);
+ * 	}
+ * }).toDestination();
+ * @category Instrument
+ */
+export class Sampler extends Instrument<SamplerOptions> {
+
+	readonly name: string = "Sampler";
+
+	/**
+	 * The stored and loaded buffers
+	 */
+	private _buffers: ToneAudioBuffers;
+
+	/**
+	 * The object of all currently playing BufferSources
+	 */
+	private _activeSources: Map<MidiNote, ToneBufferSource[]> = new Map();
+
+	/**
+	 * The envelope applied to the beginning of the sample.
+	 * @min 0
+	 * @max 1
+	 */
+	@timeRange(0)
+	attack: Time;
+
+	/**
+	 * The envelope applied to the end of the envelope.
+	 * @min 0
+	 * @max 1
+	 */
+	@timeRange(0)
+	release: Time;
+
+	/**
+	 * The shape of the attack/release curve.
+	 * Either "linear" or "exponential"
+	 */
+	curve: ToneBufferSourceCurve;
+
+	/**
+	 * @param samples An object of samples mapping either Midi Note Numbers or
+	 * 			Scientific Pitch Notation to the url of that sample.
+	 * @param onload The callback to invoke when all of the samples are loaded.
+	 * @param baseUrl The root URL of all of the samples, which is prepended to all the URLs.
+	 */
+	constructor(samples?: SamplesMap, onload?: () => void, baseUrl?: string);
+	/**
+	 * @param samples An object of samples mapping either Midi Note Numbers or
+	 * 			Scientific Pitch Notation to the url of that sample.
+	 * @param options The remaining options associated with the sampler
+	 */
+	constructor(samples?: SamplesMap, options?: Partial<Omit<SamplerOptions, "urls">>);
+	constructor(options?: Partial<SamplerOptions>);
+	constructor() {
+
+		super(optionsFromArguments(Sampler.getDefaults(), arguments, ["urls", "onload", "baseUrl"], "urls"));
+		const options = optionsFromArguments(Sampler.getDefaults(), arguments, ["urls", "onload", "baseUrl"], "urls");
+
+		const urlMap = {};
+		Object.keys(options.urls).forEach((note) => {
+			const noteNumber = parseInt(note, 10);
+			assert(isNote(note)
+				|| (isNumber(noteNumber) && isFinite(noteNumber)), `url key is neither a note or midi pitch: ${note}`);
+			if (isNote(note)) {
+				// convert the note name to MIDI
+				const mid = new FrequencyClass(this.context, note).toMidi();
+				urlMap[mid] = options.urls[note];
+			} else if (isNumber(noteNumber) && isFinite(noteNumber)) {
+				// otherwise if it's numbers assume it's midi
+				urlMap[noteNumber] = options.urls[noteNumber];
+			}
+		});
+
+		this._buffers = new ToneAudioBuffers({
+			urls: urlMap,
+			onload: options.onload,
+			baseUrl: options.baseUrl,
+			onerror: options.onerror,
+		});
+		this.attack = options.attack;
+		this.release = options.release;
+		this.curve = options.curve;
+
+		// invoke the callback if it's already loaded
+		if (this._buffers.loaded) {
+			// invoke onload deferred
+			Promise.resolve().then(options.onload);
+		}
+	}
+
+	static getDefaults(): SamplerOptions {
+		return Object.assign(Instrument.getDefaults(), {
+			attack: 0,
+			baseUrl: "",
+			curve: "exponential" as "exponential",
+			onload: noOp,
+			onerror: noOp,
+			release: 0.1,
+			urls: {},
+		});
+	}
+
+	/**
+	 * Returns the difference in steps between the given midi note at the closets sample.
+	 */
+	private _findClosest(midi: MidiNote): Interval {
+		// searches within 8 octaves of the given midi note
+		const MAX_INTERVAL = 96;
+		let interval = 0;
+		while (interval < MAX_INTERVAL) {
+			// check above and below
+			if (this._buffers.has(midi + interval)) {
+				return -interval;
+			} else if (this._buffers.has(midi - interval)) {
+				return interval;
+			}
+			interval++;
+		}
+		throw new Error(`No available buffers for note: ${midi}`);
+	}
+
+	/**
+	 * @param  notes	The note to play, or an array of notes.
+	 * @param  time     When to play the note
+	 * @param  velocity The velocity to play the sample back.
+	 */
+	triggerAttack(notes: Frequency | Frequency[], time?: Time, velocity: NormalRange = 1): this {
+		this.log("triggerAttack", notes, time, velocity);
+		if (!Array.isArray(notes)) {
+			notes = [notes];
+		}
+		notes.forEach(note => {
+			const midiFloat = ftomf(new FrequencyClass(this.context, note).toFrequency());
+			const midi = Math.round(midiFloat) as MidiNote;
+			const remainder = midiFloat - midi;
+			// find the closest note pitch
+			const difference = this._findClosest(midi);
+			const closestNote = midi - difference;
+			const buffer = this._buffers.get(closestNote);
+			const playbackRate = intervalToFrequencyRatio(difference + remainder);
+			// play that note
+			const source = new ToneBufferSource({
+				url: buffer,
+				context: this.context,
+				curve: this.curve,
+				fadeIn: this.attack,
+				fadeOut: this.release,
+				playbackRate,
+			}).connect(this.output);
+			source.start(time, 0, buffer.duration / playbackRate, velocity);
+			// add it to the active sources
+			if (!isArray(this._activeSources.get(midi))) {
+				this._activeSources.set(midi, []);
+			}
+			(this._activeSources.get(midi) as ToneBufferSource[]).push(source);
+
+			// remove it when it's done
+			source.onended = () => {
+				if (this._activeSources && this._activeSources.has(midi)) {
+					const sources = this._activeSources.get(midi) as ToneBufferSource[];
+					const index = sources.indexOf(source);
+					if (index !== -1) {
+						sources.splice(index, 1);
+					}
+				}
+			};
+		});
+		return this;
+	}
+
+	/**
+	 * @param  notes	The note to release, or an array of notes.
+	 * @param  time     	When to release the note.
+	 */
+	triggerRelease(notes: Frequency | Frequency[], time?: Time): this {
+		this.log("triggerRelease", notes, time);
+		if (!Array.isArray(notes)) {
+			notes = [notes];
+		}
+		notes.forEach(note => {
+			const midi = new FrequencyClass(this.context, note).toMidi();
+			// find the note
+			if (this._activeSources.has(midi) && (this._activeSources.get(midi) as ToneBufferSource[]).length) {
+				const sources = this._activeSources.get(midi) as ToneBufferSource[];
+				time = this.toSeconds(time);
+				sources.forEach(source => {
+					source.stop(time);
+				});
+				this._activeSources.set(midi, []);
+			}
+		});
+		return this;
+	}
+
+	/**
+	 * Release all currently active notes.
+	 * @param  time     	When to release the notes.
+	 */
+	releaseAll(time?: Time): this {
+		const computedTime = this.toSeconds(time);
+		this._activeSources.forEach(sources => {
+			while (sources.length) {
+				const source = sources.shift() as ToneBufferSource;
+				source.stop(computedTime);
+			}
+		});
+		return this;
+	}
+
+	sync(): this {
+		if (this._syncState()) {
+			this._syncMethod("triggerAttack", 1);
+			this._syncMethod("triggerRelease", 1);
+		}
+		return this;
+	}
+
+	/**
+	 * Invoke the attack phase, then after the duration, invoke the release.
+	 * @param  notes	The note to play and release, or an array of notes.
+	 * @param  duration The time the note should be held
+	 * @param  time     When to start the attack
+	 * @param  velocity The velocity of the attack
+	 */
+	triggerAttackRelease(
+		notes: Frequency[] | Frequency,
+		duration: Time | Time[],
+		time?: Time,
+		velocity: NormalRange = 1,
+	): this {
+		const computedTime = this.toSeconds(time);
+		this.triggerAttack(notes, computedTime, velocity);
+		if (isArray(duration)) {
+			assert(isArray(notes), "notes must be an array when duration is array");
+			(notes as Frequency[]).forEach((note, index) => {
+				const d = duration[Math.min(index, duration.length - 1)];
+				this.triggerRelease(note, computedTime + this.toSeconds(d));
+			});
+		} else {
+			this.triggerRelease(notes, computedTime + this.toSeconds(duration));
+		}
+		return this;
+	}
+
+	/**
+	 * Add a note to the sampler.
+	 * @param  note      The buffer's pitch.
+	 * @param  url  Either the url of the buffer, or a buffer which will be added with the given name.
+	 * @param  callback  The callback to invoke when the url is loaded.
+	 */
+	add(note: Note | MidiNote, url: string | ToneAudioBuffer | AudioBuffer, callback?: () => void): this {
+		assert(isNote(note) || isFinite(note), `note must be a pitch or midi: ${note}`);
+		if (isNote(note)) {
+			// convert the note name to MIDI
+			const mid = new FrequencyClass(this.context, note).toMidi();
+			this._buffers.add(mid, url, callback);
+		} else {
+			// otherwise if it's numbers assume it's midi
+			this._buffers.add(note, url, callback);
+		}
+		return this;
+	}
+
+	/**
+	 * If the buffers are loaded or not
+	 */
+	get loaded(): boolean {
+		return this._buffers.loaded;
+	}
+
+	/**
+	 * Clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		this._buffers.dispose();
+		this._activeSources.forEach(sources => {
+			sources.forEach(source => source.dispose());
+		});
+		this._activeSources.clear();
+		return this;
+	}
+}

package/Tone/instrument/Synth.test.ts

@@ -0,0 +1,132 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { InstrumentTest } from "test/helper/InstrumentTests";
+import { MonophonicTest } from "test/helper/MonophonicTests";
+import { Offline } from "test/helper/Offline";
+import { Frequency } from "Tone/core/type/Frequency";
+import { Synth } from "./Synth";
+
+describe("Synth", () => {
+
+	BasicTests(Synth);
+	InstrumentTest(Synth, "C4");
+	MonophonicTest(Synth, "C4");
+
+	it("matches a file basic", () => {
+		return CompareToFile(() => {
+			const synth = new Synth().toDestination();
+			synth.triggerAttackRelease("C4", 0.1, 0.05);
+		}, "synth_basic.wav", 0.3);
+	});
+
+	it("matches a file melody", () => {
+		return CompareToFile(() => {
+			const synth = new Synth().toDestination();
+			synth.triggerAttack("C4", 0);
+			synth.triggerAttack("E4", 0.1, 0.5);
+			synth.triggerAttackRelease("G4", 0.5, 0.3);
+			synth.triggerAttackRelease("B4", 0.5, 0.5, 0.2);
+		}, "synth_melody.wav", 0.3);
+	});
+
+	context("API", () => {
+
+		it("can get and set oscillator attributes", () => {
+			const simple = new Synth();
+			simple.oscillator.type = "triangle";
+			expect(simple.oscillator.type).to.equal("triangle");
+			simple.dispose();
+		});
+
+		it("can get and set envelope attributes", () => {
+			const simple = new Synth();
+			simple.envelope.attack = 0.24;
+			expect(simple.envelope.attack).to.equal(0.24);
+			simple.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const simple = new Synth({
+				envelope: {
+					sustain: 0.3,
+				},
+				oscillator: {
+					type: "sine",
+				},
+				volume: -5,
+			});
+			expect(simple.envelope.sustain).to.equal(0.3);
+			expect(simple.oscillator.type).to.equal("sine");
+			expect(simple.volume.value).to.be.closeTo(-5, 0.1);
+			simple.dispose();
+		});
+
+		it("can get/set attributes", () => {
+			const simple = new Synth();
+			simple.set({
+				envelope: {
+					decay: 0.24,
+				},
+			});
+			expect(simple.get().envelope.decay).to.equal(0.24);
+			simple.dispose();
+		});
+
+		it("can get does not include omited oscillator attributes", () => {
+			const simple = new Synth();
+			expect(simple.get().oscillator).to.not.have.key("frequency");
+			expect(simple.get().oscillator).to.not.have.key("detune");
+			expect(Object.keys(simple.get().oscillator)).to.include("type");
+			simple.dispose();
+		});
+
+		it("can be trigged with a Tone.Frequency", () => {
+			return Offline(() => {
+				const synth = new Synth().toDestination();
+				synth.triggerAttack(Frequency("C4"), 0);
+			}).then((buffer) => {
+				expect(buffer.isSilent()).to.be.false;
+			});
+		});
+
+		it("is silent after triggerAttack if sustain is 0", () => {
+			return Offline(() => {
+				const synth = new Synth({
+					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);
+			});
+		});
+	});
+
+	context("Portamento", () => {
+		it("can play notes with a portamento", () => {
+			return Offline(() => {
+				const synth = new Synth({
+					portamento: 0.1,
+				});
+				expect(synth.portamento).to.equal(0.1);
+				synth.frequency.toDestination();
+				synth.triggerAttack(440, 0);
+				synth.triggerAttack(880, 0.1);
+			}, 0.2).then((buffer) => {
+				buffer.forEach((val, time) => {
+					if (time < 0.1) {
+						expect(val).to.be.closeTo(440, 1);
+					} else if (time < 0.2) {
+						expect(val).to.within(440, 880);
+					} else {
+						expect(val).to.be.closeTo(880, 1);
+					}
+				});
+			});
+		});
+	});
+});

package/Tone/instrument/Synth.ts

@@ -0,0 +1,141 @@
+import { AmplitudeEnvelope } from "../component/envelope/AmplitudeEnvelope";
+import { Envelope, EnvelopeOptions } from "../component/envelope/Envelope";
+import { ToneAudioNode, ToneAudioNodeOptions } from "../core/context/ToneAudioNode";
+import { NormalRange, Seconds, Time } from "../core/type/Units";
+import { omitFromObject, optionsFromArguments } from "../core/util/Defaults";
+import { readOnly } from "../core/util/Interface";
+import { RecursivePartial } from "../core/util/Interface";
+import { Signal } from "../signal/Signal";
+import { OmniOscillator } from "../source/oscillator/OmniOscillator";
+import { OmniOscillatorOptions, OmniOscillatorSynthOptions } from "../source/oscillator/OscillatorInterface";
+import { Source } from "../source/Source";
+import { Monophonic, MonophonicOptions } from "./Monophonic";
+
+export interface SynthOptions extends MonophonicOptions {
+	oscillator: OmniOscillatorSynthOptions;
+	envelope: Omit<EnvelopeOptions, keyof ToneAudioNodeOptions>;
+}
+
+/**
+ * Synth is composed simply of a [[OmniOscillator]] routed through an [[AmplitudeEnvelope]].
+ * ```
+ * +----------------+   +-------------------+
+ * | OmniOscillator +>--> AmplitudeEnvelope +>--> Output
+ * +----------------+   +-------------------+
+ * ```
+ * @example
+ * const synth = new Tone.Synth().toDestination();
+ * synth.triggerAttackRelease("C4", "8n");
+ * @category Instrument
+ */
+export class Synth<Options extends SynthOptions = SynthOptions> extends Monophonic<Options> {
+
+	readonly name: string = "Synth";
+
+	/**
+	 * The oscillator.
+	 */
+	readonly oscillator: OmniOscillator<any>;
+
+	/**
+	 * The frequency signal
+	 */
+	readonly frequency: Signal<"frequency">;
+
+	/**
+	 * The detune signal
+	 */
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * The envelope
+	 */
+	readonly envelope: AmplitudeEnvelope;
+
+	/**
+	 * @param options the options available for the synth.
+	 */
+	constructor(options?: RecursivePartial<SynthOptions>);
+	constructor() {
+		super(optionsFromArguments(Synth.getDefaults(), arguments));
+		const options = optionsFromArguments(Synth.getDefaults(), arguments);
+
+		this.oscillator = new OmniOscillator(Object.assign({
+			context: this.context,
+			detune: options.detune,
+			onstop: () => this.onsilence(this),
+		}, options.oscillator));
+
+		this.frequency = this.oscillator.frequency;
+		this.detune = this.oscillator.detune;
+
+		this.envelope = new AmplitudeEnvelope(Object.assign({
+			context: this.context,
+		}, options.envelope));
+
+		// connect the oscillators to the output
+		this.oscillator.chain(this.envelope, this.output);
+		readOnly(this, ["oscillator", "frequency", "detune", "envelope"]);
+	}
+
+	static getDefaults(): SynthOptions {
+		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.3,
+				},
+			),
+			oscillator: Object.assign(
+				omitFromObject(OmniOscillator.getDefaults(), [...Object.keys(Source.getDefaults()), "frequency", "detune"]),
+				{
+					type: "triangle",
+				},
+			) as OmniOscillatorOptions,
+		});
+	}
+
+	/**
+	 * 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: number): void {
+		// the envelopes
+		this.envelope.triggerAttack(time, velocity);
+		this.oscillator.start(time);
+		// if there is no release portion, stop the oscillator
+		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.oscillator.stop(time + this.toSeconds(this.envelope.release));
+	}
+
+	getLevelAtTime(time: Time): NormalRange {
+		time = this.toSeconds(time);
+		return this.envelope.getValueAtTime(time);
+	}
+
+	/**
+	 * clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		this.oscillator.dispose();
+		this.envelope.dispose();
+		return this;
+	}
+}

package/Tone/instrument/index.ts

@@ -0,0 +1,11 @@
+export * from "./AMSynth";
+export * from "./DuoSynth";
+export * from "./FMSynth";
+export * from "./MetalSynth";
+export * from "./MembraneSynth";
+export * from "./MonoSynth";
+export * from "./NoiseSynth";
+export * from "./PluckSynth";
+export * from "./PolySynth";
+export * from "./Sampler";
+export * from "./Synth";

package/Tone/signal/Abs.test.ts

@@ -0,0 +1,42 @@
+import { BasicTests } from "test/helper/Basic";
+import { connectFrom, connectTo } from "test/helper/Connect";
+import { ConstantOutput } from "test/helper/ConstantOutput";
+import { Abs } from "./Abs";
+import { Signal } from "./Signal";
+
+describe("Abs", () => {
+
+	BasicTests(Abs);
+
+	context("Absolute Value", () => {
+
+		it("outputs the same value for positive values", () => {
+			return ConstantOutput(() => {
+				const signal = new Signal(0.4);
+				const abs = new Abs();
+				signal.connect(abs);
+				abs.toDestination();
+			}, 0.4);
+		});
+
+		it("outputs 0 when the input is 0", () => {
+			return ConstantOutput(() => {
+				const signal = new Signal(0);
+				const abs = new Abs();
+				signal.connect(abs);
+				abs.toDestination();
+			}, 0);
+		});
+
+		it("outputs the absolute value for negative numbers", () => {
+			return ConstantOutput(() => {
+				const signal = new Signal(-0.3);
+				const abs = new Abs();
+				signal.connect(abs);
+				abs.toDestination();
+			}, 0.3);
+		});
+
+	});
+
+});

package/Tone/signal/Abs.ts

@@ -0,0 +1,53 @@
+import { ToneAudioNodeOptions } from "../core/context/ToneAudioNode";
+import { SignalOperator } from "./SignalOperator";
+import { WaveShaper } from "./WaveShaper";
+
+/**
+ * Return the absolute value of an incoming signal.
+ *
+ * @example
+ * return Tone.Offline(() => {
+ * 	const abs = new Tone.Abs().toDestination();
+ * 	const signal = new Tone.Signal(1);
+ * 	signal.rampTo(-1, 0.5);
+ * 	signal.connect(abs);
+ * }, 0.5, 1);
+ * @category Signal
+ */
+export class Abs extends SignalOperator<ToneAudioNodeOptions> {
+
+	readonly name: string = "Abs";
+
+	/**
+	 * The node which converts the audio ranges
+	 */
+	private _abs = new WaveShaper({
+		context: this.context,
+		mapping: val => {
+			if (Math.abs(val) < 0.001) {
+				return 0;
+			} else {
+				return Math.abs(val);
+			}
+		},
+	});
+
+	/**
+	 * The AudioRange input [-1, 1]
+	 */
+	input = this._abs;
+
+	/**
+	 * The output range [0, 1]
+	 */
+	output = this._abs;
+
+	/**
+	 * clean up
+	 */
+	dispose(): this {
+		super.dispose();
+		this._abs.dispose();
+		return this;
+	}
+}