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.
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 desid
-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 Variableplayer
, die auf den von dir eingebetteten Videoplayer verweist. Anschließend erstellt die Funktion das Videoplayer-Objekt. -
Die
onPlayerReady
-Funktion wird bei Auslösung desonReady
-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 diestopVideo
-Funktion aufrufen soll, um das Video anzuhalten, wenn sich der Player im Status1
(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>
alsinline-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 ist640
.height
(Zahl) – die Höhe des Videoplayers. Der Standardwert ist360
.videoId
(String) – die YouTube-Video-ID, die das Video identifiziert, das der Player laden wirdplayerVars
(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 desonReady
-Ereignisses dieonPlayerReady
-Funktion ausgeführt wird, und bei Auslösung desonStateChange
-Ereignisses dieonPlayerStateChange
-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()
oderseekTo()
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, wennplayVideo()
aufgerufen wird. Wenn du einenstartSeconds
-Wert angibst und anschließendseekTo()
aufrufst, beginnt der Player die Wiedergabe bei dem im AufrufseekTo()
angegebenen Zeitpunkt. Wenn das Video positioniert und bereit für die Wiedergabe ist, sendet der Player einvideo 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, wennplayVideo()
aufgerufen wird. Wenn du einenendSeconds
-Wert angibst und anschließendseekTo()
aufrufst, wird derendSeconds
-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 FunktionsetPlaybackQuality
.
-
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 FunktionsetPlaybackQuality
.
-
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
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()
oderseekTo()
aufgerufen wird.- Der erforderliche
mediaContentUrl
-Parameter gibt eine vollqualifizierte YouTube-Player-URL im Formathttp://www.youtube.com/v/VIDEO_ID?version=3
an. In YouTube Data API-Videofeeds enthält dasurl
-Attribut des Tags<media:content>
eine vollqualifizierte Player-URL, wenn dasformat
-Attribut des Tags den Wert5
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, wennplayVideo()
aufgerufen wird. Wenn dustartSeconds
angibst und anschließendseekTo()
aufrufst, beginnt der Player die Wiedergabe bei dem Zeitpunkt, der im AufrufseekTo()
angegeben wurde. Wenn das Video positioniert und bereit für die Wiedergabe ist, überträgt der Player einvideo 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, wennplayVideo()
aufgerufen wird. Wenn du einenendSeconds
-Wert angibst und anschließendseekTo()
aufrufst, wird derendSeconds
-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 FunktionsetPlaybackQuality
.
-
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 Formathttp://www.youtube.com/v/VIDEO_ID?version=3
an. In YouTube Data API-Videofeeds enthält dasurl
-Attribut des Tags<media:content>
eine vollqualifizierte Player-URL, wenn dasformat
-Attribut des Tags den Wert5
aufweist. - Der optionale
startSeconds
-Parameter akzeptiert eine Gleitkommazahl oder ganze Zahl und gibt den Zeitpunkt an, bei dem die Wiedergabe des Videos beginnen soll. WirdstartSeconds
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 FunktionsetPlaybackQuality
.
-
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
Fügt die angegebene Playlist der Wiedergabeliste hinzu. Wenn die Playlist positioniert und bereit für die Wiedergabe ist, sendet der Player einplayer.cuePlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void
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 lautet0
. 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 FunktionplayVideo()
aufgerufen wird. Wenn du einenstartSeconds
-Wert angibst und anschließendseekTo()
aufrufst, beginnt der Player die Wiedergabe bei dem im AufrufseekTo()
angegebenen Zeitpunkt. Wenn du eine Playlist positionierst und anschließend die FunktionplayVideoAt()
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 FunktionsetPlaybackQuality
.
-
-
Objektsyntax
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 einplayer.cuePlaylist({listType:String, list:String, index:Number, startSeconds:Number, suggestedQuality:String}):Void
video cued
-Ereignis (5
).-
Die optionale
listType
-Eigenschaft gibt den Ergebnistyp-Feed an, den du abrufst. Gültige Werte sindplaylist
,search
unduser_uploads
. Der Standardwert istplaylist
. -
Die erforderliche
list
-Eigenschaft enthält einen Schlüssel zum Angeben der spezifischen Videoliste, die von YouTube zurückgegeben werden soll.- Wenn der
listType
-Eigenschaftswertplaylist
lautet, gibt dielist
-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
-Eigenschaftswertsearch
lautet, gibt dielist
-Eigenschaft die Suchanfrage an. - Wenn der
listType
-Eigenschaftswertuser_uploads
lautet, gibt dielist
-Eigenschaft den Nutzer an, dessen hochgeladene Videos zurückgegeben werden.
- Wenn der
-
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 lautet0
. 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 FunktionplayVideo()
aufgerufen wird. Wenn du einenstartSeconds
-Wert angibst und anschließendseekTo()
aufrufst, beginnt der Player die Wiedergabe bei dem im AufrufseekTo()
angegebenen Zeitpunkt. Wenn du eine Liste positionierst und anschließend die FunktionplayVideoAt()
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 FunktionsetPlaybackQuality
.
-
-
loadPlaylist
-
-
Argument syntax
Diese Funktion lädt die angegebene Playlist und gibt sie wieder.player.loadPlaylist(playlist:String|Array, index:Number, startSeconds:Number, suggestedQuality:String):Void
-
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 lautet0
. 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 FunktionsetPlaybackQuality
.
-
-
Object syntax
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.player.loadPlaylist({list:String, listType:String, index:Number, startSeconds:Number, suggestedQuality:String}):Void
-
Die optionale
listType
-Eigenschaft gibt den Suchergebnis-Feed an, den du abrufst. Gültige Werte sindplaylist
,search
unduser_uploads
. Der Standardwert istplaylist
. -
Die erforderliche
list
-Eigenschaft enthält einen Schlüssel, der die spezifische Videoliste angibt, die YouTube zurückgeben soll.- Wenn der
listType
-Eigenschaftswertplaylist
lautet, gibt dielist
-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
-Eigenschaftswertsearch
lautet, gibt dielist
-Eigenschaft die Suchanfrage an. - Wenn der
listType
-Eigenschaftswertuser_uploads
lautet, gibt dielist
-Eigenschaft den Nutzer an, dessen hochgeladene Videos zurückgegeben werden.
- Wenn der
-
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 lautet0
. 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 FunktionsetPlaybackQuality
.
-
-
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 Statusended
(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ächststopVideo
aufzurufen.
Wichtig: Im Unterschied zur FunktionpauseVideo
, bei der der Player den Statuspaused
(2
) beibehält, könnte diestopVideo
-Funktion den Player in einen Status ohne Wiedergabe versetzen, darunterended
(0
),paused
(2
),video cued
(5
) oderunstarted
(-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
odervideo 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 desNetStream
-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 derseconds
-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 auftrue
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 Wert0
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, undfalse
, wenn nicht
player.setVolume(volume:Number):Void
- Stellt die Lautstärke ein. Akzeptiert eine ganze Zahl zwischen
0
und100
player.getVolume():Number
- Gibt die aktuelle Lautstärke des Players wieder, eine ganze Zahl zwischen
0
und100
.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 wie0.25
,0.5
,1
,1.5
und2
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 auf1
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 EreignisonPlaybackRateChange
ausgelöst und dein Code sollte auf das Ereignis und nicht auf die Tatsache reagieren, dass diesetPlaybackRate
-Funktion aufgerufen wurde.
Die MethodegetAvailablePlaybackRates
gibt die möglichen Wiedergaberaten für das derzeit wiedergegebene Video zurück. Wenn du densuggestedRate
-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 Richtung1
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 Werttrue
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
und1
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 MethodengetVideoBytesLoaded
undgetVideoBytesTotal
.
player.getPlayerState():Number
- Gibt den Status des Players zurück. Mögliche Werte sind folgende:
-1
– nicht gestartet0
– beendet1
– wird wiedergegeben2
– pausiert3
– wird gepuffert5
– 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 zwischen0
und1000
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 dengetVideoBytesLoaded
-Wert durch dengetVideoBytesTotal
-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 von1000
zurück. Du könntest den bereits geladenen Teil des Videos berechnen, indem du dengetVideoBytesLoaded
-Wert durch dengetVideoBytesTotal
-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
undsmall
. Es wird auchundefined
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 diesetPlaybackQuality
-Funktion aufgerufen wurde.
DersuggestedQuality
-Parameterwert kannsmall
,medium
,large
,hd720
,hd1080
,highres
oderdefault
lauten. Wir empfehlen, dass du den Parameterwert aufdefault
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 vonhd720
besser aus als ein Video mit einer Qualität vonhd1080
. Wir empfehlen das Aufrufen dergetAvailableQualityLevels()
-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 densuggestedQuality
-Parameterwert aufdefault
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 FunktionencueVideoById
,loadVideoById
odersetPlaybackQuality
festzulegen, werden rückgängig gemacht.
setPlaybackQuality
-Funktion mit einersuggestedQuality
-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ätsstufelarge
anforderst und diese nicht verfügbar ist, wird die Wiedergabequalität aufmedium
gesetzt, sofern diese Stufe verfügbar ist.
Außerdem ist eine Einstellung vonsuggestedQuality
auf einen Wert, der nicht als Qualitätsstufe erkannt wird, gleichbedeutend mit einer Einstellung vonsuggestedQuality
aufdefault
. - Qualitätsstufe
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 sindhighres
,hd1080
,hd720
,large
,medium
undsmall
. 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 lange0
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 diegetDuration()
-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 dergetPlaylist()
-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. Beilistener
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. DasonReady
-Ereignis gibt keinedata
-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 einetarget
-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 denid
-Wertembed-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)
unstarted
(-1
). Wenn ein Video positioniert und bereit für die Wiedergabe ist, sendet der Player ein Ereignisvideo 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 FunktionsetPlaybackQuality(suggestedQuality)
aufgerufen wird. Ebenso sollte dein Code nicht annehmen, dass sich die Wiedergabequalität ausschließlich als Ergebnis eines expliziten Aufrufs vonsetPlaybackQuality
oder einer anderen Funktion ändert, die dir ermöglicht, eine empfohlene Wiedergabequalität festzulegen.
Beimdata
-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 FunktionsetPlaybackRate(suggestedRate)
aufgerufen wird. Ebenso sollte dein Code nicht annehmen, dass sich die Videowiedergaberate nur als Ergebnis eines ausdrücklichen Aufrufs vonsetPlaybackRate
ändert.
Beimdata
-Eigenschaftswert des Ereignisobjekts, den die API an die Ereignis-Listener-Funktion weiterleitet, handelt es sich um eine Zahl, die die neue Wiedergaberate angibt. Die MethodegetAvailablePlaybackRates
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. Diedata
-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 mit101
identisch. Es handelt sich eigentlich um einen101
-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.
Gegenwärtig handelt es sich beimplayer.getOptions();
cc
-Modul, das Untertitel im Player verarbeitet, um das einzige Modul, für das du Optionen festlegen kannst. Beim Empfangen einesonApiChange
-Ereignisses kann deine Anwendung über den folgenden Befehl bestimmen, welche Optionen für dascc
-Modul festgelegt werden können:
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:player.getOptions('cc');
In der folgenden Tabelle werden die von der API unterstützten Optionen aufgelistet:Option abrufen player.getOption(module, option); Option festlegen player.setOption(module, option, value);
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
und3
. Die Standardgröße ist0
, 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 als3
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 auftrue
, 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 FunktionsetVolume
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
April 28, 2014
This update contains the following changes:
-
The new removeEventListener function lets you remove a listener for a specified event.
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 whenplayVideo()
is called. -
The
getVideoStartBytes
method has been deprecated. The method now always returns a value of0
.
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 theonYouTubeIframeAPIReady
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
onPlaybackRateChange
– This event fires when the video's playback rate changes.
-
July 19, 2012
This update contains the following changes:
-
The new
getVideoLoadedFraction
method replaces the now-deprecatedgetVideoBytesLoaded
andgetVideoBytesTotal
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 of5
, 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 namedonYouTubePlayerAPIReady
. 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 anonYouTubePlayerAPIReady
function, both functions will be called, and theonYouTubeIframeAPIReady
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()
anddestroy()
methods. ThesetSize()
method sets the size in pixels of the<iframe>
that contains the player and thedestroy()
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 aninline-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.