YouTube Player-Parameter

Überblick

In diesem Dokument wird erklärt, wie du einen YouTube-Player in deine Anwendung einbetten kannst. Außerdem werden die Parameter definiert, die im eingebetteten YouTube-Player verfügbar sind.

Durch das Anfügen von Parametern an die IFrame-URL kannst du die Wiedergabe in deiner Anwendung anpassen: So kannst du beispielsweise den autoplay-Parameter verwenden, damit dein Video automatisch gestartet wird, oder den loop-Parameter verwenden, damit dein Video nach abgeschlossener Wiedergabe erneut abgespielt wird. Zudem hast du die Möglichkeit, die JavaScript API für den Player mit dem enablejsapi-Parameter zu aktivieren.

Auf dieser Seite werden zurzeit alle Parameter definiert, die von den eingebetteten YouTube-Playern unterstützt werden. Die Parameterdefinitionen weisen darauf hin, welche Player den jeweiligen Parameter unterstützen.

Hinweis: 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.

Einbetten eines YouTube-Players

Für die Einbettung eines YouTube-Players in deine Anwendung und die Festlegung von Player-Parametern stehen die unten aufgeführten Methoden zur Auswahl. Die entsprechenden Hinweise beschreiben die Einbettung eines Players, der ein einzelnes Video lädt. Im darauffolgenden Abschnitt wird erklärt, wie du deinen Player so konfigurieren kannst, dass weitere Inhaltsarten wie Playlists oder Suchergebnisse geladen werden.

IFrame-Einbettungen, die <iframe>-Tags verwenden

Definiere in deiner Anwendung ein <iframe>-Tag, dessen src-URL sowohl den Inhalt angibt, der im Player geladen werden soll, als auch alle anderen Player-Parameter, die du einstellen möchtest. Die Größe des Players wird durch die height- und width-Parameter des <iframe>-Tags festgelegt.

Wenn du das <iframe>-Element manuell erstellst, anstatt die IFrame Player API zu verwenden, kannst du die Player-Parameter direkt an das Ende der URL anfügen. Die URL hat das folgende Format:

http://www.youtube.com/embed/VIDEO_ID

Das unten folgende <iframe>-Tag würde einen Player mit 640 x 360 Pixel laden, in dem das YouTube-Video M71c1UVf-VE wiedergegeben wird. Da der autoplay-Parameter durch die URL auf 1 gesetzt wird, würde die Videowiedergabe automatisch gestartet, sobald der Ladevorgang für den Player abgeschlossen ist.

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

IFrame-Einbettungen mit der IFrame Player API

Befolge die Anleitung der IFrame Player API, um einen Videoplayer in deine Website oder in deine Anwendung zu integrieren, nachdem der JavaScript-Code der Player API geladen wurde. Beim zweiten Parameter im Konstruktor für den Videoplayer handelt es sich um ein Objekt, mit dem Player-Optionen angegeben werden. In diesem Objekt werden Player-Parameter durch die playerVars-Eigenschaft identifiziert.

Der folgende HTML- und JavaScript-Code ist ein einfaches Beispiel dafür, wie ein YouTube-Player in das Seitenelement mit dem id-Wert ytplayer eingefügt wird. Die hier angegebene onYouTubePlayerAPIReady()-Funktion wird automatisch aufgerufen, sobald der Code der IFrame Player API geladen wurde. Durch diesen Code werden weder Player-Parameter noch sonstige Event-Handler definiert.

<div id="ytplayer"></div>

<script>
  // Load the IFrame Player API code asynchronously.
  var tag = document.createElement('script');
  tag.src = "https://www.youtube.com/player_api";
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  // Replace the 'ytplayer' element with an <iframe> and
  // YouTube player after the API code downloads.
  var player;
  function onYouTubePlayerAPIReady() {
    player = new YT.Player('ytplayer', {
      height: '360',
      width: '640',
      videoId: 'M7lc1UVf-VE'
    });
  }
</script>

Auswählen von Inhalten für die Wiedergabe

Du kannst deinen eingebetteten Player so konfigurieren, dass ein bestimmtes Video, eine Playlist, die Videos eines bestimmten Nutzers oder die Suchergebnisse für eine bestimmte Anfrage geladen werden.

Diese Optionen werden in der folgenden Liste erklärt:

  • Laden eines Videos

    Für eine IFrame-Einbettung wird die YouTube-Video-ID des Videos, das du laden möchtest, in der src-URL des IFrames angegeben.

    http://www.youtube.com/embed/VIDEO_ID

    Wenn du die YouTube Data API (v3) verwendest, kannst du diese URLs programmatisch konstruieren, indem du Video-IDs aus Suchergebnissen, Playlist-Objektressourcen, Videoressourcen oder anderen Ressourcen abrufst. Ersetze den VIDEO_ID-Text in den oben stehenden URLs durch den jeweiligen Wert, um die Player-URL zu erstellen.

  • Laden einer Playlist

    Setze den listType-Player-Parameter auf playlist. Setze außerdem den list-Player-Parameter auf die YouTube-ID, die du laden möchtest.

    http://www.youtube.com/embed?listType=playlist&list=PLAYLIST_ID

    Hinweis: Der Playlist-ID muss wie im folgenden Beispiel die Buchstabenfolge PL vorangestellt werden:

    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

    Wenn du die YouTube Data API (v3) verwendest, kannst du diese URLs programmatisch konstruieren, indem du Playlist-IDs aus Suchergebnissen, Kanalressourcen oder Aktivitätsressourcen abrufst. Ersetze den PLAYLIST_ID-Text in der oben stehenden URL anschließend durch den jeweiligen Wert.

  • Laden von Videos, die von einem bestimmten Nutzer hochgeladen wurden

    Setze den listType-Player-Parameter auf user_uploads. Setze außerdem den list-Player-Parameter auf den Namen des YouTube-Nutzers, dessen Videos du laden möchtest.

    http://www.youtube.com/embed?listType=user_uploads&list=USERNAME
  • Laden von Suchergebnissen für eine bestimmte Anfrage

    Setze den listType-Player-Parameter auf search. Setze außerdem den list-Player-Parameter auf den Suchbegriff, dessen Suchergebnisse in den Player geladen werden sollen.

    http://www.youtube.com/embed?listType=search&list=QUERY

Parameter

Die folgenden Parameter sind optional.

Parameters

autoplay

Werte: 0 oder 1. Die Standardeinstellung ist 0. Legt fest, ob das erste Video automatisch wiedergegeben wird, nachdem der Player geladen wurde.

cc_load_policy

Werte: 1. Die Standardeinstellung richtet sich nach den Festlegungen des Nutzers. Wird die Einstellung 1 gewählt, werden Untertitel selbst dann standardmäßig angezeigt, wenn sie nicht vom Nutzer aktiviert wurden.

color

Dieser Parameter gibt die Farbe an, die in der Fortschrittsanzeige des Players verwendet wird, um den Teil des Videos hervorzuheben, den der Nutzer bereits gesehen hat. red und white sind gültige Parameterwerte. Standardmäßig verwendet der Player die Farbe Rot in der Fortschrittsanzeige. Weitere Informationen zu den Farboptionen findest du im YouTube API-Blog.

Hinweis: Wenn du den color-Parameter auf white setzt, wird die Option modestbranding deaktiviert.

controls

Werte: 0, 1 oder 2. Die Standardeinstellung ist 1. Dieser Parameter legt fest, ob die Steuerung des Videoplayers eingeblendet wird. Bei IFrame-Einbettungen, die einen Flash Player laden, definiert der Parameter außerdem, wann die Steuerung im Player angezeigt und wann der Player geladen wird:

  • controls=0 – Steuerung des Players wird nicht angezeigt. Bei IFrame-Einbettungen wird der Flash Player sofort geladen.
  • controls=1 – Steuerung des Players wird angezeigt. Bei IFrame-Einbettungen wird die Steuerung sofort angezeigt, und auch der Flash Player wird sofort geladen.
  • controls=2 – Steuerung des Players wird angezeigt. Bei IFrame-Einbettungen wird die Steuerung angezeigt und der Flash Player wird geladen, nachdem der Nutzer die Videowiedergabe gestartet hat.

Hinweis: Die Parameterwerte 1 und 2 sollten eine identische Nutzererfahrung bieten. Die Einstellung controls=2 sollte allerdings im Vergleich zu controls=1 eine Leistungsverbesserung für IFrame-Einbettungen erzielen. Derzeit erzeugen die beiden Werte immer noch einige visuelle Abweichungen im Player, beispielsweise im Hinblick auf die Schriftgröße des Videotitels. Wenn der Unterschied zwischen diesen zwei Werten für den Nutzer jedoch vollkommen transparent wird, wird der standardmäßige Parameterwert möglicherweise von 1 zu 2 geändert.

disablekb

Werte: 0 oder 1. Die Standardeinstellung ist 0. Durch die Einstellung 1 wird die Tastatursteuerung des Players deaktiviert. Die Tastatursteuerung umfasst folgende Funktionen:

  • Leertaste: Wiedergeben/Pausieren
  • Pfeil nach links: Im aktuellen Video 10 % zurück springen
  • Pfeil nach rechts: Im aktuellen Video 10 % nach vorn springen
  • Pfeil nach oben: Lautstärke erhöhen
  • Pfeil nach unten: Lautstärke reduzieren

enablejsapi

Werte: 0 oder 1. Die Standardeinstellung ist 0. Durch die Einstellung 1 wird die Javascript API aktiviert. Weitere Informationen zur Javascript API und ihrer Verwendung findest du in der JavaScript API-Dokumentation.

end

Werte: Eine beliebige positive ganze Zahl. Dieser Parameter gibt an, zu welchem Zeitpunkt der Player die Wiedergabe beenden soll. Die Zeit wird in Sekunden angegeben und ab dem Anfang des Videos gemessen. Dabei wird weder der Wert des Player-Parameters start noch der Wert des Parameters startSeconds berücksichtigt, der bei YouTube Player API-Funktionen zum Laden oder Hinzufügen eines Videos zu einer Wiedergabeliste verwendet wird.

fs

Werte: 0 oder 1. Der Standardwert ist 1. Diese Einstellung bewirkt, dass die Schaltfläche für den Vollbildmodus angezeigt wird. Wird dieser Parameter hingegen auf 0 gesetzt, wird die Schaltfläche für den Vollbildmodus nicht angezeigt.

hl

Legt die Spracheinstellung für die Benutzeroberfläche des Players fest. Der Parameterwert ist ein ISO 639-1-Sprachcode mit zwei Buchstaben. Es ist jedoch möglich, dass auch andere Codes für die Spracheingabe wie z. B. IETF-Sprach-Tags (BCP 47) korrekt verarbeitet werden.

Die Spracheinstellung der Benutzeroberfläche wird für Tooltipps im Player verwendet und wirkt sich zudem auf den standardmäßigen Untertiteltrack aus. YouTube kann jedoch unter Umständen eine abweichende Untertiteltrack-Sprache auswählen, die auf der individuellen Spracheinstellung des jeweiligen Nutzers und auf der Verfügbarkeit von Untertiteltracks basiert.

iv_load_policy

Werte: 1 oder 3. Die Standardeinstellung ist 1. Durch die Einstellung 1 werden Video-Anmerkungen standardmäßig angezeigt, während sie bei 3 nicht angezeigt werden.

list

Durch den list-Parameter wird – in Verbindung mit dem listType-Parameter – der Inhalt identifiziert, der vom Player geladen wird.

  • Wenn der listType-Parameterwert auf search gesetzt wird, legt der list-Parameterwert die zugehörige Suchanfrage fest.
  • Wenn der listType-Parameterwert auf user_uploads gesetzt wird, identifiziert der list-Parameterwert den YouTube-Kanal, dessen Videos im Player geladen werden.
  • Wenn der listType-Parameterwert auf playlist gesetzt wird, gibt der list-Parameterwert eine YouTube-Play-ID an. Bei der Festlegung des Parameterwertes musst du hierbei der Play-ID die Buchstabenfolge PL voranstellen, wie im folgenden Beispiel demonstriert wird:
    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

Hinweis: Wenn du Werte für die list- und listType-Parameter festlegst, muss in der URL der IFrame-Einbettung keine Video-ID angegeben werden.

listType

Durch den listType-Parameter wird – in Verbindung mit dem list-Parameter – der Inhalt identifiziert, der vom Player geladen wird. Gültige Parameterwerte sind playlist, search und user_uploads.

Wenn du Werte für die list- und listType-Parameter festlegst, muss in der URL der IFrame-Einbettung keine Video-ID angegeben werden.

loop

Werte: 0 oder 1. Die Standardeinstellung ist 0. Falls der Player zur Wiedergabe eines einzelnen Videos konfiguriert ist, wird dieses Video fortwährend wiederholt, wenn dieser Parameter auf 1 gesetzt wird. Falls es sich um einen Playlist-Player oder einen benutzerdefinierten Player handelt, wird die gesamte Playlist abgespielt und anschließend vollständig wiederholt.

Hinweis: Die Unterstützung dieses Parameters ist beim AS3-Player und in IFrame-Einbettungen eingeschränkt, die sowohl den AS3-Player als auch den HTML5-Player laden könnten. Derzeit ist der loop-Parameter nur dann mit dem AS3-Player kompatibel, wenn er gemeinsam mit dem playlist-Parameter verwendet wird. Wenn du ein einzelnes Video als Schleife wiedergeben möchtest, kannst du den loop-Parameterwert auf 1 und den playlist-Parameterwert auf die Video-ID einstellen, die auch in der Player API-URL angegeben wurde:
http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID

modestbranding

Mit diesem Parameter kannst du einen YouTube-Player verwenden, der kein YouTube-Logo anzeigt. Setze den Parameterwert auf 1, um zu verhindern, dass das YouTube-Logo in der Steuerleiste angezeigt wird. Allerdings wird in der oberen rechten Ecke eines pausierten Videos ein kleines YouTube-Textlabel erscheinen, wenn der Nutzer mit der Maus auf den Player zeigt.

origin

Bei diesem Parameter handelt es sich um eine zusätzliche Sicherheitsmaßnahme für die IFrame API, die nur für IFrame-Einbettungen unterstützt wird. Wenn du die IFrame API verwendest, indem du den enablejsapi-Parameterwert auf 1 setzt, solltest du immer deine Domain als origin-Parameterwert angeben.

playlist

Bei dem Wert für diesen Parameter handelt es sich um eine durch Kommas getrennte Liste von Video-IDs für die Wiedergabe. Wenn du einen Wert festlegst, wird zuerst das Video abgespielt, das über die VIDEO_ID im URL-Pfad angegeben wird. Anschließend folgen die im playlist-Parameter angegebenen Videos.

playsinline

Dieser Parameter legt fest, ob Videos in einem HTML5-Player auf einem iOS-Gerät inline oder im Vollbildmodus wiedergegeben werden. Die folgenden Werte sind gültig:

  • 0: Dieser Wert löst die Wiedergabe im Vollbildmodus aus. Dies ist der aktuelle Standardwert, der sich allerdings ändern kann.
  • 1: Dieser Wert löst die Inline-Wiedergabe für UIWebViews aus, bei deren Erstellung die allowsInlineMediaPlayback-Eigenschaft auf TRUE gesetzt war.

rel

Werte: 0 oder 1. Die Standardeinstellung ist 1. Über diesen Parameter wird festgelegt, ob der Player ähnliche Videos wiedergeben sollte, wenn die Wiedergabe des ersten Videos beendet wurde.

showinfo

Werte: 0 oder 1. Der Standardwert des Parameters ist 1. Wenn du den Parameterwert auf 0 setzt, werden Informationen wie z. B. der Videotitel oder der Name des Uploaders nicht im Player angezeigt, bevor die Videowiedergabe beginnt.

Wenn der Player eine Playlist lädt und du den Parameterwert ausdrücklich auf 1 gesetzt hast, zeigt der Player nach dem Ladevorgang auch Thumbnails für die Videos in der jeweiligen Playlist an. Diese Funktion wird ausschließlich für den AS3-Player unterstützt, da dies der einzige Player ist, der eine Playlist laden kann.

start

Werte: Eine positive ganze Zahl. Dieser Parameter legt eine benutzerdefinierte Startposition für die Videowiedergabe fest. Der Parameterwert gibt hierbei die Sekundenzahl an, die übersprungen wird. Ähnlich wie bei der seekTo-Funktion startet der Player mit dem Keyframe, der am nächsten an der angegebenen Zeit liegt. Dies bedeutet, dass die Wiedergabe in einigen Fällen kurz vor der angeforderten Zeit einsetzt, wobei die Abweichung normalerweise nicht mehr als ca. zwei Sekunden beträgt.

Überarbeitungsverlauf

October 14, 2014

July 18, 2014

  • The new hl parameter can be used to set the player's interface language. The interface language is used for tooltips in the player and also affects the default caption track. The selected caption track may also depend on the availability of caption tracks and user's individual language preferences.

    The parameter's value is an ISO 639-1 two-letter language code, though other language input codes, such as IETF language tags (BCP 47) may also be handled properly.

  • The definition of the playsinline parameter, which only affects HTML5 players on iOS, has been modified slightly. The definition now notes that setting the parameter value to 1 causes inline playback only for UIWebViews created with the allowsInlineMediaPlayback property set to TRUE.

January 28, 2014

  • The playsinline parameter controls whether videos play inline or fullscreen in an HTML5 player on iOS. Setting the value to 1 causes inline playback.

  • The Selecting content to play section has been updated to explain how to find YouTube video IDs and playlist IDs using the YouTube Data API (v3) rather than the older API version.

  • The controls parameter's definition has been updated to reflect the fact that the parameter value only affects the time that the Flash player actually loads in IFrame embeds. In addition, for IFrame embeds, the parameter value also determines when the controls display in the player. If you set the parameter's value to 2, then the controls display and the Flash player loads after the user initiates the video playback.

May 10, 2013

This update contains the following changes:

July 20, 2012

This update contains the following changes:

  • The definition of the controls parameter has been updated to reflect support for a parameter value of 2 and to explain that, for AS3 players, the parameter value determines the time when the Flash player actually loads. If the controls parameter is set to 0 or 1, the Flash player loads immediately. If the parameter value is 2, the Flash player does not load until the video playback is initiated.

June 5, 2012

This update contains the following changes:

  • The HTML5 player now supports the color, modestbranding, and rel parameters, and the definitions for these parameters have been updated accordingly.

  • The definition of the showinfo parameter has been updated to explain how that if the player is loading a playlist, and you explicitly set the parameter value to 1, then, upon loading, the player will also display thumbnail images for the videos in the playlist. Note that this functionality is only supported for the AS3 player since that is the only player that can load a playlist.

May 4, 2012

This update contains the following changes:

  • The showinfo parameter's definition has been updated to reflect the fact that the HTML5 player supports this parameter.

May 3, 2012

This update contains the following changes:

  • The new end parameter specifies the time, measured in seconds from the start of the video, when the player should stop playing a video. Note that the time when playback is stopped is measured from the beginning of the video and not from the value of either the start player parameter or the startSeconds parameter, which is used in YouTube Player API functions for loading or queueing a video.

March 29, 2012

This update contains the following changes:

  • The new Embedding a YouTube player section explains different ways to embed a YouTube player in your application. This section covers manual IFrame embeds, IFrame embeds that use the IFrame Player API, and AS3 and AS2 object embeds. This section incorporates information from the old Example usage section, which has been removed.

  • The new Selecting content to play section explains how to configure the player to load a video, a playlist, search results for a specified query, or uploaded videos for a specified user.

  • The new list and listType parameters let you specify the content that the player should load. You can specify a playlist, a search query, or a particular user's uploaded videos.

  • The definitions of the fs and rel parameters have been updated to more clearly explain the default parameter values for the AS3 player.

  • The border, color1, egm, hd, and showsearch parameters, which are all only supported for the deprecated AS2 Player API, have been moved to a new section named deprecated parameters only used in the AS2 Player API.

  • The document no longer provides a way to filter the parameter list to only display parameters supported in either the AS3, AS2, or HTML5 player. Instead, each parameter definition has been updated to identify the players that support that parameter.

August 11, 2011

This update contains the following changes:

  • The new theme and color parameters let you customize the appearance of the embedded player's player controls. See the YouTube API blog for more information.

June 8, 2011

This update contains the following changes:

  • The new modestbranding parameter lets you use a YouTube player that does not show a YouTube logo. As of this release, the parameter was only supported for the AS3 embedded player and for IFrame embeds that loaded the AS3 player. As of June 5, 2012, the HTML5 player also supported this parameter.

February 14, 2011

This update contains the following changes:

  • The documentation has been updated to note that the AS2 Player API has been deprecated. The deprecation of the AS2 Player API was actually announced on October 14, 2009.

February 3, 2011

This update contains the following changes:

  • The documentation has been updated to identify parameters supported in the HTML5 (IFrame) embedded player.

  • The document now displays all of the parameters supported in any of YouTube's embedded players (HTML5, AS3, AS2).

  • The following parameters are supported in the AS2 player but have been deprecated for the newer AS3 and HTML5 players: border, color1, color2, egm, hd, and showsearch.

    In addition, the loop parameter has limited support in the AS3 player and in IFrame embeds, which could load either an AS3 or HTML player. Currently, the loop parameter only works in the AS3 player when used in conjunction with the playlist parameter. To loop a single video, set the loop parameter to 1 and set the playlist parameter value to the same video ID already specified in the Player API URL:

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

    Similarly, the controls and playlist parameters are supported in the AS3 and HTML5 players but are not and will not be supported in the AS2 player.

    As noted above, IFrame embeds can load either an AS3 or HTML5 player. Though some parameters are not supported in both players, an IFrame embed that loads the AS3 player will support all parameters that work with that player and ignore all other parameters. Similarly, an IFrame embed that loads the HTML5 player will support all parameters that work with that player while ignoring all other parameters.

  • The parameter list has been updated to include the autohide parameter, which indicates whether the player's video controls will automatically hide after a video begins playing.

  • The parameter list has been updated to include the controls parameter, which indicates whether the player's video controls will display at all. (Player controls do display by default.)

  • The parameter list has been updated to include the playlist parameter, which specifies a comma-separated list of video IDs to play.

  • The definition of the fs has been updated to note that the fullscreen option will not work if you load the YouTube player into another SWF.

  • The example at the end of the document has been updated to use the embedded AS3 player instead of the embedded AS2 player. The parameters used in the example have also been updated to only include parameters that the AS3 player supports.

    In addition, the instructions for constructing the URLs that contain player parameters have been updated to reflect the URL formats used by the AS3 and AS2 embedded and chromeless players as well as by the HTML5 player.