Create a Live Coding Music App · Part 1 of 18 in the series
Part 1: A First Sound
Start loopcode, a live coding music app for the browser: set up a Vite project with TypeScript, get to know the Web Audio API as a graph of nodes, and play a first note with an oscillator and an envelope that keeps it from clicking.
Create a Live Coding Music AppPart 1 of 18
On this page
Quest objectives
- Know what you build in this series
- Create a Vite project with TypeScript
- Connect audio nodes in an AudioContext
- Give a note an envelope, so that it does not click
- Turn MIDI note numbers into frequencies
- Start sound with a click, as browsers demand
Live coding is making music by writing code while the music plays. A few lines describe a drum beat or a bass line. You run them and hear them. You change a line, run it again, and the music changes without stopping.
In this series you build loopcode, a live coding music app for the browser. It has an editor, and the code in it describes a song: drums, synths (instruments that build their sound from simple waves), effects, and the rhythms and melodies they play. Running the code changes the music while it plays. Every sound is made by the Web Audio API that browsers have built in, with no audio library. loopcode is a small relative of wicktone, a bigger app by the author of this site, which adds a canvas of nodes and more instruments to the same idea.
The series
A first sound: the project, the Web Audio API and one note (this part)
A clock that keeps time: a metronome that stays exact at any tempo
Drums from oscillators and noise: a drum machine with no recorded sounds
Patterns are functions of time: rhythms that can be combined, and swapped while they play
A small language for rhythm: a tokenizer, a parser and a compiler for rhythms written as
bd [sd sd]Speed, length and chance: steps that are faster, slower or longer, steps that play only sometimes, and hits spread evenly over a bar
Choices, polymeter and changing speeds: the rest of the notation
A synth for bass and lead: one instrument for bass lines and melodies
Code that makes music: an editor, and code that describes the song
Change it while it plays: running the code again without a gap in the music
When the code is wrong: mistakes shown at their line, endless loops stopped
Chords and pads: a synth that plays several notes at once
Filter, delay, reverb and distortion: effects, and cables between them
Movement with LFOs: slow waves that move a setting by themselves
Your own sounds: audio files of your own as instruments
See what you hear: notes that light up in the code as they play, and two displays of the sound
An editor that helps: suggestions and explanations while you type
Save and share: the song in the browser's storage, and in a link
The first eight parts build what makes the sound and what tells it when to play: a clock, drums, a synth and a small language for rhythm. From part 9 on there is an editor, and the app is played by writing code.
Every part ends with the app as it stands at that point, playable right on the page. The demo is built from exactly the code the part shows, which ran with Vite 8.3 and TypeScript 7 while the series was written.
What you need
Node.js 20.19 or newer, which Vite 8 requires, a terminal, a current browser, and speakers or headphones. The series was tested in Chromium, the browser that Chrome and Edge are built on. You should know the basics of JavaScript or TypeScript. You need no knowledge of audio or of music theory: every term is explained where it first comes up.
Create the project
Vite's project generator sets up a TypeScript project without a framework. When it offers to install and start right away, answer No:
$ npm create vite@latest loopcode -- --template vanilla-ts◇ Install with npm and start now?│ No│◇ Scaffolding project in /home/robin/loopcode...│└ Done. Now run: cd loopcode npm install npm run dev
Then install the template's packages. The app needs no others until part 9:
$ cd loopcode$ npm installadded 17 packages, and audited 18 packages in 5s8 packages are looking for funding run `npm fund` for detailsfound 0 vulnerabilities
The template comes with a small counter demo. Remove it, and the public folder with its icons, because the page gets new files:
$ rm -r src/counter.ts src/assets publicThe page
The page is a header with the app's name and a stage below it. For now the stage holds a row of keys, which the code fills in, and a hint. Replace index.html with this:
<!doctype html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Loopcode</title>
</head>
<body>
<header>
<strong class="name">loopcode</strong>
</header>
<main class="stage">
<div id="keys" class="keys"></div>
<p class="hint">Click a key to play a note.</p>
</main>
<script type="module" src="/src/main.ts"></script>
</body>
</html>The styles are long and have nothing to do with sound, so you don't need to study them: replace src/style.css with this and go on.
:root {
--void: #140822;
--night: #1d0c33;
--panel: #2a1150;
--edge: #5b21b6;
--text: #ede9fe;
--muted: #a99bc9;
--orange: #f97316;
--lilac: #c4b5fd;
color-scheme: dark;
}
* {
box-sizing: border-box;
}
html,
body {
height: 100%;
margin: 0;
}
body {
display: flex;
flex-direction: column;
background: var(--void);
color: var(--text);
font: 14px/1.4 ui-monospace, 'Cascadia Code', Menlo, Consolas, monospace;
}
header {
display: flex;
align-items: center;
gap: 12px;
padding: 8px 12px;
background: var(--night);
border-bottom: 2px solid var(--edge);
}
.name {
color: var(--orange);
letter-spacing: 0.05em;
}
button {
padding: 6px 12px;
border: 2px solid var(--edge);
border-radius: 4px;
background: var(--panel);
color: var(--text);
font: inherit;
cursor: pointer;
}
button:hover {
border-color: var(--lilac);
}
button:active,
button.on {
border-color: var(--orange);
background: var(--orange);
color: var(--void);
}
.stage {
flex: 1;
display: grid;
place-content: center;
justify-items: center;
gap: 16px;
padding: 16px;
}
.hint {
margin: 0;
color: var(--muted);
}
.keys {
display: flex;
gap: 6px;
}
.keys button {
width: 48px;
height: 120px;
padding: 0 0 10px;
display: grid;
align-items: end;
}A graph of nodes
The Web Audio API makes sound with nodes that are connected to one another. Some nodes produce sound, some change it, and one stands for the speakers: the destination. Sound flows along the connections, from the sources through whatever lies between to the destination. What is not connected to the destination, directly or through other nodes, is not heard.
All nodes belong to an AudioContext. It creates them, it owns the destination, and it has a clock: currentTime, which counts seconds while the context runs. An app needs one context.
Notes as numbers
A sound is air swinging back and forth. How often it swings per second is its frequency, measured in hertz (Hz), and the frequency is what you hear as the pitch: how high or low a note is. The A that orchestras tune to swings 440 times per second.
Songs are not written in hertz. Music counts in notes, and the usual way to number them comes from MIDI, the standard that connects keyboards and synthesizers. Every key of a piano has a number, from one key to the next it goes up by 1, and the A at 440 Hz is number 69. Twelve keys further up, the same note comes again one octave higher, with twice the frequency. The twelve steps in between are tuned so that each one multiplies the frequency by the same factor. Twelve of them make a factor of 2, so the factor is the twelfth root of 2, and a note that is midi - 69 steps away from the A has the frequency 440 * 2 ** ((midi - 69) / 12).
Create src/audio.ts with both, the context and the formula:
let context: AudioContext | undefined;
/** The one AudioContext of the app. A browser only lets it make sound after a click or a key. */
export function audio(): AudioContext {
context ??= new AudioContext();
return context;
}
/** The frequency of a MIDI note number in hertz: 69 is the A at 440 Hz, 12 notes make an octave. */
export function midiToFreq(midi: number): number {
return 440 * 2 ** ((midi - 69) / 12);
}audio() creates the context the first time it is asked for one and returns the same context from then on: ??= assigns only while the variable is still empty. Every file of the app gets the context from here.
Note 60 is the C in the middle of a piano, called C4: midiToFreq(60) gives 261.63 Hz. Note 72, the C one octave above, gives 523.25 Hz, twice as much.
An oscillator and an envelope
An oscillator is a node that produces one wave at one frequency, over and over. It is the plainest source of sound there is, and with a few nodes around it, it becomes every instrument of this series.
An oscillator alone makes a poor note. It is at full level from the moment it starts to the moment it stops, and when it stops, the wave is cut off wherever it happens to be in its swing. The speaker has to get from there to rest in no time, and that jump is heard as a click. A note needs a beginning and an end: its loudness has to rise out of silence and fall back into it. This course of the loudness over the length of a note is its envelope.
The envelope is made with a gain node, which multiplies whatever flows through it by a number, its gain: 1 leaves the sound as it is, 0.5 halves it, 0 is silence. The oscillator is sent through the gain node, and the gain goes up from 0 and back down while the note plays.
Replace src/main.ts. It begins with a function that plays one note:
import { audio, midiToFreq } from './audio.ts';
import './style.css';
/** Plays one note: an oscillator, and a gain that fades it in and out. */
function beep(midi: number, time: number, length = 0.4) {
const context = audio();
const oscillator = context.createOscillator();
oscillator.type = 'triangle';
oscillator.frequency.value = midiToFreq(midi);
const envelope = context.createGain();
envelope.gain.setValueAtTime(0, time);
envelope.gain.linearRampToValueAtTime(0.4, time + 0.01);
envelope.gain.exponentialRampToValueAtTime(0.001, time + length);
oscillator.connect(envelope).connect(context.destination);
oscillator.start(time);
oscillator.stop(time + length);
}typeis the shape of the wave. Asineis a pure tone with one frequency. Atriangleadds overtones, higher frequencies that sound along with the note, but only quiet ones. Insquareandsawtooththey are much louder.oscillator.frequencyandenvelope.gainare not plain numbers but audio parameters. Theirvaluesets them now. Their methods plan changes ahead of time, on the context's clock.setValueAtTime(0, time)says that the gain is 0 when the note starts.linearRampToValueAtTime(0.4, time + 0.01)lets it rise in a straight line and arrive at 0.4 ten milliseconds later: quick enough to sound immediate, slow enough not to click.exponentialRampToValueAtTime(0.001, time + length)lets it fall from there in a curve and arrive at 0.001 when the note ends. Each ramp begins where the step before it ended.An exponential fall loses the same share of what is left in equal times: quick at first, then slower and slower. A plucked string dies away like that. Such a curve never reaches 0, and the method throws an error when it is asked to. So the fall ends at 0.001, a thousandth of full level, where the cut at the end of the note is too small to hear.
The peak is 0.4 and not 1, because 1 is the most the output can carry, and several notes at once add up.
connect()returns the node it connected to, so a chain reads in the direction the sound flows: oscillator, envelope, speakers.start()andstop()are planned too.timeis a time on the context's clock. Passing it in looks like extra work as long as every note plays right away; the next part depends on it.
An oscillator can be started only once. After it has stopped it is done, and so is the gain node behind it, and the browser clears both away. Every note gets new nodes. The API is built to be used like that: a source for one sound, made, played and thrown away.
Eight keys
To hear it, the page gets eight keys: one octave of the C major scale, which is the white keys of a piano from one C to the next. The rest of src/main.ts follows below beep():
// One octave of C major: C4 is MIDI note 60.
const SCALE = [
['C', 60],
['D', 62],
['E', 64],
['F', 65],
['G', 67],
['A', 69],
['B', 71],
['C', 72],
] as const;
const keys = document.querySelector<HTMLDivElement>('#keys')!;
for (const [name, midi] of SCALE) {
const key = document.createElement('button');
key.textContent = name;
key.addEventListener('click', async () => {
// The context starts suspended until the page was clicked.
await audio().resume();
beep(midi, audio().currentTime);
});
keys.append(key);
}as const keeps each entry a pair of one name and one number, so the loop can take the two apart with their types. A click plays the key's note now, at currentTime.
Before that, the handler waits for resume(). Browsers don't let a page make sound before the visitor has done something on it, a click or a key press. A context that is created earlier starts out suspended: its clock stands still and nothing is heard until resume() is called after a click. Here the context is only created inside the first click, when sound is already allowed, so resume() may have nothing left to do. Later parts create the context when the page loads, and then this line is what starts the sound. It stays in every handler that starts sound from now on.
Try it
Start the dev server and open the address it prints:
$ npm run dev> loopcode@0.0.0 dev> vite VITE v8.3.8 ready in 85 ms ➜ Local: http://localhost:5173/ ➜ Network: use --host to expose
Click the keys from left to right: the C major scale, up one octave. The last C is the first one at twice the frequency. Each note is there at once and fades over 0.4 seconds. Click several keys quickly: the notes sound together, because each has an oscillator and an envelope of its own.
Then change the code and listen. Vite reloads the page when you save a file.
Set
oscillator.typeto'sawtooth'or'square': the same notes with much louder overtones.Make the notes longer:
beep(midi, audio().currentTime, 2)in the click handler lets each one ring for two seconds. The fall is still quick at first and slow at the end.Take the envelope away to hear what it is for: replace the three lines that plan the gain with
envelope.gain.value = 0.4;. Now each note is cut off at its end, and most of them click. How much depends on where in its swing the wave is cut. The A is the exception: 440 swings per second times 0.4 seconds is exactly 176 swings, so its wave ends where it began.
Put the code back as it was before you go on. In the next part a clock plays the notes, in time and by itself.
Comments
The comments are GitHub Discussions: sign in with GitHub to write one.
The comments come from GitHub, through giscus. Loading them sends your IP address to giscus.app and GitHub.