tone 15.3.12 → 15.4.0

package/Tone/core/worklet/DelayLine.worklet.ts

@@ -5,7 +5,7 @@ const delayLine = /* javascript */ `
 	 * A multichannel buffer for use within an AudioWorkletProcessor as a delay line
 	 */
 	class DelayLine {
-		
+
 		constructor(size, channels) {
 			this.buffer = [];
 			this.writeHead = []
@@ -25,7 +25,7 @@ const delayLine = /* javascript */ `
 		 */
 		push(channel, value) {
 			this.writeHead[channel] += 1;
-			if (this.writeHead[channel] > this.size) {
+			if (this.writeHead[channel] >= this.size) {
 				this.writeHead[channel] = 0;
 			}
 			this.buffer[channel][this.writeHead[channel]] = value;
@@ -43,6 +43,29 @@ const delayLine = /* javascript */ `
 			}
 			return this.buffer[channel][readHead];
 		}
+
+		/**
+		 * Get the reverse recorded value of the channel given the delay
+		 * @param channel number
+		 * @param delay number delay samples
+		 */
+		getReverse(channel, delay) {
+			if (!this.size || !delay) {
+				return 0;
+			}
+
+			const readHead = delay * 2 - this.writeHead[channel] - 1;
+
+			// Gain function to reduce clicking when read is too close to write
+			let readWriteDifference = this.writeHead[channel] - readHead;
+			if (readWriteDifference < 0) {
+				readWriteDifference += this.size
+			}
+			const delayPct = readWriteDifference / this.size;
+			const gainFunction = 4 * delayPct * (1 - delayPct);
+
+			return this.buffer[channel][readHead] * gainFunction;
+		}
 	}
 `;
 

package/Tone/core/worklet/ToneAudioWorklet.ts

@@ -5,8 +5,9 @@ import {
 import { noOp } from "../util/Interface.js";
 import { getWorkletGlobalScope } from "./WorkletGlobalScope.js";
 
-export type ToneAudioWorkletOptions = ToneAudioNodeOptions;
-
+export interface ToneAudioWorkletOptions extends ToneAudioNodeOptions {
+	workletOptions?: Partial<AudioWorkletNodeOptions>
+};
 export abstract class ToneAudioWorklet<
 	Options extends ToneAudioWorkletOptions,
 > extends ToneAudioNode<Options> {
@@ -63,6 +64,13 @@ export abstract class ToneAudioWorklet<
 			this.context
 		);
 
+		if (options.workletOptions) {
+			this.workletOptions = Object.assign({},
+				this.workletOptions,
+				options.workletOptions
+			);
+		}
+
 		if (workletPromise === undefined) {
 			workletPromise = this.context.addAudioWorkletModule(blobUrl);
 

package/Tone/effect/ReverseDelay.test.ts

@@ -0,0 +1,52 @@
+import { expect } from "chai";
+
+import { BasicTests } from "../../test/helper/Basic.js";
+import { CompareToFile } from "../../test/helper/CompareToFile.js";
+import { EffectTests } from "../../test/helper/EffectTests.js";
+import { Oscillator } from "../source/oscillator/Oscillator.js";
+import { ReverseDelay } from "./ReverseDelay.js";
+
+describe("ReverseDelay", () => {
+	BasicTests(ReverseDelay);
+	EffectTests(ReverseDelay, 0.01);
+
+	context("API", () => {
+		it("matches a file", () => {
+			return CompareToFile(() => {
+				const delay = new ReverseDelay({
+					delayTime: 0.2,
+					feedback: 0.5,
+					wet: 0.5,
+				}).toDestination();
+				const osc = new Oscillator().connect(delay);
+				osc.start(0);
+				osc.volume.linearRampToValueAtTime(0, 0.1);
+				osc.volume.exponentialRampToValueAtTime(-Infinity, 0.2);
+			}, "reverseDelay.wav");
+		});
+
+		it("can pass in options in the constructor", () => {
+			const reverse = new ReverseDelay({
+				delayTime: 1.25,
+				feedback: 0.75,
+			});
+			expect(reverse.delayTime).to.equal(1.25);
+			expect(reverse.feedback).to.equal(0.75);
+			reverse.dispose();
+		});
+
+		it("can get/set the options", () => {
+			const reverse = new ReverseDelay(1.25, 0.75);
+			expect(reverse.delayTime).to.equal(1.25);
+			expect(reverse.feedback).to.equal(0.75);
+			reverse.set({
+				delayTime: "2n",
+				feedback: 0.5,
+			});
+
+			expect(reverse.get().delayTime).to.be.closeTo(1, 0.01);
+			expect(reverse.get().feedback).to.be.closeTo(0.5, 0.01);
+			reverse.dispose();
+		});
+	});
+});

package/Tone/effect/ReverseDelay.ts

@@ -0,0 +1,192 @@
+import { Gain } from "../core/context/Gain.js";
+import { Param } from "../core/context/Param.js";
+import { connectSeries } from "../core/context/ToneAudioNode.js";
+import { NormalRange, Seconds, Time } from "../core/type/Units.js";
+import { optionsFromArguments } from "../core/util/Defaults.js";
+import {
+	ToneAudioWorklet,
+	ToneAudioWorkletOptions,
+} from "../core/worklet/ToneAudioWorklet.js";
+import { EffectOptions } from "./Effect.js";
+import { Effect } from "./Effect.js";
+import { workletName } from "./ReverseDelay.worklet.js";
+
+export interface ReverseDelayOptions extends EffectOptions {
+	delayTime: Time;
+	feedback: NormalRange;
+}
+
+/**
+ * A feedback delay effect that plays the echos in reverse.
+ * Algorithm and gain function found in [this pdf](https://ccrma.stanford.edu/~jingjiez/portfolio/echoing-harmonics/pdfs/A%20Pitch%20Shifting%20Reverse%20Echo%20Audio%20Effect.pdf)
+ *
+ * @example
+ * const reverse = new Tone.ReverseDelay(1.5, 0.75).toDestination();
+ * const synth = new Tone.Synth().connect(reverse);
+ * synth.triggerAttackRelease("C4", "2n");
+ * @category Effect
+ */
+export class ReverseDelay extends Effect<ReverseDelayOptions> {
+	readonly name: string = "ReverseDelay";
+
+	/**
+	 * The node that does the reverse delay effect.
+	 */
+	private _reverseDelayWorklet: ReverseDelayWorklet;
+
+	/**
+	 * @param delayTime The amount of time the incoming signal will be delayed and reversed.
+	 * @param feedback The amount of signal which is fed back through the delay.
+	 */
+	constructor(delayTime?: Time, feedback?: NormalRange);
+	constructor(options?: Partial<ReverseDelayOptions>);
+	constructor() {
+		const options = optionsFromArguments(
+			ReverseDelay.getDefaults(),
+			arguments,
+			["delayTime", "feedback"]
+		);
+		super(options);
+
+		this._reverseDelayWorklet = this._connectWorklet(
+			options.delayTime,
+			options.feedback
+		);
+	}
+
+	private _connectWorklet(
+		delayTime: Time,
+		feedback: NormalRange
+	): ReverseDelayWorklet {
+		const worklet = new ReverseDelayWorklet({
+			context: this.context,
+			delayTime: this.toSeconds(delayTime),
+			feedback,
+		});
+		this.connectEffect(worklet);
+
+		return worklet;
+	}
+
+	/**
+	 * The amount of time the incoming signal is delayed and reversed
+	 */
+	get delayTime(): Time {
+		return this._reverseDelayWorklet.delayTime;
+	}
+
+	set delayTime(delayTime) {
+		const prev = this._reverseDelayWorklet;
+		this._reverseDelayWorklet = this._connectWorklet(
+			delayTime,
+			this.feedback
+		);
+
+		// Prevent sudden stop when disposing previous worklet
+		prev.output.gain.linearRampTo(0, this.toSeconds(this.delayTime));
+		this.context.setTimeout(
+			() => prev.dispose(),
+			this.toSeconds(this.delayTime)
+		);
+	}
+
+	/**
+	 * The amount of signal which is fed back through the delay.
+	 */
+	get feedback(): NormalRange {
+		return this._reverseDelayWorklet.feedback.value;
+	}
+
+	set feedback(feedback) {
+		this._reverseDelayWorklet.set({ feedback });
+	}
+
+	static getDefaults(): ReverseDelayOptions {
+		return Object.assign(Effect.getDefaults(), {
+			wet: 0.5,
+			delayTime: 1,
+			feedback: 0.5,
+		});
+	}
+
+	dispose(): this {
+		super.dispose();
+		this._reverseDelayWorklet.dispose();
+		return this;
+	}
+}
+
+export interface ReverseDelayWorkletOptions extends ToneAudioWorkletOptions {
+	delayTime: Seconds;
+	feedback: NormalRange;
+}
+
+/**
+ * Internal class which creates an AudioWorklet to reverse the delay signal
+ */
+class ReverseDelayWorklet extends ToneAudioWorklet<ReverseDelayWorkletOptions> {
+	readonly name: string = "ReverseDelayWorklet";
+
+	readonly input: Gain;
+	readonly output: Gain;
+
+	readonly delayTime: Seconds;
+	readonly feedback: Param<"normalRange">;
+
+	constructor(options?: Partial<ReverseDelayOptions>);
+	constructor() {
+		const options = optionsFromArguments(
+			ReverseDelayWorklet.getDefaults(),
+			arguments,
+			["delayTime", "feedback"]
+		);
+
+		super({
+			...options,
+			workletOptions: {
+				processorOptions: {
+					delayTime: options.delayTime,
+				},
+			},
+		});
+
+		this.input = new Gain({ context: this.context });
+		this.output = new Gain({ context: this.context });
+
+		this.delayTime = options.delayTime;
+		this.feedback = new Param<"normalRange">({
+			context: this.context,
+			value: options.feedback,
+			units: "normalRange",
+			param: this._dummyParam,
+			swappable: true,
+			minValue: 0,
+			maxValue: 0.9999,
+		});
+	}
+
+	static getDefaults(): ReverseDelayWorkletOptions {
+		return Object.assign(ToneAudioWorklet.getDefaults(), {
+			delayTime: 1,
+			feedback: 0.5,
+		});
+	}
+
+	protected _audioWorkletName(): string {
+		return workletName;
+	}
+
+	onReady(node: AudioWorkletNode): void {
+		connectSeries(this.input, node, this.output);
+		const feedback = node.parameters.get("feedback") as AudioParam;
+		this.feedback.setParam(feedback);
+	}
+
+	dispose(): this {
+		super.dispose();
+		this.input.dispose();
+		this.output.dispose();
+		this.feedback.dispose();
+		return this;
+	}
+}

package/Tone/effect/ReverseDelay.worklet.ts

@@ -0,0 +1,41 @@
+import "../core/worklet/SingleIOProcessor.worklet.js";
+import "../core/worklet/DelayLine.worklet.js";
+
+import { registerProcessor } from "../core/worklet/WorkletGlobalScope.js";
+
+export const workletName = "reverse-delay";
+
+export const reverseDelayWorklet = /* javascript */ `
+	class ReverseDelayWorklet extends SingleIOProcessor {
+
+		constructor(options) {
+			super(options);
+			this.delayTime = Math.floor(this.sampleRate * options.processorOptions.delayTime);
+			const channels = options.channelCount || 2;
+			this.delayLine = new DelayLine(this.delayTime * 2, channels);
+		}
+
+		static get parameterDescriptors() {
+			return [{
+				name: "feedback",
+				defaultValue: 0.5,
+				minValue: 0,
+				maxValue: 0.9999,
+				automationRate: "k-rate"
+			}];
+		}
+
+		generate(input, channel, parameters) {
+			const reversedSample = this.delayLine.getReverse(channel, this.delayTime);
+			const delayedSample = this.delayLine.get(channel, this.delayTime);
+
+			// Push the forward sample back on the line
+			this.delayLine.push(channel, input + delayedSample * parameters.feedback);
+
+			// Play the reversed sample
+			return reversedSample;
+		}
+	}
+`;
+
+registerProcessor(workletName, reverseDelayWorklet);

package/Tone/effect/index.ts

@@ -13,6 +13,7 @@ export * from "./Phaser.js";
 export * from "./PingPongDelay.js";
 export * from "./PitchShift.js";
 export * from "./Reverb.js";
+export * from "./ReverseDelay.js";
 export * from "./StereoWidener.js";
 export * from "./Tremolo.js";
 export * from "./Vibrato.js";

package/Tone/version.ts

@@ -1 +1 @@
-export const version: string = "15.3.12";
+export const version: string = "15.4.0";