HTMLMediaElement.load() — Methode · JavaScript-Referenz

Signatur

HTMLMediaElement.prototype.load()

Beschreibung

load() führt den Media-Element-Ladealgorithmus aus: Eine laufende Wiedergabe oder ein laufender Ladevorgang wird abgebrochen, currentTime springt auf 0, readyState fällt auf HAVE_NOTHING zurück und networkState wird zurückgesetzt. Danach wählt der Browser anhand des src-Attributs bzw. der <source>-Kindelemente erneut eine passende Quelle aus und fängt an, sie zu laden.

Nötig ist die Methode vor allem, wenn du die <source>-Elemente eines Media-Elements dynamisch änderst. Das Hinzufügen, Entfernen oder Ändern von <source>-Kindern löst nämlich keine neue Quellenauswahl aus. Setzt du dagegen direkt die Eigenschaft src, startet der Browser den Ladealgorithmus automatisch – dann brauchst du load() nicht.

Während load() läuft, werden je nach Zustand Ereignisse wie abort, emptied und danach loadstart, loadedmetadata, canplay usw. ausgelöst. Auf diese Ereignisse kannst du reagieren, um den Ladefortschritt zu verfolgen oder die Wiedergabe erst zu starten, wenn genug Daten da sind.

Beispiele

Quelle über <source>-Elemente austauschen

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

const setSources = (baseName) => {
  // Alte Quellen entfernen
  video.querySelectorAll('source').forEach((s) => s.remove());

  const formats = [
    { ext: 'webm', type: 'video/webm' },
    { ext: 'mp4', type: 'video/mp4' }
  ];

  for (const { ext, type } of formats) {
    const source = document.createElement('source');
    source.src = `/media/${baseName}.${ext}`;
    source.type = type;
    video.append(source);
  }

  // Ohne load() würde der Browser die neuen <source>-Elemente ignorieren
  video.load();
};

setSources('trailer-2024');

Nach dem Laden automatisch abspielen

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

const playFromStart = async () => {
  audio.load(); // setzt currentTime auf 0 und lädt neu

  await new Promise((resolve, reject) => {
    audio.addEventListener('canplay', resolve, { once: true });
    audio.addEventListener('error', () => reject(audio.error), { once: true });
  });

  try {
    await audio.play();
    console.log('Wiedergabe läuft ab', audio.currentTime);
  } catch (err) {
    // z. B. NotAllowedError durch Autoplay-Richtlinie
    console.warn('Wiedergabe blockiert:', err.name);
  }
};

document.querySelector('#restart').addEventListener('click', playFromStart);

Wiedergabe läuft ab 0

Ladeereignisse beobachten

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

['abort', 'emptied', 'loadstart', 'loadedmetadata', 'canplay'].forEach((type) => {
  video.addEventListener(type, () => {
    console.log(type, 'readyState:', video.readyState);
  });
});

video.load();

emptied readyState: 0 loadstart readyState: 0 loadedmetadata readyState: 1 canplay readyState: 3

// Wichtig · Fallstricke

Nur bei <source>-Änderungen nötig: Wenn du element.src setzt, startet das Laden bereits automatisch. Ein zusätzlicher Aufruf von load() bricht den gerade begonnenen Ladevorgang ab und startet ihn noch einmal – unnötiger Netzwerkverkehr.
Setzt alles zurück: Wiedergabeposition, Puffer und laufende play()-Promises gehen verloren. Ausstehende play()-Promises werden mit einem AbortError abgelehnt – fange das ab, damit keine unbehandelten Ablehnungen entstehen.
Keine Wiedergabe: load() startet nicht die Wiedergabe (außer bei gesetztem autoplay). Für die Wiedergabe rufst du play() auf, das dabei den Autoplay-Richtlinien des Browsers unterliegt.
Mobile Browser: Ältere iOS-Safari-Versionen haben Medien ohne Nutzerinteraktion teilweise nicht vorgeladen; preload ist nur ein Hinweis an den Browser.
Fehler (z. B. keine unterstützte Quelle) melden sich nicht als Ausnahme, sondern über das Ereignis error und die Eigenschaft error (MediaError).

Siehe auch

HTMLMediaElement.play() HTMLMediaElement.pause() HTMLMediaElement.fastSeek() HTMLMediaElement.setSinkId() HTMLMediaElement.canPlayType()