MediaError.code — Eigenschaft · JavaScript-Referenz

Signatur

MediaError.code

Beschreibung

Die schreibgeschützte Eigenschaft MediaError.code enthält einen Ganzzahl-Code für die Fehlerart eines Media-Elements. Das zugehörige MediaError-Objekt bekommt man über HTMLMediaElement.error. Diese Eigenschaft ist null, solange kein Fehler aufgetreten ist.

Mögliche Werte, jeweils auch als statische Konstanten von MediaError verfügbar:

1 – MEDIA_ERR_ABORTED: Der Nutzer oder das Skript hat das Laden abgebrochen.
2 – MEDIA_ERR_NETWORK: Ein Netzwerkfehler hat das Laden unterbrochen, obwohl die Ressource grundsätzlich brauchbar war.
3 – MEDIA_ERR_DECODE: Beim Dekodieren ist ein Fehler aufgetreten, zum Beispiel wegen beschädigter Daten.
4 – MEDIA_ERR_SRC_NOT_SUPPORTED: Die Quelle ist ungeeignet, etwa wegen eines nicht unterstützten Formats, einer fehlenden Datei (404) oder einer CORS-Sperre.

Man wertet code typischerweise im error-Event des Media-Elements aus. So kann man verständliche Fehlermeldungen anzeigen, eine Ersatzquelle laden oder bei Netzwerkfehlern einen neuen Versuch starten. Genauere Diagnosedaten liefert zusätzlich MediaError.message.

Rückgabewert

Typ

number

Beschreibung

Eine Ganzzahl von 1 bis 4, passend zu den Konstanten MEDIA_ERR_ABORTED, MEDIA_ERR_NETWORK, MEDIA_ERR_DECODE und MEDIA_ERR_SRC_NOT_SUPPORTED.

Beispiele

Fehlercode im error-Event auswerten

const video = document.querySelector('video');

video.addEventListener('error', () => {
  const err = video.error;
  if (!err) return;

  const meldungen = {
    [MediaError.MEDIA_ERR_ABORTED]: 'Laden wurde abgebrochen.',
    [MediaError.MEDIA_ERR_NETWORK]: 'Netzwerkfehler beim Laden.',
    [MediaError.MEDIA_ERR_DECODE]: 'Datei konnte nicht dekodiert werden.',
    [MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED]: 'Format oder Quelle nicht unterstützt.'
  };

  console.log(`Code ${err.code}: ${meldungen[err.code] ?? 'Unbekannter Fehler'}`);
});

video.src = 'fehlt.mp4'; // nicht vorhandene Datei

Code 4: Format oder Quelle nicht unterstützt.

Ersatzquelle laden bei nicht unterstütztem Format

const audio = new Audio();
const quellen = ['podcast.opus', 'podcast.mp3'];
let index = 0;

audio.addEventListener('error', () => {
  if (audio.error?.code === MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED && index < quellen.length - 1) {
    index++;
    console.log(`Wechsle auf ${quellen[index]}`);
    audio.src = quellen[index];
  }
});

audio.src = quellen[index];

Wechsle auf podcast.mp3

Automatischer neuer Versuch bei Netzwerkfehler

const video = document.querySelector('#stream');
let versuche = 0;

video.onerror = () => {
  const { code, message } = video.error;
  console.warn('Medienfehler', code, message);

  if (code === MediaError.MEDIA_ERR_NETWORK && versuche < 3) {
    versuche++;
    setTimeout(() => video.load(), 1000 * versuche);
  }
};

Medienfehler 2 "" (je nach Browser mit Detailtext)

// Wichtig · Fallstricke

Vergleiche besser mit den Konstanten wie MediaError.MEDIA_ERR_NETWORK als mit festen Zahlen. Das macht den Code lesbarer.
video.error ist null, solange kein Fehler aufgetreten ist. Greife deshalb mit video.error?.code zu.
Bei mehreren <source>-Kindelementen wird das error-Event an den einzelnen <source>-Elementen ausgelöst, nicht am Media-Element. video.error bleibt dann oft null, bis alle Quellen gescheitert sind.
Code 4 fasst viele Ursachen zusammen: 404, falscher MIME-Typ, nicht unterstützter Codec, CORS. Für die Diagnose hilft MediaError.message. Deren Inhalt ist aber je nach Browser verschieden.
Code 1 (abgebrochen) wird in modernen Browsern selten als error-Event gemeldet. Ein Abbruch löst meist das Event abort aus.
Wird in allen aktuellen Browsern unterstützt.

Siehe auch

CSSMediaRule.media MediaError.message MediaStream.id CloseEvent.code DOMException.code