You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+55-47
Original file line number
Diff line number
Diff line change
@@ -1,35 +1,43 @@
1
1
Tone.js
2
2
=========
3
3
4
-
Tone.js is a Web Audio framework for creating interactive music in the browser. The architecture of Tone.js aims to be familiar to both musicians and audio programmers looking to create web-based audio applications. On the high-level, Tone offers common DAW (digital audio workstation) features like a global transport for scheduling and timing events and prebuilt synths and effects. For signal-processing programmers (coming from languages like Max/MSP), Tone provides a wealth of high performance, low latency building blocks and DSP modules to build your own synthesizers, effects, and complex control signals.
4
+
Tone.js is a Web Audio framework for creating interactive music in the browser. The architecture of Tone.js aims to be familiar to both musicians and audio programmers looking to create web-based audio applications. On the high-level, Tone offers common DAW (digital audio workstation) features like a global transport for scheduling events and prebuilt synths and effects. For signal-processing programmers (coming from languages like Max/MSP), Tone provides a wealth of high performance, low latency building blocks and DSP modules to build your own synthesizers, effects, and complex control signals.
5
5
6
-
[API](http://tonejs.org/docs/)
6
+
[API](https://tonejs.github.io/docs/)
7
7
8
-
[Examples](http://tonejs.org/examples/)
8
+
[Examples](https://tonejs.github.io/examples/)
9
9
10
10
# Demos
11
11
12
+
*[Chrome Music Lab - Google Creative Lab](https://musiclab.chromeexperiments.com)
13
+
*[Groove Pizza - NYU Music Experience Design Lab](https://apps.musedlab.org/groovepizza/)
@@ -38,75 +46,73 @@ Using Tone.js? I'd love to hear it: [email protected]
38
46
# Hello Tone
39
47
40
48
```javascript
41
-
//create one of Tone's built-in synthesizers and connect it to the master output
42
-
var synth =newTone.SimpleSynth().toMaster();
49
+
//create a synth and connect it to the master output (your speakers)
50
+
var synth =newTone.Synth().toMaster();
43
51
44
-
//play a middle c for the duration of an 8th note
52
+
//play a middle 'C' for the duration of an 8th note
45
53
synth.triggerAttackRelease("C4", "8n");
46
54
```
47
55
48
-
[SimpleSynth](http://tonejs.org/docs/#SimpleSynth) is a single oscillator, single envelope synthesizer. It's [ADSR envelope](https://en.wikipedia.org/wiki/Synthesizer#ADSR_envelope) has two phases: the attack and the release. These can be triggered by calling `triggerAttack` and `triggerRelease` separately, or combined as shown above. The first argument of `triggerAttackRelease` is the frequency, which can be given either a number (like `440`) or as "pitch-octave" notation (like `"D#2"`). The second argument is the duration of the envelope's sustain (i.e. how long the note is held for). The third (optional) argument of `triggerAttackRelease` is the time the attack should start. With no argument, the time will evaluate to "now" and play immediately. Passing in a time value let's you schedule the event in the future.
56
+
#### Tone.Synth
49
57
50
-
### Time
58
+
[Tone.Synth](https://tonejs.github.io/docs/#Synth) is a basic synthesizer with a single [oscillator](https://tonejs.github.io/docs/#OmniOscillator) and an [ADSR envelope](https://en.wikipedia.org/wiki/Synthesizer#ADSR_envelope).
51
59
52
-
Any method which takes a time as a parameter will accept either a number or a string. Numbers will be taken literally as the time in seconds and strings can encode time expressions in terms of the current tempo. For example `"4n"` is a quarter-note, `"8t"` is an eighth-note triplet, and `"1m"` is one measure. Any value prefixed with `"+"` will be added to the current time. To trigger the same note one measure from now:
60
+
#### triggerAttackRelease
53
61
54
-
```javascript
55
-
synth.triggerAttackRelease("C4", "8n", "+1m");
56
-
```
62
+
The "attack" of an envelope is the period when the amplitude is rising, and the "release" is when it is falling back to 0. These two methods can be invoked separately as `triggerAttack` and `triggerRelease`, or combined as shown above. The first argument is the frequency which can either be a number (like `440`) or as "pitch-octave" notation (like `"D#2"`). The second argument is how long the note should be held before triggering the release phases. An optional third argument schedules the event for some time in the future. With no third argument, the note will play immediately.
63
+
64
+
#### Time
65
+
66
+
In the examples above, instead of using the time in seconds (for an 8th note at 120 BPM it would be 0.25 seconds), any method which takes time as an argument can accept a number or a string. Numbers will be taken literally as the time in seconds and strings can encode time expressions in terms of the current tempo. For example `"4n"` is a quarter-note, `"8t"` is an eighth-note triplet, and `"1m"` is one measure.
57
67
58
68
[Read about Time encodings.](https://github.com/Tonejs/Tone.js/wiki/Time)
59
69
70
+
# Scheduling
71
+
60
72
### Transport
61
73
62
-
Time expressions are evaluated against the Transport's BPM. [Tone.Transport](http://tonejs.org/docs/#Transport) is the master timekeeper, allowing for application-wide synchronization of sources, signals and events along a shared timeline. Callbacks scheduled with Tone.Transport will be invoked right before the scheduled time with the exact time of the event is passed in as the first parameter to the callback.
63
-
64
-
```javascript
65
-
//schedule a callback on the second beat of the first measure
66
-
Tone.Transport.schedule(function(time){
67
-
//schedule the synth's attackRelease using the passed-in time
68
-
synth.triggerAttackRelease("C4", "8n", time);
69
-
}, "1:2:0");
70
-
71
-
//start the transport
72
-
Tone.Transport.start();
73
-
```
74
-
[Read more about scheduling events with the Transport.](https://github.com/Tonejs/Tone.js/wiki/Transport)
74
+
[Tone.Transport](https://tonejs.github.io/docs/#Transport) is the master timekeeper, allowing for application-wide synchronization of sources, signals and events along a shared timeline. Time expressions (like the ones above) are evaluated against the Transport's BPM which can be set like this: `Tone.Transport.bpm.value = 120`.
75
75
76
76
### Loops
77
77
78
-
Instead of scheduling events directly on the Transport, Tone.js provides a few higher-level classes for working with events. [Tone.Loop](http://tonejs.org/docs/#Loop) is a simple way to create a looped callback that can be scheduled to start and stop.
78
+
Tone.js provides higher-level abstractions for scheduling events. [Tone.Loop](https://tonejs.github.io/docs/#Loop) is a simple way to create a looped callback that can be scheduled to start and stop.
79
79
80
80
```javascript
81
81
//play a note every quarter-note
82
82
var loop =newTone.Loop(function(time){
83
83
synth.triggerAttackRelease("C2", "8n", time);
84
84
}, "4n");
85
+
```
86
+
87
+
Since Javascript timing is not sample-accurate, the precise time of the event is passed into the callback function. This time should be used to schedule events within the loop.
85
88
89
+
You can then start and stop the loop along the Transport's timeline.
90
+
91
+
```javascript
86
92
//loop between the first and fourth measures of the Transport's timeline
87
93
loop.start("1m").stop("4m");
88
94
```
89
95
90
-
Start the Transport to hear the looped notes:
96
+
Then start the Transport to hear the loop:
91
97
92
98
```javascript
93
99
Transport.start();
94
100
```
95
101
96
-
[Read about Tone.js' Event classes.](https://github.com/Tonejs/Tone.js/wiki/Events)
102
+
[Read about Tone.js' Event classes](https://github.com/Tonejs/Tone.js/wiki/Events) and [scheduling events with the Transport.](https://github.com/Tonejs/Tone.js/wiki/Transport)
97
103
98
104
# Instruments
99
105
100
-
Tone has a number of instruments which all inherit from the same [Instrument base class](http://tonejs.org/docs/#Instrument), giving them a common API for playing notes. [Tone.MonoSynth](http://tonejs.org/docs/#MonoSynth) is composed of one oscillator, one filter, and two envelopes connected to the amplitude and the filter frequency.
106
+
Tone has a number of instruments which all inherit from the same [Instrument base class](https://tonejs.github.io/docs/#Instrument), giving them a common API for playing notes. [Tone.Synth](https://tonejs.github.io/docs/#Synth) is composed of one oscillatorand an amplitude envelope.
101
107
102
108
```javascript
103
109
//pass in some initial values for the filter and filter envelope
104
-
varmonoSynth=newTone.MonoSynth({
105
-
"filter": {
106
-
"type":"lowpass",
107
-
"Q":7
110
+
varsynth=newTone.Synth({
111
+
"oscillator": {
112
+
"type":"pwm",
113
+
"modulationFrequency":0.2
108
114
},
109
-
"filterEnvelope": {
115
+
"envelope": {
110
116
"attack":0.02,
111
117
"decay":0.1,
112
118
"sustain":0.2,
@@ -115,14 +121,14 @@ var monoSynth = new Tone.MonoSynth({
115
121
}).toMaster();
116
122
117
123
//start the note "D3" one second from now
118
-
monoSynth.triggerAttack("D3", "+1");
124
+
synth.triggerAttack("D3", "+1");
119
125
```
120
126
121
-
All instruments are monophonic (one voice) but can be made polyphonic when the constructor is passed in as the second argument to [Tone.PolySynth](http://tonejs.org/docs/#PolySynth).
127
+
All instruments are monophonic (one voice) but can be made polyphonic when the constructor is passed in as the second argument to [Tone.PolySynth](https://tonejs.github.io/docs/#PolySynth).
122
128
123
129
```javascript
124
-
//a 4 voice MonoSynth
125
-
var polySynth =newTone.PolySynth(4, Tone.MonoSynth).toMaster();
130
+
//a 4 voice Synth
131
+
var polySynth =newTone.PolySynth(4, Tone.Synth).toMaster();
In the above examples, the synthesizer was always connected directly to the [master output](http://tonejs.org/docs/#Master), but the output of the synth could also be routed through one (or more) effects before going to the speakers.
140
+
In the above examples, the synthesizer was always connected directly to the [master output](https://tonejs.github.io/docs/#Master), but the output of the synth could also be routed through one (or more) effects before going to the speakers.
135
141
136
142
```javascript
137
143
//create a distortion effect
@@ -144,7 +150,7 @@ synth.connect(distortion);
144
150
145
151
# Sources
146
152
147
-
Tone has a few basic audio sources like [Tone.Oscillator](http://tonejs.org/docs/#Oscillator) which has sine, square, triangle, and sawtooth waveforms, a buffer player ([Tone.Player](http://tonejs.org/docs/#Player)), a noise generator ([Tone.Noise]((http://tonejs.org/docs/#Noise))), two additional oscillator types ([pwm](http://tonejs.org/docs/#PWMOscillator), [pulse](http://tonejs.org/docs/#PulseOscillator)) and [external audio input](http://tonejs.org/docs/#Microphone) (when [WebRTC is supported](http://caniuse.com/#feat=stream)).
153
+
Tone has a few basic audio sources like [Tone.Oscillator](https://tonejs.github.io/docs/#Oscillator) which has sine, square, triangle, and sawtooth waveforms, a buffer player ([Tone.Player](https://tonejs.github.io/docs/#Player)), a noise generator ([Tone.Noise]((https://tonejs.github.io/docs/#Noise))), two additional oscillator types ([pwm](https://tonejs.github.io/docs/#PWMOscillator), [pulse](https://tonejs.github.io/docs/#PulseOscillator)) and [external audio input](https://tonejs.github.io/docs/#Microphone) (when [WebRTC is supported](http://caniuse.com/#feat=stream)).
148
154
149
155
```javascript
150
156
//a pwm oscillator which is connected to the speaker and started right away
@@ -165,16 +171,18 @@ Tone.js creates an AudioContext when it loads and shims it for maximum browser c
165
171
166
172
# MIDI
167
173
168
-
To use MIDI files, you'll first need to convert them into a JSON format which Tone.js can understand using [MidiConvert](http://tonejs.github.io/MidiConvert/).
174
+
To use MIDI files, you'll first need to convert them into a JSON format which Tone.js can understand using [MidiConvert](https://tonejs.github.io/MidiConvert/).
169
175
170
176
# Performance
171
177
172
-
Tone.js uses only one ScriptProcessorNode (in Tone.Meter). The rest of Tone's modules find a native Web Audio component workaround, making extensive use of the GainNode and WaveShaperNode especially, which enables Tone.js to work well on both desktop and mobile browsers. While the ScriptProcessorNode is extremely powerful, it introduces a lot of latency and the potential for glitches more than any other node.
178
+
Tone.js makes extensive use of the native Web Audio Nodes such as the GainNode and WaveShaperNode for all signal processing, which enables Tone.js to work well on both desktop and mobile browsers. It uses no ScriptProcessorNodes.
173
179
174
180
# Contributing
175
181
176
182
There are many ways to contribute to Tone.js. Check out [this wiki](https://github.com/Tonejs/Tone.js/wiki/Contributing) if you're interested.
177
183
184
+
If you have questions (or answers) that are not necessarily bugs/issues, please post them to the [forum](https://groups.google.com/forum/#!forum/tonejs).
0 commit comments