Klicken Sie hier, um die Seiten zu sehen, die Sie zuletzt und am häufigsten aufgerufenen haben.
Ausblenden

YouTube JavaScript Player API Reference

Dieses Dokument enthält Referenzinformationen für die YouTube JavaScript Player API.

Inhalt

  1. Überblick
  2. Anforderungen
  3. Erste Schritte
  4. Operationen
    1. Funktionen
      1. Wiedergabelisten-Funktionen
      2. Wiedergabesteuerung und Player-Einstellungen
      3. Wiedergabestatus
      4. Wiedergabequalität
      5. Abrufen von Videodaten
      6. Abrufen von Playlist-Informationen
      7. Hinzufügen oder Entfernen eines Ereignis-Listeners
    2. Ereignisse
  5. Event-Handler
  6. Beispiele
    1. Einbettung der SWF-Datei
    2. Abrufen des SWF-Referenzobjekts
    3. Ausgabe von Aufrufen
    4. Abonnieren von Ereignissen
    5. Livedemo
  7. Überarbeitungsverlauf

Überblick

Die JavaScript API kann eingesetzt werden, um einen Chromeless Player oder einen eingebetteten Videoplayer von YouTube über JavaScript-Funktionen zu steuern. Mithilfe dieser Funktionen kannst du z. B. Inhalte abspielen oder pausieren, die Startposition für ein bestimmtes Video individuell festlegen, die Lautstärke regeln oder den Player stumm schalten.

Anforderungen

Auf dem Gerät des Endnutzers muss Flash Player 10.1 oder eine höhere Version installiert sein, damit der Videoplayer korrekt dargestellt werden kann. Aufgrund dieser Anforderung empfehlen wir die Verwendung von SWFObject, um die SWF-Datei einzubetten und die Flash Player-Version des Nutzers zu identifizieren.

Darüber hinaus muss jede HTML-Seite, die den YouTube-Player enthält, eine JavaScript-Funktion namens onYouTubePlayerReady implementieren. Diese Funktion wird von der API aufgerufen, sobald der Player vollständig geladen wurde und die API bereit ist, Aufrufe zu empfangen. Weitere Informationen findest du im Abschnitt Event-Handler.

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.

Erste Schritte

Hinweis: Um einen dieser Aufrufe zu testen, muss deine Datei auf einem Webserver ausgeführt werden, weil Aufrufe zwischen lokalen Dateien und dem Internet von Flash Player beschränkt werden.

Du kannst die JavaScript API-Handler für Chromeless Player und eingebettete Player aktivieren. Um die JavaScript API für einen Player zu aktivieren, musst du den URL-Parameter enablejsapi=1 zur Player-URL hinzufügen.

  • Aktivierung der JavaScript-API für einen Chromeless Player

    Wenn deine Anwendung einen Chromeless Player einsetzt, kannst du die folgende URL verwenden, um den Player in deine Anwendung zu laden und JavaScript API-Handler für diesen Player zu aktivieren. Anschließend kannst du mit JavaScript eine benutzerdefinierte Steuerung für den Player gestalten:

    http://www.youtube.com/apiplayer?enablejsapi=1&version=3
  • Aktivierung der JavaScript-API für einen eingebetteten Player

    Verwende die folgende URL, um einen eingebetteten Player zu laden. Die Zeichenfolge VIDEO_ID in der URL muss durch eine YouTube-Video-ID mit 11 Zeichen ersetzt werden, die das Video identifiziert, das der Player wiedergeben soll.

    http://www.youtube.com/v/VIDEO_ID?version=3&enablejsapi=1

Sobald der Player bereit ist, wird die onYouTubePlayerReady-Rückruffunktion von der API aufgerufen. Du kannst den optionalen playerapiid-Parameter in der Player-URL verwenden, um einen Wert – wie z. B. die Player-ID – an die Rückruffunktion zurückzugeben.

http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&version=3&playerapiid=ytplayer

Sobald die Player-SWF-Datei geladen wurde, kannst du die Wiedergabelisten-Funktionen cueVideoById(), loadVideoById(), cueVideoByUrl(), loadVideoByUrl(), cuePlaylist() oder loadPlaylist() verwenden, um ein bestimmtes YouTube-Video oder eine bestimmte YouTube-Playlist zu laden.

In der Player API-Demo kannst du die verschiedenen Player-Typen – Chromeless Player und eingebetteter Player – miteinander vergleichen. Die unten folgenden Beispiele liefern ausführliche Informationen darüber, wie eine YouTube-Player-SWF-Datei auf deiner Seite eingebettet werden kann. Außerdem kannst du deine Nutzererfahrung individuell gestalten, indem du verschiedene Player-Parameter einsetzt, um das Player-Verhalten zu steuern.

Operationen

Um die Player API-Methoden aufrufen zu können, musst du zunächst dem Playerobjekt, das du steuern möchtest, eine Referenz zuweisen. Wenn du SWFObject zur Einbettung der Player-SWF-Datei einsetzt, kannst du die Referenz zum Playerobjekt beziehen, indem du die Methode getElementById() für das <object>- oder <embed>-Tag verwendest, das die Player-SWF-Datei enthält.

Funktionen

In den folgenden Unterabschnitten werden die von der Player-API unterstützten Funktionen aufgeführt.

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'});

Die unterschiedlichen Wiedergabelisten-Funktionen für Videos und Playlists werden im Folgenden beschrieben.

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

  • Argumentsyntax

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

  • Objektsyntax

    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

  • Argumentsyntax

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

  • Objektsyntax

    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() oder seekTo() aufgerufen wird.

  • 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

  • Argumentsyntax

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

  • Objektsyntax

    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.

  • Argumentsyntax

    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.

    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.

  • 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.

    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.

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.

Hinweis: Obwohl der AS3-Player die Steuerung von Wiedergaberaten unterstützt, werden variable Geschwindigkeiten derzeit nur durch den HTML5-Player unterstützt.

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.

Gibt die Anzahl der Bytes zurück, die für das aktuelle Video geladen wurden
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

Genauer gesagt gibt diese Funktion einen geschätzten Wert der Gesamtgröße des Videos wieder, wenn der Wert von player.getVideoStartBytes() größer als null ist. Diese Funktion muss die Größe des Videos schätzen, weil die Weitergabe der tatsächlichen Größe des Videos an den Player nur dann erfolgt, wenn das Video von vorn wiedergegeben wird.

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.

Ereignisse

onStateChange
Dieses Ereignis wird immer dann ausgelöst, wenn sich der Status des Players ändert. Der Wert, den 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.

Bei dem Wert, den 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.

Bei dem Wert, den die API an die Ereignis-Listener-Funktion weiterleitet, handelt es sich um eine ganze 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.

Hinweis: Obwohl der AS3-Player dieses Ereignis unterstützt, werden variable Geschwindigkeiten derzeit nur vom HTML5-Player unterstützt.

onError
Dieses Ereignis wird ausgelöst, wenn im Player ein Fehler auftritt. Bei dem Wert, den die API an die Ereignis-Listener-Funktion weiterleitet, handelt es sich um eine ganze Zahl, die den aufgetretenen Fehlertyp angibt. 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.
  • 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.

Event-Handler

Deine HTML-Seiten, auf denen der Chromeless Player angezeigt wird, müssen eine Rückruffunktion namens onYouTubePlayerReady implementieren. Diese Funktion wird von der API aufgerufen, sobald der Player vollständig geladen wurde und die API bereit ist, Aufrufe zu empfangen.

onYouTubePlayerReady(playerid)
Wird aufgerufen, sobald der Player vollständig geladen wurde und die API bereit ist, Aufrufe zu empfangen. Wenn eine playerapiid mithilfe von URL-Argumenten in den Player eingefügt wurde, wird sie dieser Funktion zugewiesen.

Beispiele

Einbettung des YouTube-Players mit SWFObject

Wir empfehlen die Verwendung von SWFObject zur Einbettung von Playern, auf die mittels der JavaScript API zugegriffen wird. Auf diese Weise bist du in der Lage, die Flash Player-Version des Endnutzers zu identifizieren. Dies ist u. U. relevant, weil Flash Player 8 oder eine höhere Version für die JavaScript API erforderlich ist. Zudem wird dadurch das Feld "Klicken Sie hier, um dieses Steuerelement zu aktivieren und zu verwenden" entfernt, das andernfalls im Internet Explorer angezeigt wird. Um die API in der SWF-Datei zu aktivieren, musst du den Parameter enablejsapi=1 einfügen.

Unten findest du ein entsprechendes Beispiel für die Einbettung eines YouTube-Players mit aktivierter JavaScript API und mit der playerapiid von ytplayer.

  <script type="text/javascript" src="swfobject.js"></script>
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&playerapiid=ytplayer&version=3",
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

Der allowScriptAccess-Parameter im Code ist erforderlich, damit die Player-SWF-Datei Funktionen auf der HTML-Seite aufrufen kann, auf der sie eingebettet ist, weil der Player selbst auf einer anderen Domain gehostet wird.

Das einzige Attribut, das wir einfügen, ist die id des eingebetteten Objekts; in unserem Fall ist das myytplayer. Diese ID verwenden wir, um dem Player mit der Methode getElementById() eine Referenz zuzuweisen.

swfobject.embedSWF lädt den YouTube-Player und bettet ihn auf deiner Seite ein.

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

  • swfUrlStr: Dies ist die URL der SWF-Datei. In unserem Beispiel haben wir die normale YouTube-SWF-URL um die enablejsapi- und playerapiid-Parameter ergänzt, damit JavaScript API-Aufrufe aktiviert werden.
  • replaceElemIdStr: Dies ist die HTML DIV-ID, die mit dem eingebetteten Inhalt ersetzt wird. Unser Beispiel verwendet den Wert ytapiplayer.
  • widthStr: Breite des Players.
  • heightStr: Höhe des Players.
  • swfVersionStr: Dies ist die Version, die zur Darstellung der Inhalte mindestens erforderlich ist. In unserem Fall handelt es sich dabei um die Version 8. Sollte der Nutzer diese Voraussetzung nicht erfüllen, wird die Standardtextzeile im HTML DIV angezeigt.
  • xiSwfUrlStr: Optional. Legt die URL deiner SWF-Datei für die Expressinstallation fest. Wird im Beispiel nicht verwendet.
  • flashVarsObj: Optional. Legt deinen FlashVars-Wert in name:value-Paaren fest. Wird im Beispiel nicht verwendet.
  • parObj: Optional. Umfasst die Parameter für das eingebettete Objekt. Im Beispiel wurde der Wert auf allowScriptAccess gesetzt.
  • AttObj: Optional. Umfasst die Attribute für das eingebettete Objekt. Im Beispiel wurde die ID auf myytplayer gesetzt.

Nähere Informationen findest du in der SWFObject-Dokumentation.

Abrufen der Playerreferenz

Sobald der Player bereit ist, wird onYouTubePlayerReady aufgerufen.

Verwende die Methode getElementById(), um die Referenz dem Player zuzuweisen. Sobald das Objekt abgerufen wurde, können Aufrufe an die API gesendet werden.

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

Ausgabe von Aufrufen

Nun kannst du Funktionen mithilfe der Playerreferenz aufrufen. Wenn z. B. das Video abgespielt werden soll, nachdem der Nutzer auf einen Link geklickt hat, könnte der Code folgendermaßen aussehen:

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

Oder ganz einfach so:

<a href="javascript:ytplayer.playVideo()">Play</a>

Abonnieren von Ereignissen

Du kannst Ereignisse abonnieren, indem du der Playerreferenz einen Ereignis-Listener hinzufügst. So kannst du z. B. für onStateChange einen Ereignis-Listener und eine Rückruffunktion hinzufügen, um benachrichtigt zu werden, wenn sich der Player-Status ändert.

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

Livedemo

Du kannst die YouTube-Player-Demo verwenden, um die Funktionen der JavaScript API mit dem eingebetteten Player bzw. mit dem Chromeless Player zu testen.

Überarbeitungsverlauf

In diesem Abschnitt werden Änderungen an der YouTube JavaScript Player API sowie Aktualisierungen der Dokumentation aufgelistet. Änderungsprotokoll abonnieren Abonnieren

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

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

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

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

August 6, 2012

This update contains the following changes:

  • The API supports several new functions and one new event that can be used to control the video playback speed. However, note that variable playback speeds are currently only supported in the HTML5 player.

    • Functions

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

    • Events

July 19, 2012

This update contains the following changes:

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size. 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.

December 21, 2011

This update contains the following changes:

  • The Requirements section has been updated to note that the end user must have Flash Player 10.1 or higher installed for the player to display everything correctly.

December 19, 2011

This update contains the following changes:

  • The AS3 Player API now supports an object syntax for calling the cuePlaylist and loadPlaylist functions.

    The object syntax lets you pass an object as the only argument to a function. The object's properties specify the function arguments that you wish to set.

  • The cuePlaylist and loadPlaylist functions both support additional functionality when called using the object syntax. Specifically, when using the object syntax, you can use both functions to retrieve either a playlist, a list of search results, or a list of a user's uploaded videos. If you are using the argument syntax, you can only retrieve a playlist.

    To support this functionality, the object syntax defines a listType property that can be used to specify whether the player is retrieving a playlist, a list of search results, or a list of a user's uploaded videos. The object's list property then specifies the playlist ID, search query, or username that identifies the desired feed.

    To properly reflect this functionality, the Queueing functions for playlists section has been renamed to Queueing functions for lists. Within that section, the cuePlaylist and loadPlaylist functions are each defined twice to explain how to call each function using either the argument syntax or the object syntax.

December 5, 2011

This update contains the following changes:

  • The definition of the seekTo function has been updated to indicate that if the player is paused when the function is called, the player will remain paused after the function executes.

November 17, 2011

This update contains the following changes:

  • The definitions of the cueVideoByUrl and loadVideoByUrl functions have been updated in two ways:

    • The definition of the mediaContentUrl argument for each function has been updated to note that the value must specify the version parameter. As such, the argument's value must be a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID?version=3.
    • Both functions support a suggestedQuality parameter. This parameter specifies the suggested playback quality for the video.
  • The definition of the setSize function has been removed from the documentation. If you are using the JavaScript Player API, the player will automatically resize if the height and width properties of the containing elements in the embed code are modified. Since the setSize function does not currently alter the size of those containing elements, it is unlikely to have the expected effect.

  • The definition of the getDuration function has been updated to explain that if the currently playing video is a live event, the function will return the elapsed time since the video stream began.

July 29, 2011

This update contains the following changes:

  • The following API functions have been added to support playlist players:

    • The cuePlaylist function loads the thumbnail image for the first video in the specified playlist and prepares the player to play the playlist. However, the player does not request the video until your application calls either the playVideo, playVideoAt, or seekTo function.

    • The loadPlaylist function loads and plays the specified playlist.

    • The getPlaylist function plays the currently cued playlist. The final player state after this function executes will be playing (1).

    • The getPlaylistIndex function returns the position in which the current video appears in the playlist. The first video will have a position of 1, the second video will have a position of 2, and so forth.

    • The nextVideo function instructs the player to load and play the next video in the playlist.

    • The previousVideo function instructs the player to load and play the previous video in the playlist.

    • The playVideoAt function instructs the player to load and play a specific video in the playlist.

    • The setLoop function lets you dynamically instruct the player to continuously play the playlist or, alternately, to sto playing after the playlist has played all of the videos in the playlist.

    • The setShuffle function instructs YouTube to play the videos in the playlist in random order (or to play them in their designated order.

February 17, 2011

This update contains the following changes:

  • If you link to the Player Parameters document from this document, the page will now display parameters supported in any version of the player. You can use the pulldown menu in the Overview section of that document to only see parameters supported in the AS3 player (or in the HTML5 or AS2) players.

February 3, 2011

This update contains the following changes:

  • The definition of the playVideo function has been updated to note that YouTube only counts playbacks that are initiated through a native play button in either the embedded or chromeless player.

  • If you link to the Player Parameters document from either the link in the Getting started section or from this paragraph, the page will initially only display parameters supported in the AS3 player. You can use the pulldown menu in the Overview section of that document to see parameters supported in other players (HTML5 or AS2) or all parameters.