MIDIOutput.clear() — Methode · JavaScript-Referenz

Signatur

MIDIOutput.prototype.clear()

Beschreibung

Mit MIDIOutput.prototype.send(data, timestamp) kann man MIDI-Nachrichten für einen späteren Zeitpunkt einplanen. Der Zeitstempel bezieht sich auf performance.now(). Der Browser hält solche Nachrichten in einer internen Warteschlange, bis ihr Zeitpunkt erreicht ist. clear() verwirft alle Nachrichten in dieser Warteschlange, die noch nicht an das Gerät übertragen wurden.

Typische Anwendungsfälle sind Sequenzer, Arpeggiatoren und Wiedergabefunktionen für MIDI-Dateien: Wenn der Nutzer auf Stop klickt, das Tempo ändert oder an eine andere Stelle springt, müssen alle im Voraus eingeplanten Noten entfernt werden. Sonst klingen sie trotzdem noch nach.

Wichtig: clear() wirkt nur auf Nachrichten, die noch nicht gesendet wurden. Noten, die bereits erklingen (Note On schon gesendet), verstummen dadurch nicht. Wenn ein passendes Note Off gerade verworfen wurde, können sie sogar „hängen bleiben“. Deshalb sendet man nach clear() in der Regel sofort All Notes Off (Control Change 123) oder All Sound Off (CC 120) auf allen Kanälen.

Beispiele

Eingeplante Noten verwerfen

const access = await navigator.requestMIDIAccess();
const [output] = access.outputs.values();

const now = performance.now();
// C-Dur-Tonleiter, eine Note alle 500 ms einplanen
[60, 62, 64, 65, 67, 69, 71, 72].forEach((note, i) => {
  output.send([0x90, note, 100], now + i * 500);       // Note On
  output.send([0x80, note, 0], now + i * 500 + 450);   // Note Off
});

// Nach 1,2 Sekunden abbrechen: Restliche Noten werden nicht mehr gespielt
setTimeout(() => {
  output.clear();
  console.log('Warteschlange geleert');
}, 1200);

Warteschlange geleert

Panik-Knopf für einen Sequenzer (clear + All Notes Off)

const stopAll = (output) => {
  // 1. Noch nicht gesendete Nachrichten verwerfen
  if (typeof output.clear === 'function') {
    output.clear();
  }
  // 2. Bereits klingende Noten auf allen 16 Kanälen beenden
  for (let ch = 0; ch < 16; ch++) {
    output.send([0xB0 | ch, 123, 0]); // All Notes Off
    output.send([0xB0 | ch, 120, 0]); // All Sound Off
  }
};

const access = await navigator.requestMIDIAccess();
document.querySelector('#stop').addEventListener('click', () => {
  for (const output of access.outputs.values()) {
    stopAll(output);
  }
  console.log('Alle Ausgänge gestoppt');
});

Alle Ausgänge gestoppt

Funktionsprüfung mit Fallback

const supportsClear = 'MIDIOutput' in window &&
  typeof MIDIOutput.prototype.clear === 'function';

console.log(supportsClear
  ? 'clear() wird unterstützt'
  : 'clear() fehlt – Noten lieber per setTimeout nahe am Zeitpunkt senden');

clear() wird unterstützt

// Wichtig · Fallstricke

Browser-Unterstützung: Die Web MIDI API selbst läuft in Chromium-Browsern und in Firefox (ab Version 108). clear() ist in Chromium-Browsern jedoch nicht implementiert, und Safari unterstützt Web MIDI gar nicht. Vor dem Aufruf deshalb immer mit typeof output.clear === 'function' prüfen. Wo die Methode fehlt, plant man Nachrichten nur kurz im Voraus ein (z. B. mit einem Lookahead-Scheduler) und kann sie so selbst verwerfen.
Hängende Noten: Wenn clear() ein eingeplantes Note Off verwirft, dessen Note On schon gesendet wurde, klingt die Note endlos weiter. Danach deshalb CC 123 (All Notes Off) bzw. CC 120 (All Sound Off) senden.
Die Methode betrifft nur die Warteschlange dieses Ausgangs. Andere MIDIOutput-Objekte bleiben unberührt.
Web MIDI braucht einen sicheren Kontext (HTTPS) und die Erlaubnis des Nutzers über navigator.requestMIDIAccess(). SysEx-Zugriff muss zusätzlich mit { sysex: true } angefordert werden.

Siehe auch

MIDIOutput MIDIOutput.prototype.send() Navigator.requestMIDIAccess() MIDIAccess MIDIPort Performance.now() MediaKeyStatusMap.has()