MIDIAccess.sysexEnabled — Eigenschaft · JavaScript-Referenz

Signatur

MIDIAccess.sysexEnabled

Beschreibung

Die Eigenschaft sysexEnabled des MIDIAccess-Interfaces liefert true, wenn der MIDI-Zugriff mit SysEx-Unterstützung gewährt wurde, sonst false. System-Exclusive-Nachrichten (Statusbyte 0xF0 bis 0xF7) sind herstellerspezifische Befehle, mit denen man z. B. Patches in Synthesizer lädt, Firmware aktualisiert oder Geräteeinstellungen ausliest.

Ob SysEx verfügbar ist, legt man beim Aufruf von navigator.requestMIDIAccess({ sysex: true }) fest. Weil SysEx tief in ein Gerät eingreifen kann (bis hin zum Überschreiben der Firmware), fragt der Browser dafür eine eigene, strengere Berechtigung ab. Lehnt der Nutzer ab, wird das Promise abgewiesen; es wird also keine MIDIAccess-Instanz mit sysexEnabled === false „zurückgestuft“ geliefert.

In der Praxis dient die Eigenschaft dazu, nach dem Zugriff zu prüfen, welche Funktionen die Oberfläche anbieten darf: Ein Editor zeigt etwa „Patch-Dump laden“ nur an, wenn sysexEnabled true ist, und beschränkt sich sonst auf normale Kanal-Nachrichten wie Note-On oder Control Change.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn SysEx-Nachrichten über diese MIDIAccess-Instanz gesendet und empfangen werden dürfen, sonst false.

Beispiele

SysEx-Status nach dem Zugriff prüfen

const initMidi = async () => {
  try {
    const access = await navigator.requestMIDIAccess({ sysex: true });
    console.log('SysEx aktiv:', access.sysexEnabled);
  } catch (err) {
    console.error('MIDI-/SysEx-Zugriff verweigert:', err.name);
  }
};

initMidi();

SysEx aktiv: true

Ohne SysEx anfordern

const access = await navigator.requestMIDIAccess();
console.log(access.sysexEnabled);
// Nur Kanal-Nachrichten (Note-On, CC ...) sind erlaubt

false

Identity Request nur senden, wenn SysEx erlaubt ist

const access = await navigator.requestMIDIAccess({ sysex: true });

// Universal Identity Request: F0 7E 7F 06 01 F7
const identityRequest = [0xF0, 0x7E, 0x7F, 0x06, 0x01, 0xF7];

for (const input of access.inputs.values()) {
  input.onmidimessage = ({ data }) => {
    if (data[0] === 0xF0) console.log('SysEx-Antwort von', input.name, data);
  };
}

if (access.sysexEnabled) {
  for (const output of access.outputs.values()) {
    output.send(identityRequest);
  }
} else {
  console.warn('SysEx nicht verfügbar – Geräteerkennung übersprungen.');
}

SysEx-Antwort von MyDevice Uint8Array(15) [240, 126, ...]

// Wichtig · Fallstricke

Nur lesbar: Wenn man sysexEnabled zuweist, passiert nichts (im Strict Mode gibt es einen TypeError). SysEx lässt sich nur über eine neue Anfrage mit requestMIDIAccess({ sysex: true }) bekommen.
Fehler beim Senden: Wenn man ohne SysEx-Berechtigung eine SysEx-Nachricht mit MIDIOutput.send() schickt, wird eine InvalidAccessError-DOMException geworfen. Eingehende SysEx-Nachrichten werden in diesem Fall nicht zugestellt.
Sicherheit: Die Web MIDI API funktioniert nur in sicheren Kontexten (HTTPS). Mit SysEx kann eine Seite Geräte umkonfigurieren oder sogar deren Firmware überschreiben. Deshalb verlangen die Browser dafür eine eigene Berechtigung. In iframes muss die Permissions Policy midi erlaubt sein.
Kompatibilität: Wird von Chromium-Browsern und Firefox (ab 108, über eine Site-Permission-Erweiterung) unterstützt, von Safari nicht. Vorher mit 'requestMIDIAccess' in navigator prüfen.
Den Berechtigungsstatus kann man vorab abfragen, ohne dass ein Dialog erscheint: navigator.permissions.query({ name: 'midi', sysex: true }).

Siehe auch

MIDIAccess Navigator.requestMIDIAccess() MIDIAccess.inputs MIDIAccess.outputs MIDIOutput.send() MediaQueryListEvent.media