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="?url=http%3A%2F%2Fwww.youtube.com%2Fembed%2FM7lc1UVf-VE%3Fautoplay%3D1%26amp%3Borigin%3Dhttp%3A%2F%2Fexample.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

The HTML5 player now supports the cc_load_policy, disablekb, end, fs, list, and listType parameters. The parameter descriptions have been updated accordingly.

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.