Navigator.getAutoplayPolicy() — Methode · JavaScript-Referenz

Signatur

Navigator.prototype.getAutoplayPolicy(type | element | context)

Beschreibung

navigator.getAutoplayPolicy() gehört zur Autoplay Policy Detection API. Mit der Methode lässt sich vor dem Abspielen prüfen, ob der Browser automatisches Abspielen erlaubt. Bisher musste man play() einfach aufrufen und auf ein abgelehntes Promise (NotAllowedError) reagieren. Jetzt kann man das Verhalten vorab entscheiden: Video stumm starten, einen „Abspielen“-Button anzeigen oder ganz auf Autoplay verzichten.

Die Methode hat drei Aufrufvarianten:

Mit Typ-String ("mediaelement" oder "audiocontext"): Sie erhalten die allgemeine Richtlinie für diese Art von Objekt im aktuellen Dokument. Das ist nützlich, bevor überhaupt ein Element existiert.
Mit einem HTMLMediaElement (<video>/<audio>): Sie erhalten die Richtlinie für genau dieses Element. Das Ergebnis kann feiner sein, weil der Browser z. B. ein stummgeschaltetes Element anders behandelt.
Mit einem AudioContext: Sie erfahren, ob dieser Kontext ohne Nutzergeste starten darf.

Die Antwort ist eine Momentaufnahme. Nach einer Nutzerinteraktion (Klick, Tastendruck) wechselt die Richtlinie häufig von "disallowed" bzw. "allowed-muted" zu "allowed". Fragen Sie deshalb bei Bedarf erneut ab, statt das Ergebnis dauerhaft zu speichern.

Parameter

Name	Typ	Beschreibung
$type	"mediaelement" \| "audiocontext"	Variante 1: Liefert die allgemeine Autoplay-Richtlinie für alle Medienelemente bzw. alle Audiokontexte im Dokument.
$element	HTMLMediaElement	Variante 2: Ein konkretes `<video>`- oder `<audio>`-Element, dessen Richtlinie abgefragt wird. Eigenschaften wie `muted` werden dabei berücksichtigt.
$context	AudioContext	Variante 3: Ein konkreter `AudioContext` der Web Audio API.

Rückgabewert

Typ

"allowed" | "allowed-muted" | "disallowed"

Beschreibung

"allowed": Autoplay ist erlaubt, auch mit Ton. "allowed-muted": Autoplay ist nur ohne Ton erlaubt (Medienelemente ohne Tonspur oder mit muted). "disallowed": Autoplay ist nicht erlaubt. Für Audiokontexte gibt es nur "allowed" oder "disallowed".

Beispiele

Allgemeine Richtlinie mit Feature-Erkennung abfragen

const policy = typeof navigator.getAutoplayPolicy === 'function'
  ? navigator.getAutoplayPolicy('mediaelement')
  : 'unbekannt';

console.log(`Autoplay-Richtlinie für Medien: ${policy}`);

Autoplay-Richtlinie für Medien: allowed-muted

Hintergrundvideo abhängig von der Richtlinie starten

const video = document.querySelector('#hero-video');
const playButton = document.querySelector('#play-button');

const startVideo = async () => {
  const policy = navigator.getAutoplayPolicy?.(video) ?? 'unbekannt';

  switch (policy) {
    case 'allowed':
      await video.play();
      break;
    case 'allowed-muted':
      video.muted = true;
      await video.play();
      break;
    case 'disallowed':
      playButton.hidden = false; // Nutzer muss selbst starten
      break;
    default:
      // Kein API-Support: klassisch per Promise-Fehler reagieren
      try {
        await video.play();
      } catch (err) {
        if (err.name === 'NotAllowedError') playButton.hidden = false;
      }
  }
};

playButton.addEventListener('click', () => {
  playButton.hidden = true;
  video.muted = false;
  video.play();
});

startVideo();

AudioContext nur bei Erlaubnis sofort starten

const ctx = new AudioContext();

if (navigator.getAutoplayPolicy?.(ctx) === 'allowed') {
  const osc = ctx.createOscillator();
  osc.connect(ctx.destination);
  osc.start();
  osc.stop(ctx.currentTime + 0.2);
} else {
  // Auf erste Nutzergeste warten
  document.addEventListener('pointerdown', () => ctx.resume(), { once: true });
  console.log('Warte auf Nutzerinteraktion …');
}

Warte auf Nutzerinteraktion …

// Wichtig · Fallstricke

Kompatibilität: Die API ist experimentell. Bislang gibt es sie nur in Firefox (ab 112, hinter der Einstellung media.autoplay.autoplay-policy-api). Chromium-Browser und Safari unterstützen sie nicht. Prüfen Sie die Methode deshalb immer vorher (typeof navigator.getAutoplayPolicy === 'function' oder optionale Verkettung ?.()) und behalten Sie die Fehlerbehandlung von play() (NotAllowedError) als Rückfallebene.

Ein ungültiger Typ-String, z. B. "video", löst einen TypeError aus.
Das Ergebnis ist nur eine Momentaufnahme. Nach einer Nutzergeste oder durch Website-Einstellungen des Nutzers kann sich die Richtlinie ändern.
Das Ergebnis für ein konkretes Element kann von der allgemeinen Richtlinie ("mediaelement") abweichen. Fragen Sie für genaue Entscheidungen deshalb das konkrete Element ab.
Auch bei "allowed" kann play() aus anderen Gründen fehlschlagen, etwa bei Netzwerkfehlern oder nicht unterstützten Formaten. Behandeln Sie das Promise also trotzdem.

Siehe auch

HTMLMediaElement.play() HTMLMediaElement.autoplay HTMLMediaElement.muted AudioContext Navigator WorkerNavigator.clearAppBadge()