0
# Tone.js
1

2
Tone.js is a Web Audio framework for creating interactive music in the browser. The architecture aims to be familiar to both musicians and audio programmers, offering high-level DAW features like global transport for synchronizing events, prebuilt synthesizers and effects, and high-performance building blocks for custom audio applications.
3

4
## Package Information
5

6
- **Package Name**: tone
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install tone`
10

11
## Core Imports
12

13
```typescript
14
import * as Tone from "tone";
15
```
16

17
For specific imports:
18

19
```typescript
20
import { Synth, Transport, start, now } from "tone";
21
```
22

23
CommonJS:
24

25
```javascript
26
const Tone = require("tone");
27
// or
28
const { Synth, Transport, start, now } = require("tone");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import { Synth, start, now } from "tone";
35

36
// User interaction required before audio
37
document.addEventListener("click", async () => {
38
  // Start the audio context
39
  await start();
40
  
41
  // Create a synth and connect it to the main output
42
  const synth = new Synth().toDestination();
43
  
44
  // Play a middle 'C' for the duration of an 8th note
45
  synth.triggerAttackRelease("C4", "8n");
46
  
47
  // Schedule notes in the future
48
  const time = now();
49
  synth.triggerAttackRelease("E4", "8n", time + 0.5);
50
  synth.triggerAttackRelease("G4", "8n", time + 1);
51
});
52
```
53

54
## Architecture
55

56
Tone.js is built around several key architectural components:
57

58
- **Global Context**: Single audio context with utilities (Transport, Destination, Draw, Listener)
59
- **Modular Design**: Core, instruments, effects, sources, events, components, and signal processing modules
60
- **Audio-rate Control**: Sample-accurate parameter automation and signal processing
61
- **Time Abstraction**: Unified time system supporting musical notation ("4n", "8t") and absolute time
62
- **Connection Graph**: Flexible audio routing with connect/disconnect methods
63
- **Transport System**: Global timekeeper for synchronizing musical events and sequences
64

65
## Capabilities
66

67
### Core Audio System
68

69
Global audio context management, time utilities, and fundamental audio types. Essential for all Tone.js applications.
70

71
```typescript { .api }
72
function start(): Promise<void>;
73
function now(): number;
74
function immediate(): number;
75
function loaded(): Promise<void>;
76
function getContext(): Context;
77
function getTransport(): TransportInstance;
78
function getDestination(): DestinationInstance;
79
```
80

81
[Core Audio System](./core.md)
82

83
### Synthesizers and Instruments
84

85
Ready-to-use musical instruments including monophonic and polyphonic synthesizers with various synthesis techniques.
86

87
```typescript { .api }
88
class Synth {
89
  constructor(options?: Partial<SynthOptions>);
90
  triggerAttackRelease(note: Frequency, duration: Time, time?: Time): this;
91
  toDestination(): this;
92
}
93

94
class PolySynth<T = Synth> {
95
  constructor(voice?: new () => T, options?: Partial<PolySynthOptions<T>>);
96
  triggerAttackRelease(notes: Frequency[], duration: Time, time?: Time): this;
97
}
98
```
99

100
[Synthesizers and Instruments](./instruments.md)
101

102
### Audio Effects
103

104
Comprehensive collection of audio effects including reverbs, delays, modulation, and distortion effects.
105

106
```typescript { .api }
107
class Reverb {
108
  constructor(roomSize?: NormalRange);
109
  connect(destination: AudioNode): this;
110
}
111

112
class FeedbackDelay {
113
  constructor(delay?: Time, feedback?: NormalRange);
114
  toDestination(): this;
115
}
116
```
117

118
[Audio Effects](./effects.md)
119

120
### Audio Sources
121

122
Audio generation including oscillators, noise sources, and audio file players for creating sound content.
123

124
```typescript { .api }
125
class Oscillator {
126
  constructor(frequency?: Frequency, type?: OscillatorType);
127
  start(time?: Time): this;
128
  stop(time?: Time): this;
129
}
130

131
class Player {
132
  constructor(url?: string | AudioBuffer | ToneAudioBuffer);
133
  load(url: string): Promise<this>;
134
  start(time?: Time): this;
135
}
136
```
137

138
[Audio Sources](./sources.md)
139

140
### Event Scheduling and Sequencing
141

142
Musical event scheduling, loops, sequences, and patterns for creating musical arrangements.
143

144
```typescript { .api }
145
class Loop {
146
  constructor(callback: (time: number) => void, interval: Time);
147
  start(time?: TransportTime): this;
148
  stop(time?: TransportTime): this;
149
}
150

151
class Sequence {
152
  constructor(callback: (time: number, note: any) => void, events: any[], subdivision: Time);
153
  start(time?: TransportTime): this;
154
}
155
```
156

157
[Event Scheduling](./events.md)
158

159
### Audio Components
160

161
Lower-level building blocks including analysis tools, filters, envelopes, and channel utilities for custom audio processing.
162

163
```typescript { .api }
164
class Filter {
165
  constructor(frequency?: Frequency, type?: BiquadFilterType, rolloff?: number);
166
  frequency: Signal<"frequency">;
167
  Q: Signal<"positive">;
168
}
169

170
class Envelope {
171
  constructor(attack?: Time, decay?: Time, sustain?: NormalRange, release?: Time);
172
  triggerAttack(time?: Time): this;
173
  triggerRelease(time?: Time): this;
174
}
175
```
176

177
[Audio Components](./components.md)
178

179
### Signal Processing
180

181
Audio-rate signal processing utilities for mathematical operations, scaling, and control signal generation.
182

183
```typescript { .api }
184
class Signal<T extends UnitName = "number"> {
185
  constructor(value?: UnitMap[T], units?: T);
186
  value: UnitMap[T];
187
  rampTo(value: UnitMap[T], time: Time): this;
188
}
189

190
class Add {
191
  constructor(value: number);
192
  addend: Signal<"number">;
193
}
194
```
195

196
[Signal Processing](./signals.md)
197

198
## Types
199

200
### Core Types
201

202
```typescript { .api }
203
type Time = number | string;
204
type Frequency = number | string;
205
type NormalRange = number;
206
type Positive = number;
207
type Cents = number;
208
type Decibels = number;
209
type Degrees = number;
210

211
interface ToneOptions {
212
  context?: BaseAudioContext;
213
}
214

215
type UnitName = "number" | "frequency" | "time" | "decibels" | "normalRange" | "positive" | "cents" | "degrees";
216
```
217

218
### Transport Types
219

220
```typescript { .api }
221
interface TransportInstance {
222
  bpm: Signal<"bpm">;
223
  state: TransportState;
224
  start(time?: Time): this;
225
  stop(time?: Time): this;
226
  pause(time?: Time): this;
227
  toggle(time?: Time): this;
228
  scheduleOnce(callback: (time: number) => void, time: TransportTime): number;
229
  scheduleRepeat(callback: (time: number) => void, interval: Time, startTime?: TransportTime): number;
230
}
231

232
type TransportState = "started" | "stopped" | "paused";
233
```
234

235
### Context Types
236

237
```typescript { .api }
238
interface DestinationInstance {
239
  volume: Volume;
240
  mute: boolean;
241
  connect(destination: AudioNode): this;
242
}
243

244
interface Context extends BaseAudioContext {
245
  now(): number;
246
  immediate(): number;
247
  transport: TransportInstance;
248
  destination: DestinationInstance;
249
}
250
```