HTMLMediaElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLMediaElement extends HTMLElement

Beschreibung

HTMLMediaElement erweitert HTMLElement um alles, was Audio- und Videoelemente gemeinsam haben: Laden der Quelle, Starten, Pausieren und Springen innerhalb der Wiedergabe, Lautstärke, Wiedergabegeschwindigkeit sowie Informationen zum Puffer- und Netzwerkzustand. Instanzen erzeugt man nie direkt, sondern immer über die Unterklassen HTMLAudioElement (z. B. new Audio()) oder HTMLVideoElement bzw. über document.createElement('video').

Wichtige Eigenschaften sind src, currentSrc, currentTime, duration, paused, ended, volume (0–1), muted, playbackRate, loop, autoplay, controls, preload, readyState, networkState, buffered, seekable, error und srcObject (für MediaStreams, z. B. Webcam). Zentrale Methoden sind play() (liefert ein Promise), pause(), load(), canPlayType(type) und fastSeek(time).

Der Zustand eines Mediums ändert sich asynchron, daher arbeitet man vor allem mit Events: loadedmetadata (Dauer und Abmessungen bekannt), canplay/canplaythrough, play, playing, pause, ended, timeupdate, volumechange, seeking/seeked, waiting, progress und error.

Typische Einsatzfälle sind eigene Player-Oberflächen, Fortschrittsbalken, Soundeffekte in Spielen, Wiedergabelisten oder das Anzeigen eines Kamera-Streams per srcObject.

Rückgabewert

Typ

HTMLMediaElement

Beschreibung

Wird nicht direkt instanziiert; konkrete Instanzen sind HTMLAudioElement oder HTMLVideoElement.

Beispiele

Audio-Element erzeugen und sicher abspielen

const sound = new Audio('/sounds/klick.mp3');
sound.volume = 0.5;

const abspielen = async () => {
  try {
    await sound.play();
    console.log('Wiedergabe läuft');
  } catch (err) {
    // z. B. NotAllowedError, wenn Autoplay blockiert wird
    console.warn('Wiedergabe verhindert:', err.name);
  }
};

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

Wiedergabe läuft

Eigene Steuerung mit Fortschrittsanzeige für ein Video

const video = document.querySelector('video');
const toggle = document.querySelector('#toggle');
const fortschritt = document.querySelector('progress');

video.addEventListener('loadedmetadata', () => {
  fortschritt.max = video.duration;
  console.log(`Dauer: ${video.duration.toFixed(1)} s`);
});

video.addEventListener('timeupdate', () => {
  fortschritt.value = video.currentTime;
});

toggle.addEventListener('click', () => {
  video.paused ? video.play() : video.pause();
});

video.addEventListener('ended', () => {
  toggle.textContent = 'Nochmal';
});

Dauer: 42.3 s

Formatunterstützung prüfen und Geschwindigkeit ändern

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

const quelle = video.canPlayType('video/webm; codecs="vp9"')
  ? '/media/film.webm'
  : '/media/film.mp4';

video.src = quelle;
video.controls = true;
video.playbackRate = 1.5; // 1,5-fache Geschwindigkeit
document.body.append(video);

console.log(video.canPlayType('video/mp4')); // "", "maybe" oder "probably"

maybe

Webcam-Stream über srcObject anzeigen

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

const starteKamera = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  video.srcObject = stream;
  video.muted = true;
  await video.play();
};

starteKamera().catch((err) => console.error('Kamera nicht verfügbar:', err.message));

// Wichtig · Fallstricke

Autoplay-Richtlinien: Browser blockieren die Wiedergabe mit Ton ohne vorherige Nutzerinteraktion. play() gibt dann ein abgelehntes Promise (NotAllowedError) zurück – immer mit catch bzw. try/await behandeln. Stummgeschaltete Videos (muted) dürfen meist automatisch starten.
Race Condition: Ein pause() direkt nach play() lässt das Promise mit AbortError scheitern. Das ist harmlos, sollte aber abgefangen werden.
duration ist vor loadedmetadata NaN und bei Live-Streams Infinity.
timeupdate feuert nur etwa 4–66 Mal pro Sekunde; für bildgenaue Synchronisation besser requestVideoFrameCallback() (bei HTMLVideoElement) oder requestAnimationFrame verwenden.
Auf iOS ist volume schreibgeschützt (immer 1); nur muted wirkt.
Beim Wechsel von src nach dem Einfügen von <source>-Elementen muss load() aufgerufen werden, damit die neue Quelle gewählt wird.
Medien von fremden Domains benötigen für Zugriff per Canvas oder Web Audio das Attribut crossorigin und passende CORS-Header, sonst wird die Canvas „tainted“.

Siehe auch

HTMLMetaElement HTMLAudioElement HTMLDivElement HTMLMenuElement HTMLMeterElement