Zum Inhalt springen

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

Teil 9: Code, der Musik macht

Die Eingabefelder machen einem Editor Platz. Sein Code beschreibt einen Song über eine kleine API, die aus einem Schema entsteht, das Ausführen ergibt einen Patch aus reinen Daten, und eine Engine macht daraus Bausteine, die spielen. CodeMirror und zwei Tasten runden die Seite ab.

Quest-Ziele

  • Jede Art von Baustein in einem Schema beschreiben und daraus die API eines Songs bauen
  • Den Code eines Editors mit new Function ausführen und in einem Patch sammeln, was er erzeugt
  • Eine Verbindung daran prüfen, was ein Baustein gibt und der andere nimmt
  • Eine Engine bauen, die die Bausteine eines Patches erzeugt und ihnen ihre Noten schickt
  • CodeMirror 6 mit Tasten einrichten, die den Song ausführen und stoppen

Zwei Eingabefelder haben für einen Drumcomputer und einen Bass gereicht. Für einen Song reichen sie nicht. Jedes neue Instrument bräuchte ein weiteres Feld, und die Einstellungen des Synths stehen im Quellcode, unerreichbar für alle, die die Seite nur benutzen. Dieser Teil ist der Wendepunkt der Serie: Die Eingabefelder gehen, ein Editor kommt, und der Song wird zu Code. Was die App von hier an lernt, kann der Code im Editor verlangen.

Es ist auch der größte Teil. Er hat drei neue Ideen, eine API, einen Patch und eine Engine, und dazu einen Editor und eine Seite, die sie aufnimmt.

Ein Song ist Code

Das ist der Song, mit dem der Editor beginnen wird. Lege src/song.ts an:

src/song.ts
/** The code the editor starts with. */
export const SONG = `bpm(124)

const kit = drums()
pattern('bd*4, ~ cp ~ cp, hh*8?0.2').to(kit)
kit.to(out)

const bass = monoSynth({ cutoff: 300, resonance: 8 })
pattern('a1 a1:a [a2:s c2] <e2:s g2:as>').to(bass)
bass.to(out)
`;

Die Datei ist TypeScript, aber der Text zwischen den Backticks ist der Song, und der Song ist JavaScript, das die App ausführen wird. Er liest sich so:

  • bpm(124) setzt das Tempo in Schlägen pro Minute. Das war die Aufgabe des Reglers.

  • drums() erzeugt einen Drumcomputer und monoSynth() den Synth aus Teil 8. Seine Optionen stellen den Filter ein: cutoff ist die Frequenz, auf der der Filter ruht, und resonance sagt, wie stark er diese Frequenz betont.

  • pattern('…') erzeugt ein Pattern aus einem Text in Mini-Notation.

  • .to() verbindet. pattern('…').to(kit) schickt die Noten des Patterns an die Drums, und kit.to(out) schickt den Klang der Drums an out, die Lautsprecher.

Dazu gehören drei Wörter, im Code und für den Rest der Serie. Alles, was der Code erzeugt, ist ein Baustein. Eine Verbindung zwischen zwei Bausteinen ist ein Kabel, und es trägt entweder Noten oder Audio. Die Bausteine, die Kabel und das Tempo zusammen sind ein Patch. Das Wort stammt von Synthesizern, deren Teile von Hand mit Kabeln verbunden werden.

Der Patch

Der naheliegende Weg wäre, drums() auf der Stelle einen Drumcomputer erzeugen zu lassen. Aber der Code wird immer wieder ausgeführt werden, während die Musik spielt, und jeder Durchlauf würde neue Instrumente auf die setzen, die schon spielen. Also macht das Ausführen des Codes gar keinen Klang. Es beschreibt nur. Ein Durchlauf ergibt einen Patch aus reinen Daten: eine Liste dessen, was es geben soll. Etwas anderes, die Engine, macht das hörbar. Lege src/patch.ts an:

src/patch.ts
/** What an option of a unit can be set to. */
export type Value = number | string;
export type Options = Record<string, Value>;

/** One thing the code created: a pattern, an instrument, an effect. */
export interface UnitSpec {
  /** Its type and a count, such as monoSynth1: the same line of code gets the same id on every run. */
  id: string;
  type: string;
  options: Options;
}

/** A connection from one unit to another, by their ids. */
export interface Cable {
  from: string;
  to: string;
  kind: 'notes' | 'audio';
}

/** Everything a run of the code describes. Plain data: nothing in it makes a sound yet. */
export interface Patch {
  bpm: number;
  units: UnitSpec[];
  cables: Cable[];
}

Ein Baustein wird als sein Typ, seine Optionen und eine ID notiert. Die ID ist der Typ und eine Nummer, in der Reihenfolge, in der der Code die Bausteine erzeugt. Der Song vom Anfang ergibt drums1, pattern1, monoSynth1 und pattern2. Seine vier Kabel tragen Noten von pattern1 zu drums1 und von pattern2 zu monoSynth1, und Audio von drums1 und von monoSynth1 zu out.

Reine Daten lassen sich vergleichen und weiterreichen, und die nächsten Teile brauchen beides. Teil 10 vergleicht den Patch eines Durchlaufs mit dem, was gerade spielt, und ändert nur den Unterschied. Teil 11 führt den Code in einem Worker aus, der den fertigen Patch an die Seite schickt.

Die API und ihr Schema

bpm, drums, monoSynth, pattern und out sind die API eines Songs: die Namen, die sein Code benutzen kann. Die Funktionen, die Bausteine erzeugen, werden nicht einzeln geschrieben. Sie entstehen aus einer Beschreibung jeder Art von Baustein, dem Schema. Lege src/schema.ts an:

src/schema.ts
import type { Value } from './patch.ts';

export interface OptionSpec {
  doc: string;
  default: Value;
  /** The range of a number. */
  min?: number;
  max?: number;
  /** The words a text can be. */
  choices?: readonly string[];
}

export interface UnitType {
  doc: string;
  /** What its input takes, if it has one, and what its output gives. */
  takes?: 'notes' | 'audio';
  gives?: 'notes' | 'audio';
  options: Record<string, OptionSpec>;
}

Eine Art von Baustein sagt, was in sie hineingeht und was aus ihr herauskommt, notes oder audio, und zählt ihre Optionen auf, jede mit einem Standardwert. Die Arten folgen in derselben Datei:

src/schema.ts
const volume: OptionSpec = { doc: 'How loud it is, from 0 to 1.', default: 0.5, min: 0, max: 1 };

/** Every kind of unit the code can create: there is a function of the same name for each. */
export const UNITS: Record<string, UnitType> = {
  pattern: {
    doc: 'Plays notes written in mini-notation, one cycle per bar. Connect it to an instrument.',
    gives: 'notes',
    options: {
      source: { doc: 'The pattern, in mini-notation.', default: '' },
      velocity: { doc: 'How hard the notes are played, from 0 to 1.', default: 1, min: 0, max: 1 },
      legato: { doc: 'How much of its step a note is held: 0.5 is half of it.', default: 1, min: 0.05, max: 4 },
    },
  },
  drums: {
    doc: 'A drum machine. Sounds: bd sd hh oh cp rim lt mt ht cb cy.',
    takes: 'notes',
    gives: 'audio',
    options: { volume },
  },
  monoSynth: {
    doc: 'One voice for bass lines and leads. c2:a plays a note with an accent, c2:s slides into the next.',
    takes: 'notes',
    gives: 'audio',
    options: {
      wave: { doc: "The oscillator's wave.", default: 'sawtooth', choices: ['sawtooth', 'square', 'triangle', 'sine'] },
      cutoff: { doc: 'Where the filter rests, in hertz.', default: 300, min: 30, max: 8000 },
      resonance: { doc: 'How much the filter emphasizes its cutoff.', default: 8, min: 0.1, max: 20 },
      envelope: { doc: 'How far a note opens the filter, in octaves.', default: 3, min: 0, max: 6 },
      decay: { doc: 'How long the filter takes to close again, in seconds.', default: 0.2, min: 0.01, max: 2 },
      volume,
    },
  },
};

/** The speakers: `out` in the code. */
export const OUT: UnitType = { doc: 'The speakers.', takes: 'audio', options: {} };

Ein Pattern gibt Noten. Die Drums und der Mono-Synth nehmen Noten und geben Audio. out nimmt Audio und gibt nichts. Mehr muss .to() nicht wissen, um ein sinnvolles Kabel von einem sinnlosen zu unterscheiden.

Die Standardwerte von monoSynth sind die Optionen, die der Bass in Teil 8 hatte. Die Texte in doc, die Bereiche und die choices liest noch nichts. Teil 11 prüft Optionen gegen sie, und Teil 17 zeigt sie im Editor. Von jetzt an beginnt eine neue Art von Baustein als Eintrag in dieser Liste, und die Funktion für den Code des Songs kommt mit.

Aus Code wird ein Patch

Lege src/script.ts an. Die Datei beginnt mit dem, was der Code des Songs von drums() oder pattern() zurückbekommt. Der Baustein selbst kann es nicht sein, denn während der Code läuft, gibt es keinen Drumcomputer. Es ist ein Handle: ein Objekt, das die ID eines Bausteins kennt und ihn verbinden kann.

src/script.ts
import { mini, MiniError } from './mini.ts';
import type { Options, Patch } from './patch.ts';
import { OUT, UNITS, type UnitType } from './schema.ts';

/** A mistake in the code that we found, as opposed to one JavaScript found. */
export class ScriptError extends Error {}

/** What the code holds in its variables: a unit of the patch, which can be connected. */
class Handle {
  readonly id: string;
  readonly type: string;
  private readonly spec: UnitType;
  private readonly patch: Patch;

  constructor(id: string, type: string, spec: UnitType, patch: Patch) {
    this.id = id;
    this.type = type;
    this.spec = spec;
    this.patch = patch;
  }

  /** Connects this unit to another one. Gives back the other one, so that calls can be chained. */
  to(target: Handle): Handle {
    if (!(target instanceof Handle)) throw new ScriptError(`${this.type}.to() needs something to connect to, such as out`);
    const gives = this.spec.gives;
    const takes = target.spec.takes;
    if (!gives) throw new ScriptError(`${this.type} has no output`);
    if (gives !== takes) {
      throw new ScriptError(`${this.type} gives ${gives}, but ${target.type} ${takes ? `takes ${takes}` : 'has no input'}`);
    }
    this.patch.cables.push({ from: this.id, to: target.id, kind: gives });
    return target;
  }
}

to() schlägt im Schema nach, was dieser Baustein gibt und was das Ziel nimmt. Passt beides zusammen, kommt ein Kabel in den Patch. Passt es nicht, wirft es einen Fehler, der sagt, was nicht stimmt: pattern('bd*4').to(out) endet mit pattern gives notes, but out takes audio. Und es gibt das Ziel zurück, sodass sich Aufrufe verketten lassen: pattern('bd*4').to(kit).to(out) verbindet das Pattern mit dem Kit und das Kit mit den Lautsprechern.

ScriptError kennzeichnet die Fehler, die dieser Code findet, im Unterschied zu denen, die JavaScript findet. Teil 11 behandelt die beiden verschieden. Die Funktion, die den Code ausführt, folgt in derselben Datei:

src/script.ts
/** Runs the code and gives back the patch it describes. */
export function runScript(code: string): Patch {
  const patch: Patch = { bpm: 120, units: [], cables: [] };
  const counts: Record<string, number> = {};

  /** Adds a unit to the patch: the options the code gave, on top of the defaults. */
  function create(type: string, given: Options = {}): Handle {
    const spec = UNITS[type];
    counts[type] = (counts[type] ?? 0) + 1;
    const options: Options = {};
    for (const [name, option] of Object.entries(spec.options)) options[name] = given[name] ?? option.default;
    const id = `${type}${counts[type]}`;
    patch.units.push({ id, type, options });
    return new Handle(id, type, spec, patch);
  }

  /** Everything the code can use, by name. */
  const api: Record<string, unknown> = {
    out: new Handle('out', 'out', OUT, patch),
    bpm(value: number) {
      patch.bpm = Math.min(240, Math.max(40, Number(value) || 120));
    },
  };
  for (const type of Object.keys(UNITS)) api[type] = (options?: Options) => create(type, options);

  // A pattern takes its text first. Reading it here finds mistakes before anything plays.
  api.pattern = (source: string, options?: Options) => {
    try {
      mini(String(source));
    } catch (error) {
      if (error instanceof MiniError) throw new ScriptError(`${error.message} at character ${error.position + 1} of "${source}"`);
      throw error;
    }
    return create('pattern', { ...options, source: String(source) });
  };

  // The code becomes the body of a function whose parameters are the names of the API.
  const run = new Function(...Object.keys(api), `"use strict";${code}`);
  run(...Object.values(api));
  return patch;
}

create() fügt dem Patch einen Baustein hinzu. Es geht die Optionen durch, die das Schema aufzählt, und nimmt den Wert, den der Code angegeben hat, sonst den Standardwert. Ein Patch enthält also immer jede Option jedes Bausteins. Eine Option, die das Schema nicht aufzählt, fällt kommentarlos weg: monoSynth({ cutof: 900 }) spielt mit dem Standard-Cutoff. Teil 11 macht daraus eine Meldung.

api enthält alles, was der Code des Songs benutzen kann: out, bpm(), das das Tempo zwischen 40 und 240 hält, und eine Funktion pro Eintrag des Schemas. pattern bekommt danach eine eigene Fassung, weil sein Text zuerst kommt und seine Optionen danach. Sie liest den Text außerdem sofort mit mini(). Ein kaputtes Pattern bricht den Durchlauf mit einer Meldung ab, die das Zeichen nennt, bevor etwas vom neuen Code zu hören ist.

Die letzten drei Zeilen führen den Code aus. new Function() macht aus Text eine Funktion. Ihr letztes Argument ist der Rumpf, die Argumente davor sind die Namen der Parameter. Der Song wird also zum Rumpf einer Funktion mit den Parametern out, bpm, pattern, drums und monoSynth, und diese Funktion wird mit den Werten der API aufgerufen. Im Song sind die Namen dann da, ohne Import und ohne dass etwas an window gehängt wird. Das "use strict" davor macht JavaScript strenger: Einem Namen etwas zuzuweisen, der nie deklariert wurde, ist ein Fehler und keine neue globale Variable.

Wenn die Funktion zurückkehrt, ist der Patch fertig, und kein einziger Audio-Knoten wurde erzeugt.

Bausteine

Auf der anderen Seite des Patches steht das, was den Klang macht. Für jeden Baustein eines Patches wird die Engine ein Objekt erzeugen, und alle diese Objekte haben dieselbe Form. Lege src/unit.ts an:

src/unit.ts
import type { Clock } from './clock.ts';
import type { NoteEvent } from './notes.ts';
import type { Options } from './patch.ts';

/** A unit of the patch as it runs: what the engine creates for a UnitSpec. */
export interface Unit {
  /** Where audio comes in, and where it leaves. */
  readonly input?: AudioNode;
  readonly output?: AudioNode;
  /** Takes over new options without starting over. */
  update(options: Options): void;
  /** The notes this unit gives for a stretch of cycles. */
  events?(from: number, to: number, clock: Clock): NoteEvent[];
  /** Plays a note. */
  play?(event: NoteEvent): void;
  /** Called when the music stops: let go of every note that is still held. */
  stop?(): void;
  dispose(): void;
}

Das meiste davon ist optional, denn Bausteine unterscheiden sich. Ein Pattern hat events(). Ein Instrument hat play() und einen output. out hat nur einen input. Jeder Baustein kann mit update() neue Optionen übernehmen und mit dispose() weggeworfen werden.

Unit tritt an die Stelle des Instrument aus Teil 8. Entferne das Interface Instrument aus src/notes.ts.

Der Baustein hinter pattern() ist neu. Er tut, was der Callback der Uhr in der src/main.ts von Teil 8 getan hat: Er fragt ein Pattern nach einem Abschnitt von Zyklen und macht aus den Ereignissen Noten-Ereignisse. Lege src/player.ts an:

src/player.ts
import type { Clock } from './clock.ts';
import { mini, type Atom } from './mini.ts';
import { readAtom, type NoteEvent } from './notes.ts';
import { silence, type Pattern } from './pattern.ts';
import type { Unit } from './unit.ts';

export type PlayerOptions = {
  source: string;
  velocity: number;
  legato: number;
};

/** Turns a pattern into note events: what `pattern('…')` in the code creates. */
export class Player implements Unit {
  private options: PlayerOptions;
  private pattern: Pattern<Atom> = silence();

  constructor(options: PlayerOptions) {
    this.options = options;
    this.update(options);
  }

  update(options: PlayerOptions) {
    this.options = options;
    this.pattern = mini(options.source);
  }

  events(from: number, to: number, clock: Clock): NoteEvent[] {
    return this.pattern(from, to).map((hap) => ({
      ...readAtom(hap.value),
      time: clock.timeAt(hap.begin),
      duration: (hap.end - hap.begin) * clock.cycleSeconds * this.options.legato,
      velocity: this.options.velocity,
    }));
  }

  dispose() {}
}

update() liest den Text mit mini(), ein Player hält also immer ein Pattern, das gefragt werden kann. Zwei Optionen ändern die Noten unterwegs. velocity sagt, wie fest sie gespielt werden. legato skaliert ihre Länge: Mit 0,5 wird eine Note die Hälfte ihres Schritts gehalten. Für einen Slide muss die nächste Note dort beginnen, wo die vorige endet. Mit einem legato unter 1 sind die Slides aus Teil 8 also weg. Ein Player hält nichts, das freigegeben werden müsste, deshalb ist sein dispose() leer.

Die zwei Instrumente ändern sich auf dieselbe Weise. Bisher bekam jedes einen Knoten, mit dem es sich selbst verbunden hat. Als Bausteine bieten sie einen output an und überlassen das Stecken der Engine, und ihre Optionen nehmen sie als ein Objekt. Ersetze in src/drums.ts die Imports:

src/drums.ts
import { audio } from './audio.ts';
import type { NoteEvent } from './notes.ts';
import type { Unit } from './unit.ts';

Ersetze den Kopf der Klasse, von ihrem Kommentar bis zum Konstruktor, durch das Folgende. Der Typ der Optionen über der Klasse und update() sind neu:

src/drums.ts
export type DrumsOptions = {
  volume: number;
};

/** A drum machine without samples: every hit is built from oscillators and noise. */
export class Drums implements Unit {
  private readonly context = audio();
  /** Everything the kit plays goes through this gain: its volume. */
  readonly output = this.context.createGain();
  /** The open hi-hat that is still ringing. A closed one cuts it off. */
  private openHat: GainNode | undefined;

  constructor(options: DrumsOptions) {
    this.output.gain.value = options.volume;
  }

  update(options: DrumsOptions) {
    this.output.gain.setTargetAtTime(options.volume, this.context.currentTime, 0.02);
  }

Die Lautstärke stand fest auf 0,5 und ist jetzt eine Option. Ergänze dispose() unter stop():

src/drums.ts
dispose() {
  this.output.disconnect();
}

Ersetze auch in src/monoSynth.ts die Imports:

src/monoSynth.ts
import { audio, midiToFreq } from './audio.ts';
import type { NoteEvent } from './notes.ts';
import type { Unit } from './unit.ts';

Ersetze die Klasse von ihrer ersten Zeile bis zum Ende von update(). Der Gain-Knoten volume heißt jetzt output und ist öffentlich, der Konstruktor nimmt nur noch die Optionen, und die Kette der Knoten endet bei output:

src/monoSynth.ts
export class MonoSynth implements Unit {
  private readonly context = audio();
  private readonly oscillator = this.context.createOscillator();
  private readonly filter = this.context.createBiquadFilter();
  private readonly gate = this.context.createGain();
  readonly output = this.context.createGain();
  private options: MonoSynthOptions;
  /** When the last note slides: the time at which it ends, and the next one takes over. */
  private slideEnd: number | undefined;

  constructor(options: MonoSynthOptions) {
    this.options = options;
    this.filter.type = 'lowpass';
    this.gate.gain.value = 0;
    this.oscillator.connect(this.filter).connect(this.gate).connect(this.output);
    this.oscillator.start();
    this.update(options);
  }

  update(options: MonoSynthOptions) {
    this.options = options;
    const now = this.context.currentTime;
    this.oscillator.type = options.wave;
    this.filter.Q.setTargetAtTime(options.resonance, now, 0.02);
    this.filter.frequency.setTargetAtTime(options.cutoff, now, 0.02);
    this.output.gain.setTargetAtTime(options.volume, now, 0.02);
  }

play() und stop() bleiben, wie sie sind. Ersetze dispose():

src/monoSynth.ts
dispose() {
  this.oscillator.stop();
  this.output.disconnect();
}

Die Engine

Die Engine macht einen Patch hörbar. Lege src/engine.ts an. Die Datei beginnt mit einer Tabelle, die sagt, wie ein Baustein jeder Art entsteht:

src/engine.ts
import { audio } from './audio.ts';
import { Clock } from './clock.ts';
import { Drums, type DrumsOptions } from './drums.ts';
import { MonoSynth, type MonoSynthOptions } from './monoSynth.ts';
import type { Options, Patch } from './patch.ts';
import { Player, type PlayerOptions } from './player.ts';
import type { Unit } from './unit.ts';

/**
 * How a unit of each type is made. A patch holds its options as plain data. The script
 * filled in every option the schema lists, so here they are taken for what each unit expects.
 */
const FACTORIES: Record<string, (options: Options) => Unit> = {
  pattern: (options) => new Player(options as PlayerOptions),
  drums: (options) => new Drums(options as DrumsOptions),
  monoSynth: (options) => new MonoSynth(options as MonoSynthOptions),
};

Ein Patch enthält die Optionen eines Bausteins als einfachen Record aus Namen und Werten, und jede Klasse will ihren eigenen Typ für die Optionen. Das Skript hat jede Option eingetragen, die das Schema aufzählt, also nimmt die Tabelle den Record mit as als das, was die Klasse erwartet.

Die Klasse folgt in derselben Datei:

src/engine.ts
/** Makes a patch audible: creates its units, connects them, and sends them their notes. */
export class Engine {
  readonly clock = new Clock((from, to) => this.schedule(from, to));
  private readonly units = new Map<string, Unit>();
  /** For every unit that gives notes, the units that play them. */
  private routes = new Map<Unit, Unit[]>();

  constructor() {
    // `out` is a unit like the others: a gain in front of the speakers.
    const out = audio().createGain();
    out.connect(audio().destination);
    this.units.set('out', { input: out, update() {}, dispose() {} });
  }

  /** Replaces what is playing with a new patch. */
  apply(patch: Patch) {
    for (const [id, unit] of this.units) {
      if (id === 'out') continue;
      unit.dispose();
      this.units.delete(id);
    }
    for (const spec of patch.units) this.units.set(spec.id, FACTORIES[spec.type](spec.options));

    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]);
    }
    this.clock.bpm = patch.bpm;
  }

  start() {
    this.clock.start();
  }

  stop() {
    this.clock.stop();
    for (const unit of this.units.values()) unit.stop?.();
  }

  /** Asks every unit that gives notes for the next stretch, and hands them to their players. */
  private schedule(from: number, to: number) {
    for (const [source, targets] of this.routes) {
      for (const event of source.events?.(from, to, this.clock) ?? []) {
        for (const target of targets) target.play?.(event);
      }
    }
  }
}

Der Engine gehört die Uhr aus Teil 2, die schedule() mit jedem Abschnitt von Zyklen aufruft, der gleich zu hören sein wird. out ist ein Baustein wie die anderen und entsteht einmal: ein Gain-Knoten vor den Lautsprechern, mit nichts als einem Eingang.

apply() ersetzt das, was spielt, durch einen neuen Patch. Es wirft jeden Baustein außer out weg und erzeugt die Bausteine des Patches aus der Tabelle. Dann geht es die Kabel durch. Ein Audio-Kabel ist eine Verbindung der Web Audio API, vom output des einen Bausteins zum input des anderen. Ein Noten-Kabel kennt die Web Audio API nicht. Es wird ein Eintrag in routes: für jeden Baustein, der Noten gibt, die Liste der Bausteine, die sie spielen. Das Tempo kommt zuletzt. Die Uhr versetzt ihren Anker, wenn das Tempo gesetzt wird, die Position im Song springt also nicht.

schedule() benutzt die Routen. Es fragt jeden Baustein, der Noten gibt, nach den Ereignissen des Abschnitts und reicht jedes Ereignis an jeden Baustein auf seiner Liste. Ein Pattern, das mit zwei Synths verbunden ist, spielt auf beiden, und zwei Patterns, die mit einem Drumcomputer verbunden sind, spielen beide auf ihm.

Was apply() tut, ist grob, und man hört es. Jeder Durchlauf baut alle Bausteine neu. Die alten werden mitten im Klang abgesteckt, und die Noten, die auf ihnen schon eingeplant waren, gehen verloren. Jedes Mal, wenn du den Code ausführst, während die Musik spielt, wird der Klang abgeschnitten, auch wenn du nichts geändert hast. Die Position bleibt erhalten: Die Uhr läuft weiter, und die neuen Patterns werden nach den Zyklen gefragt, nach denen die alten gefragt worden wären. Teil 10 beseitigt den Schnitt. Dort behält die Engine die Bausteine, die noch im Patch stehen, und ändert nur, was der Code geändert hat.

Der Editor

Der Editor ist CodeMirror 6, ein Code-Editor für den Browser, der aus Paketen zusammengesetzt wird. Installiere fünf davon:

~/loopcode
$ npm install codemirror @codemirror/lang-javascript @codemirror/theme-one-dark @codemirror/state @codemirror/viewadded 19 packages, and audited 37 packages in 3s8 packages are looking for funding  run `npm fund` for detailsfound 0 vulnerabilities

codemirror bringt den Editor und eine Grundausstattung, @codemirror/lang-javascript kennt JavaScript, und @codemirror/theme-one-dark ist ein dunkles Farbschema. @codemirror/state und @codemirror/view sind der Kern des Editors, und der Code importiert direkt aus ihnen. Lege src/editor.ts an:

src/editor.ts
import { javascript } from '@codemirror/lang-javascript';
import { Prec } from '@codemirror/state';
import { oneDark } from '@codemirror/theme-one-dark';
import { keymap } from '@codemirror/view';
import { basicSetup, EditorView } from 'codemirror';

export interface EditorKeys {
  /** Ctrl+Enter (Cmd+Enter on a Mac). */
  run(): void;
  /** Ctrl+. */
  stop(): void;
}

/** The page's colors for the editor's background. The theme after it fills in the rest. */
const look = EditorView.theme(
  {
    '&': { backgroundColor: 'var(--void)' },
    '.cm-gutters': { backgroundColor: 'var(--void)', border: 'none' },
    '.cm-activeLine, .cm-activeLineGutter': { backgroundColor: 'var(--night)' },
  },
  { dark: true },
);

/** A code editor in `parent`, holding `code`. */
export function createEditor(parent: HTMLElement, code: string, keys: EditorKeys): EditorView {
  return new EditorView({
    parent,
    doc: code,
    extensions: [
      // Before the basic setup, and with the highest precedence: Ctrl+Enter means
      // something else there.
      Prec.highest(
        keymap.of([
          { key: 'Mod-Enter', run: () => (keys.run(), true) },
          { key: 'Mod-.', run: () => (keys.stop(), true) },
        ]),
      ),
      basicSetup,
      javascript(),
      look,
      oneDark,
    ],
  });
}

Ein CodeMirror-Editor ist ein EditorView mit einer Liste von Erweiterungen, und alles, was er kann, ist eine Erweiterung. basicSetup ist ein Bündel der üblichen, etwa Zeilennummern, Rückgängig und zusammengehörige Klammern. javascript() färbt den Code. oneDark ist das Farbschema, und look davor setzt die Hintergründe auf die Farben der Seite. Wo zwei Erweiterungen dasselbe setzen, gewinnt die frühere, und oneDark ergänzt den Rest.

Auch die Tasten sind eine Erweiterung. Mod steht für Strg, und auf einem Mac für Cmd. Ein Handler gibt true zurück, um zu sagen, dass die Taste erledigt ist. Die Grundausstattung hat für Strg+Enter eine eigene Belegung, die eine Leerzeile einfügt. Deshalb steckt die Tastenbelegung in Prec.highest() und kommt vor jeder anderen. Was die Tasten tun, ist nicht Sache des Editors. Das gibt ihm die Seite als keys mit.

Die Seite

Von der Seite bleibt wenig: die Kopfzeile, der Editor und eine Statuszeile. Ersetze index.html durch:

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>
      <button id="play">▶ Play</button>
      <span id="position" class="position">1.1</span>
      <span class="tempo"><span id="bpm">120</span> bpm</span>
      <button id="run" title="Ctrl+Enter">Run</button>
    </header>
    <main id="editor" class="editor"></main>
    <footer id="status" class="status"></footer>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

Der Tempo-Regler ist weg, denn bpm() im Code setzt das Tempo. Die Kopfzeile zeigt nur noch die Zahl, und sie hat einen Run-Button. Ersetze in src/style.css alles von der Regel .tempo bis zum Ende der Datei durch das Folgende. Damit fallen die Regeln des Reglers und die von .stage, .hint, .line und .message weg:

src/style.css
.tempo {
  margin-left: auto;
  color: var(--muted);
}

.editor {
  flex: 1;
  min-height: 0;
}

.editor .cm-editor {
  height: 100%;
}

.editor .cm-scroller {
  font: inherit;
  line-height: 1.5;
}

.status {
  min-height: 2.2em;
  padding: 6px 12px;
  background: var(--night);
  border-top: 2px solid var(--edge);
  color: var(--muted);
  white-space: pre-wrap;
}

.status.error {
  color: var(--orange);
}

Der Editor nimmt den Platz zwischen der Kopfzeile und der Statuszeile ein. Die Seite ist eine Spalte aus Flex-Elementen, und ein Flex-Element ist von sich aus mindestens so hoch wie sein Inhalt. min-height: 0 erlaubt dem Editor, kleiner zu sein als sein Text, ein langer Song scrollt also im Editor. Bei einem Fehler wird die Statuszeile orange.

Ersetze src/main.ts durch die nächsten zwei Blöcke. Der erste enthält die Funktionen zum Ausführen, Starten und Stoppen:

src/main.ts
import { audio } from './audio.ts';
import { createEditor } from './editor.ts';
import { Engine } from './engine.ts';
import { runScript } from './script.ts';
import { SONG } from './song.ts';
import './style.css';

const engine = new Engine();

const play = document.querySelector<HTMLButtonElement>('#play')!;
const status = document.querySelector<HTMLElement>('#status')!;
const bpm = document.querySelector<HTMLSpanElement>('#bpm')!;

/** 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());
    engine.apply(patch);
    bpm.textContent = String(patch.bpm);
    status.textContent = `${patch.units.length} units, ${patch.cables.length} cables`;
    status.classList.remove('error');
    return true;
  } catch (error) {
    status.textContent = String(error instanceof Error ? error.message : error);
    status.classList.add('error');
    return false;
  }
}

function start() {
  void audio().resume();
  if (!engine.clock.playing && run()) engine.start();
  showPlaying();
}

function stop() {
  engine.stop();
  showPlaying();
}

function showPlaying() {
  play.textContent = engine.clock.playing ? '■ Stop' : '▶ Play';
  play.classList.toggle('on', engine.clock.playing);
}

run() ist der ganze Weg in drei Zeilen. Der Text des Editors geht durch runScript(), der Patch geht an die Engine, und die Statuszeile sagt, was der Patch enthält. Wirft der Code einen Fehler, sei es ein Syntaxfehler, ein Name, den es nicht gibt, oder ein ScriptError, zeigt das catch die Meldung. engine.apply() wurde nie erreicht, also spielt weiter, was gespielt hat.

start() führt den Code aus und startet die Uhr nur, wenn der Durchlauf geklappt hat. Es setzt außerdem den AudioContext fort, was der Browser nach einem Klick oder einer Taste erlaubt, wie in Teil 1. Der Rest der Datei verbindet das alles mit der Seite:

src/main.ts
const editor = createEditor(document.querySelector<HTMLElement>('#editor')!, SONG, {
  // Ctrl+Enter starts the music, or runs the changed code while it plays.
  run: () => (engine.clock.playing ? run() : start()),
  stop,
});

play.addEventListener('click', () => (engine.clock.playing ? stop() : start()));
document.querySelector<HTMLButtonElement>('#run')!.addEventListener('click', () => {
  if (engine.clock.playing) run();
  else start();
});

/** Shows where the music is, as bar.beat, once per frame. */
const position = document.querySelector<HTMLSpanElement>('#position')!;
function draw() {
  const { clock } = engine;
  const cycle = clock.playing ? Math.max(0, clock.cycleAt(audio().currentTime)) : 0;
  position.textContent = `${Math.floor(cycle) + 1}.${Math.floor((cycle % 1) * 4) + 1}`;
  requestAnimationFrame(draw);
}
draw();

Strg+Enter im Editor startet die Musik oder führt den geänderten Code aus, während sie spielt. Strg+. stoppt sie. Auf einem Mac ist es bei beiden Cmd statt Strg. Der Play-Button startet und stoppt, und der Run-Button tut, was Strg+Enter tut. draw() ist die Anzeige aus Teil 2, mit der Uhr aus der Engine.

Probier es aus

Drück Play, oder klick in den Editor und drück Strg+Enter. Der Song spielt, und in der Statuszeile steht 4 units, 4 cables.

  • Ändere bpm(124) zu bpm(90) und drück Strg+Enter. Der Song ist langsamer, die Kopfzeile zeigt 90, und im Moment des Durchlaufs hörst du den Schnitt.

  • Gib dem Bass andere Optionen: monoSynth({ cutoff: 800, resonance: 12, decay: 0.5 }). Die Noten sind heller, und der Filter braucht länger, um zu schließen.

  • Lösch die Zeile kit.to(out) und führ den Code aus. Die Drums sind still, und die Statuszeile zählt ein Kabel weniger. Für die App ist das kein Fehler: Ein Baustein, dem nichts zuhört, ist erlaubt. Setz die Zeile wieder ein.

  • Ergänze pattern('~ ~ ~ [~ rim]').to(kit) unter dem ersten Pattern. Zwei Patterns spielen dasselbe Kit, und in der Statuszeile steht 5 units, 5 cables.

  • Schreib pattern('bd*4').to(out) ans Ende. Die Statuszeile wird orange und zeigt pattern gives notes, but out takes audio, und die Musik spielt weiter wie zuvor.

  • Mach noch zwei Fehler. drum() statt drums() ergibt in Chrome drum is not defined. pattern('bd [sd') ergibt Missing "]" at character 7 of "bd [sd". Die Meldungen sagen, was nicht stimmt, aber nicht, in welcher Zeile. Das ergänzt Teil 11.

Der Song ist JavaScript, also ist alles da, was JavaScript hat: Variablen, Schleifen, Funktionen. Ersetze den ganzen Song durch diesen und führ ihn aus:

javascript
bpm(110)

const kit = drums({ volume: 0.4 })
for (const beat of ['bd(3,8)', '~ sd', 'hh*<4 8>']) {
  pattern(beat).to(kit)
}
kit.to(out)

const lead = monoSynth({ wave: 'square', cutoff: 800, envelope: 2, decay: 0.1 })
pattern('{c3 e3 g3 a3 c4}%8', { legato: 0.5 }).to(lead).to(out)

Die Schleife erzeugt drei Patterns für ein Kit, und die letzte Zeile steckt zwei Kabel auf einmal. In der Statuszeile steht 6 units, 6 cables. Der Lead lässt fünf Noten über acht Schritte laufen, seine Figur beginnt also in jedem Takt auf einem anderen Schritt, und mit legato: 0.5 hört jede Note nach der Hälfte ihres Schritts auf.

Eines steht noch zwischen dem hier und Live-Coding: der Schnitt bei jedem Durchlauf. Der nächste Teil nimmt ihn weg.

Die App am Ende von Teil 9. Drück Play, ändere den Code und drück Strg+Enter (Cmd+Enter auf einem Mac), um ihn auszuführen. Strg+. stoppt. Die Zeile unter dem Editor zeigt, was der Durchlauf erzeugt hat oder was schiefging.
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.