tone 14.8.27

package/Tone/source/oscillator/OmniOscillator.ts

@@ -0,0 +1,428 @@
+import { Cents, Degrees, Frequency, Seconds, Time } from "../../core/type/Units";
+import { optionsFromArguments } from "../../core/util/Defaults";
+import { readOnly } from "../../core/util/Interface";
+import { isNumber, isString } from "../../core/util/TypeCheck";
+import { Signal } from "../../signal/Signal";
+import { Source } from "../Source";
+import { AMOscillator } from "./AMOscillator";
+import { FatOscillator } from "./FatOscillator";
+import { FMOscillator } from "./FMOscillator";
+import { Oscillator } from "./Oscillator";
+import {
+	generateWaveform,
+	OmniOscillatorOptions, 
+	OmniOscillatorType, ToneOscillatorInterface, ToneOscillatorType
+} from "./OscillatorInterface";
+import { PulseOscillator } from "./PulseOscillator";
+import { PWMOscillator } from "./PWMOscillator";
+
+export { OmniOscillatorOptions } from "./OscillatorInterface";
+
+/**
+ * All of the oscillator types that OmniOscillator can take on
+ */
+type AnyOscillator = Oscillator | PWMOscillator | PulseOscillator | FatOscillator | AMOscillator | FMOscillator;
+
+/**
+ * All of the Oscillator constructor types mapped to their name.
+ */
+interface OmniOscillatorSource {
+	"fm": FMOscillator;
+	"am": AMOscillator;
+	"pwm": PWMOscillator;
+	"pulse": PulseOscillator;
+	"oscillator": Oscillator;
+	"fat": FatOscillator;
+}
+
+/**
+ * The available oscillator types.
+ */
+export type OmniOscSourceType = keyof OmniOscillatorSource;
+
+// Conditional Types
+type IsAmOrFmOscillator<Osc, Ret> = Osc extends AMOscillator ? Ret : Osc extends FMOscillator ? Ret : undefined;
+type IsFatOscillator<Osc, Ret> = Osc extends FatOscillator ? Ret : undefined;
+type IsPWMOscillator<Osc, Ret> = Osc extends PWMOscillator ? Ret : undefined;
+type IsPulseOscillator<Osc, Ret> = Osc extends PulseOscillator ? Ret : undefined;
+type IsFMOscillator<Osc, Ret> = Osc extends FMOscillator ? Ret : undefined;
+
+type AnyOscillatorConstructor = new (...args: any[]) => AnyOscillator;
+
+const OmniOscillatorSourceMap: {
+	[key in OmniOscSourceType]: AnyOscillatorConstructor
+} = {
+	am: AMOscillator,
+	fat: FatOscillator,
+	fm: FMOscillator,
+	oscillator: Oscillator,
+	pulse: PulseOscillator,
+	pwm: PWMOscillator,
+};
+
+/**
+ * OmniOscillator aggregates all of the oscillator types into one. 
+ * @example
+ * return Tone.Offline(() => {
+ * 	const omniOsc = new Tone.OmniOscillator("C#4", "pwm").toDestination().start();
+ * }, 0.1, 1);
+ * @category Source
+ */
+export class OmniOscillator<OscType extends AnyOscillator>
+	extends Source<OmniOscillatorOptions>
+	implements Omit<ToneOscillatorInterface, "type"> {
+
+	readonly name: string = "OmniOscillator";
+
+	readonly frequency: Signal<"frequency">;
+	readonly detune: Signal<"cents">;
+
+	/**
+	 * The oscillator that can switch types
+	 */
+	private _oscillator!: AnyOscillator;
+
+	/**
+	 * the type of the oscillator source
+	 */
+	private _sourceType!: OmniOscSourceType;
+
+	/**
+	 * @param frequency The initial frequency of the oscillator.
+	 * @param type The type of the oscillator.
+	 */
+	constructor(frequency?: Frequency, type?: OmniOscillatorType);
+	constructor(options?: Partial<OmniOscillatorOptions>);
+	constructor() {
+
+		super(optionsFromArguments(OmniOscillator.getDefaults(), arguments, ["frequency", "type"]));
+		const options = optionsFromArguments(OmniOscillator.getDefaults(), arguments, ["frequency", "type"]);
+
+		this.frequency = new Signal({
+			context: this.context,
+			units: "frequency",
+			value: options.frequency,
+		});
+		this.detune = new Signal({
+			context: this.context,
+			units: "cents",
+			value: options.detune,
+		});
+		readOnly(this, ["frequency", "detune"]);
+
+		// set the options
+		this.set(options);
+	}
+
+	static getDefaults(): OmniOscillatorOptions {
+		return Object.assign(
+			Oscillator.getDefaults(),
+			FMOscillator.getDefaults(),
+			AMOscillator.getDefaults(),
+			FatOscillator.getDefaults(),
+			PulseOscillator.getDefaults(),
+			PWMOscillator.getDefaults(),
+		);
+	}
+
+	/**
+	 * start the oscillator
+	 */
+	protected _start(time: Time): void {
+		this._oscillator.start(time);
+	}
+
+	/**
+	 * start the oscillator
+	 */
+	protected _stop(time: Time): void {
+		this._oscillator.stop(time);
+	}
+
+	protected _restart(time: Seconds): this {
+		this._oscillator.restart(time);
+		return this;
+	}
+
+	/**
+	 * The type of the oscillator. Can be any of the basic types: sine, square, triangle, sawtooth. Or
+	 * prefix the basic types with "fm", "am", or "fat" to use the FMOscillator, AMOscillator or FatOscillator
+	 * types. The oscillator could also be set to "pwm" or "pulse". All of the parameters of the
+	 * oscillator's class are accessible when the oscillator is set to that type, but throws an error
+	 * when it's not. 
+	 * @example
+	 * const omniOsc = new Tone.OmniOscillator().toDestination().start();
+	 * omniOsc.type = "pwm";
+	 * // modulationFrequency is parameter which is available
+	 * // only when the type is "pwm".
+	 * omniOsc.modulationFrequency.value = 0.5;
+	 */
+	get type(): OmniOscillatorType {
+		let prefix = "";
+		if (["am", "fm", "fat"].some(p => this._sourceType === p)) {
+			prefix = this._sourceType;
+		}
+		return prefix + this._oscillator.type as OmniOscillatorType;
+	}
+	set type(type) {
+		if (type.substr(0, 2) === "fm") {
+			this._createNewOscillator("fm");
+			this._oscillator = this._oscillator as FMOscillator;
+			this._oscillator.type = type.substr(2) as ToneOscillatorType;
+		} else if (type.substr(0, 2) === "am") {
+			this._createNewOscillator("am");
+			this._oscillator = this._oscillator as AMOscillator;
+			this._oscillator.type = type.substr(2) as ToneOscillatorType;
+		} else if (type.substr(0, 3) === "fat") {
+			this._createNewOscillator("fat");
+			this._oscillator = this._oscillator as FatOscillator;
+			this._oscillator.type = type.substr(3) as ToneOscillatorType;
+		} else if (type === "pwm") {
+			this._createNewOscillator("pwm");
+			this._oscillator = this._oscillator as PWMOscillator;
+		} else if (type === "pulse") {
+			this._createNewOscillator("pulse");
+		} else {
+			this._createNewOscillator("oscillator");
+			this._oscillator = this._oscillator as Oscillator;
+			this._oscillator.type = (type as ToneOscillatorType);
+		}
+	}
+
+	/**
+	 * The value is an empty array when the type is not "custom".
+	 * This is not available on "pwm" and "pulse" oscillator types.
+	 * See [[Oscillator.partials]]
+	 */
+	get partials(): number[] {
+		return this._oscillator.partials;
+	}
+	set partials(partials) {
+		if (!this._getOscType(this._oscillator, "pulse") && !this._getOscType(this._oscillator, "pwm")) {
+			this._oscillator.partials = partials;
+		}
+	}
+
+	get partialCount(): number {
+		return this._oscillator.partialCount;
+	}
+	set partialCount(partialCount) {
+		if (!this._getOscType(this._oscillator, "pulse") && !this._getOscType(this._oscillator, "pwm")) {
+			this._oscillator.partialCount = partialCount;
+		}
+	}
+
+	set(props: Partial<OmniOscillatorOptions>): this {
+		// make sure the type is set first
+		if (Reflect.has(props, "type") && props.type) {
+			this.type = props.type;
+		}
+		// then set the rest
+		super.set(props);
+		return this;
+	}
+
+	/**
+	 * connect the oscillator to the frequency and detune signals
+	 */
+	private _createNewOscillator(oscType: OmniOscSourceType): void {
+		if (oscType !== this._sourceType) {
+			this._sourceType = oscType;
+			const OscConstructor = OmniOscillatorSourceMap[oscType];
+			// short delay to avoid clicks on the change
+			const now = this.now();
+			if (this._oscillator) {
+				const oldOsc = this._oscillator;
+				oldOsc.stop(now);
+				// dispose the old one
+				this.context.setTimeout(() => oldOsc.dispose(), this.blockTime);
+			}
+			this._oscillator = new OscConstructor({
+				context: this.context,
+			});
+			this.frequency.connect(this._oscillator.frequency);
+			this.detune.connect(this._oscillator.detune);
+			this._oscillator.connect(this.output);
+			this._oscillator.onstop = () => this.onstop(this);
+			if (this.state === "started") {
+				this._oscillator.start(now);
+			}
+		}
+	}
+
+	get phase(): Degrees {
+		return this._oscillator.phase;
+	}
+	set phase(phase) {
+		this._oscillator.phase = phase;
+	}
+
+	/**
+	 * The source type of the oscillator.
+	 * @example
+	 * const omniOsc = new Tone.OmniOscillator(440, "fmsquare");
+	 * console.log(omniOsc.sourceType); // 'fm'
+	 */
+	get sourceType(): OmniOscSourceType {
+		return this._sourceType;
+	}
+	set sourceType(sType) {
+		// the basetype defaults to sine
+		let baseType = "sine";
+		if (this._oscillator.type !== "pwm" && this._oscillator.type !== "pulse") {
+			baseType = this._oscillator.type;
+		}
+
+		// set the type
+		if (sType === "fm") {
+			this.type = "fm" + baseType as OmniOscillatorType;
+		} else if (sType === "am") {
+			this.type = "am" + baseType as OmniOscillatorType;
+		} else if (sType === "fat") {
+			this.type = "fat" + baseType as OmniOscillatorType;
+		} else if (sType === "oscillator") {
+			this.type = baseType as OmniOscillatorType;
+		} else if (sType === "pulse") {
+			this.type = "pulse";
+		} else if (sType === "pwm") {
+			this.type = "pwm";
+		}
+	}
+
+	private _getOscType<SourceType extends OmniOscSourceType>(
+		osc: AnyOscillator,
+		sourceType: SourceType,
+	): osc is OmniOscillatorSource[SourceType] {
+		return osc instanceof OmniOscillatorSourceMap[sourceType];
+	}
+
+	/**
+	 * The base type of the oscillator. See [[Oscillator.baseType]]
+	 * @example
+	 * const omniOsc = new Tone.OmniOscillator(440, "fmsquare4");
+	 * console.log(omniOsc.sourceType, omniOsc.baseType, omniOsc.partialCount);
+	 */
+	get baseType(): OscillatorType | "pwm" | "pulse" {
+		return this._oscillator.baseType;
+	}
+	set baseType(baseType) {
+		if (!this._getOscType(this._oscillator, "pulse") &&
+			!this._getOscType(this._oscillator, "pwm") &&
+			baseType !== "pulse" && baseType !== "pwm") {
+			this._oscillator.baseType = baseType;
+		}
+	}
+
+	/**
+	 * The width of the oscillator when sourceType === "pulse".
+	 * See [[PWMOscillator.width]]
+	 */
+	get width(): IsPulseOscillator<OscType, Signal<"audioRange">> {
+		if (this._getOscType(this._oscillator, "pulse")) {
+			return this._oscillator.width as IsPulseOscillator<OscType, Signal<"audioRange">>;
+		} else {
+			return undefined as IsPulseOscillator<OscType, Signal<"audioRange">>;
+		}
+	}
+
+	/**
+	 * The number of detuned oscillators when sourceType === "fat".
+	 * See [[FatOscillator.count]]
+	 */
+	get count(): IsFatOscillator<OscType, number> {
+		if (this._getOscType(this._oscillator, "fat")) {
+			return this._oscillator.count as IsFatOscillator<OscType, number>;
+		} else {
+			return undefined as IsFatOscillator<OscType, number>;
+		}
+	}
+	set count(count) {
+		if (this._getOscType(this._oscillator, "fat") && isNumber(count)) {
+			this._oscillator.count = count;
+		}
+	}
+
+	/**
+	 * The detune spread between the oscillators when sourceType === "fat".
+	 * See [[FatOscillator.count]]
+	 */
+	get spread(): IsFatOscillator<OscType, Cents> {
+		if (this._getOscType(this._oscillator, "fat")) {
+			return this._oscillator.spread as IsFatOscillator<OscType, Cents>;
+		} else {
+			return undefined as IsFatOscillator<OscType, Cents>;
+		}
+	}
+	set spread(spread) {
+		if (this._getOscType(this._oscillator, "fat") && isNumber(spread)) {
+			this._oscillator.spread = spread;
+		}
+	}
+
+	/**
+	 * The type of the modulator oscillator. Only if the oscillator is set to "am" or "fm" types. 
+	 * See [[AMOscillator]] or [[FMOscillator]]
+	 */
+	get modulationType(): IsAmOrFmOscillator<OscType, ToneOscillatorType> {
+		if (this._getOscType(this._oscillator, "fm") || this._getOscType(this._oscillator, "am")) {
+			return this._oscillator.modulationType as IsAmOrFmOscillator<OscType, ToneOscillatorType>;
+		} else {
+			return undefined as IsAmOrFmOscillator<OscType, ToneOscillatorType>;
+		}
+	}
+	set modulationType(mType) {
+		if ((this._getOscType(this._oscillator, "fm") || this._getOscType(this._oscillator, "am")) && isString(mType)) {
+			this._oscillator.modulationType = mType;
+		}
+	}
+
+	/**
+	 * The modulation index when the sourceType === "fm"
+	 * See [[FMOscillator]].
+	 */
+	get modulationIndex(): IsFMOscillator<OscType, Signal<"positive">> {
+		if (this._getOscType(this._oscillator, "fm")) {
+			return this._oscillator.modulationIndex as IsFMOscillator<OscType, Signal<"positive">>;
+		} else {
+			return undefined as IsFMOscillator<OscType, Signal<"positive">>;
+		}
+	}
+
+	/**
+	 * Harmonicity is the frequency ratio between the carrier and the modulator oscillators.
+	 * See [[AMOscillator]] or [[FMOscillator]]
+	 */
+	get harmonicity(): IsAmOrFmOscillator<OscType, Signal<"positive">> {
+		if (this._getOscType(this._oscillator, "fm") || this._getOscType(this._oscillator, "am")) {
+			return this._oscillator.harmonicity as IsAmOrFmOscillator<OscType, Signal<"positive">>;
+		} else {
+			return undefined as IsAmOrFmOscillator<OscType, Signal<"positive">>;
+		}
+	}
+
+	/**
+	 * The modulationFrequency Signal of the oscillator when sourceType === "pwm"
+	 * see [[PWMOscillator]]
+	 * @min 0.1
+	 * @max 5
+	 */
+	get modulationFrequency(): IsPWMOscillator<OscType, Signal<"frequency">> {
+		if (this._getOscType(this._oscillator, "pwm")) {
+			return this._oscillator.modulationFrequency as IsPWMOscillator<OscType, Signal<"frequency">>;
+		} else {
+			return undefined as IsPWMOscillator<OscType, Signal<"frequency">>;
+		}
+	}
+
+	async asArray(length = 1024): Promise<Float32Array> {
+		return generateWaveform(this, length);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.detune.dispose();
+		this.frequency.dispose();
+		this._oscillator.dispose();
+		return this;
+	}
+}

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

@@ -0,0 +1,278 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Offline } from "test/helper/Offline";
+import { OscillatorTests } from "test/helper/OscillatorTests";
+import { OutputAudio } from "test/helper/OutputAudio";
+import { SourceTests } from "test/helper/SourceTests";
+import { Oscillator } from "./Oscillator";
+import { ToneOscillatorType } from "./OscillatorInterface";
+
+describe("Oscillator", () => {
+
+	// run the common tests
+	BasicTests(Oscillator);
+	SourceTests(Oscillator);
+	OscillatorTests(Oscillator);
+
+	it("matches a file", () => {
+		return CompareToFile(() => {
+			const osc = new Oscillator().toDestination();
+			osc.type = "square";
+			osc.start(0).stop(0.2);
+		}, "oscillator.wav", 0.1);
+	});
+
+	context("Get/Set", () => {
+
+		it("can be set with an options object", () => {
+			const osc = new Oscillator();
+			osc.set({
+				detune: -21,
+				frequency: 231,
+				type: "square",
+			});
+			expect(osc.frequency.value).to.equal(231);
+			expect(osc.detune.value).to.equal(-21);
+			expect(osc.type).to.equal("square");
+			osc.dispose();
+		});
+
+		it("can be get the values as an object", () => {
+			const osc = new Oscillator(450, "square");
+			expect(osc.get().frequency).to.equal(450);
+			expect(osc.get().type).to.equal("square");
+			osc.dispose();
+		});
+	});
+
+	context("Phase Rotation", () => {
+		it("can change the phase to 90", () => {
+			return Offline(() => {
+				const instance = new Oscillator({
+					frequency: 1,
+					phase: 90,
+				});
+				instance.toDestination();
+				instance.start(0);
+			}, 1).then((buffer) => {
+				buffer.forEach((sample, time) => {
+					if (time < 0.25) {
+						expect(sample).to.be.within(-1, 0);
+					} else if (time > 0.25 && time < 0.5) {
+						expect(sample).to.be.within(0, 1);
+					}
+				});
+			});
+		});
+
+		it("can change the phase to -90", () => {
+			return Offline(() => {
+				const instance = new Oscillator({
+					frequency: 1,
+					phase: 270,
+				});
+				instance.toDestination();
+				instance.start(0);
+			}, 1).then((buffer) => {
+				buffer.forEach((sample, time) => {
+					if (time < 0.25) {
+						expect(sample).to.be.within(0, 1);
+					} else if (time > 0.25 && time < 0.5) {
+						expect(sample).to.be.within(-1, 0);
+					}
+				});
+			});
+		});
+
+		it("can go past the cache max size of 100", () => {
+			const osc = new Oscillator();
+			for (let i = 0; i < 110; i++) {
+				osc.phase = i;
+			}
+			osc.dispose();
+		});
+
+	});
+
+	context("Type", () => {
+
+		it("can get and set the type", () => {
+			const osc = new Oscillator({
+				type: "sawtooth",
+			});
+			expect(osc.type).to.equal("sawtooth");
+			osc.dispose();
+		});
+
+		it("can set the type after starting", () => {
+			const osc = new Oscillator(110, "sawtooth10").start();
+			expect(osc.type).to.equal("sawtooth10");
+			osc.type = "sawtooth20";
+			expect(osc.type).to.equal("sawtooth20");
+			osc.dispose();
+		});
+
+		it("handles 4 basic types", () => {
+			const osc = new Oscillator();
+			const types: ToneOscillatorType[] = ["triangle", "sawtooth", "sine", "square"];
+			for (const type of types) {
+				osc.type = type;
+				expect(osc.type).to.equal(type);
+			}
+			osc.dispose();
+		});
+
+		it("throws an error if invalid type is set", () => {
+			const osc = new Oscillator();
+			expect(() => {
+				// @ts-ignore
+				osc.type = "invalid";
+			}).to.throw(Error);
+			osc.dispose();
+		});
+
+		it("can set extended types", () => {
+			const osc = new Oscillator();
+			osc.type = "sine5";
+			expect(osc.type).to.equal("sine5");
+			osc.type = "triangle2";
+			expect(osc.type).to.equal("triangle2");
+			osc.dispose();
+		});
+
+		it("can get/set the baseType", () => {
+			const osc = new Oscillator();
+			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();
+		});
+	});
+
+	context("Partials", () => {
+
+		it("can pass partials in the constructor", () => {
+			const osc = new Oscillator({
+				partials: [1, 0.3, 0.3],
+				type: "custom",
+			});
+			expect(osc.type).to.equal("custom");
+			expect(osc.partials[1]).to.equal(0.3);
+			osc.dispose();
+		});
+
+		it("can set partials", () => {
+			const osc = new Oscillator();
+			osc.partials = [1, 0.2, 0.2, 0.2];
+			expect(osc.type).to.equal("custom");
+			expect(osc.partials[1]).to.equal(0.2);
+			osc.dispose();
+		});
+
+		it("makes a sound with custom partials", () => {
+			return OutputAudio(() => {
+				const osc = new Oscillator().toDestination().start();
+				osc.partials = [1, 0.2, 0.2, 0.2];
+			});
+		});
+
+		it("outputs the partials of the given waveform", () => {
+			const osc = new Oscillator();
+			osc.type = "sine2";
+			expect(osc.type).to.equal("sine2");
+			expect(osc.partials.length).to.equal(2);
+			expect(osc.partials).to.deep.equal([1, 1]);
+			osc.dispose();
+		});
+
+		it("partialCount is 0 when set to max", () => {
+			const osc = new Oscillator();
+			expect(osc.partialCount).to.equal(0);
+			osc.type = "square32";
+			expect(osc.partialCount).to.equal(32);
+			osc.type = "square";
+			expect(osc.partialCount).to.equal(0);
+			osc.dispose();
+		});
+
+		it("can pass in number of partials into constructor", () => {
+			const osc = new Oscillator({
+				partialCount: 3,
+				type: "sine",
+			});
+			expect(osc.type).to.equal("sine3");
+			expect(osc.partialCount).to.equal(3);
+			osc.partialCount = 4;
+			expect(osc.partialCount).to.equal(4);
+			expect(osc.type).to.equal("sine4");
+			osc.dispose();
+		});
+
+	});
+
+	context("Synchronization", () => {
+		it("can sync the frequency to the Transport", () => {
+			return Offline(({ transport }) => {
+				transport.bpm.value = 120;
+				const osc = new Oscillator(2);
+				osc.frequency.toDestination();
+				osc.syncFrequency();
+				transport.bpm.value = 240;
+			}).then((buffer) => {
+				expect(buffer.value()).to.be.closeTo(4, 0.001);
+			});
+		});
+
+		it("can unsync the frequency from the Transport", () => {
+			return Offline(({ transport }) => {
+				transport.bpm.value = 120;
+				const osc = new Oscillator(2);
+				osc.frequency.toDestination();
+				osc.syncFrequency();
+				transport.bpm.value = 240;
+				osc.unsyncFrequency();
+			}).then((buffer) => {
+				expect(buffer.value()).to.be.closeTo(2, 0.001);
+			});
+		});
+	});
+
+	context("initialValue", () => {
+		it("can get the initial value of a basic oscillator type", () => {
+			const osc = new Oscillator(10, "sine");
+			expect(osc.getInitialValue()).to.be.closeTo(0, 0.01);
+			osc.dispose();
+		});
+
+		it("can get the initial value when the phase is rotated", () => {
+			const osc = new Oscillator({
+				phase: 90,
+				type: "sine",
+			});
+			expect(osc.getInitialValue()).to.be.closeTo(-1, 0.01);
+			osc.dispose();
+		});
+
+		it("can get the initial value of more complex types", () => {
+			const osc = new Oscillator({
+				partials: [0, 2, 4, 1, 3],
+				phase: 145,
+				type: "custom",
+			});
+			expect(osc.getInitialValue()).to.be.closeTo(-0.2, 0.05);
+			osc.dispose();
+		});
+	});
+
+});