MediaError — Schnittstelle · JavaScript-Referenz

Signatur

interface MediaError

Beschreibung

Ein MediaError-Objekt beschreibt, warum ein HTMLMediaElement (also <audio> oder <video>) eine Medienquelle nicht laden, dekodieren oder abspielen konnte. Du erzeugst es nicht selbst. Der Browser legt es in der Eigenschaft HTMLMediaElement.error ab und löst dann das Ereignis error am Medienelement aus. Solange kein Fehler aufgetreten ist, hat element.error den Wert null.

Die Schnittstelle hat zwei schreibgeschützte Eigenschaften:

code: ein numerischer Fehlercode (unsigned short), der einer der folgenden Konstanten entspricht:
- MediaError.MEDIA_ERR_ABORTED (1): Der Abruf wurde abgebrochen, meist auf Wunsch des Nutzers.
- MediaError.MEDIA_ERR_NETWORK (2): Ein Netzwerkfehler hat den Download unterbrochen, nachdem die Quelle schon als nutzbar erkannt war.
- MediaError.MEDIA_ERR_DECODE (3): Beim Dekodieren ist ein Fehler aufgetreten, zum Beispiel wegen beschädigter Daten.
- MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED (4): Die Quelle ist ungeeignet, etwa bei nicht unterstütztem Format oder Codec, falscher URL, Fehler 404 oder CORS-Blockade.
message: eine Zeichenkette mit Diagnosedetails, die vom Browser abhängen. Sie kann leer sein.

Nutze MediaError, um in eigenen Mediaplayern verständliche Fehlermeldungen anzuzeigen, auf eine andere Quelle umzuschalten (Fallback) oder Wiedergabeprobleme an ein Monitoring zu melden. Vergleiche code dabei am besten mit den benannten Konstanten und nicht mit festen Zahlen.

Rückgabewert

Typ

MediaError | null

Beschreibung

Wird über HTMLMediaElement.error gelesen. Das ist ein MediaError-Objekt mit code und message oder null, wenn kein Fehler aufgetreten ist.

Beispiele

Fehler eines Videos per addEventListener auswerten

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

const beschreibeFehler = (err) => {
  switch (err.code) {
    case MediaError.MEDIA_ERR_ABORTED:
      return 'Wiedergabe wurde abgebrochen.';
    case MediaError.MEDIA_ERR_NETWORK:
      return 'Netzwerkfehler beim Laden des Videos.';
    case MediaError.MEDIA_ERR_DECODE:
      return 'Das Video ist beschädigt oder nicht dekodierbar.';
    case MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED:
      return 'Format nicht unterstützt oder Datei nicht gefunden.';
    default:
      return 'Unbekannter Medienfehler.';
  }
};

video.addEventListener('error', () => {
  const err = video.error;
  console.error(`Code ${err.code}: ${beschreibeFehler(err)}`, err.message);
});

video.src = '/videos/gibt-es-nicht.mp4';

Code 4: Format nicht unterstützt oder Datei nicht gefunden. MEDIA_ELEMENT_ERROR: Format error

Automatischer Fallback auf eine alternative Quelle

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

audio.onerror = () => {
  const { code, message } = audio.error;
  console.warn(`Quelle ${quellen[index]} fehlgeschlagen (Code ${code})`, message);

  if (code === MediaError.MEDIA_ERR_SRC_NOT_SUPPORTED && index < quellen.length - 1) {
    index += 1;
    audio.src = quellen[index]; // nächste Quelle versuchen
  } else {
    audio.onerror = null; // Handler entfernen, keine weiteren Versuche
    console.error('Keine abspielbare Quelle gefunden.');
  }
};

audio.src = quellen[index];

Quelle /audio/podcast.opus fehlgeschlagen (Code 4) ...

Medienfehler an ein Monitoring melden und Listener entfernen

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

const melde = async () => {
  const err = video.error;
  if (!err) return;
  await fetch('/api/log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      src: video.currentSrc,
      code: err.code,
      message: err.message || '(keine Details)'
    })
  });
  video.removeEventListener('error', melde);
};

video.addEventListener('error', melde);

// Wichtig · Fallstricke

Fehler bei <source>-Kindelementen: Hat das Medienelement mehrere <source>-Elemente, löst jede fehlgeschlagene Quelle das error-Ereignis am jeweiligen <source>-Element aus. video.error bleibt dabei zunächst null. Um sie abzufangen, registriere den Listener am letzten <source>-Element oder mit useCapture am Medienelement.
message ist nicht standardisiert: Inhalt und Format hängen vom Browser ab, und die Zeichenkette kann leer sein. Verwende sie nur zur Diagnose, nicht für Programmlogik oder als Text für Nutzer.
Code 4 umfasst viele Ursachen: Nicht unterstützter Codec, HTTP 404 und CORS-Blockaden (etwa bei crossorigin ohne passende Header) ergeben alle MEDIA_ERR_SRC_NOT_SUPPORTED. Aus Sicherheitsgründen verrät der Browser keine Details zu fremden Ursprüngen.
Abgelehnte play()-Aufrufe: Wenn die Autoplay-Richtlinie greift, wird das Promise von play() mit einer DOMException (NotAllowedError) abgelehnt. Es entsteht dann kein MediaError.
Das veraltete MEDIA_ERR_ENCRYPTED (Code 5) aus frühen EME-Entwürfen ist nicht mehr Teil der Spezifikation. Nutze bei verschlüsselten Medien die Ereignisse der Encrypted Media Extensions.
Kompatibilität: code und die Konstanten funktionieren in allen Browsern. message gibt es erst in neueren Versionen (Safari erst ab 15).

Siehe auch

DOMError GPUError MediaKeys MediaList MediaRecorder