Library / SDK
Tonejs/Tone.js avatar
Tonejs/Tone.js

Tone.js: a transport, musical time and prebuilt synths on top of Web Audio

Project brief: A Web Audio framework for making interactive music in the browser.

14,917 stars1,094 forksTypeScriptMIT

At a glance

What is it?
Tone.js is an MIT-licensed TypeScript framework that puts DAW-style scheduling, musical time values and ready-made instruments over the browser's Web Audio API. It removes a lot of clock arithmetic, but it cannot get around browser autoplay rules, its instruments are single-voice by default, and its tagged releases trail the code on the dev branch.
Who is it for?
Tone.js fits developers building music, sequencing or synthesis into a web page who would rather think in quarter notes and measures than raw AudioContext seconds. It is a poor fit if you only need to fire a sound effect, since you still inherit the autoplay gesture requirement and a large API.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly TypeScript, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Tonejs/Tone.js14,917 ★ · +221
Star history
Repository2026-07-302026-11-15
Tonejs/Tone.js14.7k14.9k

221 Stars in the last 108 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

A DAW model laid over the AudioContext

Tone.js describes itself as a Web Audio framework for creating interactive music in the browser, and its stated aim is an architecture that feels familiar to both musicians and audio programmers. The way it gets there is by borrowing the structure of a digital audio workstation. At the high level there is a global transport for synchronizing and scheduling events, plus prebuilt synths and effects you can connect and play straight away. Below that sit lower-level building blocks for writing your own synthesizers, effects and control signals. That split is the main reason to pick Tone.js over writing against Web Audio directly. The browser API gives you nodes and a clock measured in seconds; Tone.js gives you instruments, notes such as C4, durations such as an eighth note, and a timeline you can start, stop and loop. The price is an extra abstraction between you and the platform, which you need to understand when timing goes wrong. The project is written in TypeScript under the MIT license, with source under Tone/ and tests under test/ in the repository.

Two delivery routes: npm package or an unpinned unpkg script

There are two ways to bring Tone.js into a project. The first is npm, with a choice between the stable release and the next channel:

bash
npm install tone      # latest stable version
# Or use the next channel instead:
# npm install tone@next

Then import the whole namespace:

js
import * as Tone from "tone";

The package.json declares type module, with main and module both pointing at build/esm/index.js and type definitions at build/esm/index.d.ts, so TypeScript users get types without a separate package. The second route is a script tag served from unpkg.com, which must come before any of your own scripts:

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

That snippet has two things to watch. It names no version, so the file it loads changes whenever a new version is published, and a page that worked last month can pick up a different build without any change on your side. For anything you ship, add an explicit version to the unpkg path and use HTTPS. The unpkg field in package.json points at build/Tone.js, the bundled build.

Nothing plays until a user gesture resolves Tone.start()

The most common first failure with Tone.js is silence, and it is not a Tone.js bug. Browsers will not play any audio until a user clicks something, such as a play button. Tone.js exposes this through Tone.start(), which you must call from an event listener triggered by a user action such as click or keydown. Tone.start() returns a promise, and audio is ready only after that promise resolves:

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

The consequence goes beyond a missing first note. Scheduling or playing audio before the AudioContext is running results in silence or incorrect scheduling, so events you queue during page load can land at the wrong time or not at all. Any design that wants music to begin the moment a page opens is not achievable; the framework cannot override the browser's rule. Plan the interface around an explicit start control, and defer creating loops and starting the transport until after the promise resolves.

Musical time strings replace seconds, but the clock still runs in seconds

Web Audio schedules events against the AudioContext clock, measured in seconds; its progress depends on the context state rather than simply on page load. Tone.now() returns context time plus Tone's scheduling look-ahead; Tone.immediate() returns context time without that look-ahead. Tone.js lets any method that takes a time accept either a number or a string, so you can write "4n" for a quarter note, "8t" for an eighth-note triplet and "1m" for one measure. The time encodings are covered on the project wiki. Note playback follows the same pattern. triggerAttack starts a note, triggerRelease sends the amplitude back to 0, and triggerAttackRelease combines them. Its first argument is the note, given as a frequency in hertz like 440 or in pitch-octave form like "D#2". The second is the duration, in seconds or as a tempo-relative value. The optional third is when along the AudioContext time the note should play:

javascript
const synth = new Tone.Synth().toDestination();
const now = Tone.now();
synth.triggerAttackRelease("C4", "8n", now);
synth.triggerAttackRelease("E4", "8n", now + 0.5);
synth.triggerAttackRelease("G4", "8n", now + 1);

Notice that the offsets here are still plain seconds added to Tone.now(). The musical strings are a convenience layer, not a replacement for understanding the underlying clock.

The Transport clock and the time argument you must not ignore

Tone.getTransport() returns the main timekeeper. Unlike the AudioContext clock, it can be started, stopped, looped and adjusted on the fly, which makes it the equivalent of the arrangement view in a DAW. Multiple events and parts can be arranged along it, and Tone.Loop creates a looped callback that can be scheduled to start and stop:

javascript
// create two monophonic synths
const synthA = new Tone.FMSynth().toDestination();
const synthB = new Tone.AMSynth().toDestination();
//play a note every quarter-note
const loopA = new Tone.Loop((time) => {
	synthA.triggerAttackRelease("C2", "8n", time);
}, "4n").start(0);
//play another note every off quarter-note, by starting it "8n"
const loopB = new Tone.Loop((time) => {
	synthB.triggerAttackRelease("C4", "8n", time);
}, "4n").start("8n");
// all loops start when the Transport is started
Tone.getTransport().start();

The detail that matters is the time parameter. JavaScript callbacks are not precisely timed, so Tone.js passes the sample-accurate time of the event into each callback, and you are expected to schedule sound with that value. If you call triggerAttackRelease without it, the note plays whenever the callback happens to run, and rhythms drift or jitter. This is easy to get wrong when moving UI updates and sound into the same callback, because the callback itself does not fire at the musical moment.

Every built-in synth is monophonic until wrapped in PolySynth

Tone.js ships several instruments, including Tone.Synth, Tone.FMSynth, Tone.AMSynth and Tone.NoiseSynth. Tone.Synth is a basic synthesizer with a single oscillator and an ADSR envelope. All of these instruments are monophonic: they play one note at a time. Trigger a chord on one of them and you get a single voice, not three. To play chords, wrap a monophonic synth in Tone.PolySynth, which takes the synth class as its first parameter and handles note allocation for you:

javascript
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);

The API is close to the monophonic one with one difference that breaks ported code: triggerRelease on a PolySynth must be given a note or an array of notes. Code written for Tone.Synth that calls triggerRelease with only a time will not release the right voices once you swap in PolySynth, so audit those calls when you add polyphony.

Samples load asynchronously behind Tone.loaded()

Synthesis is not the only sound source. Tone.Player loads an audio file and plays it back, and Tone.Sampler combines multiple samples into an instrument. Files arrive over the network, so playback has to wait for them. Tone.loaded() returns a promise that resolves when all audio files are loaded, which saves you from tracking each buffer's onload event separately:

javascript
const player = new Tone.Player(
	"https://tonejs.github.io/audio/berklee/gong_1.mp3"
).toDestination();
Tone.loaded().then(() => {
	player.start();
});

There are two consequences. First, Tone.loaded() waits on every file, so one slow or large sample delays the start of everything, and a sample library with many files will hold the whole page until the last one arrives. Second, loading and the autoplay gesture are separate gates: a player can be fully loaded and still silent if Tone.start() has not resolved. Handle both before calling start. The examples folder in the repository, including grainPlayer.html, mic.html, offline.html and daw.html, shows further use of players, input and offline rendering, and the hosted examples are at tonejs.github.io/examples.

Tagged releases trail the dev branch

The default branch is dev, and the most recent push landed on 1 November 2026, so the code is moving. The release history on GitHub is sparse by comparison. The latest tagged release is 15.1.22 from 12 July 2026; before that the visible tags are 14.7.39 from July 2020 and 13.8.25 from August 2019. Meanwhile package.json on dev already reads version 15.5.66. In practice the code you read on the dev branch is not the code that npm install tone gives you, and the tone@next channel exists for those who want the newer builds. When you look up behaviour in the source, check which version you are running. The HTML example link in the README points at a master branch path while the default branch is dev, which is another place where the repository and its docs can disagree. On the quality side, package.json defines test scripts that run web-test-runner with coverage, plus test:examples, test:html, test:integrations and test:readme, the last running node ./test/scripts/test_readme.mjs.

Editorial conclusion

Tone.js fits developers building music, sequencing or synthesis into a web page who would rather think in quarter notes and measures than raw AudioContext seconds. It is a poor fit if you only need to fire a sound effect, since you still inherit the autoplay gesture requirement and a large API. Before committing, decide between the stable tone package and tone@next, pin the unpkg URL if you use a script tag, and check the API docs for anything beyond the synth, transport and player examples.

Frequently asked questions

How to install Tone.js?

Install it with npm install tone for the latest stable version, or npm install tone@next for the next version, then use import * as Tone from "tone". It can also be loaded with a script tag from unpkg.com placed before your own scripts.

What does Tone.js do?

Tone.js is a Web Audio framework for creating interactive music in the browser. It provides a global transport for scheduling events, prebuilt synths and effects, sample playback, and building blocks for custom synthesizers and effects.

How to use Tone.js without getting silence?

Call Tone.start() from a user action such as a click or keydown and wait for its promise to resolve before playing or scheduling audio. Browsers will not play any audio before a user gesture.

Tone.js vs the Web Audio API: what is the difference?

Tone.js is built on the Web Audio API. It abstracts the AudioContext time, which counts in seconds, so methods accept musical values like "4n" or "1m", and adds a Transport, instruments and effects on top.

Official sources

  1. Official documentation
  2. Official README
  3. Project repository
  4. Release notes
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/tonejs-tone-js.svg)](https://hysenlabs.com/projects/tonejs-tone-js)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/tonejs-tone-js.svg)](https://hysenlabs.com/projects/tonejs-tone-js)

Was this useful?