Create a Live Coding Music App · Part 10 of 18 in the series
Part 10: Change It While It Plays
Turn the app into a live coding app: the engine compares every run of the code with what is playing, keeps the units that are still there, creates the new ones and fades out the rest. The music changes without a gap.
Create a Live Coding Music AppPart 10 of 18
On this page
Quest objectives
- See why a unit gets the same id on every run of the code
- Compare a new patch with the units that are running
- Keep a unit and hand it its options only when they changed
- Fade a removed unit out before it is unplugged
- Show in the status line what a run kept, created and removed
Live coding is making music by writing code while the music plays: you change a line, run it, and the song changes. The app of part 9 can run code while it plays, but not like that. Every run throws all units away and builds new ones. Press Ctrl+Enter in the middle of a bar and you hear it: the bass note that was sounding is cut off with a click, and so is the tail of every drum hit, even if you changed nothing.
After this part, a run changes only what the code changed. A bass line you didn't touch plays on as if nothing had happened. A changed option moves to its new value, a new unit joins in, and a deleted one fades out. There is little code in this part. The work was done earlier, and this is where it pays off.
The same line, the same id
A run of the code makes no sound. It gives a patch: a list of units, a list of cables and a tempo, all plain data. To change as little as possible, the engine has to tell which unit of the new patch is which of the units that are running. That is what the ids are for. The script of part 9 already makes them in create(): the type of the unit and a count, in the order in which the code creates the units. The song the editor starts with gives four:
drums1fordrums()pattern1for the drum patternmonoSynth1formonoSynth(…)pattern2for the bass line
An id depends on nothing but that order. The options are not part of it, nor is the text of a pattern, nor the name of the variable. So when you change cutoff and run the code again, the synth is still monoSynth1, and the engine knows it is the one that is playing.
With ids, comparing two patches comes down to three cases:
The id is running and is in the new patch: the unit stays and takes over the new options.
The id is only in the new patch: the unit is created.
The id is only running: the unit goes.
Compare instead of rebuild
To see whether a run changed the options of a unit, the engine remembers what it last gave each one. In src/engine.ts, add a field to Engine, below units:
/** The options every unit was last given, to see which ones a run changed. */
private readonly options = new Map<string, string>();Replace apply():
/**
* Turns what is playing into a new patch, changing as little as possible. Says how many
* units stayed, how many are new and how many are gone.
*/
apply(patch: Patch): { kept: number; created: number; removed: number } {
const count = { kept: 0, created: 0, removed: 0 };
const wanted = new Set(patch.units.map((spec) => spec.id));
// 1. Units the code no longer creates fade out and go.
for (const [id, unit] of this.units) {
if (id === 'out' || wanted.has(id)) continue;
unit.dispose();
this.units.delete(id);
this.options.delete(id);
count.removed += 1;
}
// 2. Units that are still there keep running, and take over the options that changed.
// The rest are new.
for (const spec of patch.units) {
const options = JSON.stringify(spec.options);
const unit = this.units.get(spec.id);
if (!unit) {
this.units.set(spec.id, FACTORIES[spec.type](spec.options));
count.created += 1;
} else {
if (options !== this.options.get(spec.id)) unit.update(spec.options);
count.kept += 1;
}
this.options.set(spec.id, options);
}
// 3. Cables: unplug every output, then plug in what the patch says. Both happen within
// a moment, so as a rule nothing of it is heard.
for (const unit of this.units.values()) unit.output?.disconnect();
this.routes = new Map();
for (const cable of patch.cables) {
const from = this.units.get(cable.from)!;
const to = this.units.get(cable.to)!;
if (cable.kind === 'audio') from.output!.connect(to.input!);
else this.routes.set(from, [...(this.routes.get(from) ?? []), to]);
}
if (patch.bpm !== this.clock.bpm) this.clock.bpm = patch.bpm;
return count;
}Step 1 removes. wanted holds the ids of the new patch. A running unit that is not among them is disposed of and forgotten. out, the speakers, is in no patch and always stays.
Step 2 keeps and creates. The options of a unit are numbers and texts, and the script always writes them in the order of the schema. So two sets of options are the same exactly when their JSON text is the same. If the text differs from the one remembered, the unit gets the new options through update(). Every unit has had that method since part 9: the mono synth moves its filter and its volume to the new values, a pattern reads its new text. Until now only the constructors called it.
A unit whose options are the same is not touched at all. That matters for the mono synth: its update() moves the filter to the cutoff within a few hundredths of a second, and that would cut short the pluck of a note that is sounding at that moment.
Step 3 connects. Comparing the cables one by one would be possible, but there is a shorter way: unplug every output, then plug in what the new patch says. The browser works out the sound in blocks of 128 samples, which is about 3 milliseconds, and a change to the connections takes effect between two blocks, never in the middle of one. Unplugging and plugging follow each other here in a far shorter time than a block lasts. So as a rule both fall between the same two blocks, no block is worked out with the cable missing, and a cable that stays is not heard being pulled. The routes of the notes are built anew in the same loop.
A unit that step 1 removed is no longer in units, so its output is not unplugged here. It keeps its cable a moment longer, and it needs that, as you will see below.
The tempo is only set if it changed, because setting it moves the anchor of the clock (part 2), and a run that leaves the tempo alone should leave the clock alone. The method ends by handing back its three counts.
Patterns need nothing
A changed pattern is the change you will make most often, and it needs no code in this part. The update() of a pattern parses the new text and swaps one function for another. Since part 4 a pattern is a function of time: it is asked for a stretch of cycles and answers with the notes that begin in it. It holds no position and no next step that would have to be carried over to the new one.
The clock keeps counting through a run. Its next question, for the next stretch of cycles, goes to the new function instead of the old one, and the answer fits the place in the bar where the music is. Change bd*4 to bd(3,8) on the third beat, and the new rhythm goes on from the third beat. The notes of the next tenth of a second were already handed to the instruments, which is the look-ahead of the clock. So a changed pattern is heard about a tenth of a second after the run.
Fade out instead of cutting off
In part 9, dispose() unplugged a unit at once. If one of its notes is sounding, the wave is cut off in the middle of a swing, and that jump is a click, as in part 1. A unit that goes now turns itself down first. In src/drums.ts, replace dispose():
/** Fades out, and unplugs once nothing is heard any more. */
dispose() {
this.output.gain.setTargetAtTime(0, this.context.currentTime, 0.02);
window.setTimeout(() => this.output.disconnect(), 200);
}And in src/monoSynth.ts:
/** Fades out, and unplugs once nothing is heard any more. */
dispose() {
const now = this.context.currentTime;
this.output.gain.setTargetAtTime(0, now, 0.02);
this.oscillator.stop(now + 0.2);
window.setTimeout(() => this.output.disconnect(), 200);
}setTargetAtTime(0, now, 0.02) lets the volume fall towards 0 with a time constant of 0.02 seconds: every 0.02 seconds it falls to about 37% of what it was. After 0.2 seconds, ten of those, less than a ten-thousandth is left. Then the timer unplugs the output. setTimeout is not exact, as part 2 showed, but nothing depends on it here: by then there is nothing left to hear. The oscillator of the mono synth, which has been running since the synth was made, is told to stop at that moment too.
The dispose() of a pattern stays empty. It has no nodes.
Say what a run did
apply() hands back its counts so that the page can show them. In src/main.ts, replace run():
/** Runs the code in the editor. If it fails, what was playing plays on. */
function run(): boolean {
try {
const patch = runScript(editor.state.doc.toString());
const { kept, created, removed } = engine.apply(patch);
bpm.textContent = String(patch.bpm);
status.textContent = `${patch.units.length} units: ${kept} kept, ${created} new, ${removed} removed`;
status.classList.remove('error');
return true;
} catch (error) {
status.textContent = String(error instanceof Error ? error.message : error);
status.classList.add('error');
return false;
}
}The line under the editor now says how many units the patch has, how many of them were kept and how many are new, and how many of the old ones were removed. It is the quickest way to see whether a run did what you meant.
Try it
Press Play. The status line shows 4 units: 0 kept, 4 new, 0 removed. Now change the code while it plays, one change after the other, and press Ctrl+Enter (Cmd+Enter on a Mac) after each:
Change nothing. The line shows
4 units: 4 kept, 0 new, 0 removed, and the music goes on without a trace of the run. In part 9 the same key cut every note off.Change a pattern. Turn
bd*4intobd(3,8). Still 4 kept: the kick changes its rhythm from where the bar is, and the hi-hats, the clap and the bass play on.Change an option. Set
cutoffto 900. Again 4 kept: from one note to the next the bass lets more of its high frequencies through, and its line doesn't start over. Addwave: 'square'to the options as well.Change the tempo. Write
bpm(140). 4 kept: the music gets faster, and the counter of bars and beats in the header doesn't jump.
Then add a second pattern for the drums, a cowbell, below the first one:
const kit = drums()
pattern('bd*4, ~ cp ~ cp, hh*8?0.2').to(kit)
pattern('cb(3,8)').to(kit)
kit.to(out)The line shows 5 units: 4 kept, 1 new, 0 removed, and the cowbell comes in at the place in the bar where the music is. The new unit is not the cowbell, by the way. The cowbell line is the second pattern of the code now, so the running pattern2 got its text, and the bass line plays from the new pattern3. You hear no difference.
Delete the bass. Remove its three lines:
3 units: 3 kept, 0 new, 2 removed. The bass fades out within a fraction of a second, without a click, and the drums don't miss a beat.Bring it back. Undo the deletion with Ctrl+Z and run the code:
5 units: 3 kept, 2 new, 0 removed. The bass comes in where its line would be by now.Pull a cable. Delete only
bass.to(out):5 units: 5 kept, 0 new, 0 removed, and the bass is silent at once. The synth is still there and still gets its notes, but nothing leads from it to the speakers.Stop and start. Press Ctrl+. and then Play again. All units are kept: they stay when the music stops.
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.