HTMLMediaElement.readyState — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.readyState

Beschreibung

Die schreibgeschützte Eigenschaft readyState gibt an, wie viele Daten ein Medienelement (<audio> oder <video>) schon hat. Der Wert ist eine ganze Zahl, zu der es jeweils eine Konstante auf HTMLMediaElement gibt:

0 – HAVE_NOTHING: Es gibt noch keine Informationen über die Mediendatei.
1 – HAVE_METADATA: Die Metadaten sind geladen. Dauer (duration), Abmessungen (videoWidth/videoHeight) und Tonspuren sind bekannt, Bilddaten fehlen aber noch.
2 – HAVE_CURRENT_DATA: Für die aktuelle Wiedergabeposition sind Daten da, für das nächste Bild aber noch nicht.
3 – HAVE_FUTURE_DATA: Für die aktuelle Position und mindestens ein kurzes Stück danach sind Daten da.
4 – HAVE_ENOUGH_DATA: Es sind genug Daten gepuffert. Nach Schätzung des Browsers kann das Medium bei gleichbleibender Ladegeschwindigkeit bis zum Ende ohne Unterbrechung laufen.

Die Eigenschaft ist nützlich, wenn man den aktuellen Zustand sofort abfragen möchte, statt auf ein Ereignis zu warten. Ein typischer Fall: Ein Skript läuft erst, nachdem das Medium schon geladen ist, und hat das Ereignis loadedmetadata oder canplay deshalb verpasst. Dann prüft man zuerst readyState und registriert nur bei Bedarf einen Event-Listener.

Zu den Zustandsänderungen gehören diese Ereignisse: loadedmetadata (Wert ≥ 1), loadeddata (≥ 2), canplay (≥ 3) und canplaythrough (4). Sinkt der Wert während der Wiedergabe, weil der Puffer leer ist, löst der Browser waiting aus.

Rückgabewert

Typ

number

Beschreibung

Eine ganze Zahl von 0 bis 4, die einer der Konstanten HAVE_NOTHING, HAVE_METADATA, HAVE_CURRENT_DATA, HAVE_FUTURE_DATA oder HAVE_ENOUGH_DATA entspricht.

Beispiele

Zustand als lesbaren Text ausgeben

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

const zustaende = [
  'HAVE_NOTHING',
  'HAVE_METADATA',
  'HAVE_CURRENT_DATA',
  'HAVE_FUTURE_DATA',
  'HAVE_ENOUGH_DATA'
];

console.log(`readyState: ${video.readyState} (${zustaende[video.readyState]})`);

readyState: 4 (HAVE_ENOUGH_DATA)

Auf Metadaten warten, auch wenn das Ereignis schon vorbei ist

const whenMetadata = (media) =>
  new Promise((resolve) => {
    if (media.readyState >= HTMLMediaElement.HAVE_METADATA) {
      resolve(media); // Metadaten sind schon da
    } else {
      media.addEventListener('loadedmetadata', () => resolve(media), { once: true });
    }
  });

const video = document.querySelector('#trailer');
const v = await whenMetadata(video);
console.log(`Dauer: ${v.duration.toFixed(1)} s, Größe: ${v.videoWidth}×${v.videoHeight}`);

Dauer: 132.5 s, Größe: 1920×1080

Wiedergabe erst starten, wenn sie flüssig laufen kann

const audio = new Audio('/sounds/podcast.mp3');
audio.preload = 'auto';

const startWhenReady = async () => {
  if (audio.readyState < HTMLMediaElement.HAVE_ENOUGH_DATA) {
    await new Promise((r) => audio.addEventListener('canplaythrough', r, { once: true }));
  }
  try {
    await audio.play();
    console.log('Wiedergabe läuft');
  } catch (err) {
    console.warn('Autoplay blockiert:', err.name);
  }
};

document.querySelector('#play').addEventListener('click', startWhenReady);

Wiedergabe läuft

Puffer-Anzeige mit readyState

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

const update = () => {
  // Unter HAVE_FUTURE_DATA fehlt es an Daten zum Weiterspielen
  spinner.hidden = video.readyState >= HTMLMediaElement.HAVE_FUTURE_DATA;
};

['waiting', 'canplay', 'playing', 'seeking', 'seeked'].forEach((type) =>
  video.addEventListener(type, update)
);
update();

// Wichtig · Fallstricke

Nur lesbar: Wenn man readyState einen Wert zuweist, passiert nichts. Im strikten Modus gibt es dabei einen TypeError.
Konstanten statt Zahlen: Für besser lesbaren Code lieber HTMLMediaElement.HAVE_ENOUGH_DATA usw. vergleichen statt fester Zahlen. Mit >= vergleichen, weil höhere Zustände die niedrigeren einschließen.
HAVE_ENOUGH_DATA ist eine Schätzung: Auch bei Wert 4 kann die Wiedergabe später stocken, wenn das Netz langsamer wird.
Nicht mit networkState verwechseln: readyState sagt, welche Daten vorhanden sind. networkState beschreibt dagegen den Ladevorgang über das Netzwerk.
Einfluss von preload: Bei preload="none" bleibt der Wert oft bei 0, bis load() oder play() aufgerufen wird. Mobile Browser laden teils auch bei preload="auto" nur Metadaten. Dann erreicht readyState erst durch eine Nutzeraktion höhere Werte, und canplaythrough kommt unter Umständen sehr spät oder gar nicht.
Zurücksetzen: Setzt man src neu oder ruft load() auf, fällt der Wert auf 0 zurück.
Wird von allen modernen Browsern unterstützt.

Siehe auch

HTMLTemplateElement.shadowRootSlotAssignment HTMLMediaElement.networkState HTMLMediaElement.remote HTMLMediaElement.defaultMuted HTMLMediaElement.ended