Tone.js/Tone/core/context/Context.ts

import { Ticker, TickerClockSource } from "../clock/Ticker";
import { Seconds } from "../type/Units";
import { isAudioContext } from "../util/AdvancedTypeCheck";
import { optionsFromArguments } from "../util/Defaults";
import { Omit } from "../util/Interface";
import { Timeline } from "../util/Timeline";
import { isDefined, isString } from "../util/TypeCheck";
import { AnyAudioContext, createAudioContext, createAudioWorkletNode } from "./AudioContext";
import { closeContext, initializeContext } from "./ContextInitialization";
import { BaseContext, ContextLatencyHint } from "./BaseContext";
import { assert } from "../util/Debug";

type Transport = import("../clock/Transport").Transport;
type Destination = import("./Destination").Destination;
type Listener = import("./Listener").Listener;
type Draw = import("../util/Draw").Draw;

// these are either not used in Tone.js or deprecated and not implemented.
export type ExcludedFromBaseAudioContext = "onstatechange" | "addEventListener" | "removeEventListener" | "listener" | "dispatchEvent" | "audioWorklet" | "destination" | "createScriptProcessor";
// "createMediaStreamSource" | "createMediaElementSource" | "createMediaStreamTrackSource" |
// "baseLatency" | "suspend" |

// the subset of the BaseAudioContext which Tone.Context implements.
export type BaseAudioContextSubset = Omit<BaseAudioContext, ExcludedFromBaseAudioContext>;

export interface ContextOptions {
	clockSource: TickerClockSource;
	latencyHint: ContextLatencyHint;
	lookAhead: Seconds;
	updateInterval: Seconds;
	context: AnyAudioContext;
}

export interface ContextTimeoutEvent {
	callback: (...args: any[]) => void;
	id: number;
	time: Seconds;
}

/**
 * Wrapper around the native AudioContext.
 * @category Core
 */
export class Context extends BaseContext {

	readonly name: string = "Context";

	/**
	 * The amount of time into the future events are scheduled. Giving Web Audio
	 * a short amount of time into the future to schedule events can reduce clicks and
	 * improve performance. This value can be set to 0 to get the lowest latency.
	 */
	lookAhead: Seconds;

	/**
	 * private reference to the BaseAudioContext
	 */
	protected readonly _context: AnyAudioContext;

	/**
	 * A reliable callback method
	 */
	private readonly _ticker: Ticker;

	/**
	 * The default latency hint
	 */
	private _latencyHint!: ContextLatencyHint | Seconds;

	/**
	 * An object containing all of the constants AudioBufferSourceNodes
	 */
	private _constants = new Map<number, AudioBufferSourceNode>();

	/**
	 * All of the setTimeout events.
	 */
	private _timeouts: Timeline<ContextTimeoutEvent> = new Timeline();

	/**
	 * The timeout id counter
	 */
	private _timeoutIds = 0;

	/**
	 * A reference the Transport singleton belonging to this context
	 */
	private _transport!: Transport;

	/**
	 * A reference the Listener singleton belonging to this context
	 */
	private _listener!: Listener;

	/**
	 * A reference the Destination singleton belonging to this context
	 */
	private _destination!: Destination;

	/**
	 * A reference the Transport singleton belonging to this context
	 */
	private _draw!: Draw;

	/**
	 * Private indicator if the context has been initialized
	 */
	private _initialized = false;

	/**
	 * Indicates if the context is an OfflineAudioContext or an AudioContext
	 */
	readonly isOffline: boolean = false;

	constructor(context?: AnyAudioContext);
	constructor(options?: Partial<ContextOptions>);
	constructor() {
		super();
		const options = optionsFromArguments(Context.getDefaults(), arguments, ["context"]);

		if (options.context) {
			this._context = options.context;
		} else {
			this._context = createAudioContext({
				latencyHint: options.latencyHint,
			});
		}

		this._ticker = new Ticker(this.emit.bind(this, "tick"), options.clockSource, options.updateInterval);
		this.on("tick", this._timeoutLoop.bind(this));

		// fwd events from the context
		this._context.onstatechange = () => {
			this.emit("statechange", this.state);
		};

		this._setLatencyHint(options.latencyHint);
		this.lookAhead = options.lookAhead;
	}

	static getDefaults(): ContextOptions {
		return {
			clockSource: "worker",
			latencyHint: "interactive",
			lookAhead: 0.1,
			updateInterval: 0.05,
		} as ContextOptions;
	}

	/**
	 * Finish setting up the context. **You usually do not need to do this manually.**
	 */
	private initialize(): this {
		if (!this._initialized) {
			// add any additional modules
			initializeContext(this);
			this._initialized = true;
		}
		return this;
	}

	//---------------------------
	// BASE AUDIO CONTEXT METHODS
	//---------------------------

	createAnalyser(): AnalyserNode {
		return this._context.createAnalyser();
	}
	createOscillator(): OscillatorNode {
		return this._context.createOscillator();
	}
	createBufferSource(): AudioBufferSourceNode {
		return this._context.createBufferSource();
	}
	createBiquadFilter(): BiquadFilterNode {
		return this._context.createBiquadFilter();
	}
	createBuffer(numberOfChannels: number, length: number, sampleRate: number): AudioBuffer {
		return this._context.createBuffer(numberOfChannels, length, sampleRate);
	}
	createChannelMerger(numberOfInputs?: number | undefined): ChannelMergerNode {
		return this._context.createChannelMerger(numberOfInputs);
	}
	createChannelSplitter(numberOfOutputs?: number | undefined): ChannelSplitterNode {
		return this._context.createChannelSplitter(numberOfOutputs);
	}
	createConstantSource(): ConstantSourceNode {
		return this._context.createConstantSource();
	}
	createConvolver(): ConvolverNode {
		return this._context.createConvolver();
	}
	createDelay(maxDelayTime?: number | undefined): DelayNode {
		return this._context.createDelay(maxDelayTime);
	}
	createDynamicsCompressor(): DynamicsCompressorNode {
		return this._context.createDynamicsCompressor();
	}
	createGain(): GainNode {
		return this._context.createGain();
	}
	createIIRFilter(feedForward: number[] | Float32Array, feedback: number[] | Float32Array): IIRFilterNode {
		// @ts-ignore
		return this._context.createIIRFilter(feedForward, feedback);
	}
	createPanner(): PannerNode {
		return this._context.createPanner();
	}
	createPeriodicWave(
		real: number[] | Float32Array,
		imag: number[] | Float32Array,
		constraints?: PeriodicWaveConstraints | undefined,
	): PeriodicWave {
		return this._context.createPeriodicWave(real, imag, constraints);
	}
	createStereoPanner(): StereoPannerNode {
		return this._context.createStereoPanner();
	}
	createWaveShaper(): WaveShaperNode {
		return this._context.createWaveShaper();
	}
	createMediaStreamSource(stream: MediaStream): MediaStreamAudioSourceNode {
		assert(isAudioContext(this._context), "Not available if OfflineAudioContext");
		const context = this._context as AudioContext;
		return context.createMediaStreamSource(stream);
	}
	createMediaStreamDestination(): MediaStreamAudioDestinationNode {
		assert(isAudioContext(this._context), "Not available if OfflineAudioContext");
		const context = this._context as AudioContext;
		return context.createMediaStreamDestination();
	}
	decodeAudioData(audioData: ArrayBuffer): Promise<AudioBuffer> {
		return this._context.decodeAudioData(audioData);
	}

	/**
	 * The current time in seconds of the AudioContext.
	 */
	get currentTime(): Seconds {
		return this._context.currentTime;
	}
	/**
	 * The current time in seconds of the AudioContext.
	 */
	get state(): AudioContextState {
		return this._context.state;
	}
	/**
	 * The current time in seconds of the AudioContext.
	 */
	get sampleRate(): number {
		return this._context.sampleRate;
	}

	/**
	 * The listener
	 */
	get listener(): Listener {
		this.initialize();
		return this._listener;
	}
	set listener(l) {
		assert(!this._initialized, "The listener cannot be set after initialization.");
		this._listener = l;
	}

	/**
	 * There is only one Transport per Context. It is created on initialization.
	 */
	get transport(): Transport {
		this.initialize();
		return this._transport;
	}
	set transport(t: Transport) {
		assert(!this._initialized, "The transport cannot be set after initialization.");
		this._transport = t;
	}

	/**
	 * This is the Draw object for the context which is useful for synchronizing the draw frame with the Tone.js clock.
	 */
	get draw(): Draw {
		this.initialize();
		return this._draw;
	}
	set draw(d) {
		assert(!this._initialized, "Draw cannot be set after initialization.");
		this._draw = d;
	}

	/**
	 * A reference to the Context's destination node.
	 */
	get destination(): Destination {
		this.initialize();
		return this._destination;
	}
	set destination(d: Destination) {
		assert(!this._initialized, "The destination cannot be set after initialization.");
		this._destination = d;
	}

	//--------------------------------------------
	// AUDIO WORKLET
	//--------------------------------------------

	/**
	 * Maps a module name to promise of the addModule method
	 */
	private _workletModules: Map<string, Promise<void>> = new Map()

	/**
	 * Create an audio worklet node from a name and options. The module
	 * must first be loaded using [[addAudioWorkletModule]]. 
	 */
	createAudioWorkletNode(
		name: string,
		options?: Partial<AudioWorkletNodeOptions>
	): AudioWorkletNode {
		return createAudioWorkletNode(this.rawContext, name, options);
	}

	/**
	 * Add an AudioWorkletProcessor module
	 * @param url The url of the module
	 * @param name The name of the module
	 */
	async addAudioWorkletModule(url: string, name: string): Promise<void> {
		assert(isDefined(this.rawContext.audioWorklet), "AudioWorkletNode is only available in a secure context (https or localhost)");
		if (!this._workletModules.has(name)) {
			this._workletModules.set(name, this.rawContext.audioWorklet.addModule(url));
		}
		await this._workletModules.get(name);
	}

	/**
	 * Returns a promise which resolves when all of the worklets have been loaded on this context
	 */
	protected async workletsAreReady(): Promise<void> {
		const promises: Promise<void>[] = [];
		this._workletModules.forEach(promise => promises.push(promise));
		await Promise.all(promises);
	}

	//---------------------------
	// TICKER
	//---------------------------

	/**
	 * How often the interval callback is invoked.
	 * This number corresponds to how responsive the scheduling
	 * can be. context.updateInterval + context.lookAhead gives you the
	 * total latency between scheduling an event and hearing it.
	 */
	get updateInterval(): Seconds {
		return this._ticker.updateInterval;
	}
	set updateInterval(interval: Seconds) {
		this._ticker.updateInterval = interval;
	}

	/**
	 * What the source of the clock is, either "worker" (default),
	 * "timeout", or "offline" (none).
	 */
	get clockSource(): TickerClockSource {
		return this._ticker.type;
	}
	set clockSource(type: TickerClockSource) {
		this._ticker.type = type;
	}

	/**
	 * The type of playback, which affects tradeoffs between audio
	 * output latency and responsiveness.
	 * In addition to setting the value in seconds, the latencyHint also
	 * accepts the strings "interactive" (prioritizes low latency),
	 * "playback" (prioritizes sustained playback), "balanced" (balances
	 * latency and performance).
	 * @example
	 * // prioritize sustained playback
	 * const context = new Tone.Context({ latencyHint: "playback" });
	 * // set this context as the global Context
	 * Tone.setContext(context);
	 * // the global context is gettable with Tone.getContext()
	 * console.log(Tone.getContext().latencyHint);
	 */
	get latencyHint(): ContextLatencyHint | Seconds {
		return this._latencyHint;
	}

	/**
	 * Update the lookAhead and updateInterval based on the latencyHint
	 */
	private _setLatencyHint(hint: ContextLatencyHint | Seconds): void {
		let lookAheadValue = 0;
		this._latencyHint = hint;
		if (isString(hint)) {
			switch (hint) {
				case "interactive":
					lookAheadValue = 0.1;
					break;
				case "playback":
					lookAheadValue = 0.5;
					break;
				case "balanced":
					lookAheadValue = 0.25;
					break;
			}
		}
		this.lookAhead = lookAheadValue;
		this.updateInterval = lookAheadValue / 2;
	}

	/**
	 * The unwrapped AudioContext or OfflineAudioContext
	 */
	get rawContext(): AnyAudioContext {
		return this._context;
	}

	/**
	 * The current audio context time plus a short [[lookAhead]].
	 */
	now(): Seconds {
		return this._context.currentTime + this.lookAhead;
	}

	/**
	 * The current audio context time without the [[lookAhead]]. 
	 * In most cases it is better to use [[now]] instead of [[immediate]] since
	 * with [[now]] the [[lookAhead]] is applied equally to _all_ components including internal components,
	 * to making sure that everything is scheduled in sync. Mixing [[now]] and [[immediate]]
	 * can cause some timing issues. If no lookAhead is desired, you can set the [[lookAhead]] to `0`.
	 */
	immediate(): Seconds {
		return this._context.currentTime;
	}

	/**
	 * Starts the audio context from a suspended state. This is required
	 * to initially start the AudioContext. See [[Tone.start]]
	 */
	resume(): Promise<void> {
		if (this._context.state === "suspended" && isAudioContext(this._context)) {
			return this._context.resume();
		} else {
			return Promise.resolve();
		}
	}

	/**
	 * Close the context. Once closed, the context can no longer be used and
	 * any AudioNodes created from the context will be silent. 
	 */
	async close(): Promise<void> {
		if (isAudioContext(this._context)) {
			await this._context.close();
		}
		if (this._initialized) {
			closeContext(this);
		}
	}

	/**
	 * **Internal** Generate a looped buffer at some constant value. 
	 */
	getConstant(val: number): AudioBufferSourceNode {
		if (this._constants.has(val)) {
			return this._constants.get(val) as AudioBufferSourceNode;
		} else {
			const buffer = this._context.createBuffer(1, 128, this._context.sampleRate);
			const arr = buffer.getChannelData(0);
			for (let i = 0; i < arr.length; i++) {
				arr[i] = val;
			}
			const constant = this._context.createBufferSource();
			constant.channelCount = 1;
			constant.channelCountMode = "explicit";
			constant.buffer = buffer;
			constant.loop = true;
			constant.start(0);
			this._constants.set(val, constant);
			return constant;
		}
	}

	/**
	 * Clean up. Also closes the audio context.
	 */
	dispose(): this {
		super.dispose();
		this._ticker.dispose();
		this._timeouts.dispose();
		Object.keys(this._constants).map(val => this._constants[val].disconnect());
		return this;
	}

	//---------------------------
	// TIMEOUTS
	//---------------------------

	/**
	 * The private loop which keeps track of the context scheduled timeouts
	 * Is invoked from the clock source
	 */
	private _timeoutLoop(): void {
		const now = this.now();
		let firstEvent = this._timeouts.peek();
		while (this._timeouts.length && firstEvent && firstEvent.time <= now) {
			// invoke the callback
			firstEvent.callback();
			// shift the first event off
			this._timeouts.shift();
			// get the next one
			firstEvent = this._timeouts.peek();
		}
	}

	/**
	 * A setTimeout which is guaranteed by the clock source.
	 * Also runs in the offline context.
	 * @param  fn       The callback to invoke
	 * @param  timeout  The timeout in seconds
	 * @returns ID to use when invoking Context.clearTimeout
	 */
	setTimeout(fn: (...args: any[]) => void, timeout: Seconds): number {
		this._timeoutIds++;
		const now = this.now();
		this._timeouts.add({
			callback: fn,
			id: this._timeoutIds,
			time: now + timeout,
		});
		return this._timeoutIds;
	}

	/**
	 * Clears a previously scheduled timeout with Tone.context.setTimeout
	 * @param  id  The ID returned from setTimeout
	 */
	clearTimeout(id: number): this {
		this._timeouts.forEach(event => {
			if (event.id === id) {
				this._timeouts.remove(event);
			}
		});
		return this;
	}

	/**
	 * Clear the function scheduled by [[setInterval]]
	 */
	clearInterval(id: number): this {
		return this.clearTimeout(id);
	}

	/**
	 * Adds a repeating event to the context's callback clock
	 */
	setInterval(fn: (...args: any[]) => void, interval: Seconds): number {
		const id = ++this._timeoutIds;
		const intervalFn = () => {
			const now = this.now();
			this._timeouts.add({
				callback: () => {
					// invoke the callback
					fn();
					// invoke the event to repeat it
					intervalFn();
				},
				id,
				time: now + interval,
			});
		};
		// kick it off
		intervalFn();
		return id;
	}
}