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

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.