Tone.js Scheduling Time Units Explained

This article explains the units of time used by Tone.js for its audio scheduling methods. While Tone.js fundamentally operates on seconds under the hood to align with the Web Audio API, it provides a highly flexible Time representation that allows developers to use musical notation, transport time, ticks, and frequency values interchangeably.

Seconds: The Base Unit

By default, any raw number passed into a Tone.js scheduling method (such as Tone.Transport.schedule()) is interpreted as seconds.

For example, if you pass 2.5 to a scheduler, the event will trigger exactly 2.5 seconds after the Transport starts.

// Schedules an event at exactly 2 seconds
Tone.Transport.schedule((time) => {
    synth.triggerAttackRelease("C4", "8n", time);
}, 2);

The Tone.js Time Type

To make music programming more intuitive, Tone.js wraps numbers in a custom global type called Time. Whenever a method accepts a time argument, you can pass a string representing various musical and synchronization formats instead of doing manual math in seconds.

The primary time formats supported include:

1. Musical Notation

You can specify time relative to the current tempo (BPM) using standard musical notation strings: * "4n" - Quarter note * "8n" - Eighth note * "16n" - Sixteenth note * "2m" - Two measures (bars) * "4nt" - Quarter note triplet * "8n." - Dotted eighth note

2. Transport Time (Bars:Beats:Sixteenths)

For arranging music along a timeline, Tone.js uses a "B:B:S" format: * "0:0:0" - The very start of the timeline. * "2:1:0" - Measure 2, beat 1, 0 sixteenths.

3. Ticks

Ticks are the smallest unit of measurement on the Transport timeline. By default, there are 192 ticks per quarter note (PPQ). Ticks are represented by appending an "i" to the number: * "192i" - Equivalent to one quarter note.

4. Frequency

Time can also be expressed in terms of frequency (Hertz), which Tone.js automatically converts to the corresponding period duration. This is represented by appending "hz": * "4hz" - Equivalent to 0.25 seconds.

Relative Scheduling

When scheduling events dynamically, you can use the prefix "+" to schedule an event relative to the current AudioContext time.

// Schedules an event 1 quarter note from the current moment
synth.triggerAttackRelease("C4", "8n", "+4n");