Autoplay-Leitfaden für Medien und Web Audio APIs

Der Begriff Autoplay bezieht sich auf jede Funktion, die dazu führt, dass Medien ohne ausdrückliche Anforderung des Benutzers mit der Wiedergabe beginnen. Dies schließt sowohl die Verwendung von HTML-Attributen zum automatischen Abspielen von Medien als auch die Verwendung von JavaScript-Code ein, um die Wiedergabe außerhalb des Kontexts einer Benutzerinteraktion zu starten.

Das bedeutet, dass sowohl das folgende als auch das folgende Verhalten als Autoplay betrachtet werden und daher der Blockierungsrichtlinie des Browsers unterliegen:

<audio src="/music.mp3" autoplay></audio>

und

audioElement.play();

Die folgenden Webfunktionen und APIs können von der Autoplay-Blockierung betroffen sein:

• Die HTML <audio> und <video> Elemente
• Die Web Audio API

Aus der Perspektive des Benutzers kann eine Webseite oder App, die spontan ohne Vorwarnung Lärm macht, erschütternd, unangenehm oder abschreckend wirken. Aus diesem Grund erlauben Browser in der Regel nur unter bestimmten Umständen das erfolgreiche Autoplay.

Im Allgemeinen können Sie davon ausgehen, dass Medien nur dann automatisch abgespielt werden dürfen, wenn mindestens eines der folgenden zutrifft:

• Der Ton ist stummgeschaltet oder die Lautstärke ist auf 0 eingestellt
• Der Benutzer hat mit der Website interagiert (durch Klicken, Tippen, Tastendrücken usw.)
• Wenn die Site auf die Liste der erlaubten Sites gesetzt wurde; dies kann entweder automatisch geschehen, wenn der Browser feststellt, dass der Benutzer häufig mit Medien interagiert, oder manuell über Einstellungen oder andere Benutzeroberflächenmerkmale
• Wenn die Autoplay Permissions Policy verwendet wird, um einem <iframe> und seinem Dokument Autoplay-Unterstützung zu gewähren.

Andernfalls wird die Wiedergabe wahrscheinlich blockiert. Die genauen Situationen, die zur Blockierung führen, und die Besonderheiten, wie Sites auf die Liste der erlaubten Sites gelangen, variieren von Browser zu Browser, aber die oben genannten Punkte sind gute Richtlinien.

Einzelheiten finden Sie in den Autoplay-Richtlinien für Google Chrome und WebKit.

Da wir nun besprochen haben, was Autoplay ist und was verhindern kann, dass Autoplay erlaubt wird, werden wir uns ansehen, wie Ihre Website oder App Medien automatisch beim Laden der Seite abspielen kann, wie man erkennt, wann Autoplay nicht auftritt, und Tipps zum Umgang damit, wenn Autoplay vom Browser abgelehnt wird.

Der einfachste Weg, Inhalte automatisch abzuspielen, besteht darin, das autoplay-Attribut zu Ihrem <audio> oder <video>-Element hinzuzufügen, das die autoplay-Eigenschaft des Elements auf true setzt. Wenn autoplay auf true steht, beginnt das Medium automatisch so früh wie möglich nach folgenden Vorgängen zu spielen:

• Die Seite darf die Autoplay-Funktionalität nutzen
• Das Element wurde beim Laden der Seite erstellt
• Es wurde genügend Medium empfangen, um die Wiedergabe zu beginnen und bis zum Ende des Mediums ohne Unterbrechung fortzusetzen, vorausgesetzt, es gibt keine dramatischen Änderungen in der Netzwerkleistung oder Bandbreite.

Beispiel: Das Autoplay-Attribut

Ein <audio>-Element, das das autoplay-Attribut verwendet, könnte so aussehen:

<audio id="musicplayer" autoplay>
  <source src="/music/chapter1.mp3" />
</audio>

Beispiel 2: Erkennen, ob Autoplay erlaubt ist

Wenn Autoplay für Ihre Anwendung wichtig ist, müssen Sie möglicherweise das Verhalten anpassen, je nachdem, ob Autoplay erlaubt, nicht erlaubt oder nur für unhörbare Inhalte unterstützt wird. Wenn Ihre Anwendung beispielsweise ein Video automatisch abspielen muss und Sie wissen, dass die Seite nur das Autoplay von unhörbaren Inhalten erlaubt, können Sie es entweder stummschalten oder ein Video ohne Audiotrack bereitstellen. Ebenso, wenn Sie wissen, dass Autoplay überhaupt nicht erlaubt ist, könnten Sie ein Standardbild für das Video bereitstellen (unter Verwendung des poster-Attributs) oder das Laden des Videos bis zu einer expliziten Anforderung aufschieben.

Die Methode Navigator.getAutoplayPolicy() kann verwendet werden, um die Autoplay-Policy für eine Art von Medienfunktion (z. B. alle Medienelemente oder alle Audio-Kontexte) in einem Dokument zu überprüfen oder um zu überprüfen, ob ein spezifisches Medienelement oder ein Audiokontext automatisch abgespielt werden kann.

Das folgende Beispiel zeigt, wie Sie den String mediaelement übergeben, um die Autoplay-Policy für alle Medienelemente im Dokument zu erhalten (geben Sie audiocontext an, um die Policy für Audio-Kontexte zu erhalten). Der Code setzt voraus, dass video ein HTMLVideoElement-Medienelement ist, das das <video>-Tag oder HTMLVideoElement verwendet und standardmäßig so konfiguriert ist, dass es mit Audio automatisch abgespielt wird. Wenn Autoplay nur für unhörbare Inhalte erlaubt ist, stumm schalten wir das Audio; wenn Autoplay nicht erlaubt ist, stellen wir sicher, dass ein Platzhalterbild für das Video angezeigt wird.

if (navigator.getAutoplayPolicy("mediaelement") === "allowed") {
  // The video element will autoplay with audio.
} else if (navigator.getAutoplayPolicy("mediaelement") === "allowed-muted") {
  // Mute audio on video
  video.muted = true;
} else if (navigator.getAutoplayPolicy("mediaelement") === "disallowed") {
  // Set a default placeholder image.
  video.poster = "http://example.com/poster_image_url";
}

Der Code zum Testen eines spezifischen Elements oder Audiokontextes ist derselbe, außer dass Sie das zu testende Element oder den Kontext statt des Typ-Strings übergeben. Hier übergeben wir das video-Objekt, das wir testen möchten.

if (navigator.getAutoplayPolicy(video) === "allowed") {
  // The video element will autoplay with audio.
} else if (navigator.getAutoplayPolicy(video) === "allowed-muted") {
  // Mute audio on video
  video.muted = true;
} else if (navigator.getAutoplayPolicy(video) === "disallowed") {
  // Set a default placeholder image.
  video.poster = "http://example.com/poster_image_url";
}

Die Autoplay-Policy für einen Typ kann sich aufgrund einer Benutzerinteraktion mit der Site, der Seite oder einem bestimmten Element ändern. Ebenso könnte bei einigen Browsern die Policy für ein spezifisches Element geändert werden, obwohl die Policy für den Typ unverändert bleibt (zum Beispiel bei Browsern, bei denen das Berühren eines bestimmten Elements nur diesem Element erlaubt, automatisch abgespielt zu werden).

Da es keine Möglichkeit gibt, benachrichtigt zu werden, wenn sich die Autoplay-Policy geändert hat (entweder für einen Typ oder ein Element), empfehlen wir im Allgemeinen, die Policy zu überprüfen, wenn die Seite geladen wird, unter Verwendung des Typs.

Beispiel 3: Erkennen des Autoplay-Fehlers als Fallback

Kein spezielles Ereignis (oder eine andere Benachrichtigung) wird durch den Erfolg oder Misserfolg des Autoplays ausgelöst, sodass Browser, die Navigator.getAutoplayPolicy() nicht unterstützen, keine einfache Möglichkeit haben, festzustellen, ob Autoplay unterstützt wird oder nicht.

Ein Ansatz besteht darin, auf das erste Auftreten des play-Ereignisses zu lauschen, das auf dem Medienelement ausgelöst wird, wenn es fortgesetzt wird, nachdem es pausiert und Autoplay aufgetreten ist. Das bedeutet, dass das erste Mal, wenn das play-Ereignis ausgelöst wird, Sie wissen, dass Ihr Medium zum ersten Mal gestartet wurde, nachdem die Seite geöffnet wurde.

Betrachten Sie dieses HTML für ein Medienelement:

<video src="my-video.mp4" id="video" autoplay></video>

Hier haben wir ein <video>-Element, dessen autoplay-Attribut gesetzt ist und mit einem play-Ereignishandler ausgestattet ist; das Ereignis wird von einer Funktion namens handleFirstPlay() gehandhabt, die das play-Ereignis als Eingabe empfängt.

handleFirstPlay() sieht folgendermaßen aus:

const video = document.getElementById("video");
video.addEventListener("play", handleFirstPlay, false);

let hasPlayed = false;
function handleFirstPlay(event) {
  if (!hasPlayed) {
    hasPlayed = true;

    // Remove listener so this only gets called once.
    const vid = event.target;
    vid.removeEventListener("play", handleFirstPlay);

    // Start whatever you need to do after first playback has started
  }
}

Nachdem wir eine Referenz auf das Videoelement vom Event-Objekt über dessen target erhalten haben, verwenden wir es, um den Ereignislistener zu entfernen. Dies verhindert, dass zukünftige play-Ereignisse an den Handler übermittelt werden. Das könnte passieren, wenn das Video vom Benutzer pausiert und wieder fortgesetzt wird oder automatisch vom Browser, wenn das Dokument in einem Hintergrund-Tab ist.

An diesem Punkt kann Ihre Site oder App mit allem beginnen, was sie benötigt, um den mittlerweile gestarteten Video abzurufen.

Der Begriff "Autoplay" bezieht sich auch auf Szenarien, in denen ein Skript versucht, die Wiedergabe von Medien mit Audio zu starten, außerhalb des Kontexts der Bearbeitung eines Benutzereingabeevents. Dies wird durch den Aufruf der play()-Methode des Medienelements durchgeführt.

Beispiel: Videowiedergabe

Dieses einfache Beispiel spielt das erste <video>-Element im Dokument ab. play() lässt die Wiedergabe nicht starten, es sei denn das Dokument hat die Erlaubnis zur automatischen Wiedergabe von Medien.

document.querySelector("video").play();

Beispiel: Umgang mit play()-Fehlern

Es ist viel einfacher, einen Fehler beim Autoplay zu erkennen, wenn Sie die play()-Methode verwenden, um es zu starten. play() gibt ein Promise zurück, das aufgelöst wird, sobald das Medium erfolgreich zu spielen beginnt, und abgelehnt wird, wenn die Wiedergabe nicht beginnt (z. B. wenn Autoplay verweigert wird). Wenn Autoplay fehlschlägt, möchten Sie wahrscheinlich eine Möglichkeit bieten, dem Benutzer manuell zu ermöglichen, dem Browser die Wiedergabe von Medien zu gestatten.

Sie könnten Code wie diesen verwenden, um die Aufgabe zu erledigen:

let startPlayPromise = videoElem.play();

if (startPlayPromise !== undefined) {
  startPlayPromise
    .then(() => {
      // Start whatever you need to do only after playback
      // has begun.
    })
    .catch((error) => {
      if (error.name === "NotAllowedError") {
        showPlayButton(videoElem);
      } else {
        // Handle a load or playback error
      }
    });
}

Das Erste, was wir mit dem Ergebnis von play() machen, ist sicherzustellen, dass es nicht undefined ist. Wir überprüfen dies, denn in früheren Versionen der HTML-Spezifikation gab play() keinen Wert zurück. Das Zurückgeben eines Versprechens zur Bestimmung des Erfolgs oder Misserfolgs der Operation wurde kürzlich hinzugefügt. Das Überprüfen von undefined verhindert, dass dieser Code in älteren Browserversionen mit einem Fehler fehlschlägt.

Wenn das von play() zurückgegebene Versprechen ohne Fehler aufgelöst wird, wird die then()-Klausel ausgeführt und kann alles starten, was getan werden muss, wenn Autoplay begonnen hat.

Wir fügen dann einen catch()-Handler zum Versprechen hinzu. Dieser sieht sich den name des Fehlers an, um zu überprüfen, ob er NotAllowedError lautet. Dies zeigt an, dass die Wiedergabe aufgrund eines Berechtigungsproblems fehlgeschlagen ist, z. B. wenn Autoplay verweigert wird. Wenn dies der Fall ist, sollten wir eine Benutzeroberfläche präsentieren, um dem Benutzer zu ermöglichen, die Wiedergabe manuell zu starten; dies wird hier von einer Funktion showPlayButton() gehandhabt.

Alle anderen Fehler werden nach Bedarf behandelt.

Wenn Sie das Video nach der ersten Interaktion mit der Seite starten möchten, könnte setInterval() verwendet werden, um dies zu erreichen:

let playAttempt = setInterval(() => {
  videoElem
    .play()
    .then(() => {
      clearInterval(playAttempt);
    })
    .catch((error) => {
      console.log("Unable to play the video, User has not interacted yet.");
    });
}, 3000);

In der Web Audio API kann eine Website oder App Audio mithilfe der start()-Methode auf einem Quellknoten starten, der mit dem AudioContext verbunden ist. Dies geschieht außer im Kontext der Bearbeitung eines Benutzereingabereignisses und unterliegt den Autoplay-Regeln.

Zusätzlich zur browserseitigen Verwaltung und Steuerung der oben beschriebenen Autoplay-Funktionalität kann ein Webserver auch seine Bereitschaft ausdrücken, Autoplay zuzulassen. Der HTTP Permissions-Policy-Header mit der Direktive autoplay wird verwendet, um zu steuern, welche Domains, falls vorhanden, für das automatische Abspielen von Medien verwendet werden können. Standardmäßig ist die autoplay-Berechtigungsrichtlinie auf self gesetzt, was anzeigt, dass das Autoplay erlaubt ist, wie sie auf derselben Domain wie das Dokument gehostet sind.

Sie können auch eine leere Liste der erlaubten Medien (()) angeben, um Autoplay vollständig zu deaktivieren, * verwenden, um Autoplay von allen Domains zuzulassen, oder eine oder mehrere spezifische Quellen, von denen Medien automatisch abgespielt werden können. Diese Quellen sind durch Leerzeichenzeichen getrennt.

Wenn Sie das allow-Attribut auf einem <iframe> verwenden, um eine Berechtigungsrichtlinie für diesen Frame und seine eingebetteten Frames festzulegen, können Sie auch den Wert 'src' angeben, um das automatische Abspielen von Medien nur von derselben Domain zu ermöglichen, die vom src-Attribut des Frames angegeben ist.

Um den Permissions-Policy-Header zu verwenden, um nur Medien von der Ursprung des Dokuments automatisch abzuspielen:

Permissions-Policy: autoplay=(self)

Um dasselbe für ein <iframe> zu tun:

<iframe src="mediaplayer.html" allow="autoplay"> </iframe>

Wenn Sie die Berechtigung der Fullscreen API zum vorherigen Beispiel hinzufügen, erhalten Sie einen Permissions-Policy-Header wie den folgenden, wenn Vollbildzugriff unabhängig von der Domain erlaubt ist; eine Domainsbeschränkung kann nach Bedarf ebenfalls hinzugefügt werden.

Permissions-Policy: autoplay=(self), fullscreen=(self)

Die gleichen Berechtigungen, die unter Verwendung des allow-Eigentums des <iframe>-Elements erteilt wurden, sehen so aus:

<iframe src="mediaplayer.html" allow="autoplay; fullscreen"> </iframe>

Der Permissions-Policy-Header, um die Wiedergabe von Medien sowohl von der Domain des Dokuments (oder <iframe>) als auch von https://example.media zu ermöglichen, sieht folgendermaßen aus:

Permissions-Policy: autoplay=(self "https://example.media")

Ein <iframe>-Element, das angeben soll, dass diese Autoplay-Richtlinie für sich selbst und alle darin verschachtelten Frames gelten soll, würde so geschrieben werden:

<iframe
  width="300"
  height="200"
  src="mediaplayer.html"
  allow="autoplay 'src' https://example.media">
</iframe>

Das Setzen der autoplay-Berechtigungsrichtlinie auf ()/none deaktiviert das Autoplay vollständig für das Dokument oder <iframe> und alle darin eingebetteten Frames. Der HTTP-Header lautet:

Permissions-Policy: autoplay=()

Verwendung des allow-Attributs des <iframe>:

<iframe src="mediaplayer.html" allow="autoplay 'none'"> </iframe>

Hier werden Tipps und empfohlene beste Praktiken angeboten, um Ihnen zu helfen, das Beste aus der Arbeit mit Autoplay zu machen.

Ein gängiger Anwendungsfall für Autoplay ist das automatische Abspielen eines Videoclips, der mit einem Artikel, einer Werbung oder einer Vorschau der Hauptfunktionalität der Seite verbunden ist. Um solche Videos automatisch abzuspielen, haben Sie zwei Möglichkeiten: keinen Audiotrack zu haben oder einen Audiotrack zu haben, aber das <video>-Element so zu konfigurieren, dass es standardmäßig stumm geschaltet ist, wie folgt:

<video
  src="/videos/awesomevid.webm"
  controls
  autoplay
  playsinline
  muted></video>

Dieses Videoelement ist so konfiguriert, dass es die Benutzersteuerungen (normalerweise Wiedergabe/Pause, Vor- und Zurückspulen in der Zeitleiste des Videos, Lautstärkeregelung und Stummschaltung) enthält; auch, da das muted-Attribut enthalten ist und das für Autoplay in Safari erforderliche playsinline-Attribut umfasst, wird das Video automatisch abgespielt, jedoch stummgeschaltet. Der Benutzer hat jedoch die Möglichkeit, das Audio zu aktivieren, indem er auf die Lautstärketaste in den Steuerungen klickt.

Browser können Präferenzen haben, die die Funktionsweise von Autoplay oder die Handhabung von Autoplay-Blockierungen steuern. Hier sind solche Präferenzen aufgelistet, die für Sie als Webentwickler von besonderer Bedeutung oder Wichtigkeit sein könnten. Dazu gehören alle, die bei Tests oder Fehlerbehebungen helfen können, sowie alle, die in einer Weise eingestellt wurden, die Sie beachten müssen.

media.allowed-to-play.enabled

Eine boolesche Präferenz, die angibt, ob die nicht standardisierte HTMLMediaElement.allowedToPlay-Eigenschaft dem Web verfügbar gemacht wird. Diese ist derzeit standardmäßig auf false gesetzt (außer in Nightly-Builds, in denen sie standardmäßig true ist). Wenn diese auf false ist, fehlt die allowedToPlay-Eigenschaft in der HTMLMediaElement-Schnittstelle und ist daher nicht auf <audio> oder <video>-Elementen vorhanden.

media.autoplay.allow-extension-background-pages

Diese boolesche Präferenz ermöglicht, wenn true, dass Hintergrundskripte von Browsererweiterungen automatisch Audiomedien abspielen. Wenn dieser Wert auf false gesetzt ist, wird diese Fähigkeit deaktiviert. Der Standardwert ist true.

media.autoplay.allow-muted

Eine boolesche Präferenz, die, wenn true (der Standardwert), erlaubt, dass stummgeschaltete Audiomedien automatisch abgespielt werden. Wenn dies auf false geändert wurde, wird die Wiedergabe von Medien mit einem Audiotrack nicht erlaubt, auch wenn sie stummgeschaltet sind.

media.autoplay.block-webaudio

Eine boolesche Präferenz, die angibt, ob Autoplay-Blockierung auf die Web Audio API angewendet wird. Wenn false, ist Web-Audio immer erlaubt. Wenn true, können Audiokontexte auf Seiten nur gespielt werden, nachdem eine Sticky activation stattgefunden hat. Der Standardwert ist true.

media.autoplay.default

Eine ganze Zahl Präferenz, die angibt, ob die Konfiguration der Autoplay-Unterstützung pro Domain von Standard (0), blockiert (1) oder prompt-bei-Verwendung (2) erlaubt wird. Der Standardwert ist 0.

media.autoplay.enabled.user-gestures-needed (Nur Nightly-Builds)

Eine boolesche Präferenz, die steuert, ob die Erkennung von Benutzerinteraktionen die Einstellung von media.autoplay.default überschreiben darf. Wenn media.autoplay.default nicht auf 0 (Autoplay standardmäßig erlaubt) eingestellt ist, erlaubt diese Präferenz bei true das Autoplay von Medien mit Audiotracks trotzdem, wenn die Seite durch Benutzerinteraktionen aktiviert wurde, und Medien, die nicht hörbar sind, sind überhaupt nicht beschränkt.

media.block-autoplay-until-in-foreground

Eine boolesche Präferenz, die angibt, ob die Medienwiedergabe blockiert wird, wenn sie in einem Hintergrundkostenfenster gestartet werden. Der Standardwert true bedeutet, dass selbst wenn anderweitig verfügbar, das Autoplay erst nach dem Wechsel in den Vordergrund stattfindet. Dies verhindert die störende Situation, in der ein Tab-Geräusch anfängt zu spielen und der Benutzer den Tab inmitten seiner vielen Tabs und Fenster nicht finden können.

• Web-Medientechnologien
• Video- und Audioinhalte (Lern-Leitfaden)
• Verwendung der Web Audio API
• Cross-browser Audio Basics