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. Im Unterschied zu den Player-APIs von Flash und JavaScript, bei denen ein Flash-Objekt auf deiner Seite eingebettet wird, veröffentlicht die Iframe API Inhalte in einem <iframe>-Tag auf deiner Seite. Auf diese Weise wird im Vergleich zu älteren verfügbaren APIs eine größere Flexibilität erreicht, so dass YouTube für Mobilgeräte, die Flash nicht unterstützen, statt eines Flash-Players einen HTML5-Player anbieten kann.

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. bei einer Änderung des Player-Status oder der Wiedergabequalität des Videos.

In dieser Anleitung werden die Verwendung der Iframe-API erklärt und die verschiedenen Ereignistypen aufgeführt, die diese API versenden kann. Außerdem erfährst du, wie Ereignis-Listener als Reaktion auf solche Ereignisse geschrieben werden. 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.

Anforderungen

Der Endnutzer muss einen Browser verwenden, der die HTML5-postMessage-Funktion unterstützt. Abgesehen von Internet Explorer 7 wird postMessage von den meisten aktuellen 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 die Seite das Herunterladen von JavaScript für die Player-API abgeschlossen hat. 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: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          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.

Das <div>-Tag in diesem Abschnitt gibt die Stelle auf der Seite an, an der die Iframe API den Videoplayer platziert. Der Konstruktor für das Player-Objekt, das im Abschnitt Videoplayer laden beschrieben wird, identifiziert das <div>-Tag anhand des id-Werts, um sicherzustellen, dass die API <iframe> an der richtigen Stelle platziert. Genauer gesagt ersetzt die Iframe API das <div>-Tag durch das <iframe>-Tag.

Alternativ kannst du das <iframe>-Element auch direkt auf der Seite platzieren. Wie das funktioniert, wird im Abschnitt Videoplayer laden beschrieben.
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 zudem asynchrone Downloads ermöglicht, wird noch nicht von allen modernen Browsern unterstützt, wie dieser Stack Overflow-Antwort zu entnehmen ist.
Die onYouTubeIframeAPIReady-Funktion wird ausgeführt, sobald der Player-API-Code heruntergeladen wird. Dieser Teil des Codes definiert die globale Variable player, die auf den von dir eingebetteten Videoplayer verweist. Anschließend erstellt die Funktion das Videoplayer-Objekt.
Die onPlayerReady-Funktion wird bei Auslösung des onReady-Ereignisses ausgeführt. In diesem Beispiel zeigt die Funktion an, dass die Wiedergabe beginnen sollte, wenn der Videoplayer bereit ist.
Die API ruft die onPlayerStateChange-Funktion auf, wenn sich der Status des Players ändert. Dies kann bedeuten, dass der Player ein Video wiedergibt bzw. die Wiedergabe eines Videos abgeschlossen hat, pausiert wird oder Ähnliches. Die Funktion zeigt an, dass der Player das Video sechs Sekunden lang wiedergeben und anschließend die stopVideo-Funktion aufrufen soll, um das Video anzuhalten, wenn sich der Player im Status 1 (wird wiedergegeben) befindet.

Videoplayer laden

Nach dem Laden des JavaScript-Codes der API ruft die API die onYouTubeIframeAPIReady-Funktion auf. Du hast nun die Möglichkeit, ein YT.Player-Objekt zu erstellen und deiner Seite einen Videoplayer hinzuzufügen. Der folgende HTML-Ausschnitt zeigt die onYouTubeIframeAPIReady-Funktion aus dem obigen Beispiel:

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

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

Der erste Parameter gibt entweder das DOM-Element oder den id-Wert des HTML-Elements an, in dem die API das <iframe>-Tag hinzufügt, das den Player enthält.

Die Iframe API ersetzt das angegebene Element durch das <iframe>-Element, das den Player enthält. Hierdurch könnte das Layout deiner Seite beeinflusst werden, wenn das ersetzte Element über einen anderen Anzeigestil verfügt als das eingefügte <iframe>-Element. Standardmäßig wird <iframe> als inline-block-Element angezeigt.
Beim zweiten Parameter handelt es sich um ein Objekt, das Player-Optionen angibt. Das Objekt weist die folgenden Eigenschaften auf:
- width (Zahl) – die Breite des Videoplayers. Der Standardwert ist 640.
- height (Zahl) – die Höhe des Videoplayers. Der Standardwert ist 360.
- videoId (String) – die YouTube-Video-ID, die das Video identifiziert, das der Player laden wird
- playerVars (Objekt) – Die Eigenschaften des Objekts geben Player-Parameter an, die für die Anpassung des Players verwendet werden können.
- events (Objekt) – Die Eigenschaften des Objekts geben die Ereignisse an, die von der API ausgelöst werden, und die Funktionen (Ereignis-Listener), die von der API beim Eintreten dieser Ereignisse aufgerufen werden. Im Beispiel zeigt der Konstruktor an, dass bei Auslösung des onReady-Ereignisses die onPlayerReady-Funktion ausgeführt wird, und bei Auslösung des onStateChange-Ereignisses die onPlayerStateChange-Funktion.

Wie bereits im Abschnitt Erste Schritte erwähnt, könntest du ein eigenes <iframe>-Tag erstellen, statt ein leeres <div>-Element auf deine Seite zu schreiben, das anschließend vom JavaScript-Code der Player-API durch ein <iframe>-Element ersetzt wird.

<iframe id="player" type="text/html" width="640" height="360"
  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 weder Werte für width und height angeben, die als Attribute des <iframe>-Tags angegeben werden, noch videoId und Player-Parameter, die in der src-URL angegeben werden. Als zusätzliche Sicherheitsmaßnahme solltest du zudem der URL den origin-Parameter hinzufügen, der das URL-Schema (http:// oder https://) und die vollständige Domain deiner Hostseite als Parameterwert angibt. Die Verwendung von origin ist zwar optional, schützt das Element jedoch vor schädlichem JavaScript-Code von Drittanbietern, der auf deiner Seite implementiert werden und die Steuerung deines YouTube-Players übernehmen könnte.

Im Abschnitt Beispiele findest du weitere Beispiele für die Erstellung von Videoplayer-Objekten.

Optionen

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

Funktionen

Wiedergabelisten-Funktionen

Mit Wiedergabelisten-Funktionen kannst du Videos, Playlists sowie andere Videolisten laden und wiedergeben. Wenn du zum Aufrufen dieser Funktionen die unten beschriebene Objektsyntax verwendest, kannst du auch eine Liste mit Suchergebnissen oder eine Nutzerliste hochgeladener Videos laden oder in eine Wiedergabeliste aufnehmen.

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 beiden folgenden Weisen aufgerufen werden. Beachte, dass die Objektsyntax die endSeconds-Eigenschaft unterstützt, die Argumentsyntax hingegen nicht.

Argumentsyntax

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

Objektsyntax

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

Wiedergabelisten-Funktionen für Videos

cueVideoById

Argumentsyntax

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

Objektsyntax

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

Diese Funktion lädt das Thumbnail des angegebenen Videos und bereitet den Player auf die Wiedergabe des Videos vor. Die FLV-Datei wird vom Player erst angefordert, wenn playVideo() oder seekTo() aufgerufen wird.

Der erforderliche videoId-Parameter gibt die YouTube-Video-ID des Videos an, das wiedergegeben werden soll. In den Videofeeds der YouTube Data API wird die ID durch das Tag <yt:videoid> angegeben.
Der optionale startSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des Videos gestartet werden soll, wenn playVideo() aufgerufen wird. Wenn du einen startSeconds-Wert angibst und anschließend seekTo() aufrufst, beginnt der Player die Wiedergabe bei dem im Aufruf seekTo() angegebenen Zeitpunkt. Wenn das Video positioniert und bereit für die Wiedergabe ist, sendet der Player ein video cued-Ereignis (5).
Der optionale endSeconds-Parameter, der nur in der Objektsyntax unterstützt wird, akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, zu dem die Wiedergabe des Videos gestoppt werden soll, wenn playVideo() aufgerufen wird. Wenn du einen endSeconds-Wert angibst und anschließend seekTo() aufrufst, wird der endSeconds-Wert ignoriert.
Der optionale suggestedQuality-Parameter gibt die empfohlene Wiedergabequalität für das Video an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.

loadVideoById

Argument syntax

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

Object syntax

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

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

Der erforderliche videoId-Parameter gibt die YouTube-Video-ID des Videos an, das wiedergegeben werden soll. In den Videofeeds der YouTube Data API wird die ID durch das Tag <yt:videoid> angegeben.
Der optionale startSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl. Wird sie angegeben, beginnt das Video mit dem Keyframe, der dem angegebenen Zeitpunkt am nächsten ist.
Der optionale endSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl. Wird sie angegeben, wird die Wiedergabe des Videos zum angegebenen Zeitpunkt beendet.
Der optionale suggestedQuality-Parameter gibt die vorgeschlagene Wiedergabequalität für das Video an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.

cueVideoByUrl

Argument syntax

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

Object syntax

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

Der erforderliche mediaContentUrl-Parameter gibt eine vollqualifizierte YouTube-Player-URL im Format http://www.youtube.com/v/VIDEO_ID?version=3 an. In YouTube Data API-Videofeeds enthält das url-Attribut des Tags <media:content> eine vollqualifizierte Player-URL, wenn das format-Attribut des Tags den Wert 5 aufweist.
Der optionale startSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des Videos gestartet werden soll, wenn playVideo() aufgerufen wird. Wenn du startSeconds angibst und anschließend seekTo() aufrufst, beginnt der Player die Wiedergabe bei dem Zeitpunkt, der im Aufruf seekTo() angegeben wurde. Wenn das Video positioniert und bereit für die Wiedergabe ist, überträgt der Player ein video cued-Ereignis (5).
Der optionale endSeconds-Parameter, der nur in Objektsyntax unterstützt wird, akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, zu dem das Video beendet werden soll, wenn playVideo() aufgerufen wird. Wenn du einen endSeconds-Wert angibst und anschließend seekTo() aufrufst, wird der endSeconds-Wert ignoriert.
Der optionale suggestedQuality-Parameter gibt die vorgeschlagene Wiedergabequalität für das Video an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.

loadVideoByUrl

Argument syntax

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

Object syntax

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

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

Der erforderliche mediaContentUrl-Parameter gibt eine vollqualifizierte YouTube-Player-URL im Format http://www.youtube.com/v/VIDEO_ID?version=3 an. In YouTube Data API-Videofeeds enthält das url-Attribut des Tags <media:content> eine vollqualifizierte Player-URL, wenn das format-Attribut des Tags den Wert 5 aufweist.
Der optionale startSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des Videos beginnen soll. Wird startSeconds angegeben, wobei die Zahl eine Gleitkommazahl sein kann, beginnt das Video mit dem Keyframe, der dem angegebenen Zeitpunkt am nächsten ist.
Der optionale endSeconds-Parameter, der nur in Objektsyntax unterstützt wird, akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, zu dem die Wiedergabe des Videos beendet werden soll.
Der optionale suggestedQuality-Parameter gibt die vorgeschlagene Wiedergabequalität für das Video an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.

Wiedergabelisten-Funktionen für Listen

Mit den Funktionen cuePlaylist und loadPlaylist kannst du deine Playlist oder Videoliste laden und wiedergeben. Wenn du zum Aufrufen dieser Funktionen die Objektsyntax verwendest, kannst du zudem eine Liste der Suchergebnisse oder eine Nutzerliste hochgeladener Videos einer Wiedergabeliste hinzufügen 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

Argument syntax
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number,
                   suggestedQuality:String):Void
```
Fügt die angegebene Playlist der Wiedergabeliste hinzu. Wenn die Playlist positioniert und bereit für die Wiedergabe ist, sendet der Player ein video cued-Ereignis (5).
- Der erforderliche playlist-Parameter gibt ein Array der YouTube-Video-IDs an. In YouTube Data API-Feeds gibt das Tag <yt:videoid> eine Video-ID an.
- Der optionale index-Parameter gibt den Index des ersten Videos der Playlist an, das wiedergegeben wird. Der Parameter verwendet einen nullbasierten Index und der Standardparameterwert lautet 0. Standardmäßig wird also das erste Video der Playlist geladen und wiedergegeben.
- Der optionale startSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des ersten Videos der Playlist beginnen soll, wenn die Funktion playVideo() aufgerufen wird. Wenn du einen startSeconds-Wert angibst und anschließend seekTo() aufrufst, beginnt der Player die Wiedergabe bei dem im Aufruf seekTo() angegebenen Zeitpunkt. Wenn du eine Playlist positionierst und anschließend die Funktion playVideoAt() aufrufst, beginnt der Player die Wiedergabe am Anfang des angegebenen Videos.
- Der optionale suggestedQuality-Parameter gibt die vorgeschlagene Wiedergabequalität für das Video an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.
Objektsyntax
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String}):Void
```
Fügt die angegebene Videoliste der Wiedergabeliste hinzu. Bei dieser Liste kann es sich um eine Playlist, einen Suchergebnis-Feed oder einen Feed zu einer Nutzerliste mit hochgeladenen Videos handeln. Wenn die Liste positioniert und bereit für die Wiedergabe ist, sendet der Player ein video cued-Ereignis (5).
- Die optionale listType-Eigenschaft gibt den Ergebnistyp-Feed an, den du abrufst. Gültige Werte sind playlist, search und user_uploads. Der Standardwert ist playlist.
- Die erforderliche list-Eigenschaft enthält einen Schlüssel zum Angeben der spezifischen Videoliste, die von YouTube zurückgegeben werden soll.
  - Wenn der listType-Eigenschaftswert playlist lautet, gibt die list-Eigenschaft die Playlist-ID oder ein Array von Video-IDs an. In YouTube Data API-Feeds gibt das Tag <yt:playlistid> eine Playlist-ID und das Tag <yt:videoid> eine Video-ID an.
  - Wenn der listType-Eigenschaftswert search lautet, gibt die list-Eigenschaft die Suchanfrage an.
  - Wenn der listType-Eigenschaftswert user_uploads lautet, gibt die list-Eigenschaft den Nutzer an, dessen hochgeladene Videos zurückgegeben werden.
- Die optionale index-Eigenschaft gibt den Index des ersten Videos in der Liste an, das wiedergegeben wird. Der Parameter verwendet einen nullbasierten Index und der Standardparameterwert lautet 0. Standardmäßig wird also das erste Video der Liste geladen und wiedergegeben.
- Die optionale startSeconds-Eigenschaft akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des ersten Videos der Liste beginnen soll, wenn die Funktion playVideo() aufgerufen wird. Wenn du einen startSeconds-Wert angibst und anschließend seekTo() aufrufst, beginnt der Player die Wiedergabe bei dem im Aufruf seekTo() angegebenen Zeitpunkt. Wenn du eine Liste positionierst und anschließend die Funktion playVideoAt() aufrufst, beginnt der Player die Wiedergabe am Anfang des angegebenen Videos.
- Die optionale suggestedQuality-Eigenschaft gibt die empfohlene Wiedergabequalität für die Videoliste an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.

loadPlaylist

Argument syntax
```
player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number,
                    suggestedQuality:String):Void
```
Diese Funktion lädt die angegebene Playlist und gibt sie wieder.
- Der erforderliche playlist-Parameter gibt ein Array der YouTube-Video-IDs an. In YouTube Data API-Feeds gibt das Tag <yt:videoid> eine Video-ID an.
- Der optionale index-Parameter gibt den Index des ersten Videos der Playlist an, das wiedergegeben wird. Der Parameter verwendet einen nullbasierten Index und der Standardparameterwert lautet 0. Standardmäßig wird also das erste Video der Playlist geladen und wiedergegeben.
- Der optionale startSeconds-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des ersten Videos der Playlist beginnen soll.
- Der optionale suggestedQuality-Parameter gibt die vorgeschlagene Wiedergabequalität für das Video an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.
Object syntax
```
player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number,
                     suggestedQuality:String}):Void
```
Diese Funktion lädt die angegebene Liste und gibt sie wieder. Bei dieser Liste kann es sich um eine Playlist, einen Suchergebnis-Feed oder einen Feed zu einer Nutzerliste mit hochgeladenen Videos handeln.
- Die optionale listType-Eigenschaft gibt den Suchergebnis-Feed an, den du abrufst. Gültige Werte sind playlist, search und user_uploads. Der Standardwert ist playlist.
- Die erforderliche list-Eigenschaft enthält einen Schlüssel, der die spezifische Videoliste angibt, die YouTube zurückgeben soll.
  - Wenn der listType-Eigenschaftswert playlist lautet, gibt die list-Eigenschaft eine Playlist-ID oder ein Array von Video-IDs an. In YouTube Data API-Feeds gibt das Tag <yt:playlistid> eine Playlist-ID und das Tag <yt:videoid> eine Video-ID an.
  - Wenn der listType-Eigenschaftswert search lautet, gibt die list-Eigenschaft die Suchanfrage an.
  - Wenn der listType-Eigenschaftswert user_uploads lautet, gibt die list-Eigenschaft den Nutzer an, dessen hochgeladene Videos zurückgegeben werden.
- Die optionale index-Eigenschaft gibt den Index des ersten Videos in der Liste an, das wiedergegeben wird. Der Parameter verwendet einen nullbasierten Index und der Standardparameterwert lautet 0. Standardmäßig wird also das erste Video der Liste geladen und wiedergegeben.
- Die optionale startSeconds-Eigenschaft akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem das erste Video der Liste wiedergegeben werden soll.
- Die optionale suggestedQuality-Eigenschaft gibt die empfohlene Wiedergabequalität für die Videoliste an. Weitere Informationen zur Wiedergabequalität findest du in der Definition der Funktion setPlaybackQuality.

Wiedergabesteuerung und Player-Einstellungen

Video wiedergeben

player.playVideo():Void: Gibt das derzeit positionierte/geladene Video wieder. Der letzte Player-Status nach der Ausführung dieser Funktion ist playing (1).

Hinweis: Eine Wiedergabe wird nur dann als offizieller Videoaufruf gezählt, wenn sie über eine eigene Wiedergabeschaltfläche des Players ausgelöst wird.

player.pauseVideo():Void: Pausiert das derzeit wiedergegebene Video. Der letzte Player-Status nach der Ausführung dieser Funktion ist paused (2). Dies gilt nicht, wenn sich der Player beim Abrufen der Funktion im Status ended (0) befindet. In diesem Fall ändert sich der Status des Players nicht.

player.stopVideo():Void: Stoppt das Laden des aktuellen Videos und bricht den Vorgang 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 der Player wiedergibt, kannst du direkt eine der Wiedergabelisten-Funktionen aufrufen, ohne zunächst stopVideo aufzurufen.

Wichtig: Im Unterschied zur Funktion pauseVideo, bei der der Player den Status paused (2) beibehält, könnte die stopVideo-Funktion den Player in einen Status ohne Wiedergabe versetzen, darunter ended (0), paused (2), video cued (5) oder unstarted (-1).

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

Sucht im Video nach einem bestimmten Zeitpunkt. Wenn der Player beim Aufrufen der Funktion pausiert, pausiert er weiter. Wird die Funktion bei einem anderen Status wie z. B. playing oder video cued aufgerufen, gibt der Player das Video wieder.

Der seconds-Parameter gibt den Zeitpunkt an, zu dem der Player springen 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. In diesem Fall springt der Player gemäß der seek()-Methode des NetStream-Objekts des Flash-Players zum nächsten Keyframe vor oder nach dem festgelegten Zeitpunkt. Weitere Informationen findest du in der Dokumentation von Adobe.
Der allowSeekAhead-Parameter bestimmt, ob der Player eine neue Anfrage an den Server sendet, wenn der seconds-Parameter einen Zeitpunkt angibt, der außerhalb der derzeit gepufferten Videodaten liegt.

Wir empfehlen, dass du diesen Parameter auf false setzt, wenn der Nutzer die Maus eine Videofortschrittsleiste entlangzieht, und ihn anschließend auf true setzt, wenn der Nutzer die Maus wieder 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.

player.clearVideo():Void: Löscht die Videoanzeige. Diese Funktion ist nützlich, wenn du nach dem Aufrufen von stopVideo() den Rest des Videos löschen möchtest. Diese Funktion wird seit der ActionScript 3.0 Player API nicht mehr unterstützt.

Video in einer Playlist wiedergeben

player.nextVideo():Void

Diese Funktion lädt das nächste Video der Playlist und gibt es wieder.

Wenn während der Wiedergabe des letzten Videos der Playlist player.nextVideo() aufgerufen wird und die Playlist auf fortlaufende Wiedergabe (loop) eingestellt ist, lädt der Player das erste Video der Liste und spielt es ab.
Wenn während der Wiedergabe des letzten Videos der Playlist player.nextVideo() aufgerufen wird und die Playlist nicht auf fortlaufende Wiedergabe eingestellt ist, wird die Wiedergabe beendet.

player.previousVideo():Void

Diese Funktion lädt das vorherige Video der Playlist und gibt es wieder.

Wenn player.previousVideo() während der Wiedergabe des ersten Videos der Playlist aufgerufen wird und die Playlist auf fortlaufende Wiedergabe (loop) eingestellt ist, lädt der Player das letzte Video der Liste und gibt es wieder.
Wenn während der Wiedergabe des ersten Videos der Playlist player.previousVideo() aufgerufen wird und die Playlist nicht auf fortlaufende Wiedergabe eingestellt ist, startet der Player das erste Video der Playlist noch einmal von vorn.

player.playVideoAt(index:Number):Void

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

Der erforderliche index-Parameter gibt den Index des Videos an, das du in der Playlist wiedergeben möchtest. Der Parameter verwendet einen nullbasierten Index, sodass das erste Video der Liste durch den Wert 0 identifiziert wird. Wenn du die Playlist als Zufallsmix wiedergibst, gibt diese Funktion das Video an der angegebenen Position des Zufallsmix wieder.

Player-Lautstärke ändern

player.mute():Void: Schaltet den Player stumm

player.unMute():Void: Hebt die Stummschaltung des Players auf

player.isMuted():Boolean: Gibt true zurück, wenn der Player stummgeschaltet wurde, und false, wenn nicht

player.setVolume(volume:Number):Void: Stellt die Lautstärke ein. Akzeptiert eine ganze Zahl zwischen 0 und 100

player.getVolume():Number: Gibt die aktuelle Lautstärke des Players wieder, eine ganze Zahl zwischen 0 und 100. getVolume() gibt die Lautstärke selbst dann zurück, wenn der Player stummgeschaltet ist.

Player-Größe festlegen

player.setSize(width:Number, height:Number):Object: Legt die Größe von <iframe> als maximale Größe des Players in Pixeln fest

Wiedergaberate festlegen

player.getPlaybackRate():Number: Diese Funktion ruft die Wiedergaberate des derzeit wiedergegebenen Videos ab. Die Standardwiedergaberate beträgt 1, wodurch angezeigt wird, dass das Video mit einer normalen Geschwindigkeit wiedergegeben wird. Wiedergaberaten können Werte wie 0.25, 0.5, 1, 1.5 und 2 aufweisen.

player.setPlaybackRate(suggestedRate:Number):Void: Diese Funktion stellt die empfohlene Wiedergaberate für das aktuelle Video ein. Wenn sich die Wiedergaberate ändert, ändert sie sich nur für das Video, das bereits positioniert ist oder wiedergegeben wird. Wenn du die Wiedergaberate für ein positioniertes Video festlegst, ist diese Rate auch dann aktiv, wenn die playVideo-Funktion aufgerufen wird oder der Nutzer die Wiedergabe direkt über die Steuerung des Players beginnt. Außerdem wird durch das Aufrufen von Funktionen zum Positionieren oder Laden von Videos oder Playlists (z. B. cueVideoById, loadVideoById) die Wiedergaberate auf 1 zurückgesetzt.

Durch das Aufrufen dieser Funktion wird nicht gewährleistet, dass sich die Wiedergaberate tatsächlich ändert. Sollte sich die Wiedergaberate allerdings ändern, wird das Ereignis onPlaybackRateChange ausgelöst und dein Code sollte auf das Ereignis und nicht auf die Tatsache reagieren, dass die setPlaybackRate-Funktion aufgerufen wurde.

Die Methode getAvailablePlaybackRates gibt die möglichen Wiedergaberaten für das derzeit wiedergegebene Video zurück. Wenn du den suggestedRate-Parameter jedoch auf eine nicht unterstützte ganze Zahl oder Gleitkommazahl setzt, rundet der Player diesen Wert auf den nächsten unterstützten Wert in Richtung 1 ab.

player.getAvailablePlaybackRates():Array: Diese Funktion gibt die Wiedergaberaten zurück, die für das aktuelle Video verfügbar sind. Der Standardwert lautet 1 und zeigt an, dass das Video in normaler Geschwindigkeit wiedergegeben wird.

Die Funktion gibt ein Array von Zahlen zurück, die nach ansteigender Wiedergabegeschwindigkeit sortiert sind. Selbst wenn der Player keine variablen Wiedergabegeschwindigkeiten unterstützt, sollte das Array der Zahlen mindestens einen Wert enthalten (1).

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 aktiv, wenn du eine andere Playlist lädst oder positionierst. Wenn du also eine Playlist lädst, die setLoop-Funktion mit dem Wert true aufrufst und anschließend eine zweite Playlist lädst, wird auch die zweite Playlist als Schleife gespielt.

Der erforderliche loopPlaylists-Parameter gibt das Schleifenverhalten an.

Wenn der Parameterwert true lautet, gibt der Videoplayer Playlists fortlaufend wieder. Nach der Wiedergabe des letzten Videos einer Playlist setzt der Videoplayer die Wiedergabe mit dem ersten Video der Playlist fort.
Wenn der Parameterwert false lautet, werden Wiedergaben beendet, nachdem der Videoplayer das letzte Video einer Playlist wiedergegeben 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 positionierst. Wenn du also eine Playlist lädst, die setShuffle-Funktion aufrufst und anschließend eine zweite Playlist lädst, wird die zweite Playlist nicht als Zufallsmix wiedergegeben.

Der erforderliche shufflePlaylist-Parameter gibt an, ob YouTube die Playlist als Zufallsmix wiedergeben soll.

Wenn der Parameterwert true lautet, erstellt YouTube die Reihenfolge der Playlist nach dem Zufallsprinzip. 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 lautet, stellt YouTube die ursprüngliche Playlist-Reihenfolge wieder her.

Wiedergabestatus

player.getVideoLoadedFraction():Float: Gibt eine Zahl zwischen 0 und 1 zurück, die den prozentualen Anteil des Videos angibt, den der Player als gepuffert anzeigt. Diese Methode gibt eine zuverlässigere Zahl zurück als die mittlerweile veralteten Methoden getVideoBytesLoaded und getVideoBytesTotal.

player.getPlayerState():Number

Gibt den Status des Players zurück. Mögliche Werte sind folgende:

-1 – nicht gestartet
0 – beendet
1 – wird wiedergegeben
2 – pausiert
3 – wird gepuffert
5 – Video positioniert

player.getCurrentTime():Number: Gibt die seit dem Beginn der Wiedergabe des Videos vergangene Zeit in Sekunden an

player.getVideoStartBytes():Number: Wird seit dem 31. Oktober 2012 nicht mehr unterstützt. Gibt die Anzahl der Bytes zurück, die die Videodatei bereits geladen hat. Diese Methode gibt nun immer den Wert 0 zurück. Beispielszenario: Der Nutzer springt zu einer Stelle des Videos, die noch nicht geladen wurde, und der Player erstellt eine neue Anfrage für die Wiedergabe eines Videosegments, das noch nicht geladen wurde.

player.getVideoBytesLoaded():Number: Wird seit dem 18. Juli 2012 nicht mehr unterstützt. Verwende stattdessen die Methode getVideoLoadedFraction, um den prozentualen Anteil des Videos zu bestimmen, der bereits gepuffert wurde.

Diese Methode gibt einen Wert zwischen 0 und 1000 zurück, der den Teil des Videos schätzt, der bereits geladen wurde. Du könntest den bereits geladenen Teil des Videos berechnen, indem du den getVideoBytesLoaded-Wert durch den getVideoBytesTotal-Wert teilst.

player.getVideoBytesTotal():Number: Wird seit dem 18. Juli 2012 nicht mehr unterstützt. Verwende stattdessen die Methode getVideoLoadedFraction, um den prozentualen Anteil des Videos zu bestimmen, der bereits gepuffert wurde.

Gibt die Größe des derzeit geladenen/wiedergegebenen Videos in Bytes oder eine Schätzung der Größe des Videos zurück

Diese Methode gibt immer einen Wert von 1000 zurück. Du könntest den bereits geladenen Teil des Videos berechnen, indem du den getVideoBytesLoaded-Wert durch den getVideoBytesTotal-Wert teilst.

Wiedergabequalität

player.getPlaybackQuality():String: Diese Funktion ruft die tatsächliche Videoqualität des aktuellen Videos ab. Mögliche Rückgabewerte sind highres, hd1080, hd720, large, medium und small. Es wird auch undefined zurückgegeben, wenn kein aktuelles Video vorhanden ist.

player.setPlaybackQuality(suggestedQuality:String):Void

Diese Funktion legt die empfohlene Videoqualität für das aktuelle Video fest. Sie bewirkt, dass das Video an der aktuellen Position mit der neuen Qualität erneut geladen wird. Wenn sich die Wiedergabequalität ändert, ändert sie sich nur für das gerade wiedergegebene Video. Durch das Aufrufen dieser Funktion wird nicht gewährleistet, dass sich die Wiedergabequalität tatsächlich ändert. Sollte sich die Wiedergabequalität allerdings ändern, wird das Ereignis onPlaybackQualityChange ausgelöst und dein Code sollte auf das Ereignis und nicht auf die Tatsache reagieren, dass die setPlaybackQuality-Funktion aufgerufen wurde.

Der suggestedQuality-Parameterwert kann small, medium, large, hd720, hd1080, highres oder default lauten. Wir empfehlen, dass du den Parameterwert auf default setzt. Hierdurch wird YouTube angewiesen, die am besten geeignete Wiedergabequalität auszuwählen, die sich nach Nutzer, Video, System und anderen Wiedergabebedingungen richtet.

Wenn du eine Wiedergabequalität für ein Video vorschlägst, wird die vorgeschlagene Qualität nur für das jeweilige Video aktiviert. Du solltest eine Wiedergabequalität auswählen, die zur Größe deines Videoplayers passt. Wenn auf deiner Seite beispielsweise ein Videoplayer mit einer Größe von 1280 x 720 Pixel angezeigt wird, sieht ein Video mit einer Qualität von hd720 besser aus als ein Video mit einer Qualität von hd1080. Wir empfehlen das Aufrufen der getAvailableQualityLevels()-Funktion, um zu bestimmen, welche Stufen für ein Video zur Verfügung stehen.

In der unten stehenden Liste werden die Stufen für die Wiedergabequalität gezeigt, die sich auf verschiedene Standardgrößen von Playern beziehen. Wir empfehlen, dass du die Höhe des Players auf einen der unten aufgelisteten Werte setzt und die Größe deines Players auf die Verwendung eines Seitenverhältnisses von 16:9 ausrichtest. Wie bereits oben erwähnt, empfehlen wir bei Auswahl einer Standard-Player-Größe, dass du den suggestedQuality-Parameterwert auf default setzt, damit YouTube die am besten geeignete Wiedergabequalität auswählen kann.

Qualitätsstufe small: Die Player-Höhe beträgt 240 Pixel und die Abmessungen betragen mindestens 320 x 240 Pixel für ein Seitenverhältnis von 4:3.
Qualitätsstufe medium: Die Player-Höhe beträgt 360 Pixel und die Abmessungen betragen 640 x 360 Pixel für ein Seitenverhältnis von 16:9 sowie 480 x 360 Pixel für ein Seitenverhältnis von 4:3.
Qualitätsstufe large: Die Player-Höhe beträgt 480 Pixel und die Abmessungen betragen 853 x 480 Pixel für ein Seitenverhältnis von 16:9 sowie 640 x 480 Pixel für ein Seitenverhältnis von 4:3.
Qualitätsstufe hd720: Die Player-Höhe beträgt 720 Pixel und die Abmessungen betragen 1280 x 720 Pixel für ein Seitenverhältnis von 16:9 sowie 960 x 720 Pixel für ein Seitenverhältnis von 4:3.
Qualitätsstufe hd1080: Die Player-Höhe beträgt 1080 Pixel und die Abmessungen betragen 1920 x 1080 Pixel für ein Seitenverhältnis von 16:9 sowie 1440 x 1080 Pixel für ein Seitenverhältnis von 4:3.
Qualitätsstufe highres: Die Player-Höhe ist größer als 1080 Pixel. Hieraus ergibt sich, dass das Seitenverhältnis des Players größer als 1920 x 1080 Pixel ist.
Qualitätsstufe default: YouTube wählt die geeignete Wiedergabequalität aus. Durch diese Einstellung wird die Qualitätsstufe auf den Standardwert zurückgesetzt. Alle vorherigen Versuche, die Wiedergabequalität mithilfe der Funktionen cueVideoById, loadVideoById oder setPlaybackQuality festzulegen, werden rückgängig gemacht.

Wenn du die setPlaybackQuality-Funktion mit einer suggestedQuality-Stufe aufrufst, die für das Video nicht verfügbar ist, wird die Qualität auf die nächstniedrigere verfügbare Stufe eingestellt. Wenn du beispielsweise die Qualitätsstufe large anforderst und diese nicht verfügbar ist, wird die Wiedergabequalität auf medium gesetzt, sofern diese Stufe verfügbar ist.

Außerdem ist eine Einstellung von suggestedQuality auf einen Wert, der nicht als Qualitätsstufe erkannt wird, gleichbedeutend mit einer Einstellung von suggestedQuality auf default.

player.getAvailableQualityLevels():Array: Diese Funktion gibt die Qualitätsformate zurück, in denen das aktuelle Video verfügbar ist. Du könntest mithilfe dieser Funktion bestimmen, ob das Video in einer höheren Qualität verfügbar ist als jene, die der Nutzer gerade für die Wiedergabe verwendet. Dein Player könnte eine Schaltfläche oder ein anderes Element anzeigen, damit der Nutzer die Qualität entsprechend anpassen kann.

Die Funktion gibt verschiedene Strings zurück, die nach abnehmender Qualität sortiert sind. Mögliche Array-Elementwerte sind highres, hd1080, hd720, large, medium und small. Diese Funktion gibt ein leeres Array zurück, wenn kein aktuelles Video vorhanden ist.

Dein Client sollte nicht automatisch zur höchsten oder niedrigsten Videoqualität oder zu einem unbekannten Formatnamen wechseln. YouTube könnte die Liste der Qualitätsstufen erweitern und Formate aufnehmen, die unter Umständen für deinen Player-Kontext nicht geeignet sind. Ebenso könnte YouTube Optionen entfernen, sodass die dem Nutzer gebotene Qualität möglicherweise beeinträchtigt wird. Wenn dein Client nur zu bekannten verfügbaren Formaten wechselt, wird die Client-Leistung weder durch die Einführung neuer Qualitätsstufen noch durch das Entfernen von Qualitätsstufen beeinflusst, die für deinen Player-Kontext nicht geeignet sind.

Videoinformationen abrufen

player.getDuration():Number: Gibt die Dauer des derzeit wiedergegebenen Videos in Sekunden an. getDuration() gibt so lange 0 zurück, bis die Metadaten des Videos geladen sind. Dies ist in der Regel direkt nach dem Beginn der Wiedergabe der Fall.

Wenn es sich bei dem gerade wiedergegebenen Video um eine Liveveranstaltung handelt, gibt die getDuration()-Funktion die seit dem Start des Live-Videostreams vergangene Zeit 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: Gibt die YouTube.com-URL für das derzeit geladene/wiedergegebene Video zurück

player.getVideoEmbedCode():String: Gibt den eingebetteten Code für das derzeit geladene/wiedergegebene Video zurück

Playlist-Informationen abrufen

player.getPlaylist():Array: Diese Funktion gibt ein Array von 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 allerdings die Funktion setShuffle aufgerufen hast, um die Playlist als Zufallsmix wiederzugeben, spiegelt der Rückgabewert der getPlaylist()-Funktion die Reihenfolge des Zufallsmix wieder.

player.getPlaylistIndex():Number

Diese Funktion gibt den Index des Playlist-Videos zurück, das gerade wiedergegeben wird.

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 Listener-Funktion für das angegebene event-Element hinzu. Der unten stehende Abschnitt Ereignisse gibt die unterschiedlichen Ereignisse an, die durch den Player ausgelöst werden können. 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 Listener-Funktion für das angegebene event-Element. Bei listener handelt es sich um einen String, der die Funktion festlegt, die bei Auslösung des angegebenen Ereignisses nicht mehr ausgeführt wird.

DOM-Knoten aufrufen und ändern

player.getIframe():Object: Diese Methode gibt den DOM-Knoten für das eingebettete <iframe>-Element zurück.

player.destroy():Void: Entfernt das <iframe>-Element, das den Player enthält

Ereignisse

Die API löst Ereignisse aus, um deine Anwendung über Änderungen am eingebetteten Player zu informieren. Wie im vorigen Abschnitt erwähnt, kannst du Ereignisse abonnieren, indem du beim Erstellen des YT.Player-Objekts einen Ereignis-Listener verwendest. Du kannst außerdem die Funktion addEventListener verwenden.

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

Das target-Element des Ereignisses gibt den Videoplayer an, der sich auf das Ereignis bezieht.
Das data-Element des Ereignisses gibt einen relevanten Wert für das Ereignis an. Das onReady-Ereignis gibt keine data-Eigenschaft an.

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

onReady

Dieses Ereignis wird immer dann ausgelöst, wenn ein Player einen Ladevorgang abgeschlossen hat und bereit ist, API-Aufrufe zu empfangen. Deine Anwendung sollte diese Funktion implementieren, wenn du bestimmte Vorgänge wie das Wiedergeben eines Videos oder das Anzeigen von Informationen zum Video ausführen möchtest, sobald der Player bereit ist.

Im folgenden Beispiel wird eine Funktion zum Verarbeiten dieses Ereignisses gezeigt. Das Ereignisobjekt, das von der API an die Funktion weitergeleitet wird, verfügt über eine target-Eigenschaft, die den Player angibt. Die Funktion ruft den eingebetteten Code für das derzeit geladene Video ab, beginnt die Wiedergabe des Videos und zeigt den eingebetteten Code in dem Seitenelement an, das den id-Wert embed-code aufweist.

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 immer dann ausgelöst, wenn sich der Status des Players ändert. Die data-Eigenschaft des Ereignisobjekts, das die API an deine Ereignis-Listener-Funktion weiterleitet, gibt eine ganze Zahl an, die dem neuen Player-Status entspricht. Mögliche Werte sind folgende:

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

Wenn der Player zuerst ein Video lädt, sendet er ein Ereignis unstarted (-1). Wenn ein Video positioniert und bereit für die Wiedergabe ist, sendet der Player ein 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 immer dann ausgelöst, wenn sich die Qualität der Videowiedergabe ändert. Wenn du beispielsweise die Funktion setPlaybackQuality(suggestedQuality) aufrufst, wird dieses Ereignis ausgelöst, wenn sich die Wiedergabequalität tatsächlich ändert. Deine Anwendung sollte auf das Ereignis reagieren und nicht annehmen, dass sich die Qualität automatisch ändert, wenn die Funktion setPlaybackQuality(suggestedQuality) aufgerufen wird. Ebenso sollte dein Code nicht annehmen, dass sich die Wiedergabequalität ausschließlich als Ergebnis eines expliziten Aufrufs von setPlaybackQuality oder einer anderen Funktion ändert, die dir ermöglicht, eine empfohlene Wiedergabequalität festzulegen.

Beim data-Eigenschaftswert des Ereignisobjekts, das die API an die Ereignis-Listener-Funktion weiterleitet, handelt es sich um einen String, der die neue Wiedergabequalität angibt. Mögliche Werte sind folgende:

small
medium
large
hd720
hd1080
highres

onPlaybackRateChange: Dieses Ereignis wird immer dann ausgelöst, wenn sich die Videowiedergaberate ändert. Wenn du beispielsweise die Funktion setPlaybackRate(suggestedRate) aufrufst, wird dieses Ereignis ausgelöst, wenn sich die Wiedergaberate tatsächlich ändert. Deine Anwendung sollte auf das Ereignis reagieren und nicht annehmen, dass sich die Wiedergaberate automatisch ändert, wenn die Funktion setPlaybackRate(suggestedRate) aufgerufen wird. Ebenso sollte dein Code nicht annehmen, dass sich die Videowiedergaberate nur als Ergebnis eines ausdrücklichen Aufrufs von setPlaybackRate ändert.

Beim data-Eigenschaftswert des Ereignisobjekts, den die API an die Ereignis-Listener-Funktion weiterleitet, handelt es sich um eine Zahl, die die neue Wiedergaberate angibt. Die Methode getAvailablePlaybackRates gibt eine Liste gültiger Wiedergaberaten für das derzeit positionierte oder wiedergegebene Video zurück.

onError

Dieses Ereignis wird ausgelöst, wenn im Player ein Fehler auftritt. Die API leitet das event-Objekt an die Ereignis-Listener-Funktion weiter. Die data-Eigenschaft dieses Objekts gibt eine ganze Zahl an, die den aufgetretenen Fehlertyp identifiziert. Mögliche Werte sind folgende:

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 handelt sich eigentlich um einen 101-Fehler.

onApiChange

Dieses Ereignis wird ausgelöst, um anzuzeigen, dass der Player ein Modul mit eingeblendeten 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.

Der folgende Befehl ruft ein Array von Modulnamen ab, für die du Player-Optionen festlegen kannst.

player.getOptions();

Gegenwärtig handelt es sich beim cc-Modul, das Untertitel im Player verarbeitet, um das einzige Modul, für das du Optionen festlegen kannst. Beim Empfangen eines onApiChange-Ereignisses kann deine Anwendung über den folgenden Befehl bestimmen, welche Optionen für das cc-Modul festgelegt werden können:

player.getOptions('cc');

Durch das Abfragen des Players mit diesem Befehl kannst du bestätigen, dass auf die Optionen, auf die du zugreifen möchtest, auch tatsächlich zugegriffen werden kann. Moduloptionen werden mit den folgenden Befehlen abgerufen und aktualisiert:

Option abrufen
player.getOption(module, option);

Option festlegen
player.setOption(module, option, value);

In der folgenden Tabelle werden die von der API unterstützten Optionen aufgelistet:

Modul	Option	Beschreibung
cc	fontSize	Diese Option passt die Schriftgröße der im Player angezeigten Untertitel an. Gültige Werte sind `-1`, `0`, `1`, `2` und `3`. Die Standardgröße ist `0`, die kleinste Größe `-1`. Durch das Einstellen dieser Option auf eine ganze Zahl, die kleiner als `-1` ist, wird die kleinste Untertitelgröße angezeigt. Das Einstellen auf eine ganze Zahl, die größer als `3` ist, bewirkt, dass die größte Untertitelgröße angezeigt wird.
cc	reload	Diese Option lädt die Untertiteldaten für das wiedergegebene Video erneut. Der Wert lautet `null`, wenn du den Wert der Option abrufst. Setze den Wert auf `true`, um die Untertiteldaten erneut zu laden.

Überlegungen zu Mobilgeräten

Autoplay- und Skriptwiedergabe

Das HTML5-<video>-Element lässt in bestimmten mobilen Browsern wie z. B. Chrome und Safari die Wiedergabe nur dann zu, wenn sie durch eine Interaktion des Nutzers initiiert wird, z. B. durch das Tippen auf den Player. Folgendes ist ein Auszug aus der Apple-Dokumentation:

"Warnung: Um unerwünschte Downloads über mobile Netzwerke auf Kosten des Nutzers zu verhindern, können mit Safari für iOS keine eingebetteten Medien automatisch wiedergegeben werden. Die Wiedergabe muss immer vom Nutzer initiiert werden."

Aus diesem Grund können Funktionen und Parameter wie z. B. autoplay, playVideo() und loadVideoById() nicht in allen mobilen Umgebungen verwendet werden.

Beispiele

YT.Player-Objekte erstellen

Beispiel 1: Laute Wiedergabe

In diesem Beispiel wird ein Videoplayer mit einer Größe von 1280 x 720 Pixel erstellt. Anschließend ruft der Ereignis-Listener für das onReady-Ereignis die Funktion setVolume auf, um für die Lautstärke die höchstmögliche Einstellung auszuwählen.

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

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

Beispiel 2: In diesem Beispiel werden die Player-Parameter so festgelegt, dass das Video beim Laden automatisch wiedergegeben und die Steuerung des Videoplayers ausgeblendet wird. Außerdem werden Ereignis-Listener für alle 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,
      'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

Überarbeitungsverlauf

Dieser Abschnitt enthält Änderungen der YouTube Iframe Player API und Aktualisierungen der Dokumentation. Dieses Änderungsprotokoll abonnieren