tone 15.3.6 → 15.3.8

package/Tone/core/clock/Clock.ts

@@ -22,14 +22,17 @@ interface ClockOptions extends ToneWithContextOptions {
 type ClockEvent = "start" | "stop" | "pause";
 
 /**
- * A sample accurate clock which provides a callback at the given rate.
- * While the callback is not sample-accurate (it is still susceptible to
- * loose JS timing), the time passed in as the argument to the callback
- * is precise. For most applications, it is better to use Tone.Transport
- * instead of the Clock by itself since you can synchronize multiple callbacks.
+ * A sample-accurate clock that provides a callback at a given rate.
+ *
+ * While the callback is not sample-accurate (it is susceptible to
+ * loose JavaScript timing), the time passed to the callback is precise.
+ *
+ * For most applications, it is better to use {@link Transport} instead of the
+ * Clock by itself, since you can synchronize multiple callbacks.
+ *
  * @example
- * // the callback will be invoked approximately once a second
- * // and will print the time exactly once a second apart.
+ * // The callback will be invoked approximately once a second,
+ * // and it will print the time exactly one second apart.
  * const clock = new Tone.Clock(time => {
  * 	console.log(time);
  * }, 1);
@@ -112,17 +115,16 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 	}
 
 	/**
-	 * Returns the playback state of the source, either "started", "stopped" or "paused".
+	 * The playback state of the clock, either "started", "stopped", or "paused".
 	 */
 	get state(): PlaybackState {
 		return this._state.getValueAtTime(this.now());
 	}
 
 	/**
-	 * Start the clock at the given time. Optionally pass in an offset
-	 * of where to start the tick counter from.
-	 * @param  time    The time the clock should start
-	 * @param offset  Where the tick counter starts counting from.
+	 * Start the clock at the given time.
+	 * @param time The time the clock should start.
+	 * @param offset The number of ticks to start the clock from.
 	 */
 	start(time?: Time, offset?: Ticks): this {
 		// make sure the context is running
@@ -148,7 +150,7 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 	 * 	console.log(time);
 	 * }, 1);
 	 * clock.start();
-	 * // stop the clock after 10 seconds
+	 * // Stop the clock after 10 seconds.
 	 * clock.stop("+10");
 	 */
 	stop(time?: Time): this {
@@ -165,7 +167,7 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 
 	/**
 	 * Pause the clock. Pausing does not reset the tick counter.
-	 * @param time The time when the clock should stop.
+	 * @param time The time when the clock should pause.
 	 */
 	pause(time?: Time): this {
 		const computedTime = this.toSeconds(time);
@@ -180,8 +182,9 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 	}
 
 	/**
-	 * The number of times the callback was invoked. Starts counting at 0
-	 * and increments after the callback was invoked.
+	 * The number of times the callback has been invoked.
+	 *
+	 * Starts counting at 0 and increments after the callback is invoked.
 	 */
 	get ticks(): Ticks {
 		return Math.ceil(this.getTicksAtTime(this.now()));
@@ -191,7 +194,9 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 	}
 
 	/**
-	 * The time since ticks=0 that the Clock has been running. Accounts for tempo curves
+	 * The time since ticks=0 that the clock has been running.
+	 *
+	 * Accounts for tempo curves.
 	 */
 	get seconds(): Seconds {
 		return this._tickSource.seconds;
@@ -202,8 +207,8 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 
 	/**
 	 * Return the elapsed seconds at the given time.
-	 * @param  time  When to get the elapsed seconds
-	 * @return  The number of elapsed seconds
+	 * @param time When to get the elapsed seconds.
+	 * @return The number of elapsed seconds.
 	 */
 	getSecondsAtTime(time: Time): Seconds {
 		return this._tickSource.getSecondsAtTime(time);
@@ -211,8 +216,8 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 
 	/**
 	 * Set the clock's ticks at the given time.
-	 * @param  ticks The tick value to set
-	 * @param  time  When to set the tick value
+	 * @param ticks The tick value to set.
+	 * @param time When to set the tick value.
 	 */
 	setTicksAtTime(ticks: Ticks, time: Time): this {
 		this._tickSource.setTicksAtTime(ticks, time);
@@ -220,11 +225,14 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 	}
 
 	/**
-	 * Get the time of the given tick. The second argument
-	 * is when to test before. Since ticks can be set (with setTicksAtTime)
-	 * there may be multiple times for a given tick value.
-	 * @param  tick The tick number.
-	 * @param  before When to measure the tick value from.
+	 * Get the time of the given tick.
+	 *
+	 * The second argument is when to test before. Since ticks can be set
+	 * (with {@link setTicksAtTime}), there may be multiple times for a given
+	 * tick value.
+	 *
+	 * @param tick The tick number.
+	 * @param before When to measure the tick value from.
 	 * @return The time of the tick
 	 */
 	getTimeOfTick(tick: Ticks, before = this.now()): Seconds {
@@ -233,7 +241,7 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 
 	/**
 	 * Get the clock's ticks at the given time.
-	 * @param  time  When to get the tick value
+	 * @param time When to get the tick value.
 	 * @return The tick value at the given time.
 	 */
 	getTicksAtTime(time?: Time): Ticks {
@@ -241,8 +249,8 @@ export class Clock<TypeName extends "bpm" | "hertz" = "hertz">
 	}
 
 	/**
-	 * Get the time of the next tick
-	 * @param  offset The tick number.
+	 * Get the time of the next tick.
+	 * @param offset The tick number.
 	 */
 	nextTickTime(offset: Ticks, when: Time): Seconds {
 		const computedTime = this.toSeconds(when);

package/Tone/core/clock/Transport.ts

@@ -68,23 +68,25 @@ type TransportCallback = (time: Seconds) => void;
 
 /**
  * Transport for timing musical events.
- * Supports tempo curves and time changes. Unlike browser-based timing (setInterval, requestAnimationFrame)
+ *
+ * Supports tempo curves and time changes.
+ *
+ * Unlike browser-based timing (setInterval, requestAnimationFrame),
  * Transport timing events pass in the exact time of the scheduled event
- * in the argument of the callback function. Pass that time value to the object
- * you're scheduling. <br><br>
+ * in the argument of the callback function.
+ *
  * A single transport is created for you when the library is initialized.
- * <br><br>
- * The transport emits the events: "start", "stop", "pause", and "loop" which are
- * called with the time of that event as the argument.
+ *
+ * The transport emits "start", "stop", "pause", and "loop" events.
  *
  * @example
  * const osc = new Tone.Oscillator().toDestination();
- * // repeated event every 8th note
+ * // Repeated event every 8th note.
  * Tone.getTransport().scheduleRepeat((time) => {
- * 	// use the callback time to schedule events
+ * 	// Use the callback time to schedule events.
  * 	osc.start(time).stop(time + 0.1);
  * }, "8n");
- * // transport must be started before it starts invoking events
+ * // Transport must be started before it starts invoking events.
  * Tone.getTransport().start();
  * @category Core
  */
@@ -276,14 +278,14 @@ export class TransportInstance
 	//-------------------------------------
 
 	/**
-	 * Schedule an event along the timeline.
-	 * @param callback The callback to be invoked at the time.
+	 * Schedule an event to be invoked at a specific time.
+	 * @param callback The callback to invoke at the given time.
 	 * @param time The time to invoke the callback at.
-	 * @return The id of the event which can be used for canceling the event.
+	 * @return The ID of the event, which can be used to cancel the event.
 	 * @example
-	 * // schedule an event on the 16th measure
+	 * // Schedule an event on the 16th measure.
 	 * Tone.getTransport().schedule((time) => {
-	 * 	// invoked on measure 16
+	 * 	// Invoked on measure 16.
 	 * 	console.log("measure 16!");
 	 * }, "16:0:0");
 	 */
@@ -299,17 +301,18 @@ export class TransportInstance
 	}
 
 	/**
-	 * Schedule a repeated event along the timeline. The event will fire
-	 * at the `interval` starting at the `startTime` and for the specified
-	 * `duration`.
-	 * @param  callback   The callback to invoke.
-	 * @param  interval   The duration between successive callbacks. Must be a positive number.
-	 * @param  startTime  When along the timeline the events should start being invoked.
-	 * @param  duration How long the event should repeat.
-	 * @return  The ID of the scheduled event. Use this to cancel the event.
+	 * Schedule a repeated event.
+	 *
+	 * The event will fire at the `interval` starting at the `startTime` and for the specified `duration`.
+	 *
+	 * @param callback The callback to invoke.
+	 * @param interval The duration between successive callbacks.
+	 * @param startTime When the event should start.
+	 * @param duration How long the event should repeat.
+	 * @return The ID of the scheduled event. Use this to cancel the event.
 	 * @example
 	 * const osc = new Tone.Oscillator().toDestination().start();
-	 * // a callback invoked every eighth note after the first measure
+	 * // A callback invoked every eighth note after the first measure.
 	 * Tone.getTransport().scheduleRepeat((time) => {
 	 * 	osc.start(time).stop(time + 0.1);
 	 * }, "8n", "1m");
@@ -420,7 +423,7 @@ export class TransportInstance
 	}
 
 	/**
-	 * Returns the playback state of the source, either "started", "stopped", or "paused"
+	 * The playback state of the transport, either "started", "stopped", or "paused".
 	 */
 	get state(): PlaybackState {
 		return this._clock.getStateAtTime(this.now());
@@ -428,10 +431,10 @@ export class TransportInstance
 
 	/**
 	 * Start the transport and all sources synced to the transport.
-	 * @param  time The time when the transport should start.
-	 * @param  offset The timeline offset to start the transport.
+	 * @param time The time when the transport should start.
+	 * @param offset The timeline offset to start the transport from.
 	 * @example
-	 * // start the transport in one second starting at beginning of the 5th measure.
+	 * // Start the transport in one second, beginning at the start of the 5th measure.
 	 * Tone.getTransport().start("+1", "4:0:0");
 	 */
 	start(time?: Time, offset?: TransportTime): this {
@@ -466,9 +469,11 @@ export class TransportInstance
 	}
 
 	/**
-	 * Toggle the current state of the transport. If it is
-	 * started, it will stop it, otherwise it will start the Transport.
-	 * @param  time The time of the event
+	 * Toggle the current state of the transport.
+	 *
+	 * If it is started, it will stop it. If it is stopped, it will start it.
+	 *
+	 * @param time The time of the event.
 	 */
 	toggle(time?: Time): this {
 		time = this.toSeconds(time);

package/Tone/core/context/Context.ts

@@ -33,29 +33,29 @@ export interface ContextTimeoutEvent {
 }
 
 /**
- * Wrapper around the native AudioContext.
+ * Wraps the native AudioContext.
  * @category Core
  */
 export class Context extends BaseContext {
 	readonly name: string = "Context";
 
 	/**
-	 * private reference to the BaseAudioContext
+		 * A private reference to the BaseAudioContext.
 	 */
 	protected readonly _context: AnyAudioContext;
 
 	/**
-	 * A reliable callback method
+	 * A reliable callback method.
 	 */
 	private readonly _ticker: Ticker;
 
 	/**
-	 * The default latency hint
+	 * The default latency hint.
 	 */
 	private _latencyHint!: ContextLatencyHint | Seconds;
 
 	/**
-	 * An object containing all of the constants AudioBufferSourceNodes
+	 * An object containing all of the AudioBufferSourceNodes with constant values.
 	 */
 	private _constants = new Map<number, AudioBufferSourceNode>();
 
@@ -580,11 +580,13 @@ export class Context extends BaseContext {
 	}
 
 	/**
-	 * A setTimeout which is guaranteed by the clock source.
+	 * 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
+	 *
+	 * @param fn The callback to invoke.
+	 * @param timeout The timeout in seconds.
+	 * @returns ID to use when invoking {@link clearTimeout}.
 	 */
 	setTimeout(fn: (...args: any[]) => void, timeout: Seconds): number {
 		this._timeoutIds++;
@@ -598,8 +600,8 @@ export class Context extends BaseContext {
 	}
 
 	/**
-	 * Clears a previously scheduled timeout with Tone.context.setTimeout
-	 * @param  id  The ID returned from setTimeout
+	 * Clears a previously scheduled timeout with {@link setTimeout}.
+	 * @param id The ID returned from {@link setTimeout}.
 	 */
 	clearTimeout(id: number): this {
 		this._timeouts.forEach((event) => {
@@ -611,14 +613,18 @@ export class Context extends BaseContext {
 	}
 
 	/**
-	 * Clear the function scheduled by {@link setInterval}
+	 * Clear the function scheduled by {@link setInterval}.
+	 * @param id The ID returned from {@link setInterval}.
 	 */
 	clearInterval(id: number): this {
 		return this.clearTimeout(id);
 	}
 
 	/**
-	 * Adds a repeating event to the context's callback clock
+	 * Adds a repeating event to the context's callback clock.
+	 * @param fn The callback to invoke.
+	 * @param interval The timeout in seconds.
+	 * @returns ID to use when invoking {@link clearInterval}.
 	 */
 	setInterval(fn: (...args: any[]) => void, interval: Seconds): number {
 		const id = ++this._timeoutIds;

package/Tone/core/context/Destination.ts

@@ -16,17 +16,19 @@ interface DestinationOptions extends ToneAudioNodeOptions {
 }
 
 /**
- * A single master output which is connected to the
- * AudioDestinationNode (aka your speakers).
- * It provides useful conveniences such as the ability
+ * A single master output that is connected to the
+ * AudioDestinationNode (i.e. your speakers).
+ *
+ * It provides useful conveniences, such as the ability
  * to set the volume and mute the entire application.
+ *
  * It also gives you the ability to apply master effects to your application.
  *
  * @example
  * const oscillator = new Tone.Oscillator().start();
- * // the audio will go from the oscillator to the speakers
+ * // The audio will go from the oscillator to the speakers.
  * oscillator.connect(Tone.getDestination());
- * // a convenience for connecting to the master output is also provided:
+ * // A convenience for connecting to the master output is also provided:
  * oscillator.toDestination();
  * @category Core
  */
@@ -37,11 +39,14 @@ export class DestinationInstance extends ToneAudioNode<DestinationOptions> {
 	output: Gain = new Gain({ context: this.context });
 
 	/**
-	 * The volume of the master output in decibels. -Infinity is silent, and 0 is no change.
+	 * The volume of the master output in decibels.
+	 *
+	 * -Infinity is silent, and 0 is no change.
+	 *
 	 * @example
 	 * const osc = new Tone.Oscillator().toDestination();
 	 * osc.start();
-	 * // ramp the volume down to silent over 10 seconds
+	 * // Ramp the volume down to silent over 10 seconds.
 	 * Tone.getDestination().volume.rampTo(-Infinity, 10);
 	 */
 	volume: Param<"decibels"> = this.input.volume;
@@ -80,7 +85,7 @@ export class DestinationInstance extends ToneAudioNode<DestinationOptions> {
 	 * @example
 	 * const oscillator = new Tone.Oscillator().start().toDestination();
 	 * setTimeout(() => {
-	 * 	// mute the output
+	 * 	// Mute the output.
 	 * 	Tone.Destination.mute = true;
 	 * }, 1000);
 	 */
@@ -92,11 +97,13 @@ export class DestinationInstance extends ToneAudioNode<DestinationOptions> {
 	}
 
 	/**
-	 * Add a master effects chain. NOTE: this will disconnect any nodes which were previously
-	 * chained in the master effects chain.
-	 * @param args All arguments will be connected in a row and the Master will be routed through it.
+	 * Add a master effects chain.
+	 *
+	 * NOTE: This will disconnect any nodes that were previously chained in the master effects chain.
+	 *
+	 * @param args All arguments will be connected in a row, and the master output will be routed through it.
 	 * @example
-	 * // route all audio through a filter and compressor
+	 * // Route all audio through a filter and compressor.
 	 * const lowpass = new Tone.Filter(800, "lowpass");
 	 * const compressor = new Tone.Compressor(-18);
 	 * Tone.Destination.chain(lowpass, compressor);
@@ -110,7 +117,7 @@ export class DestinationInstance extends ToneAudioNode<DestinationOptions> {
 	}
 
 	/**
-	 * The maximum number of channels the system can output
+	 * The maximum number of channels the system can output.
 	 * @example
 	 * console.log(Tone.Destination.maxChannelCount);
 	 */

package/Tone/version.ts

@@ -1 +1 @@
-export const version: string = "15.3.6";
+export const version: string = "15.3.8";