Parametry odtwarzacza

Przegląd

W tym dokumencie opisany jest sposób umieszczania odtwarzacza YouTube w aplikacji oraz parametry, które są dostępne w takim odtwarzaczu.

Sposób odtwarzania można modyfikować przez dodanie odpowiednich parametrów do elementu IFrame do URL. Parametr autoplay pozwala na przykład automatycznie włączać odtwarzanie, a parametr loop sprawia, że wideo jest odtwarzane w pętli. Parametr enablejsapi pozwala dodatkowo włączyć dla odtwarzacza interfejs API JavaScript.

W tej chwili na tej stronie zdefiniowane są wszystkie parametry, jakie obsługuje dowolny umieszczony odtwarzacz YouTube. W każdej definicji parametru są podane obsługujące go odtwarzacze.

Uwaga: Odtwarzacz umieszczony na stronie musi mieć okno wyświetlania o rozmiarze co najmniej 200 x 200 pikseli. Jeżeli w odtwarzaczu mają być widoczne elementy sterujące, musi on być na tyle duży, aby elementy te były całkowicie widoczne bez zmniejszania okna wyświetlania poniżej rozmiaru minimalnego. W przypadku odtwarzaczy 16:9 zalecamy rozmiar co najmniej 480 pikseli szerokości i 270 pikseli wysokości.

Umieszczanie odtwarzacza YouTube

Aby umieścić w swojej aplikacji odtwarzacz YouTube i określić jego parametry, możesz użyć dowolnej z wymienionych tu metod. Zwróć uwagę, że podane instrukcje dotyczą umieszczania odtwarzacza, w którym wczytywany jest jeden film. W sekcji poniżej wyjaśniono, jak skonfigurować odtwarzacz tak, aby ładował inne rodzaje zawartości, na przykład playlisty albo wyniki wyszukiwania.

Odtwarzacze umieszczone z użyciem elementu IFrame i korzystające z tagów <iframe>

Zdefiniuj w aplikacji tag <iframe>, w którym URL w parametrze src będzie oznaczać materiał do wczytania. Dodatkowo ustaw pozostałe parametry odtwarzacza, które chcesz zdefiniować. Parametry height i width tagu <iframe> określają rozmiary odtwarzacza.

Jeżeli nie korzystasz z interfejsu API IFrame odtwarzacza, tylko tworzysz element <iframe> samodzielnie, to parametry odtwarzacza możesz dopisać bezpośrednio na końcu URL-a. Format adresu jest następujący:

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

Pokazany tag <iframe> ładuje odtwarzacz o rozmiarach 640x360 pikseli, który odtwarza film YouTube M7lc1UVf-VE. W URL-u parametr autoplay ma wartość 1, więc film zostanie odtworzony automatycznie po wczytaniu odtwarzacza.

<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"/>

Odtwarzacze umieszczone z użyciem elementu IFrame i korzystające z interfejsu API IFrame odtwarzacza

Aby po załadowaniu kodu JavaScript Player API wstawić na stronie lub w aplikacji odtwarzacz wideo, zastosuj się do instrukcji interfejsu API odtwarzacza w elemencie IFrame. Drugi parametr konstruktora odtwarzacza to obiekt określający jego opcje. Znajdująca się w nim zmienna playerVars określa parametry odtwarzacza.

Pokazany poniżej kod HTML i JavaScript jest prostym przykładem wstawienia odtwarzacza YouTube w elemencie strony, którego wartość ytplayer wynosi id. Określona tu funkcja onYouTubePlayerAPIReady() jest wywoływana automatycznie po załadowaniu kodu API IFrame odtwarzacza. Ten kod nie określa parametrów odtwarzacza ani nie definiuje innych modułów obsługi zdarzeń.

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

Wybieranie materiału do odtwarzania

Dzięki odpowiednim ustawieniom konfiguracji w umieszczonym odtwarzaczu mogą być wczytywane klipy wideo, playlisty, filmy przesłane przez wybranego użytkownika lub wyniki wyszukiwań wskazanych haseł.

Opis opcji znajduje się na liście poniżej:

  • Wczytywanie filmu

    Identyfikator filmu YouTube, który ma być załadowany w odtwarzaczu umieszczonym w elemencie IFrame, jest podany w URL-u parametru src tego elementu.

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

    Jeżeli korzystasz z interfejsu YouTube Data API (v3), możesz programowo tworzyć te URL-e, pobierając identyfikatory filmów z wyników wyszukiwania, zasobów zawartości playlist, zasobów wideo oraz innych zasobów. Aby utworzyć URL odtwarzacza, zastąp tekst VIDEO_ID w powyższym adresie uzyskanym identyfikatorem filmu.

  • Wczytywanie playlisty

    Ustaw wartość parametru listType odtwarzacza na playlist. Dodatkowo jako wartość parametru list odtwarzacza ustaw identyfikator playlisty YouTube, którą chcesz załadować.

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

    Zwróć uwagę, że musisz poprzedzić go literami PL – tak jak widać w przykładzie poniżej:

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

    Jeżeli korzystasz z interfejsu YouTube Data API (v3), możesz programowo tworzyć te URL-e, pobierając identyfikatory playlist z wyników wyszukiwania, zasobów kanału lub zasobów aktywności. Po uzyskaniu identyfikatora playlisty zastąp jego wartością tekst PLAYLIST_ID w URL-u powyżej.

  • Wczytywanie filmów przesłanych przez użytkownika

    Ustaw wartość parametru listType odtwarzacza na user_uploads. Dodatkowo jako wartość parametru list odtwarzacza podaj nazwę użytkownika YouTube, którego filmy chcesz wczytywać.

    http://www.youtube.com/embed?listType=user_uploads&list=USERNAME

  • Wczytywanie wyników wyszukiwania dla określonego zapytania

    Ustaw wartość parametru listType odtwarzacza na search. Dodatkowo jako wartość parametru list odtwarzacza ustaw frazę wyszukiwania, którego wyniki mają być wczytane w odtwarzaczu.

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

Parametry

Wszystkie parametry podane poniżej są opcjonalne.

Parameters

autoplay

 Wartości: 0 lub 1. Domyślna wartość to 0. Określa, czy odtwarzanie pierwszego filmu ma się zacząć automatycznie po wczytaniu odtwarzacza.

cc_load_policy

 Wartości: 1. Wartość domyślna zależy od preferencji użytkownika. Przy ustawieniu 1 napisy ukażą się domyślnie, nawet jeśli użytkownik wcześniej je wyłączy.

color

 Parametr określa, jakim kolorem będzie zaznaczana obejrzana część filmu na pasku postępu wideo. Prawidłowe wartości to red i white, a domyślnym kolorem jest czerwony. Więcej informacji o dostępnych kolorach znajdziesz na blogu API YouTube.

Uwaga: ustawienie wartości white dla parametru color wyłącza opcję modestbranding.

controls

 Wartości: 0, 1 lub 2. Domyślna wartość to 1. Ten parametr określa, czy będą wyświetlane elementy sterujące odtwarzaczem. W przypadku odtwarzaczy Flash, które są umieszczane z użyciem elementu IFrame, określa on dodatkowo moment ukazania się tych elementów w odtwarzaczu oraz moment załadowania samego odtwarzacza:

  • controls=0 – elementy sterujące odtwarzaczem nie są widoczne. Przy umieszczaniu poprzez element IFrame odtwarzacz Flash jest wczytywany natychmiast.
  • controls=1 – elementy sterujące odtwarzaczem są widoczne. Przy umieszczaniu poprzez element IFrame elementy sterujące pokazują się od razu, a odtwarzacz Flash jest wczytywany natychmiast.
  • controls=2 – elementy sterujące odtwarzaczem są widoczne. Przy umieszczaniu poprzez element IFrame elementy sterujące pokazują się od razu, a odtwarzacz Flash jest wczytywany, gdy użytkownik rozpocznie odtwarzanie filmu.

Uwaga: wartości 1 i 2 z założenia działają tak samo, ale przy umieszczaniu poprzez element IFrame ustawienie controls=2 daje lepszą wydajność niż controls=1. Obecnie ustawienie jednej lub drugiej wartości wiąże się z pewnymi różnicami w wyglądzie odtwarzacza, na przykład tytuł filmu jest podany innym rozmiarem czcionki. Jednak gdy różnica stanie się niezauważalna, wartość domyślna może się zmienić z 1 na 2.

disablekb

 Wartości: 0 lub 1. Domyślna wartość to 0. Wartość 1 wyłącza sterowanie odtwarzaczem z klawiatury. Klawisze sterujące to:

  • Spacja: odtwarzanie/pauza
  • Strzałka w lewo: przeskok wstecz o 10% w odtwarzanym filmie
  • Strzałka w prawo: przeskok do przodu o 10% w odtwarzanym filmie
  • Strzałka w górę: zwiększenie głośności
  • Strzałka w górę: zmniejszenie głośności

enablejsapi

 Wartości: 0 lub 1. Domyślna wartość to 0. Ustawienie 1 włącza Javascript API. Więcej informacji o tym interfejsie API i korzystaniu z niego znajdziesz w dokumentacji JavaScript API.

end

 Wartość: dodatnia liczba całkowita. Ten parametr określa czas (w sekundach) mierzony od początku odtwarzania wideo, po upływie którego odtwarzanie powinno zostać wyłączone. Zwróć uwagę, że ten czas jest mierzony od początku filmu, a nie oparty na wartości parametru odtwarzacza start ani wartości parametru odtwarzacza startSeconds, które są używane w funkcjach API odtwarzacza YouTube do ładowania lub kolejkowania filmów.

fs

 Wartości: 0 lub 1. Domyślna wartość wynosi 1 i powoduje wyświetlenie przycisku trybu pełnoekranowego. Ustawienie wartości 0 sprawia, że ten przycisk się nie pojawia.

hl

 Określa język interfejsu odtwarzacza. Wartością tego parametru jest dwuliterowy kod języka w standardzie ISO 639-1, choć możliwa jest też prawidłowa obsługa innych kodów języków, na przykład tagów IETF (BCP 47).

Język interfejsu służy do wyświetlania podpowiedzi w odtwarzaczu, ma też wpływ na to, jaka będzie domyślna ścieżka napisów. Pamiętaj, że YouTube może wybrać dla jakiegoś użytkownika inny język ścieżki napisów, opierając się na jego preferencjach językowych oraz dostępności ścieżek.

iv_load_policy

 Wartości: 1 lub 3. Domyślna wartość to 1. Ustawienie 1 spowoduje, że adnotacje w filmach będą domyślnie pokazywane, a przy ustawieniu 3 będą one domyślnie niewidoczne.

list

 Parametr list w połączeniu z listType wskazuje materiał, który zostanie załadowany w odtwarzaczu.

  • Jeśli parametr listType ma wartość search, to wartość parametru list określa wyszukiwane hasło.
  • Jeżeli parametr listType ma wartość user_uploads, to parametr list wskazuje kanał YouTube, z którego będą wczytywane filmy.
  • Jeżeli parametr listType ma wartość playlist, to parametr list wskazuje identyfikator playlisty YouTube. Jak widać na przykładzie poniżej, identyfikator ten trzeba poprzedzić literami PL.
    http://www.youtube.com/embed?listType=playlist&list=PLC77007E23FF423C6

Uwaga: w przypadku podania wartości parametrów list i listType, w URL-u odtwarzacza umieszczanego poprzez element IFrame nie trzeba już podawać identyfikatora filmu.

listType

 Parametr listType użyty w połączeniu z parametrem list wskazuje zawartość, która ma być załadowana do odtwarzacza. Prawidłowe wartości tego parametru to playlist, search i user_uploads.

Jeżeli zostaną podane wartości dla parametrów list i listType, to w URL-u odtwarzacza umieszczanego poprzez IFrame nie trzeba określać identyfikatora filmu.

loop

 Wartości: 0 lub 1. Domyślna wartość to 0. Ustawienie wartości 1 dla odtwarzacza, który wyświetla jeden film, spowoduje odtwarzanie tego filmu w pętli. Odtwarzacze playlist (lub niestandardowe) będą odtwarzać całą playlistę, przechodzić z powrotem do pierwszego wideo i zaczynać od początku.

Uwaga: obsługa tego parametru jest ograniczona w odtwarzaczach AS3 oraz odtwarzaczach umieszczanych w elemencie IFrame, które mogą wczytywać odtwarzacze AS3 lub HTML5. Parametr loop działa w odtwarzaczach AS3 tylko wtedy, gdy jest użyty razem z parametrem playlist. Jeśli chcesz odtwarzać pojedynczy film w pętli, ustaw dla parametru loop wartość 1, a jako wartość parametru playlist podaj identyfikator filmu, który jest już wpisany w URL-u API odtwarzacza:
http://www.youtube.com/v/VIDEO_ID?version=3&loop=1&playlist=VIDEO_ID

modestbranding

 Ten parametr pozwala użyć odtwarzacza YouTube, w którym nie jest wyświetlane logo YouTube. Wartość 1 sprawi, że logo YouTube nie pokaże się na pasku sterowania. Jednak mimo tego, gdy po wstrzymaniu odtwarzania filmu użytkownik najedzie wskaźnikiem na odtwarzacz, w prawym górnym rogu pokaże się mała tekstowa etykietka YouTube.

origin

 Ten parametr dostarcza dodatkowych zabezpieczeń dla API IFrame i jest obsługiwany tylko w przypadku umieszczenia odtwarzacza za pośrednictwem elementu IFrame. Jeżeli korzystasz z API IFrame (czyli dla parametru enablejsapi ustawiasz wartość 1), jako wartość parametru origin musisz wpisać swoją domenę.

playlist

 Wartością jest rozdzielana przecinkami lista identyfikatorów filmów, które mają być odtworzone. Jeśli zostanie określona, to jako pierwszy zostanie odtworzony film, którego VIDEO_ID jest podane w URL-u, a filmy wskazane poprzez parametr playlist będą odtwarzane w dalszej kolejności.

playsinline

 Ten parametr decyduje czy filmy wyświetlane w odtwarzaczu HTML5 w systemie iOS ukazują się w treści strony czy na pełnym ekranie. Prawidłowe wartości to:

  • 0: film jest odtwarzany w trybie pełnoekranowym. W tej chwili jest to wartość domyślna, ale może to ulec zmianie.
  • 1:ta wartość sprawia, że odtwarzacz umieszczony za pomocą elementu UIWebViews utworzonego przy użyciu wartości TRUE właściwości allowsInlineMediaPlayback wyświetla film w treści strony.

rel

 Wartości: 0 lub 1. Domyślna wartość to 1. Ten parametr określa, czy po zakończeniu odtwarzania wybranego wideo w odtwarzaczu powinny być pokazane podobne filmy.

showinfo

 Wartości: 0 lub 1. Domyślna wartość tego parametru to 1. Ustawienie 0 jako wartości tego parametru powoduje, że przed rozpoczęciem wyświetlania filmu odtwarzacz nie pokazuje takich informacji, jak tytuł filmu czy nazwa przesyłającego.

Jeżeli w odtwarzaczu jest wczytywana playlista, a jako wartość parametru zostanie ustawione 1, to po załadowaniu zawartości odtwarzacz pokaże także miniatury filmów z playlisty. Zwróć uwagę, że ta funkcja może być użyta tylko z odtwarzaczem AS3, ponieważ jest to jedyny typ odtwarzacza, który może wczytać playlistę.

start

 Wartość: dodatnia liczba całkowita. Ten parametr powoduje, że film jest odtwarzany od określonej sekundy. Podobnie jak w przypadku funkcji seekTo odtwarzacz będzie poszukiwać najbliższej podanemu momentowi klatki kluczowej. To znaczy, że suwak odtwarzania może się czasem ustawić nieco wcześniej od żądanego momentu, ale na ogół nie więcej niż ok. dwie sekundy.

Historia wersji

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.