Zum Inhalt springen

Eine Live-Coding-Musik-App bauen · Teil 1 von 18 der Serie

Teil 1: Ein erster Ton

Der Anfang von loopcode, einer Live-Coding-Musik-App für den Browser: Du richtest ein Vite-Projekt mit TypeScript ein, lernst die Web Audio API als Graph aus Knoten kennen und spielst eine erste Note mit einem Oszillator und einer Hüllkurve, die das Knacken verhindert.

Quest-Ziele

  • Wissen, was du in dieser Serie baust
  • Ein Vite-Projekt mit TypeScript anlegen
  • Audio-Knoten in einem AudioContext verbinden
  • Einer Note eine Hüllkurve geben, damit sie nicht knackt
  • MIDI-Notennummern in Frequenzen umrechnen
  • Klang mit einem Klick starten, wie Browser es verlangen

Live-Coding heißt, Musik zu machen, indem man Code schreibt, während die Musik läuft. Ein paar Zeilen beschreiben einen Schlagzeugrhythmus oder eine Basslinie. Du führst sie aus und hörst sie. Du änderst eine Zeile, führst sie noch einmal aus, und die Musik ändert sich, ohne anzuhalten.

In dieser Serie baust du loopcode, eine Live-Coding-Musik-App für den Browser. Sie hat einen Editor, und der Code darin beschreibt einen Song: Drums, Synths (Instrumente, die ihren Klang aus einfachen Wellen bauen), Effekte und die Rhythmen und Melodien, die sie spielen. Den Code auszuführen ändert die Musik, während sie läuft. Jeder Klang kommt aus der Web Audio API, die Browser eingebaut haben, ohne Audio-Bibliothek. loopcode ist ein kleiner Verwandter von wicktone, einer größeren App vom Autor dieser Seite, die dieselbe Idee um eine Arbeitsfläche mit Knoten und um weitere Instrumente erweitert.

Die Serie

  1. Ein erster Ton: das Projekt, die Web Audio API und eine Note (dieser Teil)

  2. Eine Uhr, die den Takt hält: ein Metronom, das bei jedem Tempo genau bleibt

  3. Drums aus Oszillatoren und Rauschen: ein Drumcomputer ohne aufgenommene Klänge

  4. Patterns sind Funktionen der Zeit: Rhythmen, die sich kombinieren und im Spielen austauschen lassen

  5. Eine kleine Sprache für Rhythmus: Tokenizer, Parser und Compiler für Rhythmen, die als bd [sd sd] geschrieben sind

  6. Tempo, Länge und Zufall: Schritte, die schneller, langsamer oder länger sind, Schritte, die nur manchmal spielen, und Anschläge, die sich gleichmäßig über einen Takt verteilen

  7. Auswahl, Polymeter und wechselnde Tempi: der Rest der Notation

  8. Ein Synth für Bass und Lead: ein Instrument für Basslinien und Melodien

  9. Code, der Musik macht: ein Editor und Code, der den Song beschreibt

  10. Ändern, während es spielt: den Code noch einmal ausführen, ohne Lücke in der Musik

  11. Wenn der Code falsch ist: Fehler an ihrer Zeile angezeigt, Endlosschleifen gestoppt

  12. Akkorde und Flächen: ein Synth, der mehrere Noten zugleich spielt

  13. Filter, Delay, Hall und Verzerrung: Effekte und Kabel zwischen ihnen

  14. Bewegung mit LFOs: langsame Wellen, die eine Einstellung von selbst bewegen

  15. Deine eigenen Sounds: eigene Audiodateien als Instrumente

  16. Sehen, was man hört: Noten, die im Code aufleuchten, während sie klingen, und zwei Anzeigen für den Klang

  17. Ein Editor, der hilft: Vorschläge und Erklärungen beim Tippen

  18. Speichern und teilen: der Song im Speicher des Browsers und in einem Link

Die ersten acht Teile bauen das, was den Klang macht, und das, was ihm sagt, wann er spielen soll: eine Uhr, Drums, einen Synth und eine kleine Sprache für Rhythmus. Ab Teil 9 gibt es einen Editor, und die App wird gespielt, indem man Code schreibt.

Jeder Teil endet mit der App auf ihrem Stand an dieser Stelle, spielbar direkt auf der Seite. Die Demo ist aus genau dem Code gebaut, den der Teil zeigt, und der lief mit Vite 8.3 und TypeScript 7, als die Serie entstand.

Was du brauchst

Node.js 20.19 oder neuer, das Vite 8 voraussetzt, ein Terminal, einen aktuellen Browser und Lautsprecher oder Kopfhörer. Getestet wurde die Serie in Chromium, dem Browser, auf dem Chrome und Edge aufbauen. Die Grundlagen von JavaScript oder TypeScript solltest du kennen. Wissen über Audio oder Musiktheorie brauchst du nicht: Jeder Begriff wird dort erklärt, wo er zum ersten Mal vorkommt.

Das Projekt anlegen

Der Projektgenerator von Vite richtet ein TypeScript-Projekt ohne Framework ein. Wenn er anbietet, gleich zu installieren und zu starten, antworte mit 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

Installiere dann die Pakete der Vorlage. Andere braucht die App bis Teil 9 nicht:

~
$ cd loopcode$ npm installadded 17 packages, and audited 18 packages in 5s8 packages are looking for funding  run `npm fund` for detailsfound 0 vulnerabilities

Die Vorlage bringt eine kleine Zähler-Demo mit. Entferne sie und den Ordner public mit seinen Icons, denn die Seite bekommt neue Dateien:

~/loopcode
$ rm -r src/counter.ts src/assets public

Die Seite

Die Seite besteht aus einer Kopfzeile mit dem Namen der App und einer Bühne darunter. Vorerst stehen auf der Bühne eine Reihe Tasten, die der Code einfügt, und ein Hinweis. Ersetze index.html durch das hier:

index.html
<!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>

Die Styles sind lang und haben mit Klang nichts zu tun, du musst sie also nicht durcharbeiten: Ersetze src/style.css durch das hier und mach weiter.

src/style.css
: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;
}

Ein Graph aus Knoten

Die Web Audio API macht Klang mit Knoten, die miteinander verbunden sind. Manche Knoten erzeugen Klang, manche verändern ihn, und einer steht für die Lautsprecher: die destination. Der Klang fließt die Verbindungen entlang, von den Quellen durch alles, was dazwischen liegt, bis zur destination. Was nicht mit ihr verbunden ist, direkt oder über andere Knoten, hört man nicht.

Alle Knoten gehören zu einem AudioContext. Er erzeugt sie, ihm gehört die destination, und er hat eine Uhr: currentTime, die Sekunden zählt, solange der Context läuft. Eine App braucht einen Context.

Noten als Zahlen

Ein Klang ist Luft, die hin- und herschwingt. Wie oft sie das pro Sekunde tut, ist seine Frequenz, gemessen in Hertz (Hz), und die Frequenz hörst du als Tonhöhe: wie hoch oder tief eine Note ist. Das A, auf das Orchester stimmen, schwingt 440-mal pro Sekunde.

Songs schreibt man nicht in Hertz. Musik zählt in Noten, und die übliche Art, sie zu nummerieren, kommt von MIDI, dem Standard, der Keyboards und Synthesizer verbindet. Jede Taste eines Klaviers hat eine Nummer, von einer Taste zur nächsten steigt sie um 1, und das A mit 440 Hz hat die Nummer 69. Zwölf Tasten weiter oben kommt dieselbe Note wieder, eine Oktave höher, mit der doppelten Frequenz. Die zwölf Schritte dazwischen sind so gestimmt, dass jeder die Frequenz mit demselben Faktor multipliziert. Zwölf davon ergeben den Faktor 2, der Faktor ist also die zwölfte Wurzel aus 2, und eine Note, die midi - 69 Schritte vom A entfernt ist, hat die Frequenz 440 * 2 ** ((midi - 69) / 12).

Lege src/audio.ts mit beidem an, dem Context und der Formel:

src/audio.ts
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() erzeugt den Context, wenn zum ersten Mal nach ihm gefragt wird, und gibt von da an immer denselben zurück: ??= weist nur zu, solange die Variable noch leer ist. Jede Datei der App holt sich den Context von hier.

Note 60 ist das C in der Mitte eines Klaviers, C4 genannt: midiToFreq(60) ergibt 261,63 Hz. Note 72, das C eine Oktave darüber, ergibt 523,25 Hz, das Doppelte.

Ein Oszillator und eine Hüllkurve

Ein Oszillator ist ein Knoten, der eine Welle mit einer Frequenz erzeugt, immer wieder. Er ist die schlichteste Klangquelle, die es gibt, und mit ein paar Knoten um ihn herum wird aus ihm jedes Instrument dieser Serie.

Ein Oszillator allein ergibt eine schlechte Note. Er hat vom Start bis zum Stopp die volle Lautstärke, und beim Stopp wird die Welle dort abgeschnitten, wo sie in ihrer Schwingung gerade ist. Der Lautsprecher muss von dort ohne Übergang in die Ruhelage, und diesen Sprung hört man als Knacken. Eine Note braucht einen Anfang und ein Ende: Ihre Lautstärke muss aus der Stille ansteigen und wieder in sie zurückfallen. Dieser Verlauf der Lautstärke über die Dauer einer Note ist ihre Hüllkurve.

Die Hüllkurve entsteht mit einem Gain-Knoten, der alles, was durch ihn fließt, mit einer Zahl multipliziert, seinem gain: 1 lässt den Klang, wie er ist, 0,5 halbiert ihn, 0 ist Stille. Der Oszillator läuft durch den Gain-Knoten, und dessen Lautstärke geht von 0 hinauf und wieder hinunter, während die Note klingt.

Ersetze src/main.ts. Die Datei beginnt mit einer Funktion, die eine Note spielt:

src/main.ts
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);
}
  • type ist die Form der Welle. Ein sine, ein Sinus, ist ein reiner Ton mit einer einzigen Frequenz. Ein triangle, ein Dreieck, hat dazu Obertöne, also höhere Frequenzen, die mit der Note mitklingen, aber nur leise. Bei square und sawtooth sind sie viel lauter.

  • oscillator.frequency und envelope.gain sind keine einfachen Zahlen, sondern Audio-Parameter. Ihr value setzt sie jetzt. Ihre Methoden planen Änderungen im Voraus ein, auf der Uhr des Contexts.

  • setValueAtTime(0, time) sagt, dass die Lautstärke 0 ist, wenn die Note beginnt. linearRampToValueAtTime(0.4, time + 0.01) lässt sie in einer geraden Linie steigen und zehn Millisekunden später bei 0,4 ankommen: schnell genug, um sofort da zu sein, langsam genug, um nicht zu knacken. exponentialRampToValueAtTime(0.001, time + length) lässt sie von dort in einer Kurve fallen und am Ende der Note bei 0,001 ankommen. Jede Rampe beginnt dort, wo der Schritt vor ihr geendet hat.

  • Ein exponentieller Abfall verliert in gleichen Zeiten den gleichen Anteil von dem, was noch da ist: erst schnell, dann immer langsamer. So verklingt eine gezupfte Saite. Eine solche Kurve erreicht 0 nie, und die Methode wirft einen Fehler, wenn man es von ihr verlangt. Deshalb endet der Abfall bei 0,001, einem Tausendstel der vollen Lautstärke, und dort ist der Schnitt am Ende der Note zu klein, um ihn zu hören.

  • Die Spitze liegt bei 0,4 und nicht bei 1, weil 1 das Äußerste ist, was der Ausgang verträgt, und mehrere Noten zugleich sich addieren.

  • connect() gibt den Knoten zurück, mit dem es verbunden hat. So liest sich eine Kette in der Richtung, in der der Klang fließt: Oszillator, Hüllkurve, Lautsprecher.

  • Auch start() und stop() werden eingeplant. time ist eine Zeit auf der Uhr des Contexts. Sie zu übergeben wirkt wie unnötige Arbeit, solange jede Note sofort spielt. Der nächste Teil baut darauf.

Ein Oszillator lässt sich nur einmal starten. Nach dem Stopp ist er fertig, der Gain-Knoten hinter ihm auch, und der Browser räumt beide weg. Jede Note bekommt neue Knoten. Die API ist dafür gebaut, so benutzt zu werden: eine Quelle für einen Klang, erzeugt, gespielt und weggeworfen.

Acht Tasten

Damit man etwas hört, bekommt die Seite acht Tasten: eine Oktave der C-Dur-Tonleiter, das sind die weißen Tasten eines Klaviers von einem C zum nächsten. Der Rest von src/main.ts folgt unter beep():

src/main.ts
// 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);
}

Durch as const bleibt jeder Eintrag ein Paar aus einem Namen und einer Zahl, und die Schleife kann beide mit ihren Typen auseinandernehmen. Ein Klick spielt die Note der Taste jetzt, bei currentTime.

Davor wartet der Handler auf resume(). Browser lassen eine Seite erst Klang machen, wenn jemand etwas auf ihr getan hat, einen Klick oder einen Tastendruck. Ein Context, der früher erzeugt wird, ist zunächst angehalten: Seine Uhr steht, und man hört nichts, bis nach einem Klick resume() aufgerufen wird. Hier entsteht der Context erst im ersten Klick, wenn Klang schon erlaubt ist, und resume() hat dann womöglich nichts mehr zu tun. Spätere Teile erzeugen den Context beim Laden der Seite, und dann ist es diese Zeile, die den Klang startet. Sie bleibt ab jetzt in jedem Handler, der Klang startet.

Probier es aus

Starte den Dev-Server und öffne die Adresse, die er ausgibt:

~/loopcode
$ 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

Klick die Tasten von links nach rechts an: die C-Dur-Tonleiter, eine Oktave hinauf. Das letzte C ist das erste mit der doppelten Frequenz. Jede Note ist sofort da und verklingt über 0,4 Sekunden. Klick mehrere Tasten schnell hintereinander an: Die Noten klingen zusammen, denn jede hat ihren eigenen Oszillator und ihre eigene Hüllkurve.

Ändere dann den Code und hör hin. Vite lädt die Seite neu, wenn du eine Datei speicherst.

  • Setz oscillator.type auf 'sawtooth' oder 'square': dieselben Noten mit viel lauteren Obertönen.

  • Mach die Noten länger: Mit beep(midi, audio().currentTime, 2) im Klick-Handler klingt jede zwei Sekunden lang. Der Abfall ist weiterhin am Anfang schnell und am Ende langsam.

  • Nimm die Hüllkurve weg, um zu hören, wozu sie da ist: Ersetze die drei Zeilen, die die Lautstärke einplanen, durch envelope.gain.value = 0.4;. Jetzt wird jede Note an ihrem Ende abgeschnitten, und die meisten knacken. Wie stark, hängt davon ab, wo in ihrer Schwingung die Welle abgeschnitten wird. Das A ist die Ausnahme: 440 Schwingungen pro Sekunde mal 0,4 Sekunden sind genau 176 Schwingungen, seine Welle endet also dort, wo sie begonnen hat.

Stell den Code wieder her, bevor du weitermachst. Im nächsten Teil spielt eine Uhr die Noten, im Takt und von selbst.

Die App am Ende von Teil 1. Klick eine Taste an, um ihre Note zu spielen.
In neuem Tab öffnen

Kommentare

Die Kommentare sind GitHub Discussions: Zum Schreiben mit GitHub anmelden.

Die Kommentare kommen über giscus von GitHub. Beim Laden gehen deine IP-Adresse an giscus.app und GitHub.