YouTube Player API Reference for iframe Embeds

Mit der Iframe-Player-API kannst du auf deiner Website einen YouTube-Videoplayer einbetten und den Player mit JavaScript steuern.

Mit den JavaScript-Funktionen der API kannst du Videos zu Wiedergabelisten hinzufügen und diese Videos wiedergeben, pausieren oder anhalten, die Lautstärke des Players einstellen oder Informationen zum wiedergegebenen Video abrufen. Du kannst auch Ereignis-Listener hinzufügen, die als Reaktion auf bestimmte Player-Ereignisse ausgeführt werden, z. B. eine Änderung des Player-Status.

In diesem Leitfaden wird erläutert, wie du die IFrame API verwendest. Dort werden die verschiedenen Ereignistypen aufgeführt, die die API senden kann, und es wird erklärt, wie Sie Ereignis-Listener schreiben, um auf diese Ereignisse zu reagieren. Zudem werden sowohl die verschiedenen JavaScript-Funktionen vorgestellt, die du aufrufen kannst, um den Videoplayer zu steuern, als auch die Player-Parameter, mit denen du den Player noch individueller gestalten kannst.

Voraussetzungen

Der Browser des Nutzers muss die HTML5-Funktion postMessage unterstützen. postMessage wird von den meisten modernen Browsern unterstützt.

Eingebettete Player müssen einen Darstellungsbereich mit mindestens 200 x 200 Pixel haben. Wenn die Steuerung angezeigt wird, muss der Player groß genug sein, um die Steuerelemente vollständig anzuzeigen, ohne dass der Darstellungsbereich dabei die genannte Mindestgröße unterschreitet. Für 16:9-Player empfehlen wir eine Breite von mindestens 480 Pixel und eine Höhe von mindestens 270 Pixel.

Webseiten, die die IFrame API verwenden, müssen auch die folgende JavaScript-Funktion implementieren:

  • onYouTubeIframeAPIReady: Die API ruft diese Funktion auf, wenn das JavaScript für die Player API vollständig heruntergeladen wurde. Anschließend kannst du die API auf deiner Seite verwenden. Diese Funktion kann die Player-Objekte erstellen, die beim Laden der Seite angezeigt werden sollen.

Erste Schritte

Die folgende HTML-Beispielseite erstellt einen eingebetteten Player, der ein Video lädt, dieses sechs Sekunden lang wiedergibt und anschließend die Wiedergabe stoppt. Die nummerierten Kommentare im HTML-Code werden in der Liste unter dem Beispiel erklärt.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

In der folgenden Liste werden weitere Informationen zum obigen Beispiel bereitgestellt.

  1. Mit dem <div>-Tag in diesem Abschnitt wird der Ort auf der Seite angegeben, an dem die IFrame API den Videoplayer platziert. Der Konstruktor für das Player-Objekt, der im Abschnitt Videoplayer laden beschrieben wird, identifiziert das <div>-Tag anhand seines id, damit die API die <iframe> an der richtigen Stelle platziert. Insbesondere ersetzt die IFrame API das <div>-Tag durch das <iframe>-Tag.

    Alternativ können Sie das <iframe>-Element auch direkt auf der Seite platzieren. Im Abschnitt Videoplayer laden wird dies erläutert.

  2. Der Code in diesem Abschnitt lädt den JavaScript-Code der Iframe Player API. Im Beispiel wird der API-Code mithilfe einer DOM-Änderung heruntergeladen, damit der Code asynchron abgerufen wird. Das async-Attribut des <script>-Tags, das auch asynchrone Downloads ermöglicht, wird in dieser Stack Overflow-Antwort erläutert und wird noch nicht von allen modernen Browsern unterstützt.

  3. Die Funktion onYouTubeIframeAPIReady wird ausgeführt, sobald der Player API-Code heruntergeladen wurde. In diesem Codeabschnitt wird die globale Variable player definiert, die sich auf den eingebetteten Videoplayer bezieht. Die Funktion erstellt dann das Videoplayer-Objekt.

  4. Die Funktion onPlayerReady wird ausgeführt, wenn das Ereignis onReady ausgelöst wird. In diesem Beispiel zeigt die Funktion an, dass die Wiedergabe beginnen sollte, wenn der Videoplayer bereit ist.

  5. Die API ruft die Funktion onPlayerStateChange auf, wenn sich der Status des Players ändert. Dies kann beispielsweise bedeuten, dass der Player wiedergegeben, pausiert oder beendet wird. Die Funktion gibt an, dass der Player, wenn sein Status 1 (Wiedergabe) ist, sechs Sekunden lang wiedergegeben werden und dann die Funktion stopVideo aufgerufen werden soll, um das Video anzuhalten.

Videoplayer laden

Nachdem der JavaScript-Code der API geladen wurde, ruft die API die onYouTubeIframeAPIReady-Funktion auf. Anschließend kannst du ein YT.Player-Objekt erstellen, um einen Videoplayer auf deiner Seite einzufügen. Im folgenden HTML-Ausschnitt ist die Funktion onYouTubeIframeAPIReady aus dem Beispiel oben zu sehen:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

Der Konstruktor für den Videoplayer gibt die folgenden Parameter an:

  1. Der erste Parameter gibt entweder das DOM-Element oder das id des HTML-Elements an, an dem die API das <iframe>-Tag mit dem Player einfügt.

    Die IFrame API ersetzt das angegebene Element durch das Element <iframe>, das den Player enthält. Das kann sich auf das Layout Ihrer Seite auswirken, wenn das ersetzte Element einen anderen Darstellungsstil als das eingefügte <iframe>-Element hat. Standardmäßig wird ein <iframe> als inline-block-Element angezeigt.

  2. Beim zweiten Parameter handelt es sich um ein Objekt, das Player-Optionen angibt. Das Objekt enthält die folgenden Eigenschaften:
    • width (Zahl): Die Breite des Videoplayers. Der Standardwert ist 640.
    • height (Zahl): Die Höhe des Videoplayers. Der Standardwert ist 390.
    • videoId (String): Die YouTube-Video-ID, die das Video identifiziert, das der Player lädt.
    • playerVars (Objekt): Die Eigenschaften des Objekts geben Player-Parameter an, mit denen der Player angepasst werden kann.
    • events (Objekt): Die Eigenschaften des Objekts identifizieren die Ereignisse, die von der API ausgelöst werden, und die Funktionen (Ereignis-Listener), die die API bei diesen Ereignissen aufruft. Im Beispiel gibt der Konstruktor an, dass die Funktion onPlayerReady ausgeführt wird, wenn das Ereignis onReady ausgelöst wird, und dass die Funktion onPlayerStateChange ausgeführt wird, wenn das Ereignis onStateChange ausgelöst wird.

Wie im Abschnitt Einstieg erwähnt, kannst du anstelle eines leeren <div>-Elements auf deiner Seite, das dann vom JavaScript-Code der Player API durch ein <iframe>-Element ersetzt wird, das <iframe>-Tag selbst erstellen. Das erste Beispiel im Abschnitt Beispiele zeigt, wie das geht.

<iframe id="player" type="text/html" width="640" height="390"
  src="http://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1&origin=http://example.com"
  frameborder="0"></iframe>

Wenn du das <iframe>-Tag schreibst, musst du beim Erstellen des YT.Player-Objekts keine Werte für width und height angeben, die als Attribute des <iframe>-Tags angegeben sind, oder für die videoId- und Player-Parameter, die in der src-URL angegeben sind. Als zusätzliche Sicherheitsmaßnahme sollten Sie der URL auch den Parameter origin hinzufügen. Geben Sie dabei das URL-Schema (http:// oder https://) und die vollständige Domain Ihrer Hostseite als Parameterwert an. origin ist optional. Wenn du ihn einfügst, wird verhindert, dass schädliches JavaScript von Drittanbietern in deine Seite eingeschleust und die Kontrolle über deinen YouTube-Player übernommen wird.

Weitere Beispiele zum Erstellen von Videoplayer-Objekten findest du unter Beispiele.

Vorgänge

Zum Aufrufen der Player-API-Methoden musst du zunächst eine Referenz für das Player-Objekt erhalten, das du steuern möchtest. Sie erhalten die Referenz, indem Sie ein YT.Player-Objekt erstellen, wie in den Abschnitten Erste Schritte und Videoplayer laden dieses Dokuments beschrieben.

Funktionen

Wiedergabelisten-Funktionen

Mit Wiedergabelisten-Funktionen kannst du Videos, Playlists sowie andere Videolisten laden und wiedergeben. Wenn du diese Funktionen mit der unten beschriebenen Objektsyntax aufrufst, kannst du auch eine Liste der von einem Nutzer hochgeladenen Videos in die Wiedergabeliste aufnehmen oder laden.

Die API unterstützt zwei verschiedene Syntaxen zum Aufrufen der Wiedergabelisten-Funktionen.

  • Für die Argumentsyntax müssen die Funktionsargumente in der vorgesehenen Reihenfolge aufgelistet werden.

  • Mit der Objektsyntax kannst du ein Objekt als einzelnen Parameter zuweisen und Objekteigenschaften für die Funktionsargumente definieren, die du festlegen möchtest. Darüber hinaus ist es möglich, dass die API Funktionen unterstützt, die von der Argumentsyntax nicht unterstützt werden.

Die Funktion loadVideoById kann beispielsweise auf eine der folgenden Arten aufgerufen werden. Die Objektsyntax unterstützt die Property endSeconds, die Argumentsyntax jedoch nicht.

  • Syntax von Argumenten

    loadVideoById("bHQqvYy5KYo", 5, "large")

  • Objektsyntax

    loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60});

Wiedergabelisten-Funktionen für Videos

cueVideoById

  • Syntax von Argumenten

    player.cueVideoById(videoId:String,
                    startSeconds:Number):Void

  • Objektsyntax

    player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):Void

Diese Funktion lädt das Thumbnail des angegebenen Videos und bereitet den Player auf die Wiedergabe des Videos vor. Der Player fordert das FLV erst an, wenn playVideo() oder seekTo() aufgerufen wird.

  • Der erforderliche Parameter videoId gibt die YouTube-Video-ID des abzuspielenden Videos an. In der YouTube Data API wird die ID über die Property id einer video-Ressource angegeben.
  • Der optionale Parameter startSeconds kann einen Float-/Ganzzahlwert annehmen und gibt an, ab wann das Video abgespielt werden soll, wenn playVideo() aufgerufen wird. Wenn du einen startSeconds-Wert angibst und dann seekTo() aufrufst, beginnt der Player mit der Wiedergabe ab der im seekTo()-Aufruf angegebenen Zeit. Wenn das Video cued ist und wiedergegeben werden kann, sendet der Player das Ereignis video cued (5).
  • Der optionale Parameter endSeconds, der nur in der Objektsyntax unterstützt wird, kann einen Float-/Integerwert annehmen und gibt an, wann die Wiedergabe des Videos beendet werden soll, wenn playVideo() aufgerufen wird. Wenn Sie einen endSeconds-Wert angeben und dann seekTo() aufrufen, ist der endSeconds-Wert nicht mehr gültig.

loadVideoById

  • Syntax von Argumenten

    player.loadVideoById(videoId:String,
                     startSeconds:Number):Void

  • Objektsyntax

    player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

Diese Funktion lädt das angegebene Video und gibt es wieder.

  • Der erforderliche Parameter videoId gibt die YouTube-Video-ID des abzuspielenden Videos an. In der YouTube Data API wird die ID über die Property id einer video-Ressource angegeben.
  • Der optionale Parameter startSeconds akzeptiert eine Gleitkommazahl oder Ganzzahl. Wird sie angegeben, beginnt das Video mit dem Keyframe, der dem angegebenen Zeitpunkt am nächsten ist.
  • Der optionale Parameter endSeconds akzeptiert eine Gleitkommazahl oder Ganzzahl. Wird sie angegeben, wird die Wiedergabe des Videos zum angegebenen Zeitpunkt beendet.

cueVideoByUrl

  • Syntax von Argumenten

    player.cueVideoByUrl(mediaContentUrl:String,
                     startSeconds:Number):Void

  • Objektsyntax

    player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

Diese Funktion lädt das Thumbnail des angegebenen Videos und bereitet den Player auf die Wiedergabe des Videos vor. Der Player fordert das FLV erst an, wenn playVideo() oder seekTo() aufgerufen wird.

  • Der erforderliche Parameter mediaContentUrl gibt eine vollständig qualifizierte YouTube-Player-URL im Format http://www.youtube.com/v/VIDEO_ID?version=3 an.
  • Der optionale Parameter startSeconds kann einen Float-/Ganzzahlwert annehmen und gibt an, ab wann das Video abgespielt werden soll, wenn playVideo() aufgerufen wird. Wenn du startSeconds festlegst und dann seekTo() aufrufst, wird der Player ab der im seekTo()-Aufruf angegebenen Zeit wiedergegeben. Wenn das Video cued ist und abgespielt werden kann, sendet der Player ein video cued-Ereignis (5).
  • Der optionale Parameter endSeconds, der nur in der Objektsyntax unterstützt wird, kann einen Float-/Integerwert annehmen und gibt an, wann die Wiedergabe des Videos beendet werden soll, wenn playVideo() aufgerufen wird. Wenn Sie einen endSeconds-Wert angeben und dann seekTo() aufrufen, ist der endSeconds-Wert nicht mehr gültig.

loadVideoByUrl

  • Syntax von Argumenten

    player.loadVideoByUrl(mediaContentUrl:String,
                      startSeconds:Number):Void

  • Objektsyntax

    player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number}):Void

Diese Funktion lädt das angegebene Video und gibt es wieder.

  • Der erforderliche Parameter mediaContentUrl gibt eine vollständig qualifizierte YouTube-Player-URL im Format http://www.youtube.com/v/VIDEO_ID?version=3 an.
  • Der optionale Parameter startSeconds kann einen Gleitkomma-/Ganzzahlwert annehmen und gibt an, ab wann das Video wiedergegeben werden soll. Wenn startSeconds (eine Zahl, die auch ein Gleitkommawert sein kann) angegeben ist, beginnt das Video mit dem nächstgelegenen Keyframe zur angegebenen Zeit.
  • Der optionale Parameter endSeconds, der nur in der Objektsyntax unterstützt wird, akzeptiert einen Gleitkomma-/Ganzzahlwert und gibt an, wann die Wiedergabe des Videos beendet werden soll.

Wiedergabelisten-Funktionen für Listen

Mit den Funktionen cuePlaylist und loadPlaylist kannst du eine Playlist laden und abspielen. Wenn du diese Funktionen mithilfe der Objektsyntax aufrufst, kannst du auch eine Liste der hochgeladenen Videos eines Nutzers in die Wiedergabeliste aufnehmen (oder laden).

Die Arbeitsweise der Funktionen richtet sich danach, ob sie mit der Argument- oder der Objektsyntax aufgerufen werden. Die beiden Methoden werden im Folgenden beschrieben.

cuePlaylist

  • Syntax von Argumenten

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
     Die angegebene Playlist wird der Wiedergabeliste hinzugefügt. Wenn die Playlist cued ist und abgespielt werden kann, sendet der Player ein video cued-Ereignis (5).

    • Der erforderliche Parameter playlist gibt ein Array mit YouTube-Video-IDs an. In der YouTube Data API wird die ID des Videos durch das Attribut id der Ressource video angegeben.

    • Der optionale Parameter index gibt den Index des ersten Videos in der Playlist an, das wiedergegeben werden soll. Der Parameter verwendet eine nullbasierte Indexierung und der Standardparameterwert ist 0. Standardmäßig wird also das erste Video in der Playlist geladen und abgespielt.

    • Der optionale Parameter startSeconds kann einen Gleitkomma-/Ganzzahlwert annehmen und gibt an, ab wann das erste Video in der Playlist abgespielt werden soll, wenn die Funktion playVideo() aufgerufen wird. Wenn du einen startSeconds-Wert angibst und dann seekTo() aufrufst, wird der Player ab der im seekTo()-Aufruf angegebenen Zeit wiedergegeben. Wenn du eine Playlist anzeigst und dann die Funktion playVideoAt() aufrufst, beginnt die Wiedergabe im Player am Anfang des angegebenen Videos.

  • Objektsyntax

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     Die angegebene Liste von Videos wird der Wiedergabeliste hinzugefügt. Die Liste kann eine Playlist oder der Feed mit den hochgeladenen Videos eines Nutzers sein. Die Möglichkeit, eine Liste von Suchergebnissen in die Wiedergabeliste aufzunehmen, wird eingestellt und ab dem 15. November 2020 nicht mehr unterstützt.

    Wenn die Liste cued ist und abgespielt werden kann, sendet der Player ein video cued-Ereignis (5).

    • Mit der optionalen Property listType wird der Typ des Ergebnisfeeds angegeben, der abgerufen wird. Gültige Werte sind playlist und user_uploads. Der eingestellte Wert search wird ab dem 15. November 2020 nicht mehr unterstützt. Der Standardwert ist playlist.

    • Die erforderliche Property list enthält einen Schlüssel, der die Liste der Videos angibt, die von YouTube zurückgegeben werden sollen.

      • Wenn der Wert des Attributs listType playlist ist, gibt das Attribut list die Playlist-ID oder ein Array von Video-IDs an. In der YouTube Data API wird mit dem Attribut id der Ressource playlist die ID einer Playlist angegeben. Das Attribut id der Ressource video gibt eine Video-ID an.
      • Wenn der Wert der Property listType user_uploads ist, wird mit der Property list der Nutzer identifiziert, dessen hochgeladene Videos zurückgegeben werden.
      • Wenn der Wert der Property listType search ist, wird die Suchanfrage in der Property list angegeben. Hinweis:Diese Funktion wurde eingestellt und wird ab dem 15. November 2020 nicht mehr unterstützt.

    • Mit der optionalen Property index wird der Index des ersten Videos in der Liste angegeben, das wiedergegeben werden soll. Der Parameter verwendet einen nullbasierten Index und der Standardparameterwert ist 0. Standardmäßig wird also das erste Video in der Liste geladen und abgespielt.

    • Die optionale Eigenschaft startSeconds akzeptiert eine Gleitkommazahl/Ganzzahl und gibt an, ab wann das erste Video in der Liste wiedergegeben werden soll, wenn die Funktion playVideo() aufgerufen wird. Wenn du einen startSeconds-Wert angibst und dann seekTo() aufrufst, wird der Player ab der im seekTo()-Aufruf angegebenen Zeit wiedergegeben. Wenn du eine Liste anzeigst und dann die Funktion playVideoAt() aufrufst, beginnt die Wiedergabe im Player am Anfang des angegebenen Videos.

loadPlaylist

  • Syntax von Argumenten

    player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
     Diese Funktion lädt die angegebene Playlist und spielt sie ab.

    • Der erforderliche Parameter playlist gibt ein Array mit YouTube-Video-IDs an. In der YouTube Data API wird in der Property id der Ressource video eine Video-ID angegeben.

    • Der optionale Parameter index gibt den Index des ersten Videos in der Playlist an, das wiedergegeben werden soll. Der Parameter verwendet eine nullbasierte Indexierung und der Standardparameterwert ist 0. Standardmäßig wird also das erste Video in der Playlist geladen und abgespielt.

    • Der optionale Parameter startSeconds kann einen Gleitkomma-/Ganzzahlwert annehmen und gibt an, ab wann das erste Video in der Playlist wiedergegeben werden soll.

  • Objektsyntax

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
     Diese Funktion lädt die angegebene Liste und spielt sie ab. Die Liste kann eine Playlist oder der Feed mit den hochgeladenen Videos eines Nutzers sein. Die Möglichkeit, eine Liste mit Suchergebnissen zu laden, wird eingestellt und ab dem 15. November 2020 nicht mehr unterstützt.

    • Mit der optionalen Property listType wird der Typ des Ergebnisfeeds angegeben, der abgerufen wird. Gültige Werte sind playlist und user_uploads. Der eingestellte Wert search wird ab dem 15. November 2020 nicht mehr unterstützt. Der Standardwert ist playlist.

    • Die erforderliche Property list enthält einen Schlüssel, der die Liste der Videos angibt, die von YouTube zurückgegeben werden sollen.

      • Wenn der Wert des Attributs listType playlist ist, gibt das Attribut list eine Playlist-ID oder ein Array von Video-IDs an. In der YouTube Data API gibt das Attribut id der Ressource playlist die ID einer Playlist an und das Attribut id der Ressource video die ID eines Videos.
      • Wenn der Wert der Property listType user_uploads ist, wird mit der Property list der Nutzer identifiziert, dessen hochgeladene Videos zurückgegeben werden.
      • Wenn der Wert der Property listType search ist, wird die Suchanfrage in der Property list angegeben. Hinweis:Diese Funktion wird eingestellt und ab dem 15. November 2020 nicht mehr unterstützt.

    • Mit der optionalen Property index wird der Index des ersten Videos in der Liste angegeben, das wiedergegeben werden soll. Der Parameter verwendet einen nullbasierten Index und der Standardparameterwert ist 0. Standardmäßig wird also das erste Video in der Liste geladen und abgespielt.

    • Die optionale startSeconds-Eigenschaft akzeptiert einen Gleitkomma-/Ganzzahlwert und gibt an, wann die Wiedergabe des ersten Videos in der Liste beginnen soll.

Wiedergabesteuerung und Player-Einstellungen

Video wiedergeben

player.playVideo():Void
Spielt das aktuell cued/geladene Video ab. Der endgültige Player-Status nach Ausführung dieser Funktion ist playing (1).

Hinweis:Eine Wiedergabe wird nur dann für die offizielle Aufrufzahl eines Videos gezählt, wenn sie über eine native Wiedergabeschaltfläche im Player gestartet wird.
player.pauseVideo():Void
Pausiert das gerade wiedergegebene Video. Der endgültige Player-Status nach Ausführung dieser Funktion ist paused (2), es sei denn, der Player befindet sich beim Aufruf der Funktion im Status ended (0). In diesem Fall ändert sich der Player-Status nicht.
player.stopVideo():Void
Stoppt und bricht das Laden des aktuellen Videos ab. Diese Funktion ist für Ausnahmefälle gedacht, in denen du weißt, dass sich der Nutzer mit dem Player keine weiteren Videos ansehen wird. Wenn du das Video pausieren möchtest, solltest du einfach die Funktion pauseVideo aufrufen. Wenn du das Video ändern möchtest, das gerade im Player abgespielt wird, kannst du eine der Funktionen zur Wiedergabeliste aufrufen, ohne vorher stopVideo aufzurufen.

Wichtig:Im Gegensatz zur Funktion pauseVideo, die den Player im Status paused (2) belässt, kann die Funktion stopVideo den Player in einen beliebigen Status setzen, in dem die Wiedergabe nicht aktiv ist, z. B. ended (0), paused (2), video cued (5) oder unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Springt zu einer bestimmten Stelle im Video. Wenn der Player beim Aufrufen der Funktion pausiert, pausiert er weiterhin. Wenn die Funktion aus einem anderen Status (playing, video cued usw.) aufgerufen wird, spielt der Player das Video ab.

  • Der Parameter seconds gibt an, zu welcher Zeit der Spieler vorspulen soll.

    Der Player springt zum nächsten Keyframe vor dem angegebenen Zeitpunkt. Dies gilt nicht, wenn der Player bereits den Teil des Videos heruntergeladen hat, nach dem der Nutzer sucht.

  • Der Parameter allowSeekAhead bestimmt, ob der Player eine neue Anfrage an den Server sendet, wenn der Parameter seconds eine Zeit außerhalb der aktuell im Puffer befindlichen Videodaten angibt.

    Wir empfehlen, diesen Parameter auf „false“ festzulegen, während der Nutzer die Maus über die Fortschrittsanzeige des Videos zieht, und dann auf „true“, wenn der Nutzer die Maus loslässt. Auf diese Weise kann ein Nutzer zu verschiedenen Stellen eines Videos scrollen, ohne neue Videostreams anzufordern, indem er an nicht gepufferten Stellen des Videos vorbeiscrollt. Wenn der Nutzer die Maustaste loslässt, springt der Player an die gewünschte Stelle des Videos und fordert bei Bedarf einen neuen Videostream an.

Wiedergabe von 360°-Videos steuern

Hinweis:Die Wiedergabe von 360°-Videos wird auf Mobilgeräten nur eingeschränkt unterstützt. Auf nicht unterstützten Geräten werden 360°-Videos verzerrt dargestellt und es gibt keine Möglichkeit, die Wiedergabeperspektive zu ändern – weder über die API noch mithilfe von Ausrichtungssensoren oder durch Berühren/Ziehen auf dem Display des Geräts.

player.getSphericalProperties():Object
Ruft Eigenschaften ab, die die aktuelle Perspektive oder Ansicht des Betrachters für die Videowiedergabe beschreiben. Außerdem gilt:
  • Dieses Objekt wird nur für 360°-Videos (auch sphärische Videos genannt) erfasst.
  • Wenn das aktuelle Video kein 360°-Video ist oder die Funktion von einem nicht unterstützten Gerät aufgerufen wird, gibt die Funktion ein leeres Objekt zurück.
  • Wenn auf unterstützten Mobilgeräten die Eigenschaft enableOrientationSensor auf true festgelegt ist, gibt diese Funktion ein Objekt zurück, in dem die Eigenschaft fov den korrekten Wert enthält und die anderen Eigenschaften auf 0 festgelegt sind.
Das Objekt enthält die folgenden Eigenschaften:
Attribute
yaw Eine Zahl im Bereich [0, 360], die den horizontalen Winkel der Ansicht in Grad angibt. Sie gibt an, inwieweit der Nutzer die Ansicht nach links oder rechts dreht. Die neutrale Position, die in der äquirectangulären Projektion auf die Mitte des Videos gerichtet ist, entspricht 0°. Dieser Wert steigt, wenn sich der Betrachter nach links dreht.
pitch Eine Zahl im Bereich [-90, 90], die den vertikalen Winkel der Ansicht in Grad angibt. Sie gibt an, inwieweit der Nutzer die Ansicht nach oben oder unten richtet. Die neutrale Position, die in der äquirectangulären Projektion auf die Mitte des Videos gerichtet ist, entspricht 0°. Dieser Wert steigt, wenn der Betrachter aufblickt.
roll Eine Zahl im Bereich [-180, 180], die den Drehwinkel der Ansicht im Uhrzeigersinn oder gegen den Uhrzeigersinn in Grad angibt. Die neutrale Position, bei der die horizontale Achse in der flächentreuen Projektion parallel zur horizontalen Achse der Ansicht ist, entspricht 0°. Der Wert steigt, wenn sich die Ansicht im Uhrzeigersinn dreht, und sinkt, wenn sich die Ansicht gegen den Uhrzeigersinn dreht.

Der eingebettete Player bietet keine Benutzeroberfläche zum Anpassen der Drehung der Ansicht. Die Rollung kann auf zwei sich gegenseitig ausschließende Arten angepasst werden:
  1. Verwenden Sie den Ausrichtungssensor in einem mobilen Browser, um die Ansicht zu neigen. Wenn der Orientierungssensor aktiviert ist, gibt die Funktion getSphericalProperties immer 0 als Wert der Eigenschaft roll zurück.
  2. Wenn der Ausrichtungssensor deaktiviert ist, setzen Sie die Rollung mit dieser API auf einen Wert ungleich 0.
fov Eine Zahl im Bereich [30, 120], die den Sichtbereich der Ansicht in Grad entlang der längeren Kante des Darstellungsbereichs darstellt. Die kürzere Seite wird automatisch so angepasst, dass sie proportional zum Seitenverhältnis der Ansicht ist.

Der Standardwert ist 100 Grad. Wenn Sie den Wert verringern, ist das so, als würden Sie in den Videocontent hineinzoomen. Wenn Sie den Wert erhöhen, ist das so, als würden Sie herauszoomen. Dieser Wert kann entweder über die API oder mit dem Mausrad angepasst werden, wenn sich das Video im Vollbildmodus befindet.
player.setSphericalProperties(properties:Object):Void
Legt die Videoausrichtung für die Wiedergabe eines 360°-Videos fest. Wenn das aktuelle Video nicht sphärisch ist, wird die Methode unabhängig von der Eingabe nicht ausgeführt.

Die Wiedergabeansicht reagiert auf Aufrufe dieser Methode, indem sie aktualisiert wird, um die Werte aller bekannten Eigenschaften im properties-Objekt widerzuspiegeln. In der Ansicht werden Werte für alle anderen bekannten Properties gespeichert, die nicht in diesem Objekt enthalten sind.

Zusätzlich gilt:
  • Wenn das Objekt unbekannte und/oder unerwartete Eigenschaften enthält, werden diese vom Player ignoriert.
  • Wie bereits zu Beginn dieses Abschnitts erwähnt, wird die Wiedergabe von 360°-Videos nicht auf allen Mobilgeräten unterstützt.
  • Auf unterstützten Mobilgeräten wird mit dieser Funktion standardmäßig nur die Property fov festgelegt. Die Properties yaw, pitch und roll für die Wiedergabe von 360°-Videos sind davon nicht betroffen. Weitere Informationen finden Sie unten im Abschnitt zum Attribut enableOrientationSensor.
Das an die Funktion übergebene properties-Objekt enthält die folgenden Eigenschaften:
Attribute
yaw Siehe Definition oben.
pitch Siehe Definition oben.
roll Siehe Definition oben.
fov Siehe Definition oben.
enableOrientationSensor Hinweis:Diese Eigenschaft wirkt sich nur auf die 360°-Wiedergabe auf unterstützten Geräten aus. Ein boolescher Wert, der angibt, ob das IFrame-Embed auf Ereignisse reagieren soll, die Änderungen an der Ausrichtung eines unterstützten Geräts signalisieren, z. B. die DeviceOrientationEvent eines mobilen Browsers. Der Standardparameterwert ist true.

Unterstützte Mobilgeräte
  • Wenn der Wert true ist, berücksichtigt ein eingebetteter Player bei der Anpassung der Properties yaw, pitch und roll für die 360°-Videowiedergabe nur die Bewegung des Geräts. Das Attribut fov kann jedoch weiterhin über die API geändert werden. Die API ist in der Tat die einzige Möglichkeit, das Attribut fov auf einem Mobilgerät zu ändern. Das ist das Standardverhalten.
  • Wenn der Wert false ist, hat die Bewegung des Geräts keine Auswirkungen auf die 360°-Ansicht. Die Eigenschaften yaw, pitch, roll und fov müssen dann alle über die API festgelegt werden.

Nicht unterstützte Mobilgeräte
Der Wert der Property enableOrientationSensor hat keinen Einfluss auf die Wiedergabe.

Video in einer Playlist wiedergeben

player.nextVideo():Void
Mit dieser Funktion wird das nächste Video in der Playlist geladen und abgespielt.

  • Wenn player.nextVideo() aufgerufen wird, während das letzte Video in der Playlist angesehen wird und die Playlist auf „Kontinuierliche Wiedergabe“ (loop) eingestellt ist, lädt der Player das erste Video in der Liste und spielt es ab.

  • Wenn player.nextVideo() aufgerufen wird, während das letzte Video in der Playlist angesehen wird und die Playlist nicht so eingestellt ist, dass sie fortlaufend wiedergegeben wird, wird die Wiedergabe beendet.

player.previousVideo():Void
Mit dieser Funktion wird das vorherige Video in der Playlist geladen und abgespielt.

  • Wenn player.previousVideo() aufgerufen wird, während das erste Video in der Playlist angesehen wird, und die Playlist auf „Kontinuierliche Wiedergabe“ (loop) eingestellt ist, lädt der Player das letzte Video in der Liste und spielt es ab.

  • Wenn player.previousVideo() aufgerufen wird, während das erste Video in der Playlist angesehen wird, und die Playlist nicht auf „Ununterbrochen wiedergeben“ eingestellt ist, startet der Player das erste Playlist-Video von vorn.

player.playVideoAt(index:Number):Void
Mit dieser Funktion wird das angegebene Video in der Playlist geladen und abgespielt.

  • Mit dem erforderlichen Parameter index wird der Index des Videos angegeben, das in der Playlist wiedergegeben werden soll. Der Parameter verwendet einen nullbasierten Index. Der Wert 0 gibt also das erste Video in der Liste an. Wenn du die Playlist zufällig abgemischt hast, wird mit dieser Funktion das Video an der angegebenen Position in der Playlist abgespielt.

Player-Lautstärke ändern

player.mute():Void
Stummschaltet den Player.
player.unMute():Void
Die Stummschaltung des Players wird aufgehoben.
player.isMuted():Boolean
Gibt true zurück, wenn der Player stummgeschaltet ist, andernfalls false.
player.setVolume(volume:Number):Void
Lautstärke einstellen Akzeptiert Ganzzahlen zwischen 0 und 100.
player.getVolume():Number
Gibt die aktuelle Lautstärke des Players als Ganzzahl zwischen 0 und 100 zurück. Beachte, dass getVolume() die Lautstärke zurückgibt, auch wenn der Player stummgeschaltet ist.

Player-Größe festlegen

player.setSize(width:Number, height:Number):Object
Legt die Größe in Pixeln des <iframe> fest, das den Player enthält.

Wiedergaberate festlegen

player.getPlaybackRate():Number
Mit dieser Funktion wird die Wiedergabegeschwindigkeit des aktuell wiedergegebenen Videos abgerufen. Die Standardwiedergabegeschwindigkeit ist 1, was bedeutet, dass das Video mit normaler Geschwindigkeit abgespielt wird. Zulässige Werte für die Wiedergabegeschwindigkeit sind 0.25, 0.5, 1, 1.5 und 2.
player.setPlaybackRate(suggestedRate:Number):Void
Mit dieser Funktion wird die vorgeschlagene Wiedergabegeschwindigkeit für das aktuelle Video festgelegt. Wenn sich die Wiedergaberate ändert, ändert sie sich nur für das Video, das bereits positioniert ist oder wiedergegeben wird. Wenn du die Wiedergabegeschwindigkeit für ein Video mit Cue festlegst, ist diese Geschwindigkeit weiterhin aktiv, wenn die Funktion playVideo aufgerufen wird oder der Nutzer die Wiedergabe direkt über die Playersteuerung startet. Außerdem wird die Wiedergabegeschwindigkeit auf 1 zurückgesetzt, wenn Funktionen zum Abspielen oder Laden von Videos oder Playlists (cueVideoById, loadVideoById usw.) aufgerufen werden.

Durch den Aufruf dieser Funktion wird nicht garantiert, dass sich die Wiedergabegeschwindigkeit tatsächlich ändert. Wenn sich die Wiedergabegeschwindigkeit jedoch ändert, wird das Ereignis onPlaybackRateChange ausgelöst. Dein Code sollte auf das Ereignis reagieren und nicht darauf, dass die setPlaybackRate-Funktion aufgerufen wurde.

Die Methode getAvailablePlaybackRates gibt die möglichen Wiedergaberaten für das aktuell wiedergegebene Video zurück. Wenn du den Parameter suggestedRate jedoch auf einen nicht unterstützten Ganzzahl- oder Gleitkommawert festlegst, wird der Wert vom Player auf den nächsten unterstützten Wert in Richtung 1 abgerundet.
player.getAvailablePlaybackRates():Array
Diese Funktion gibt die Wiedergaberaten zurück, in denen das aktuelle Video verfügbar ist. Der Standardwert ist 1, was bedeutet, dass das Video mit normaler Geschwindigkeit abgespielt wird.

Die Funktion gibt ein Array mit Zahlen zurück, die von der langsamsten bis zur schnellsten Wiedergabegeschwindigkeit sortiert sind. Auch wenn der Player keine variablen Wiedergabegeschwindigkeiten unterstützt, sollte das Array immer mindestens einen Wert (1) enthalten.

Wiedergabeverhalten für Playlists festlegen

player.setLoop(loopPlaylists:Boolean):Void

Diese Funktion zeigt an, ob der Videoplayer eine Playlist fortlaufend wiedergeben oder die Wiedergabe nach dem letzten Video der Playlist beenden soll. Playlists werden standardmäßig nicht als Schleifen gespielt.

Diese Einstellung bleibt auch dann erhalten, wenn du eine andere Playlist lädst oder anspielst. Wenn du also eine Playlist lädst, die setLoop-Funktion mit dem Wert true aufrufst und dann eine zweite Playlist lädst, wird auch die zweite Playlist in einer Schleife abgespielt.

Der erforderliche Parameter loopPlaylists gibt das Looping-Verhalten an.

  • Wenn der Parameterwert true ist, spielt der Videoplayer Playlists kontinuierlich ab. Nach der Wiedergabe des letzten Videos einer Playlist setzt der Videoplayer die Wiedergabe mit dem ersten Video der Playlist fort.

  • Wenn der Parameterwert false ist, endet die Wiedergabe, nachdem der Videoplayer das letzte Video in einer Playlist abgespielt hat.

player.setShuffle(shufflePlaylist:Boolean):Void

Diese Funktion zeigt an, ob die Videos einer Playlist als Zufallsmix wiedergegeben werden sollen, sodass sie in einer anderen Reihenfolge als der vom Playlist-Ersteller vorgesehenen wiedergegeben werden. Wenn du eine Playlist als Zufallsmix wiedergeben möchtest, nachdem die Wiedergabe bereits gestartet wurde, wird die Reihenfolge der Liste geändert, während die Wiedergabe des aktuellen Videos fortgesetzt wird. Das nächste Video wird dann gemäß der neuen Liste ausgewählt.

Diese Einstellung wird nicht beibehalten, wenn du eine andere Playlist lädst oder abspielst. Wenn du also eine Playlist lädst, die setShuffle-Funktion aufrufst und dann eine zweite Playlist lädst, wird die zweite Playlist nicht zufällig abgespielt.

Der erforderliche Parameter shufflePlaylist gibt an, ob YouTube die Playlist im Zufallsmix abspielen soll.

  • Wenn der Parameterwert true ist, wird die Playlist-Reihenfolge von YouTube zufällig festgelegt. Wenn du die Funktion anweist, eine bereits nach dem Zufallsprinzip gemischte Playlist erneut nach dem Zufallsprinzip zu mischen, erstellt YouTube eine neue Reihenfolge nach dem Zufallsprinzip.

  • Wenn der Parameterwert false ist, ändert YouTube die Playlistreihenfolge wieder in die ursprüngliche Reihenfolge zurück.

Wiedergabestatu

player.getVideoLoadedFraction():Float
Gibt eine Zahl zwischen 0 und 1 zurück, die den Prozentsatz des Videos angibt, der im Player als gepuffert angezeigt wird. Diese Methode liefert eine zuverlässigere Zahl als die inzwischen eingestellten Methoden getVideoBytesLoaded und getVideoBytesTotal.
player.getPlayerState():Number
Gibt den Status des Players zurück. Mögliche Werte sind:
  • -1 – nicht gestartet
  • 0 – beendet
  • 1 – wird wiedergegeben
  • 2 – pausiert
  • 3 – wird gepuffert
  • 5 – Video positioniert
player.getCurrentTime():Number
Gibt die verstrichene Zeit in Sekunden seit Beginn der Videowiedergabe zurück.
player.getVideoStartBytes():Number
Seit dem 31. Oktober 2012 eingestellt. Gibt die Anzahl der Bytes zurück, die die Videodatei bereits geladen hat. (Diese Methode gibt jetzt immer den Wert 0 zurück.) Beispielszenario: Der Nutzer springt zu einem Punkt, der noch nicht geladen wurde, und der Player sendet eine neue Anfrage, um ein Segment des Videos abzuspielen, das noch nicht geladen wurde.
player.getVideoBytesLoaded():Number
Seit dem 18. Juli 2012 eingestellt. Verwenden Sie stattdessen die Methode getVideoLoadedFraction, um den Prozentsatz des Videos zu ermitteln, der zwischengespeichert wurde.

Diese Methode gibt einen Wert zwischen 0 und 1000 zurück, der ungefähr dem Prozentsatz des geladenen Videos entspricht. Du kannst den geladenen Anteil des Videos berechnen, indem du den Wert getVideoBytesLoaded durch den Wert getVideoBytesTotal teilst.
player.getVideoBytesTotal():Number
Seit dem 18. Juli 2012 eingestellt. Verwenden Sie stattdessen die Methode getVideoLoadedFraction, um den Prozentsatz des Videos zu ermitteln, der zwischengespeichert wurde.

Gibt die Größe in Byte des aktuell geladenen/abgespielten Videos oder eine Schätzung der Größe des Videos zurück.

Diese Methode gibt immer den Wert 1000 zurück. Du kannst den geladenen Anteil des Videos berechnen, indem du den Wert getVideoBytesLoaded durch den Wert getVideoBytesTotal teilst.

Videoinformationen abrufen

player.getDuration():Number
Gibt die Dauer des gerade wiedergegebenen Videos in Sekunden zurück. Hinweis: Für getDuration() wird 0 zurückgegeben, bis die Metadaten des Videos geladen sind. Das geschieht normalerweise kurz nach Beginn der Wiedergabe.

Wenn das aktuell wiedergegebene Video ein Liveereignis ist, gibt die Funktion getDuration() die verstrichene Zeit seit Beginn des Livestreams zurück. Genau genommen handelt es sich hierbei um die Zeit, die das Video gestreamt wurde, ohne zurückgesetzt oder unterbrochen zu werden. Außerdem ist diese Zeit in der Regel länger als die tatsächliche Veranstaltung, da das Streaming bereits vor dem Start der Veranstaltung beginnen kann.
player.getVideoUrl():String
Die YouTube.com-URL für das aktuell geladene/abgespielte Video.
player.getVideoEmbedCode():String
Gibt den Einbettungscode für das aktuell geladene/abgespielte Video zurück.

Playlist-Informationen abrufen

player.getPlaylist():Array
Diese Funktion gibt ein Array der Video-IDs in der Playlist in der aktuellen Reihenfolge zurück. Standardmäßig gibt diese Funktion Video-IDs in der Reihenfolge zurück, die vom Playlist-Eigentümer festgelegt wurde. Wenn du jedoch die Funktion setShuffle aufgerufen hast, um die Reihenfolge der Playlist zufällig zu ändern, entspricht der Rückgabewert der Funktion getPlaylist() der Reihenfolge nach Zufallsmix.
player.getPlaylistIndex():Number
Diese Funktion gibt den Index des aktuell wiedergegebenen Playlist-Videos zurück.

  • Wenn du die Playlist nicht als Zufallsmix wiedergibst, gibt der Rückgabewert die Position an, an der der Ersteller der Playlist das Video platziert hat. Der Rückgabewert verwendet einen nullbasierten Index, sodass das erste Video in der Playlist durch den Wert 0 identifiziert wird.

  • Wenn du die Playlist als Zufallsmix wiedergibst, gibt der Rückgabewert die Position des Videos innerhalb der Playlist an, die als Zufallsmix wiedergegeben wird.

Ereignis-Listener hinzufügen oder entfernen

player.addEventListener(event:String, listener:String):Void
Fügt eine Listenerfunktion für die angegebene event hinzu. Im Abschnitt Ereignisse unten werden die verschiedenen Ereignisse aufgeführt, die der Spieler auslösen kann. Beim Listener handelt es sich um einen String, der die Funktion festlegt, die bei Auslösung des angegebenen Ereignisses ausgeführt wird.
player.removeEventListener(event:String, listener:String):Void
Entfernt eine Listenerfunktion für den angegebenen event. listener ist ein String, der die Funktion angibt, die nicht mehr ausgeführt wird, wenn das angegebene Ereignis ausgelöst wird.

DOM-Knoten aufrufen und ändern

player.getIframe():Object
Diese Methode gibt den DOM-Knoten für die eingebettete <iframe> zurück.
player.destroy():Void
Entfernt den <iframe>, der den Spieler enthält.

Ereignisse

Die API löst Ereignisse aus, um deine Anwendung über Änderungen am eingebetteten Player zu informieren. Wie im vorherigen Abschnitt erwähnt, können Sie Ereignisse abonnieren, indem Sie beim Erstellen des YT.Player-Objekts einen Ereignis-Listener hinzufügen. Sie können auch die Funktion addEventListener verwenden.

Die API leitet ein Ereignisobjekt als einzelnes Argument an die jeweiligen Funktionen weiter. Das Ereignisobjekt weist die folgenden Eigenschaften auf:

  • Die target des Ereignisses gibt den Videoplayer an, der dem Ereignis entspricht.
  • Mit dem data des Ereignisses wird ein für das Ereignis relevanter Wert angegeben. Für die Ereignisse onReady und onAutoplayBlocked wird kein data-Attribut angegeben.

In der folgenden Liste werden die Ereignisse definiert, die von der API ausgelöst werden:

onReady
Dieses Ereignis wird ausgelöst, wenn ein Player fertig geladen ist und bereit ist, API-Aufrufe zu empfangen. Diese Funktion sollte in Ihrer Anwendung implementiert sein, wenn Sie bestimmte Vorgänge automatisch ausführen möchten, z. B. das Abspielen des Videos oder das Anzeigen von Informationen zum Video, sobald der Player bereit ist.

Das Beispiel unten zeigt eine Beispielfunktion für die Verarbeitung dieses Ereignisses. Das Ereignisobjekt, das die API an die Funktion weitergibt, hat die Property target, mit der der Player identifiziert wird. Die Funktion ruft den Einbettungscode für das aktuell geladene Video ab, startet die Wiedergabe des Videos und zeigt den Einbettungscode im Seitenelement an, das den id-Wert embed-code hat. 
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
Dieses Ereignis wird ausgelöst, wenn sich der Status des Spielers ändert. Die Eigenschaft data des Ereignisobjekts, das die API an deine Ereignis-Listener-Funktion weitergibt, gibt eine Ganzzahl an, die dem neuen Spielerstatus entspricht. Folgende Werte sind möglich:

  • -1 (nicht gestartet)
  • 0 (beendet)
  • 1 (wird wiedergegeben)
  • 2 (pausiert)
  • 3 (wird gepuffert)
  • 5 (Video positioniert)

Wenn der Player ein Video zum ersten Mal lädt, wird das Ereignis unstarted (-1) gesendet. Wenn ein Video an der richtigen Stelle pausiert ist und abgespielt werden kann, sendet der Player das Ereignis video cued (5). In deinem Code kannst du ganze Zahlen als Werte angeben oder eine der folgenden Namespace-Variablen verwenden:

  • YT.PlayerState.ENDED
  • YT.PlayerState.PLAYING
  • YT.PlayerState.PAUSED
  • YT.PlayerState.BUFFERING
  • YT.PlayerState.CUED

onPlaybackQualityChange
Dieses Ereignis wird ausgelöst, wenn sich die Videowiedergabequalität ändert. Dies kann auf eine Änderung der Wiedergabeumgebung des Betrachters hinweisen. Weitere Informationen zu Faktoren, die sich auf die Wiedergabebedingungen auswirken oder das Ereignis auslösen können, findest du in der YouTube-Hilfe.

Der Attributwert data des Ereignisobjekts, das die API an die Ereignis-Listener-Funktion weitergibt, ist ein String, der die neue Wiedergabequalität angibt. Folgende Werte sind möglich:

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

onPlaybackRateChange
Dieses Ereignis wird ausgelöst, wenn sich die Wiedergabegeschwindigkeit des Videos ändert. Wenn du beispielsweise die Funktion setPlaybackRate(suggestedRate) aufrufst, wird dieses Ereignis ausgelöst, wenn sich die Wiedergabegeschwindigkeit tatsächlich ändert. Deine Anwendung sollte auf das Ereignis reagieren und nicht davon ausgehen, dass sich die Wiedergabegeschwindigkeit automatisch ändert, wenn die Funktion setPlaybackRate(suggestedRate) aufgerufen wird. Ebenso sollte in deinem Code nicht davon ausgegangen werden, dass sich die Wiedergabegeschwindigkeit des Videos nur durch einen expliziten Aufruf von setPlaybackRate ändert.

Der Wert der Eigenschaft data des Ereignisobjekts, das die API an die Ereignis-Listener-Funktion übergibt, ist eine Zahl, die die neue Wiedergabegeschwindigkeit angibt. Die getAvailablePlaybackRates-Methode gibt eine Liste der gültigen Wiedergaberaten für das derzeit cued oder wiedergegebene Video zurück.
onError
Dieses Ereignis wird ausgelöst, wenn im Player ein Fehler auftritt. Die API übergibt der Funktion „event listener“ ein event-Objekt. Die data-Eigenschaft dieses Objekts gibt eine Ganzzahl an, die den aufgetretenen Fehlertyp identifiziert. Folgende Werte sind möglich:

  • 2 – Die Anfrage enthält einen ungültigen Parameterwert. Dieser Fehler tritt beispielsweise auf, wenn du eine Video-ID angibst, die nicht aus elf Zeichen besteht, oder wenn die Video-ID ungültige Zeichen wie z. B. Ausrufezeichen oder Sternchen enthält.
  • 5 – Der angeforderte Inhalt kann nicht mit einem HTML5-Player wiedergegeben werden oder es ist ein anderer Fehler im Zusammenhang mit dem HTML5-Player aufgetreten.
  • 100 – Der angeforderte Video wurde nicht gefunden. Dieser Fehler tritt auf, wenn ein Video aus irgendeinem Grund entfernt oder als privat markiert wurde.
  • 101 – Der Rechteinhaber des angeforderten Videos untersagt die Wiedergabe des Videos in eingebetteten Playern.
  • 150 – Dieser Fehler ist mit 101 identisch. Es ist nur ein getarnter 101-Fehler.
onApiChange
Dieses Ereignis wird ausgelöst, um anzugeben, dass der Player ein Modul mit freigegebenen API-Methoden geladen (oder entladen) hat. Deine Anwendung kann dieses Ereignis erkennen und anschließend den Player abfragen, um festzustellen, welche Optionen für das kürzlich geladene Modul zur Verfügung stehen. Danach kann deine Anwendung die für diese Optionen vorhandenen Einstellungen abrufen oder aktualisieren.

Mit dem folgenden Befehl wird ein Array mit Modulnamen abgerufen, für die du Playeroptionen festlegen kannst:
player.getOptions();
 Derzeit kannst du nur Optionen für das captions-Modul festlegen, das Untertitel im Player verarbeitet. Wenn deine Anwendung ein onApiChange-Ereignis empfängt, kann sie mit dem folgenden Befehl ermitteln, welche Optionen für das captions-Modul festgelegt werden können:
player.getOptions('captions');
 Wenn du den Player mit diesem Befehl abfragst, kannst du prüfen, ob du auf die gewünschten Optionen zugreifen kannst. Mit den folgenden Befehlen können Sie Moduloptionen abrufen und aktualisieren:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
 In der folgenden Tabelle sind die von der API unterstützten Optionen aufgeführt:

Modul Option Beschreibung
captions fontSize Mit dieser Option wird die Schriftgröße der Untertitel angepasst, die im Player angezeigt werden.

Gültige Werte sind -1, 0, 1, 2 und 3. Die Standardgröße ist 0 und die kleinste Größe ist -1. Wenn du diese Option auf eine Ganzzahl unter -1 festlegst, wird die kleinste Untertitelgröße angezeigt. Wenn du sie auf eine Ganzzahl über 3 festlegst, wird die größte Untertitelgröße angezeigt.
captions Neu laden Diese Option lädt die Untertiteldaten für das wiedergegebene Video erneut. Wenn Sie den Wert der Option abrufen, wird null zurückgegeben. Lege den Wert auf true fest, um die Untertiteldaten neu zu laden.
onAutoplayBlocked
Dieses Ereignis wird jedes Mal ausgelöst, wenn der Browser die automatische Wiedergabe oder die Wiedergabe von Videos mit Script blockiert, was zusammen als „automatische Wiedergabe“ bezeichnet wird. Dazu gehört auch die Wiedergabe, die mit einer der folgenden Player-APIs versucht wird:

Die meisten Browser haben Richtlinien, die Autoplay auf Computern, Mobilgeräten und anderen Plattformen blockieren können, wenn bestimmte Bedingungen erfüllt sind. Beispiele für Fälle, in denen diese Richtlinie ausgelöst werden kann, sind die Wiedergabe ohne Stummschaltung ohne Nutzerinteraktion oder wenn keine Berechtigungsrichtlinie zum Zulassen der automatischen Wiedergabe in einem iframe mit unterschiedlichen Ursprüngen festgelegt wurde.

Weitere Informationen finden Sie in den browserspezifischen Richtlinien (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) und im Autoplay-Leitfaden von Mozilla.

Beispiele

YT.Player-Objekte erstellen

  • Beispiel 1: API mit vorhandenem <iframe> verwenden

    In diesem Beispiel wird der Player, mit dem die API verwendet wird, bereits in einem <iframe>-Element auf der Seite definiert. Beachte, dass entweder der Parameter enablejsapi in der src-URL des Players auf 1 gesetzt sein muss oder das Attribut enablejsapi des Elements <iframe> auf true.

    Mit der Funktion onPlayerReady wird die Farbe des Rahmens um den Spieler herum in Orange geändert, wenn er bereit ist. Die Funktion onPlayerStateChange ändert dann die Farbe des Rahmens um den Spieler herum basierend auf dem aktuellen Spielerstatus. Die Farbe ist beispielsweise grün, wenn der Player wiedergegeben wird, rot, wenn er pausiert ist, blau, wenn er puffert, usw.

    In diesem Beispiel wird der folgende Code verwendet:

    <iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
        frameborder="0"
        style="border: solid 4px #37474F"
></iframe>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

  • Beispiel 2: Laute Wiedergabe

    In diesem Beispiel wird ein Videoplayer mit einer Größe von 1280 x 720 Pixel erstellt. Der Ereignis-Listener für das Ereignis onReady ruft dann die Funktion setVolume auf, um die Lautstärke auf die höchste Einstellung zu stellen.

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

  • Beispiel 3 : In diesem Beispiel werden die Playerparameter so festgelegt, dass das Video beim Laden automatisch wiedergegeben und die Steuerelemente des Videoplayers ausgeblendet werden. Außerdem werden Ereignis-Listener für mehrere Ereignisse hinzugefügt, die von der API gesendet werden.

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

360°-Videos steuern

In diesem Beispiel wird der folgende Code verwendet:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Einbindung der Media Integrity API in Android WebView

YouTube hat die Android WebView Media Integrity API erweitert, damit eingebettete Mediaplayer, einschließlich eingebetteter YouTube-Player in Android-Anwendungen, die Authentizität der einbettenden App überprüfen können. Durch diese Änderung senden eingebettete Apps automatisch eine bestätigte App-ID an YouTube. Die Daten, die über diese API erhoben werden, sind die App-Metadaten (Paketname, Versionsnummer und Signaturzertifikat) und ein Geräteattestierungstoken, das von Google Play-Diensten generiert wird.

Die Daten werden verwendet, um die Integrität der Anwendung und des Geräts zu prüfen. Die Daten werden verschlüsselt, nicht an Dritte weitergegeben und nach einer festgelegten Aufbewahrungsdauer gelöscht. App-Entwickler können ihre App-Identität in der WebView Media Integrity API konfigurieren. Die Konfiguration unterstützt eine Opt-out-Option.

Überarbeitungsverlauf

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.