HTMLMediaElement.preload — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.preload

Beschreibung

Die Eigenschaft preload spiegelt das gleichnamige HTML-Attribut von <audio> und <video>. Mit ihr sagst du dem Browser, was du für das beste Nutzererlebnis hältst: gar nichts vorab laden, nur die Metadaten (Dauer, Abmessungen, Tonspuren) oder die ganze Datei vorsorglich puffern.

Erlaubt sind die Werte "none", "metadata" und "auto". Der leere String "" gilt als "auto". Ungültige Werte behandelt der Browser nach seinem eigenen Standardwert, laut Spezifikation empfohlen ist "metadata". Beim Lesen bekommst du den Wert zurück, der tatsächlich gilt, also bereits normalisiert.

Praktisch nützlich ist preload für die Bandbreitensteuerung. Auf Seiten mit vielen Videos (Galerien, Feeds) oder für Nutzer mit Datenspar-Modus setzt du "none" oder "metadata". Für ein Hauptvideo, das der Nutzer mit hoher Wahrscheinlichkeit abspielt, verkürzt "auto" die Startzeit.

Wichtig: Der Wert ist nur ein Hinweis. Browser dürfen ihn ignorieren, etwa wegen Mobilfunk, Energiesparmodus oder eigener Regeln. Außerdem hat das Attribut autoplay Vorrang: Ist es gesetzt, lädt der Browser die Daten in jedem Fall.

Parameter

Name	Typ	Default	Beschreibung
$value	"none" \| "metadata" \| "auto" \| ""	browserabhängig (empfohlen: "metadata")	Wert beim Setzen. `"none"`: nichts vorab laden. `"metadata"`: nur Metadaten laden. `"auto"` oder `""`: der Browser darf die ganze Datei laden.

Rückgabewert

Typ

string

Beschreibung

Der aktuell geltende, normalisierte Wert: "none", "metadata" oder "auto".

Beispiele

Wert lesen und setzen

const video = document.createElement('video');
video.src = 'intro.mp4';

console.log(video.preload); // Standardwert des Browsers

video.preload = 'metadata';
console.log(video.preload);
console.log(video.getAttribute('preload'));

video.preload = ''; // leerer String gilt als "auto"
console.log(video.preload);

metadata (z. B. in Chrome/Firefox) metadata metadata auto

Galerie: nur Metadaten laden, beim Hover vorladen

const videos = document.querySelectorAll('.gallery video');

videos.forEach((video) => {
  video.preload = 'metadata'; // Dauer und Maße anzeigen, Bandbreite sparen

  video.addEventListener('mouseenter', () => {
    video.preload = 'auto'; // Nutzer zeigt Interesse → puffern
  }, { once: true });

  video.addEventListener('loadedmetadata', () => {
    const min = Math.floor(video.duration / 60);
    const sek = Math.round(video.duration % 60).toString().padStart(2, '0');
    video.dataset.dauer = `${min}:${sek}`;
  });
});

Datensparmodus berücksichtigen

const audio = document.querySelector('#podcast');
const verbindung = navigator.connection;

// Network Information API gibt es nicht überall → Fallback einbauen
const sparen = verbindung?.saveData ||
  ['slow-2g', '2g'].includes(verbindung?.effectiveType);

audio.preload = sparen ? 'none' : 'auto';
console.log(`Preload-Modus: ${audio.preload}`);

Preload-Modus: auto

// Wichtig · Fallstricke

Nur ein Hinweis: Browser dürfen preload ignorieren. Mobile Browser, vor allem Safari auf iOS, laden oft nichts vorab, auch nicht bei "auto". Verlass dich also nicht darauf, dass Daten schon gepuffert sind.
autoplay hat Vorrang: Ist autoplay gesetzt, spielt preload keine Rolle.
Späte Änderungen: Hat der Ladevorgang schon begonnen, bewirkt eine Änderung von preload möglicherweise nichts. Willst du sofort laden, ruf load() auf oder starte mit play().
Mit "none" sind duration und videoWidth bis zum Laden NaN bzw. 0. Ohne poster-Attribut zeigen Videos dann kein Vorschaubild.
Den Standardwert legt jeder Browser selbst fest. Die Spezifikation empfiehlt "metadata". Setz den Wert deshalb ausdrücklich, wenn dir das Verhalten wichtig ist.
Kompatibilität: wird von allen modernen Browsern unterstützt. Das veraltete Attribut autobuffer ist abgelöst.

Siehe auch

HTMLMediaElement.loading HTMLMediaElement.remote HTMLMediaElement.ended HTMLMediaElement.error HTMLMediaElement.loop