tone 14.8.27

package/Tone/source/buffer/ToneBufferSource.ts

@@ -0,0 +1,253 @@
+import { connect } from "../../core/context/ToneAudioNode";
+import { Param } from "../../core/context/Param";
+import { ToneAudioBuffer } from "../../core/context/ToneAudioBuffer";
+import { GainFactor, Positive, Seconds, Time } from "../../core/type/Units";
+import { defaultArg, optionsFromArguments } from "../../core/util/Defaults";
+import { noOp } from "../../core/util/Interface";
+import { isDefined } from "../../core/util/TypeCheck";
+import { assert } from "../../core/util/Debug";
+import { OneShotSource, OneShotSourceCurve, OneShotSourceOptions } from "../OneShotSource";
+import { EQ, GTE, LT } from "../../core/util/Math";
+
+export type ToneBufferSourceCurve = OneShotSourceCurve;
+
+export interface ToneBufferSourceOptions extends OneShotSourceOptions {
+	url: string | AudioBuffer | ToneAudioBuffer;
+	curve: ToneBufferSourceCurve;
+	playbackRate: Positive;
+	fadeIn: Time;
+	fadeOut: Time;
+	loopStart: Time;
+	loopEnd: Time;
+	loop: boolean;
+	onload: () => void;
+	onerror: (error: Error) => void;
+}
+
+/**
+ * Wrapper around the native BufferSourceNode.
+ * @category Source
+ */
+export class ToneBufferSource extends OneShotSource<ToneBufferSourceOptions> {
+
+	readonly name: string = "ToneBufferSource";
+
+	/**
+	 * The oscillator
+	 */
+	private _source = this.context.createBufferSource();
+	protected _internalChannels = [this._source];
+
+	/**
+	 * The frequency of the oscillator
+	 */
+	readonly playbackRate: Param<"positive">;
+
+	/**
+	 * The private instance of the buffer object
+	 */
+	private _buffer: ToneAudioBuffer;
+
+	/**
+	 * indicators if the source has started/stopped
+	 */
+	private _sourceStarted = false;
+	private _sourceStopped = false;
+
+	/**
+	 * @param url The buffer to play or url to load
+	 * @param onload The callback to invoke when the buffer is done playing.
+	 */
+	constructor(url?: ToneAudioBuffer | AudioBuffer | string, onload?: () => void);
+	constructor(options?: Partial<ToneBufferSourceOptions>);
+	constructor() {
+
+		super(optionsFromArguments(ToneBufferSource.getDefaults(), arguments, ["url", "onload"]));
+		const options = optionsFromArguments(ToneBufferSource.getDefaults(), arguments, ["url", "onload"]);
+
+		connect(this._source, this._gainNode);
+		this._source.onended = () => this._stopSource();
+
+		/**
+		 * The playbackRate of the buffer
+		 */
+		this.playbackRate = new Param({
+			context: this.context,
+			param: this._source.playbackRate,
+			units: "positive",
+			value: options.playbackRate,
+		});
+
+		// set some values initially
+		this.loop = options.loop;
+		this.loopStart = options.loopStart;
+		this.loopEnd = options.loopEnd;
+		this._buffer = new ToneAudioBuffer(options.url, options.onload, options.onerror);
+
+		this._internalChannels.push(this._source);
+	}
+
+	static getDefaults(): ToneBufferSourceOptions {
+		return Object.assign(OneShotSource.getDefaults(), {
+			url: new ToneAudioBuffer(),
+			loop: false,
+			loopEnd: 0,
+			loopStart: 0,
+			onload: noOp,
+			onerror: noOp,
+			playbackRate: 1,
+		});
+	}
+
+	/**
+	 * The fadeIn time of the amplitude envelope.
+	 */
+	get fadeIn(): Time {
+		return this._fadeIn;
+	}
+	set fadeIn(t: Time) {
+		this._fadeIn = t;
+	}
+
+	/**
+	 * The fadeOut time of the amplitude envelope.
+	 */
+	get fadeOut(): Time {
+		return this._fadeOut;
+	}
+	set fadeOut(t: Time) {
+		this._fadeOut = t;
+	}
+
+	/**
+	 * The curve applied to the fades, either "linear" or "exponential"
+	 */
+	get curve(): ToneBufferSourceCurve {
+		return this._curve;
+	}
+	set curve(t) {
+		this._curve = t;
+	}
+
+	/**
+	 * Start the buffer
+	 * @param  time When the player should start.
+	 * @param  offset The offset from the beginning of the sample to start at.
+	 * @param  duration How long the sample should play. If no duration is given, it will default to the full length of the sample (minus any offset)
+	 * @param  gain  The gain to play the buffer back at.
+	 */
+	start(time?: Time, offset?: Time, duration?: Time, gain: GainFactor = 1): this {
+		assert(this.buffer.loaded, "buffer is either not set or not loaded");
+		const computedTime = this.toSeconds(time);
+
+		// apply the gain envelope
+		this._startGain(computedTime, gain);
+
+		// if it's a loop the default offset is the loopstart point
+		if (this.loop) {
+			offset = defaultArg(offset, this.loopStart);
+		} else {
+			// otherwise the default offset is 0
+			offset = defaultArg(offset, 0);
+		}
+		// make sure the offset is not less than 0
+		let computedOffset = Math.max(this.toSeconds(offset), 0);
+
+		// start the buffer source
+		if (this.loop) {
+			// modify the offset if it's greater than the loop time
+			const loopEnd = this.toSeconds(this.loopEnd) || this.buffer.duration;
+			const loopStart = this.toSeconds(this.loopStart);
+			const loopDuration = loopEnd - loopStart;
+			// move the offset back
+			if (GTE(computedOffset, loopEnd)) {
+				computedOffset = ((computedOffset - loopStart) % loopDuration) + loopStart;
+			}
+			// when the offset is very close to the duration, set it to 0
+			if (EQ(computedOffset, this.buffer.duration)) {
+				computedOffset = 0;
+			}
+		}
+		
+		// this.buffer.loaded would have return false if the AudioBuffer was undefined
+		this._source.buffer = this.buffer.get() as AudioBuffer;
+		this._source.loopEnd = this.toSeconds(this.loopEnd) || this.buffer.duration;
+		if (LT(computedOffset, this.buffer.duration)) {
+			this._sourceStarted = true;
+			this._source.start(computedTime, computedOffset);
+		}
+
+		// if a duration is given, schedule a stop
+		if (isDefined(duration)) {
+			let computedDur = this.toSeconds(duration);
+			// make sure it's never negative
+			computedDur = Math.max(computedDur, 0);
+			this.stop(computedTime + computedDur);
+		}
+
+		return this;
+	}
+
+	protected _stopSource(time?: Seconds): void {
+		if (!this._sourceStopped && this._sourceStarted) {
+			this._sourceStopped = true;
+			this._source.stop(this.toSeconds(time));
+			this._onended();
+		}
+	}
+
+	/**
+	 * If loop is true, the loop will start at this position.
+	 */
+	get loopStart(): Time {
+		return this._source.loopStart;
+	}
+	set loopStart(loopStart: Time) {
+		this._source.loopStart = this.toSeconds(loopStart);
+	}
+
+	/**
+	 * If loop is true, the loop will end at this position.
+	 */
+	get loopEnd(): Time {
+		return this._source.loopEnd;
+	}
+	set loopEnd(loopEnd: Time) {
+		this._source.loopEnd = this.toSeconds(loopEnd);
+	}
+
+	/**
+	 * The audio buffer belonging to the player.
+	 */
+	get buffer(): ToneAudioBuffer {
+		return this._buffer;
+	}
+	set buffer(buffer: ToneAudioBuffer) {
+		this._buffer.set(buffer);
+	}
+
+	/**
+	 * If the buffer should loop once it's over.
+	 */
+	get loop(): boolean {
+		return this._source.loop;
+	}
+	set loop(loop: boolean) {
+		this._source.loop = loop;
+		if (this._sourceStarted) {
+			this.cancelStop();
+		}
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this._source.onended = null;
+		this._source.disconnect();
+		this._buffer.dispose();
+		this.playbackRate.dispose();
+		return this;
+	}
+}

package/Tone/source/index.ts

@@ -0,0 +1,15 @@
+export * from "./Noise";
+export * from "./UserMedia";
+export * from "./oscillator/Oscillator";
+export * from "./oscillator/AMOscillator";
+export * from "./oscillator/FMOscillator";
+export * from "./oscillator/PulseOscillator";
+export * from "./oscillator/FatOscillator";
+export * from "./oscillator/PWMOscillator";
+export * from "./oscillator/OmniOscillator";
+export * from "./oscillator/ToneOscillatorNode";
+export * from "./oscillator/LFO";
+export * from "./buffer/ToneBufferSource";
+export * from "./buffer/Player";
+export * from "./buffer/Players";
+export * from "./buffer/GrainPlayer";

package/Tone/source/oscillator/AMOscillator.test.ts

@@ -0,0 +1,69 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { OscillatorTests } from "test/helper/OscillatorTests";
+import { SourceTests } from "test/helper/SourceTests";
+import { AMOscillator } from "./AMOscillator";
+
+describe("AMOscillator", () => {
+
+	// run the common tests
+	BasicTests(AMOscillator);
+	SourceTests(AMOscillator);
+	OscillatorTests(AMOscillator);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const osc = new AMOscillator().toDestination();
+			osc.start(0.1).stop(0.4);
+		}, "amOscillator.wav", 0.03);
+	});
+
+	context("Amplitude Modulation", () => {
+
+		it("can pass in parameters in the constructor", () => {
+			const amOsc = new AMOscillator({
+				harmonicity: 3,
+				modulationType: "square3",
+				type: "triangle2",
+			});
+			expect(amOsc.type).to.equal("triangle2");
+			expect(amOsc.harmonicity.value).to.be.closeTo(3, 0.001);
+			expect(amOsc.modulationType).to.equal("square3");
+			amOsc.dispose();
+		});
+
+		it("can set the harmonicity", () => {
+			const amOsc = new AMOscillator();
+			amOsc.harmonicity.value = 0.2;
+			expect(amOsc.harmonicity.value).to.be.closeTo(0.2, 0.001);
+			amOsc.dispose();
+		});
+
+		it("can set the modulationType", () => {
+			const amOsc = new AMOscillator();
+			amOsc.modulationType = "triangle5";
+			expect(amOsc.modulationType).to.equal("triangle5");
+			amOsc.dispose();
+		});
+
+		it("can get/set the baseType", () => {
+			const osc = new AMOscillator();
+			osc.type = "sine5";
+			expect(osc.baseType).to.equal("sine");
+			osc.baseType = "triangle";
+			expect(osc.type).to.equal("triangle5");
+			expect(osc.partialCount).to.equal(5);
+			osc.partialCount = 2;
+			expect(osc.type).to.equal("triangle2");
+			osc.baseType = "custom";
+			expect(osc.type).to.equal("custom");
+			osc.partials = [1, 2, 3];
+			expect(osc.baseType).to.equal("custom");
+			expect(osc.partials).to.deep.equal([1, 2, 3]);
+			osc.baseType = "square";
+			expect(osc.type).to.equal("square");
+			osc.dispose();
+		});
+	});
+});

package/Tone/source/oscillator/AMOscillator.ts

@@ -0,0 +1,222 @@
+import { Gain } from "../../core/context/Gain";
+import { Degrees, Frequency, Seconds } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { readOnly } from "../../core/util/Interface";
+import { AudioToGain } from "../../signal/AudioToGain";
+import { Multiply } from "../../signal/Multiply";
+import { Signal } from "../../signal/Signal";
+import { Source } from "../Source";
+import { Oscillator } from "./Oscillator";
+import {
+	AMConstructorOptions, AMOscillatorOptions,
+	generateWaveform, NonCustomOscillatorType,
+	ToneOscillatorInterface,
+	ToneOscillatorType
+} from "./OscillatorInterface";
+
+export { AMOscillatorOptions } from "./OscillatorInterface";
+
+/**
+ * An amplitude modulated oscillator node. It is implemented with
+ * two oscillators, one which modulators the other's amplitude
+ * through a gain node.
+ * ```
+ *    +-------------+       +----------+
+ *    | Carrier Osc +>------> GainNode |
+ *    +-------------+       |          +--->Output
+ *                      +---> gain     |
+ * +---------------+    |   +----------+
+ * | Modulator Osc +>---+
+ * +---------------+
+ * ```
+ * @example
+ * return Tone.Offline(() => {
+ * 	const amOsc = new Tone.AMOscillator(30, "sine", "square").toDestination().start();
+ * }, 0.2, 1);
+ * @category Source
+ */
+export class AMOscillator extends Source<AMOscillatorOptions> implements ToneOscillatorInterface {
+
+	readonly name: string = "AMOscillator";
+
+	/**
+	 * The carrier oscillator
+	 */
+	private _carrier: Oscillator;
+
+	readonly frequency: Signal<"frequency">;
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * The modulating oscillator
+	 */
+	private _modulator: Oscillator;
+
+	/**
+	 * convert the -1,1 output to 0,1
+	 */
+	private _modulationScale = new AudioToGain({ context: this.context });
+
+	/**
+	 * Harmonicity is the frequency ratio between the carrier and the modulator oscillators.
+	 * A harmonicity of 1 gives both oscillators the same frequency.
+	 * Harmonicity = 2 means a change of an octave.
+	 * @example
+	 * const amOsc = new Tone.AMOscillator("D2").toDestination().start();
+	 * Tone.Transport.scheduleRepeat(time => {
+	 * 	amOsc.harmonicity.setValueAtTime(1, time);
+	 * 	amOsc.harmonicity.setValueAtTime(0.5, time + 0.5);
+	 * 	amOsc.harmonicity.setValueAtTime(1.5, time + 1);
+	 * 	amOsc.harmonicity.setValueAtTime(1, time + 2);
+	 * 	amOsc.harmonicity.linearRampToValueAtTime(2, time + 4);
+	 * }, 4);
+	 * Tone.Transport.start();
+	 */
+	readonly harmonicity: Signal<"positive">;
+
+	/**
+	 * the node where the modulation happens
+	 */
+	private _modulationNode = new Gain({
+		context: this.context,
+	});
+
+	/**
+	 * @param frequency The starting frequency of the oscillator.
+	 * @param type The type of the carrier oscillator.
+	 * @param modulationType The type of the modulator oscillator.
+	 */
+	constructor(frequency?: Frequency, type?: ToneOscillatorType, modulationType?: ToneOscillatorType);
+	constructor(options?: Partial<AMConstructorOptions>);
+	constructor() {
+
+		super(optionsFromArguments(AMOscillator.getDefaults(), arguments, ["frequency", "type", "modulationType"]));
+		const options = optionsFromArguments(AMOscillator.getDefaults(), arguments, ["frequency", "type", "modulationType"]);
+
+		this._carrier = new Oscillator({
+			context: this.context,
+			detune: options.detune,
+			frequency: options.frequency,
+			onstop: () => this.onstop(this),
+			phase: options.phase,
+			type: options.type,
+		} as OscillatorOptions);
+		this.frequency = this._carrier.frequency,
+		this.detune = this._carrier.detune;
+
+		this._modulator = new Oscillator({
+			context: this.context,
+			phase: options.phase,
+			type: options.modulationType,
+		} as OscillatorOptions);
+
+		this.harmonicity = new Multiply({
+			context: this.context,
+			units: "positive",
+			value: options.harmonicity,
+		});
+
+		// connections
+		this.frequency.chain(this.harmonicity, this._modulator.frequency);
+		this._modulator.chain(this._modulationScale, this._modulationNode.gain);
+		this._carrier.chain(this._modulationNode, this.output);
+
+		readOnly(this, ["frequency", "detune", "harmonicity"]);
+	}
+
+	static getDefaults(): AMOscillatorOptions {
+		return Object.assign(Oscillator.getDefaults(), {
+			harmonicity: 1,
+			modulationType: "square" as NonCustomOscillatorType,
+		});
+	}
+
+	/**
+	 * start the oscillator
+	 */
+	protected _start(time: Seconds): void {
+		this._modulator.start(time);
+		this._carrier.start(time);
+	}
+
+	/**
+	 * stop the oscillator
+	 */
+	protected _stop(time: Seconds): void {
+		this._modulator.stop(time);
+		this._carrier.stop(time);
+	}
+
+	protected _restart(time: Seconds): void {
+		this._modulator.restart(time);
+		this._carrier.restart(time);
+	}
+
+	/**
+	 * The type of the carrier oscillator
+	 */
+	get type(): ToneOscillatorType {
+		return this._carrier.type;
+	}
+	set type(type: ToneOscillatorType) {
+		this._carrier.type = type;
+	}
+
+	get baseType(): OscillatorType {
+		return this._carrier.baseType;
+	}
+	set baseType(baseType: OscillatorType) {
+		this._carrier.baseType = baseType;
+	}
+
+	get partialCount(): number {
+		return this._carrier.partialCount;
+	}
+	set partialCount(partialCount: number) {
+		this._carrier.partialCount = partialCount;
+	}
+
+	/**
+	 * The type of the modulator oscillator
+	 */
+	get modulationType(): ToneOscillatorType {
+		return this._modulator.type;
+	}
+	set modulationType(type: ToneOscillatorType) {
+		this._modulator.type = type;
+	}
+
+	get phase(): Degrees {
+		return this._carrier.phase;
+	}
+	set phase(phase: Degrees) {
+		this._carrier.phase = phase;
+		this._modulator.phase = phase;
+	}
+
+	get partials(): number[] {
+		return this._carrier.partials;
+	}
+	set partials(partials: number[]) {
+		this._carrier.partials = partials;
+	}
+
+	async asArray(length = 1024): Promise<Float32Array> {
+		return generateWaveform(this, length);
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this.frequency.dispose();
+		this.detune.dispose();
+		this.harmonicity.dispose();
+		this._carrier.dispose();
+		this._modulator.dispose();
+		this._modulationNode.dispose();
+		this._modulationScale.dispose();
+		return this;
+	}
+}

package/Tone/source/oscillator/FMOscillator.test.ts

@@ -0,0 +1,85 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { connectFrom } from "test/helper/Connect";
+import { OscillatorTests } from "test/helper/OscillatorTests";
+import { SourceTests } from "test/helper/SourceTests";
+import { FMOscillator } from "./FMOscillator";
+
+describe("FMOscillator", () => {
+
+	// run the common tests
+	BasicTests(FMOscillator);
+	SourceTests(FMOscillator);
+	OscillatorTests(FMOscillator);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const osc = new FMOscillator().toDestination();
+			osc.start(0);
+		}, "fmOscillator.wav", 0.01);
+	});
+
+	context("Frequency Modulation", () => {
+
+		it("can pass in parameters in the constructor", () => {
+			const fmOsc = new FMOscillator({
+				harmonicity: 3,
+				modulationType: "square3",
+				type: "triangle2",
+			});
+			expect(fmOsc.type).to.equal("triangle2");
+			expect(fmOsc.harmonicity.value).to.be.closeTo(3, 0.001);
+			expect(fmOsc.modulationType).to.equal("square3");
+			fmOsc.dispose();
+		});
+
+		it("can set the harmonicity", () => {
+			const fmOsc = new FMOscillator();
+			fmOsc.harmonicity.value = 0.2;
+			expect(fmOsc.harmonicity.value).to.be.closeTo(0.2, 0.001);
+			fmOsc.dispose();
+		});
+
+		it("can set the modulationIndex", () => {
+			const fmOsc = new FMOscillator({
+				modulationIndex: 3,
+			});
+			expect(fmOsc.modulationIndex.value).to.be.closeTo(3, 0.001);
+			fmOsc.modulationIndex.value = 0.2;
+			expect(fmOsc.modulationIndex.value).to.be.closeTo(0.2, 0.001);
+			fmOsc.dispose();
+		});
+
+		it("can connect a signal to the harmonicity", () => {
+			const fmOsc = new FMOscillator();
+			connectFrom().connect(fmOsc.harmonicity);
+			fmOsc.dispose();
+		});
+
+		it("can set the modulationType", () => {
+			const fmOsc = new FMOscillator();
+			fmOsc.modulationType = "triangle5";
+			expect(fmOsc.modulationType).to.equal("triangle5");
+			fmOsc.dispose();
+		});
+
+		it("can get/set the baseType", () => {
+			const osc = new FMOscillator();
+			osc.type = "sine5";
+			expect(osc.baseType).to.equal("sine");
+			osc.baseType = "triangle";
+			expect(osc.type).to.equal("triangle5");
+			expect(osc.partialCount).to.equal(5);
+			osc.partialCount = 2;
+			expect(osc.type).to.equal("triangle2");
+			osc.baseType = "custom";
+			expect(osc.type).to.equal("custom");
+			osc.partials = [1, 2, 3];
+			expect(osc.baseType).to.equal("custom");
+			osc.baseType = "square";
+			expect(osc.type).to.equal("square");
+			osc.dispose();
+		});
+	});
+});