tone 14.8.27

package/Tone/signal/SyncedSignal.ts

@@ -0,0 +1,172 @@
+import { Signal, SignalOptions } from "./Signal";
+import { NormalRange, Seconds, Time, TransportTime, UnitMap, UnitName } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { TransportTimeClass } from "../core/type/TransportTime";
+import { ToneConstantSource } from "./ToneConstantSource";
+import { OutputNode } from "../core/context/ToneAudioNode";
+
+/**
+ * Adds the ability to synchronize the signal to the [[Transport]]
+ */
+export class SyncedSignal<TypeName extends UnitName = "number"> extends Signal<TypeName> {
+
+	readonly name: string = "SyncedSignal";
+	
+	/**
+	 * Don't override when something is connected to the input
+	 */
+	readonly override = false;
+
+	readonly output: OutputNode;
+
+	/**
+	 * Keep track of the last value as an optimization.
+	 */
+	private _lastVal: UnitMap[TypeName];
+
+	/**
+	 * The ID returned from scheduleRepeat
+	 */
+	private _synced: number;
+
+	/**
+	 * Remember the callback value
+	 */
+	private _syncedCallback: () => void;
+
+	/**
+	 * @param value Initial value of the signal
+	 * @param units The unit name, e.g. "frequency"
+	 */
+	constructor(value?: UnitMap[TypeName], units?: TypeName);
+	constructor(options?: Partial<SignalOptions<TypeName>>);
+	constructor() {
+
+		super(optionsFromArguments(Signal.getDefaults(), arguments, ["value", "units"]));
+		const options = optionsFromArguments(Signal.getDefaults(), arguments, ["value", "units"]) as SignalOptions<TypeName>;
+
+		this._lastVal = options.value;
+		this._synced = this.context.transport.scheduleRepeat(this._onTick.bind(this), "1i");
+
+		this._syncedCallback = this._anchorValue.bind(this);
+		this.context.transport.on("start", this._syncedCallback);
+		this.context.transport.on("pause", this._syncedCallback);
+		this.context.transport.on("stop", this._syncedCallback);
+
+		// disconnect the constant source from the output and replace it with another one
+		this._constantSource.disconnect();
+		this._constantSource.stop(0);
+
+		// create a new one
+		this._constantSource = this.output = new ToneConstantSource<TypeName>({ 
+			context: this.context,
+			offset: options.value,
+			units: options.units,
+		}).start(0);
+		this.setValueAtTime(options.value, 0);
+	}
+
+	/**
+	 * Callback which is invoked every tick.
+	 */
+	private _onTick(time: Seconds): void {
+		const val = super.getValueAtTime(this.context.transport.seconds);
+		// approximate ramp curves with linear ramps
+		if (this._lastVal !== val) {
+			this._lastVal = val;
+			this._constantSource.offset.setValueAtTime(val, time);
+		}
+	}
+
+	/**
+	 * Anchor the value at the start and stop of the Transport
+	 */
+	private _anchorValue(time: Seconds): void {
+		const val = super.getValueAtTime(this.context.transport.seconds);
+		this._lastVal = val;
+		this._constantSource.offset.cancelAndHoldAtTime(time);
+		this._constantSource.offset.setValueAtTime(val, time);
+	}
+
+	getValueAtTime(time: TransportTime): UnitMap[TypeName] {
+		const computedTime = new TransportTimeClass(this.context, time).toSeconds();
+		return super.getValueAtTime(computedTime);
+	}
+	
+	setValueAtTime(value: UnitMap[TypeName], time: TransportTime) {
+		const computedTime = new TransportTimeClass(this.context, time).toSeconds();
+		super.setValueAtTime(value, computedTime);
+		return this;
+	}
+
+	linearRampToValueAtTime(value: UnitMap[TypeName], time: TransportTime) {
+		const computedTime = new TransportTimeClass(this.context, time).toSeconds();
+		super.linearRampToValueAtTime(value, computedTime);
+		return this;
+	}
+
+	exponentialRampToValueAtTime(value: UnitMap[TypeName], time: TransportTime) {
+		const computedTime = new TransportTimeClass(this.context, time).toSeconds();
+		super.exponentialRampToValueAtTime(value, computedTime);
+		return this;
+	}
+
+	setTargetAtTime(value, startTime: TransportTime, timeConstant: number): this {
+		const computedTime = new TransportTimeClass(this.context, startTime).toSeconds();
+		super.setTargetAtTime(value, computedTime, timeConstant);
+		return this;
+	}
+
+	cancelScheduledValues(startTime: TransportTime): this {
+		const computedTime = new TransportTimeClass(this.context, startTime).toSeconds();
+		super.cancelScheduledValues(computedTime);
+		return this;
+	}
+
+	setValueCurveAtTime(values: UnitMap[TypeName][], startTime: TransportTime, duration: Time, scaling: NormalRange): this {
+		const computedTime = new TransportTimeClass(this.context, startTime).toSeconds();
+		duration = this.toSeconds(duration);
+		super.setValueCurveAtTime(values, computedTime, duration, scaling);
+		return this;
+	}
+
+	cancelAndHoldAtTime(time: TransportTime): this {
+		const computedTime = new TransportTimeClass(this.context, time).toSeconds();
+		super.cancelAndHoldAtTime(computedTime);
+		return this;
+	}
+	
+	setRampPoint(time: TransportTime): this {
+		const computedTime = new TransportTimeClass(this.context, time).toSeconds();
+		super.setRampPoint(computedTime);
+		return this;
+	}
+	
+	exponentialRampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: TransportTime): this {
+		const computedTime = new TransportTimeClass(this.context, startTime).toSeconds();
+		super.exponentialRampTo(value, rampTime, computedTime);
+		return this;
+	}
+	
+	linearRampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: TransportTime): this {
+		const computedTime = new TransportTimeClass(this.context, startTime).toSeconds();
+		super.linearRampTo(value, rampTime, computedTime);
+		return this;
+	}
+
+	targetRampTo(value: UnitMap[TypeName], rampTime: Time, startTime?: TransportTime): this {
+		const computedTime = new TransportTimeClass(this.context, startTime).toSeconds();
+		super.targetRampTo(value, rampTime, computedTime);
+		return this;
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.context.transport.clear(this._synced);
+		this.context.transport.off("start", this._syncedCallback);
+		this.context.transport.off("pause", this._syncedCallback);
+		this.context.transport.off("stop", this._syncedCallback);
+		this._constantSource.dispose();
+		return this;
+	}
+}

package/Tone/signal/ToneConstantSource.test.ts

@@ -0,0 +1,202 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { CompareToFile } from "test/helper/CompareToFile";
+import { Offline, whenBetween } from "test/helper/Offline";
+import { ONLINE_TESTING } from "test/helper/Supports";
+import { ToneConstantSource } from "./ToneConstantSource";
+
+describe("ToneConstantSource", () => {
+
+	BasicTests(ToneConstantSource);
+
+	context("Constructor", () => {
+
+		it("can be constructed with an offset", () => {
+			const source = new ToneConstantSource(330);
+			expect(source.offset.value).to.equal(330);
+			source.dispose();
+		});
+
+		it("can be constructed with no arguments", () => {
+			const source = new ToneConstantSource();
+			expect(source.offset.value).to.equal(1);
+			source.dispose();
+		});
+
+		it("can be constructed with an options object", () => {
+			const source = new ToneConstantSource({
+				offset: 2,
+			});
+			expect(source.offset.value).to.be.closeTo(2, 0.01);
+			source.dispose();
+		});
+
+	});
+
+	context("onended", () => {
+
+		if (ONLINE_TESTING) {
+
+			it("invokes the onended callback in the online context", (done) => {
+				const source = new ToneConstantSource();
+				source.start();
+				source.stop("+0.3");
+				const now = source.now();
+				source.onended = () => {
+					expect(source.now() - now).to.be.within(0.25, 0.5);
+					source.dispose();
+					done();
+				};
+			});
+
+			it("invokes the onended callback only once in the online context", (done) => {
+				const source = new ToneConstantSource();
+				source.start();
+				source.stop("+0.1");
+				source.stop("+0.2");
+				source.stop("+0.3");
+				const now = source.now();
+				source.onended = () => {
+					expect(source.now() - now).to.be.within(0.25, 0.5);
+					source.dispose();
+					done();
+				};
+			});
+		}
+
+		it("invokes the onended callback in the offline context", () => {
+			let wasInvoked = false;
+			return Offline(() => {
+				const source = new ToneConstantSource();
+				source.start(0);
+				source.stop(0.2);
+				source.onended = () => {
+					expect(source.now() - 0.2).to.be.closeTo(0, 0.05);
+					source.dispose();
+					wasInvoked = true;
+				};
+			}, 0.3).then(() => {
+				expect(wasInvoked).to.equal(true);
+			});
+		});
+
+		it("invokes the onended callback only once in offline context", () => {
+			let wasInvoked = false;
+			return Offline(() => {
+				const source = new ToneConstantSource();
+				source.start(0);
+				source.stop(0.1);
+				source.stop(0.2);
+				source.stop(0.3);
+				source.onended = () => {
+					expect(source.now() - 0.3).to.be.closeTo(0, 0.05);
+					source.dispose();
+					expect(wasInvoked).to.equal(false);
+					wasInvoked = true;
+				};
+			}, 0.4).then(() => {
+				expect(wasInvoked).to.equal(true);
+			});
+		});
+	});
+
+	context("Scheduling", () => {
+
+		it("throw an error if start is called multiple time", () => {
+			const source = new ToneConstantSource();
+			source.start();
+			expect(() => {
+				source.start();
+			}).to.throw();
+			source.dispose();
+		});
+
+		it("can play for a specific duration", () => {
+			return Offline(() => {
+				const source = new ToneConstantSource().toDestination();
+				source.start(0).stop(0.1);
+			}, 0.4).then(buffer => {
+				expect(buffer.getValueAtTime(0)).to.be.above(0);
+				expect(buffer.getValueAtTime(0.09)).to.be.above(0);
+				expect(buffer.getValueAtTime(0.1)).to.equal(0);
+			});
+		});
+
+		it("can call stop multiple times and takes the last value", () => {
+			return Offline(() => {
+				const source = new ToneConstantSource().toDestination();
+				source.start(0).stop(0.1).stop(0.2);
+			}, 0.4).then((buffer) => {
+				expect(buffer.getValueAtTime(0)).to.be.above(0);
+				expect(buffer.getValueAtTime(0.1)).to.be.above(0);
+				expect(buffer.getValueAtTime(0.19)).to.be.above(0);
+				expect(buffer.getValueAtTime(0.2)).to.equal(0);
+			});
+		});
+
+		if (ONLINE_TESTING) {
+
+			it("clamps start time to the currentTime", () => {
+				const source = new ToneConstantSource();
+				source.start(0);
+				const currentTime = source.context.currentTime;
+				expect(source.getStateAtTime(0)).to.equal("stopped");
+				expect(source.getStateAtTime(currentTime)).to.equal("started");
+				source.dispose();
+			});
+
+			it("clamps stop time to the currentTime", (done) => {
+				const source = new ToneConstantSource();
+				source.start(0);
+				let currentTime = source.context.currentTime;
+				expect(source.getStateAtTime(0)).to.equal("stopped");
+				expect(source.getStateAtTime(currentTime)).to.equal("started");
+				setTimeout(() => {
+					currentTime = source.context.currentTime;
+					source.stop(0);
+					expect(source.getStateAtTime(currentTime + 0.01)).to.equal("stopped");
+					source.dispose();
+					done();
+				}, 100);
+			});
+		}
+	});
+
+	context("State", () => {
+
+		it("reports the right state", () => {
+
+			return Offline(() => {
+				const source = new ToneConstantSource();
+				source.start(0);
+				source.stop(0.05);
+				return (time) => {
+					whenBetween(time, 0, 0.05, () => {
+						expect(source.state).to.equal("started");
+					});
+					whenBetween(time, 0.05, 0.1, () => {
+						expect(source.state).to.equal("stopped");
+					});
+				};
+			}, 0.1);
+		});
+
+		it("can call stop multiple times, takes the last value", () => {
+
+			return Offline(() => {
+				const source = new ToneConstantSource();
+				source.start(0);
+				source.stop(0.05);
+				source.stop(0.1);
+				return (time) => {
+					whenBetween(time, 0, 0.1, () => {
+						expect(source.state).to.equal("started");
+					});
+					whenBetween(time, 0.1, 0.2, () => {
+						expect(source.state).to.equal("stopped");
+					});
+				};
+			}, 0.2);
+		});
+	});
+});

package/Tone/signal/ToneConstantSource.ts

@@ -0,0 +1,90 @@
+import { connect } from "../core/context/ToneAudioNode";
+import { Param } from "../core/context/Param";
+import { Seconds, Time, UnitMap, UnitName } from "../core/type/Units";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { OneShotSource, OneShotSourceOptions } from "../source/OneShotSource";
+
+export interface ToneConstantSourceOptions<TypeName extends UnitName> extends OneShotSourceOptions {
+	convert: boolean;
+	offset: UnitMap[TypeName];
+	units: TypeName;
+	minValue?: number;
+	maxValue?: number;
+}
+
+/**
+ * Wrapper around the native fire-and-forget ConstantSource.
+ * Adds the ability to reschedule the stop method.
+ * @category Signal
+ */
+export class ToneConstantSource<TypeName extends UnitName = "number"> extends OneShotSource<ToneConstantSourceOptions<TypeName>> {
+
+	readonly name: string = "ToneConstantSource";
+
+	/**
+	 * The signal generator
+	 */
+	private _source = this.context.createConstantSource();
+
+	/**
+	 * The offset of the signal generator
+	 */
+	readonly offset: Param<TypeName>;
+
+	/**
+	 * @param  offset   The offset value
+	 */
+	constructor(offset: UnitMap[TypeName]);
+	constructor(options?: Partial<ToneConstantSourceOptions<TypeName>>);
+	constructor() {
+
+		super(optionsFromArguments(ToneConstantSource.getDefaults(), arguments, ["offset"]));
+		const options = optionsFromArguments(ToneConstantSource.getDefaults(), arguments, ["offset"]);
+
+		connect(this._source, this._gainNode);
+
+		this.offset = new Param({
+			context: this.context,
+			convert: options.convert,
+			param: this._source.offset,
+			units: options.units,
+			value: options.offset,
+			minValue: options.minValue,
+			maxValue: options.maxValue,
+		});
+	}
+
+	static getDefaults(): ToneConstantSourceOptions<any> {
+		return Object.assign(OneShotSource.getDefaults(), {
+			convert: true,
+			offset: 1,
+			units: "number" as UnitName,
+		});
+	}
+
+	/**
+	 * Start the source node at the given time
+	 * @param  time When to start the source
+	 */
+	start(time?: Time): this {
+		const computedTime = this.toSeconds(time);
+		this.log("start", computedTime);
+		this._startGain(computedTime);
+		this._source.start(computedTime);
+		return this;
+	}
+
+	protected _stopSource(time?: Seconds): void {
+		this._source.stop(time);
+	}
+
+	dispose(): this {
+		super.dispose();
+		if (this.state === "started") {
+			this.stop();
+		}
+		this._source.disconnect();
+		this.offset.dispose();
+		return this;
+	}
+}

package/Tone/signal/WaveShaper.test.ts

@@ -0,0 +1,95 @@
+import { expect } from "chai";
+import { BasicTests } from "test/helper/Basic";
+import { ConstantOutput } from "test/helper/ConstantOutput";
+import { Offline } from "test/helper/Offline";
+import { Signal } from "./Signal";
+import { WaveShaper } from "./WaveShaper";
+
+describe("WaveShaper", () => {
+
+	BasicTests(WaveShaper);
+
+	describe("Construction Options", () => {
+
+		it("can be constructed with an array", () => {
+			const waveshaper = new WaveShaper([1, 2, 3, 4, 5, 6]);
+			expect(waveshaper.curve && waveshaper.curve[0]).to.equal(1);
+			expect(waveshaper.curve && waveshaper.curve[2]).to.equal(3);
+		});
+
+		it("can be constructed with a mapping function", () => {
+			const waveshaper = new WaveShaper(() => {
+				return -2;
+			});
+			expect(waveshaper.curve && waveshaper.curve[0]).to.equal(-2);
+			expect(waveshaper.curve && waveshaper.curve[1]).to.equal(-2);
+		});
+
+		it("can be constructed with a length and then set with a map", () => {
+			const waveshaper = new WaveShaper(() => 10, 2048);
+			expect(waveshaper.curve && waveshaper.curve.length).to.equal(2048);
+			expect(waveshaper.curve && waveshaper.curve[0]).to.equal(10);
+			expect(waveshaper.curve && waveshaper.curve[1]).to.equal(10);
+		});
+
+		it("can be set to oversample", () => {
+			const waveshaper = new WaveShaper();
+			expect(waveshaper.oversample).to.equal("none");
+			waveshaper.oversample = "2x";
+			expect(waveshaper.oversample).to.equal("2x");
+			expect(() => {
+				// @ts-ignore
+				waveshaper.oversample = "3x";
+			}).to.throw(Error);
+		});
+
+	});
+
+	describe("Logic", () => {
+
+		it("shapes the output of the incoming signal", () => {
+			return ConstantOutput(() => {
+				const signal = new Signal(1);
+				const waveshaper = new WaveShaper([-10, -10, -10]);
+				signal.connect(waveshaper);
+				waveshaper.toDestination();
+			}, -10);
+		});
+
+		it("outputs the last curve value when the input is above 1", () => {
+			return ConstantOutput(() => {
+				const signal = new Signal(10);
+				const waveshaper = new WaveShaper([-20, 20]);
+				signal.connect(waveshaper);
+				waveshaper.toDestination();
+			}, 20);
+		});
+
+		it("outputs the first curve value when the input is below -1", () => {
+			return ConstantOutput(() => {
+				const signal = new Signal(-1);
+				const waveshaper = new WaveShaper([-20, 20]);
+				signal.connect(waveshaper);
+				waveshaper.toDestination();
+			}, -20);
+		});
+
+		it("maps the input through the waveshaping curve", () => {
+			return Offline(() => {
+				const signal = new Signal(-1);
+				const waveshaper = new WaveShaper((input) => {
+					return input * 2;
+				});
+				signal.connect(waveshaper);
+				waveshaper.toDestination();
+				signal.setValueAtTime(-1, 0);
+				signal.linearRampToValueAtTime(1, 1);
+			}, 1).then((buffer) => {
+				buffer.forEach((sample, time) => {
+					expect(sample).to.be.closeTo(2 * ((time * 2) - 1), 0.005);
+				});
+			});
+		});
+
+	});
+});

package/Tone/signal/WaveShaper.ts

@@ -0,0 +1,136 @@
+import { ToneAudioNodeOptions } from "../core/context/ToneAudioNode";
+import { optionsFromArguments } from "../core/util/Defaults";
+import { isArray, isFunction } from "../core/util/TypeCheck";
+import { assert } from "../core/util/Debug";
+import { Signal } from "./Signal";
+import { SignalOperator } from "./SignalOperator";
+
+export type WaveShaperMappingFn = (value: number, index?: number) => number;
+
+type WaveShaperMapping = WaveShaperMappingFn | number[] | Float32Array;
+
+interface WaveShaperOptions extends ToneAudioNodeOptions {
+	mapping?: WaveShaperMapping;
+	length: number;
+	curve?: number[] | Float32Array;
+}
+
+/**
+ * Wraps the native Web Audio API
+ * [WaveShaperNode](http://webaudio.github.io/web-audio-api/#the-waveshapernode-interface).
+ *
+ * @example
+ * const osc = new Tone.Oscillator().toDestination().start();
+ * // multiply the output of the signal by 2 using the waveshaper's function
+ * const timesTwo = new Tone.WaveShaper((val) => val * 2, 2048).connect(osc.frequency);
+ * const signal = new Tone.Signal(440).connect(timesTwo);
+ * @category Signal
+ */
+export class WaveShaper extends SignalOperator<WaveShaperOptions> {
+
+	readonly name: string = "WaveShaper";
+
+	/**
+	 * the waveshaper node
+	 */
+	private _shaper: WaveShaperNode = this.context.createWaveShaper();
+
+	/**
+	 * The input to the waveshaper node.
+	 */
+	input = this._shaper;
+
+	/**
+	 * The output from the waveshaper node
+	 */
+	output = this._shaper;
+
+	/**
+	 * @param mapping The function used to define the values.
+	 *                The mapping function should take two arguments:
+	 *                the first is the value at the current position
+	 *                and the second is the array position.
+	 *                If the argument is an array, that array will be
+	 *                set as the wave shaping function. The input
+	 *                signal is an AudioRange [-1, 1] value and the output
+	 *                signal can take on any numerical values.
+	 *
+	 * @param bufferLen The length of the WaveShaperNode buffer.
+	 */
+	constructor(mapping?: WaveShaperMapping, length?: number);
+	constructor(options?: Partial<WaveShaperOptions>);
+	constructor() {
+		super(Object.assign(optionsFromArguments(WaveShaper.getDefaults(), arguments, ["mapping", "length"])));
+		const options = optionsFromArguments(WaveShaper.getDefaults(), arguments, ["mapping", "length"]);
+
+		if (isArray(options.mapping) || options.mapping instanceof Float32Array) {
+			this.curve = Float32Array.from(options.mapping);
+		} else if (isFunction(options.mapping)) {
+			this.setMap(options.mapping, options.length);
+		}
+	}
+
+	static getDefaults(): WaveShaperOptions {
+		return Object.assign(Signal.getDefaults(), {
+			length: 1024,
+		});
+	}
+
+	/**
+	 * Uses a mapping function to set the value of the curve.
+	 * @param mapping The function used to define the values.
+	 *                The mapping function take two arguments:
+	 *                the first is the value at the current position
+	 *                which goes from -1 to 1 over the number of elements
+	 *                in the curve array. The second argument is the array position.
+	 * @example
+	 * const shaper = new Tone.WaveShaper();
+	 * // map the input signal from [-1, 1] to [0, 10]
+	 * shaper.setMap((val, index) => (val + 1) * 5);
+	 */
+	setMap(mapping: WaveShaperMappingFn, length = 1024): this {
+		const array = new Float32Array(length);
+		for (let i = 0, len = length; i < len; i++) {
+			const normalized = (i / (len - 1)) * 2 - 1;
+			array[i] = mapping(normalized, i);
+		}
+		this.curve = array;
+		return this;
+	}
+
+	/**
+	 * The array to set as the waveshaper curve. For linear curves
+	 * array length does not make much difference, but for complex curves
+	 * longer arrays will provide smoother interpolation.
+	 */
+	get curve(): Float32Array | null {
+		return this._shaper.curve;
+	}
+
+	set curve(mapping: Float32Array | null) {
+		this._shaper.curve = mapping;
+	}
+
+	/**
+	 * Specifies what type of oversampling (if any) should be used when
+	 * applying the shaping curve. Can either be "none", "2x" or "4x".
+	 */
+	get oversample(): OverSampleType {
+		return this._shaper.oversample;
+	}
+
+	set oversample(oversampling: OverSampleType) {
+		const isOverSampleType = ["none", "2x", "4x"].some(str => str.includes(oversampling));
+		assert(isOverSampleType, "oversampling must be either 'none', '2x', or '4x'");
+		this._shaper.oversample = oversampling;
+	}
+
+	/**
+	 * Clean up.
+	 */
+	dispose(): this {
+		super.dispose();
+		this._shaper.disconnect();
+		return this;
+	}
+}