HTMLMediaElement.autoplay — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.autoplay

Beschreibung

Die Eigenschaft autoplay ist ein boolescher Wert, der das gleichnamige Inhaltsattribut von <audio>- und <video>-Elementen widerspiegelt. Ist sie true, beginnt der Browser mit der Wiedergabe, sobald er genug Daten gepuffert hat (etwa beim Erreichen von readyState HAVE_ENOUGH_DATA). Das Setzen auf true fügt das Attribut autoplay hinzu, false entfernt es.

Moderne Browser setzen Autoplay-Richtlinien durch: Medien mit Ton starten meist nur automatisch, wenn der Nutzer bereits mit der Seite interagiert hat oder die Seite laut Browser-Heuristik (z. B. Chromes „Media Engagement Index“) vertrauenswürdig ist. Stummgeschaltete Medien (muted) dürfen in der Regel ohne Einschränkung automatisch abspielen. Auf iOS ist für Inline-Videos zusätzlich playsinline nötig.

Wichtig: autoplay ist nur eine Absichtserklärung. Ob die Wiedergabe wirklich startet, erfährt man über das play- bzw. playing-Event oder zuverlässiger, indem man selbst play() aufruft und das zurückgegebene Promise auswertet. Wird die automatische Wiedergabe blockiert, gibt es kein eigenes Fehler-Event beim Attribut – das Element bleibt einfach pausiert.

Beispiele

Autoplay-Status lesen und setzen

const video = document.querySelector('video');
console.log(video.autoplay); // Attribut vorhanden?

video.autoplay = true;
console.log(video.hasAttribute('autoplay'));

video.autoplay = false;
console.log(video.hasAttribute('autoplay'));

false true false

Stummes Hintergrundvideo per JavaScript erzeugen

const bg = document.createElement('video');
bg.src = '/media/hero.mp4';
bg.muted = true;        // Voraussetzung für Autoplay in fast allen Browsern
bg.autoplay = true;
bg.loop = true;
bg.playsInline = true;  // iOS: kein automatischer Vollbildmodus
document.querySelector('.hero').append(bg);

Prüfen, ob Autoplay blockiert wurde, mit Fallback

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

const tryAutoplay = async () => {
  try {
    await player.play();
    console.log('Wiedergabe läuft');
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.log('Autoplay blockiert – starte stumm');
      player.muted = true;
      await player.play();
      document.querySelector('#unmute').hidden = false;
    }
  }
};

if (player.autoplay) tryAutoplay();

Autoplay blockiert – starte stumm

Autoplay abhängig von Nutzerpräferenzen

const video = document.querySelector('video');
const reduceMotion = matchMedia('(prefers-reduced-motion: reduce)').matches;

// Keine automatische Wiedergabe für Nutzer mit reduzierter Bewegung
video.autoplay = !reduceMotion;
if (reduceMotion) video.pause();
console.log(`Autoplay: ${video.autoplay}`);

Autoplay: true

// Wichtig · Fallstricke

Autoplay-Richtlinien: Chrome, Firefox und Safari blockieren Autoplay mit Ton ohne vorherige Nutzerinteraktion. Setze muted, wenn Autoplay zuverlässig funktionieren soll. In iframes muss zusätzlich allow="autoplay" (Permissions Policy) gesetzt sein.
Kein Erfolgsnachweis: autoplay === true bedeutet nicht, dass etwas abgespielt wird. Prüfe paused oder werte das Promise von play() aus (NotAllowedError bei Blockade).
Zeitpunkt: Wird autoplay erst gesetzt, nachdem das Medium bereits genug Daten hat, startet die Wiedergabe je nach Browser nicht mehr automatisch – dann play() direkt aufrufen.
Barrierefreiheit: Automatisch startender Ton stört Screenreader-Nutzer (WCAG 1.4.2). Biete immer eine Pause- bzw. Stummschalt-Möglichkeit an.
Mit autoplay wird preload ignoriert; der Browser lädt die Daten ohnehin.
Über navigator.getAutoplayPolicy() lässt sich die Richtlinie abfragen – bisher nur in Firefox verfügbar.

Siehe auch

HTMLMediaElement.controller HTMLMediaElement.loop HTMLMediaElement.muted HTMLMediaElement.played HTMLMediaElement.audioTracks