Tone.js

Tone.js uses audio-rate signal control for parameters, allowing for sample-accurate automation. Many properties (like frequency on an Oscillator) are Signal objects. You can use methods like rampTo to create smooth automation curves.

const osc = new Tone.Oscillator().toDestination();
// start at "C4"
osc.frequency.value = "C4";
// ramp to "C2" over 2 seconds
osc.frequency.rampTo("C2", 2);
// start the oscillator for 2 seconds
osc.start().stop("+3");

Tone.js uses the Web Audio API's AudioContext time, which starts at 0 when the page loads and counts up in seconds.

• Tone.now(): Returns the current AudioContext time.
• Tempo-relative values: Tone.js abstracts seconds by allowing strings like "4n" (quarter-note), "8t" (eighth-note triplet), or "1m" (one measure) as arguments for time-based methods.

//get the current AudioContext time
setInterval(() => console.log(Tone.now()), 100);

You can route the output of a source (like a synth or player) through one or more effects before it reaches the Destination. Connections can be serial or parallel.

• Serial: source.connect(effect).toDestination()
• Parallel: source.connect(effect1); source.connect(effect2);

const player = new Tone.Player({
	url: "https://tonejs.github.io/audio/drum-samples/loops/ominous.mp3",
	autostart: true,
});
const filter = new Tone.Filter(400, "lowpass").toDestination();
const feedbackDelay = new Tone.FeedbackDelay(0.125, 0.5).toDestination();

// connect the player to the feedback delay and filter in parallel
player.connect(filter);
player.connect(feedbackDelay);

Browsers prevent audio from playing until a user interaction occurs (like a click or keydown). To enable audio, you must call Tone.start() inside an event listener triggered by a user action. Tone.start() returns a promise that resolves when the AudioContext is ready.

Warning: Scheduling or playing audio before this promise resolves may result in silence or incorrect scheduling.

//attach a click listener to a play button
document.querySelector("button")?.addEventListener("click", async () => {
	await Tone.start();
	console.log("audio is ready");
});

You can incorporate Tone.js into your project using npm for local development or by including it directly in an HTML document via unpkg.com.

Using npm

Install the latest stable version:

npm install tone

Or install the 'next' version:

npm install tone@next

Then import it in your JavaScript files:

import * as Tone from "tone";

Using unpkg (CDN)

Add the script tag to your HTML document. Ensure it precedes any of your project's scripts:

<script src="http://unpkg.com/tone"></script>

To run the official Tone.js examples on your local machine, follow these steps:

1. Install dependencies and build the project from the repository root:

   npm install
   npm run build

2. Start a local development server using http-server:

   npx http-server -e html -p 8000

3. Open your browser and navigate to http://localhost:8000/examples.

Note: These examples utilize web components (such as <tone-example>) defined in the Tonejs/ui repository.

The tone package provides the core audio engine, including the global Context, Transport, and various audio nodes. It serves as the central hub for managing the Web Audio API lifecycle, scheduling, and audio processing. Key components include:

• Contexts: Context (standard real-time audio) and OfflineContext (for rendering audio to a buffer).
• Audio Nodes: Base classes for audio processing like Gain, Delay, and ToneAudioNode.
• Time & Scheduling: Utilities for handling Time, Midi, Ticks, and TransportTime.
• Conversions: Mathematical utilities for translating between musical and technical units.

Tone.Synth is a basic monophonic synthesizer with a single oscillator and an ADSR envelope.

triggerAttack / triggerRelease

• triggerAttack(note, time): Starts the note (amplitude rises).
• triggerRelease(time): Ends the note (amplitude returns to 0).

triggerAttackRelease

A convenience method that combines attack and release.

• Argument 1 (note): A frequency in hertz (e.g., 440) or pitch-octave notation (e.g., "D#2").
• Argument 2 (duration): How long the note is held. Can be in seconds or tempo-relative values (e.g., "8n").
• Argument 3 (time, optional): When to play the note along the AudioContext time.

//create a synth and connect it to the main output (your speakers)
const synth = new Tone.Synth().toDestination();

//play a middle 'C' for the duration of an 8th note
synth.triggerAttackRelease("C4", "8n");

Most standard synths (like Tone.FMSynth, Tone.AMSynth, and Tone.NoiseSynth) are monophonic, meaning they can only play one note at a time.

To play multiple notes simultaneously, wrap a monophonic synth in Tone.PolySynth. The API is similar, but triggerRelease must be provided with a note or an array of notes.

const synth = new Tone.PolySynth(Tone.Synth).toDestination();
const now = Tone.now();
synth.triggerAttack("D4", now);
synth.triggerAttack("F4", now + 0.5);
synth.triggerAttack("A4", now + 1);
synth.triggerAttack("C5", now + 1.5);
synth.triggerAttack("E5", now + 2);
synth.triggerRelease(["D4", "F4", "A4", "C5", "E5"], now + 4);