WissensdatenbankPrüfungszentrum
DEDeutsch
Sprache wählen13

CKTIS / JavaScript

Ereignisse von HTMLMediaElement

Nutze neun Audio- und Videoereignisse, um Position, Dauer und Steuerelemente zu synchronisieren und das Zurücksetzen, das Wiedergabeende oder Fehler zu erkennen.

Version: ECMAScript 2024 and the current web platform; runtime support varies

Syntax

media.addEventListener(type, (event) => { /* read event.currentTarget here */ });
// type: "timeupdate" | "loadedmetadata" | "durationchange" | "emptied"
//     | "play" | "pause" | "volumechange" | "ended" | "error"

HTMLMediaElement ist die gemeinsame Browserschnittstelle für audio- und video-Elemente, nicht Teil von ECMAScript. Registriere Listener mit addEventListener() direkt am Medienelement, möglichst bevor du src setzt: Diese Ereignisse durchlaufen keine Bubbling-Phase und sind nicht abbrechbar. Lies im Handler den aktuellen Zustand des Elements, statt ihn aus der Ereignisreihenfolge abzuleiten.

loadedmetadata bedeutet, dass Metadaten wie die Videoabmessungen verfügbar sind, nicht dass die Wiedergabe bereit ist. durationchange meldet eine erstmals ermittelte oder aktualisierte Dauer: duration ist in Sekunden angegeben, bei fehlenden Daten als NaN und bei unbegrenztem Ende als Infinity. emptied bedeutet, dass der Zustand der Ressource zurückgesetzt wurde, etwa beim erneuten Laden. Entferne dann die alten Medienangaben aus der Oberfläche; das Zurücksetzen allein muss kein durationchange auslösen.

Lies bei timeupdate den Wert von currentTime in Sekunden, um die Positionsanzeige zu aktualisieren. Das Ereignis kann beim Abspielen oder Springen auftreten; es ist weder ein fester Takt noch ein Signal pro Frame. play bedeutet, dass paused auf false gewechselt hat, nicht dass die Wiedergabe tatsächlich begonnen hat (playing). pause meldet den Wechsel in den Pausenzustand, keinen vorübergehenden Datenmangel. Lies bei volumechange sowohl volume als auch muted: Beide Änderungen können das Ereignis auslösen.

ended meldet das Erreichen des Endes, keine gewöhnliche Pause, obwohl am Ende auch pause auftreten kann. Ist loop auf true gesetzt und playbackRate nicht negativ, wird ended nicht ausgelöst. Prüfe bei error die Eigenschaft media.error, etwa media.error?.code; dieses MediaError-Objekt betrifft die Medienressource. Behandle Ablehnungen des von play() zurückgegebenen Promise separat: NotAllowedError kann etwa durch Autoplay-Regeln entstehen, ohne ein Medienereignis error auszulösen.

Beispiele

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>HTMLMediaElement events</title>
</head>
<body>
<script>
(() => {
  const panel = document.createElement('div');
  const audio = document.createElement('audio');
  audio.controls = true;
  audio.preload = 'metadata';
  panel.append(audio);

  // Generate three seconds of silence as mono, 8-bit PCM WAV.
  const rate = 8000;
  const samples = 3 * rate;
  const bytes = new Uint8Array(44 + samples);
  const view = new DataView(bytes.buffer);
  const tag = (offset, text) => bytes.set(new TextEncoder().encode(text), offset);
  const u16 = (offset, value) => view.setUint16(offset, value, true);
  const u32 = (offset, value) => view.setUint32(offset, value, true);
  tag(0, 'RIFF'); u32(4, 36 + samples); tag(8, 'WAVE');
  tag(12, 'fmt '); u32(16, 16); u16(20, 1); u16(22, 1);
  u32(24, rate); u32(28, rate); u16(32, 1); u16(34, 8);
  tag(36, 'data'); u32(40, samples); bytes.fill(128, 44);
  const wav = URL.createObjectURL(new Blob([bytes], { type: 'audio/wav' }));
  const bad = URL.createObjectURL(new Blob(['not audio'], { type: 'audio/wav' }));

  const listeners = new AbortController();
  const types = ['timeupdate', 'loadedmetadata', 'durationchange', 'emptied',
    'play', 'pause', 'volumechange', 'ended', 'error'];
  for (const type of types) {
    audio.addEventListener(type, ({ currentTarget: media }) => {
      console.log(type, {
        currentTime: media.currentTime, duration: media.duration,
        paused: media.paused, ended: media.ended,
        volume: media.volume, muted: media.muted,
        errorCode: media.error?.code ?? null
      });
    }, { signal: listeners.signal });
  }

  function button(label, action) {
    const control = document.createElement('button');
    control.type = 'button';
    control.textContent = label;
    control.addEventListener('click', action);
    panel.append(control);
  }
  button('Mute / unmute', () => { audio.muted = !audio.muted; });
  button('Reload', () => { audio.src = wav; });
  button('Load invalid audio', () => { audio.src = bad; });
  button('Remove demo', () => {
    listeners.abort();
    audio.removeAttribute('src');
    audio.load();
    panel.remove();
    URL.revokeObjectURL(wav);
    URL.revokeObjectURL(bad);
  });
  document.body.prepend(panel);
  audio.src = wav;
})();
</script>
</body>
</html>

Ergebnis

Expected observations, not a fixed transcript (each event name is logged with a state object):
- Initial load: durationchange and loadedmetadata; duration is 3 seconds at loadedmetadata.
- Play, pause, resume, and let the clip finish: play, timeupdate (repeated), pause, play again, and eventually ended. A pause event can also occur at the end.
- Mute / unmute: volumechange; muted toggles.
- Reload after metadata is available: emptied, then fresh durationchange and loadedmetadata.
- Load invalid audio: error with a non-null errorCode; emptied can appear first.

Speichere das Beispiel als HTML-Datei und öffne es im Browser. Der Browser muss PCM-WAV unterstützen und Medien über `blob:` zulassen. Die Ereignisse siehst du in der Entwicklerkonsole. Starte und pausiere mit den eingebauten Steuerelementen. Das Beispiel erzeugt drei Sekunden Stille ohne Dateidownload; Zeitpunkt und Anzahl der Ereignisse können variieren. `Remove demo` entfernt die Steuerelemente und gibt die Objekt-URLs frei.

Zugehörige Lektionen

  • JavaScript · Lektion 28 · Mittlere Stufe · Version: 3

Quellen