YouTube Player API Reference for iframe Embeds

Interfejs IFrame Player API umożliwia osadzenie odtwarzacza filmów YouTube w witrynie i sterowanie jego działaniem za pomocą języka JavaScript.

Za pomocą funkcji tego interfejsu API pisanych w języku JavaScript możesz kolejkować filmy do odtwarzania, odtwarzać te filmy oraz wstrzymywać i zatrzymywać ich odtwarzanie, dostosowywać poziom głośności odtwarzacza lub pobierać informacje o odtwarzanym filmie. Możesz też dodać odbiorniki zdarzeń, które będą wykonywane w odpowiedzi na określone zdarzenia odtwarzacza, np. zmianę stanu odtwarzacza.

Z tego przewodnika dowiesz się, jak korzystać z interfejsu IFrame API. W tym artykule opisano różne typy zdarzeń, które może wysyłać interfejs API, oraz wyjaśniono, jak pisać odbiorniki zdarzeń, aby na nie odpowiadać. Podręcznik zawiera też szczegółowy opis różnych funkcji języka JavaScript, które możesz wywoływać, by sterować odtwarzaczem filmów, a także parametrów odtwarzacza, które umożliwiają jego dostosowywanie.

Wymagania

Przeglądarka użytkownika musi obsługiwać funkcję HTML5 postMessage. Większość nowoczesnych przeglądarek obsługuje postMessage.

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.

Każda strona, na której jest używany interfejs IFrame API, musi także implementować następującą funkcję JavaScript:

  • onYouTubeIframeAPIReady – interfejs API wywoła tę funkcję, gdy skończy się pobieranie kodu JavaScript dla interfejsu API odtwarzacza, co umożliwi Ci korzystanie z interfejsu API na stronie. Dzięki temu funkcja ta może tworzyć obiekty odtwarzacza, które mają się pojawiać po wczytaniu strony.

Pierwsze kroki

Na przedstawionej poniżej przykładowej stronie HTML umieszczany jest odtwarzacz, który wczytuje film, odtwarza go przez sześć sekund, a następnie zatrzymuje odtwarzanie. Komentarze opatrzone numerami w kodzie HTML są objaśnione na liście znajdującej się pod tym przykładem.

<!DOCTYPE html>
<html>
  <body>
    <!-- 1. The <iframe> (and video player) will replace this <div> tag. -->
    <div id="player"></div>

    <script>
      // 2. This code loads the IFrame Player API code asynchronously.
      var tag = document.createElement('script');

      tag.src = "https://www.youtube.com/iframe_api";
      var firstScriptTag = document.getElementsByTagName('script')[0];
      firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

      // 3. This function creates an <iframe> (and YouTube player)
      //    after the API code downloads.
      var player;
      function onYouTubeIframeAPIReady() {
        player = new YT.Player('player', {
          height: '390',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          playerVars: {
            'playsinline': 1
          },
          events: {
            'onReady': onPlayerReady,
            'onStateChange': onPlayerStateChange
          }
        });
      }

      // 4. The API will call this function when the video player is ready.
      function onPlayerReady(event) {
        event.target.playVideo();
      }

      // 5. The API calls this function when the player's state changes.
      //    The function indicates that when playing a video (state=1),
      //    the player should play for six seconds and then stop.
      var done = false;
      function onPlayerStateChange(event) {
        if (event.data == YT.PlayerState.PLAYING && !done) {
          setTimeout(stopVideo, 6000);
          done = true;
        }
      }
      function stopVideo() {
        player.stopVideo();
      }
    </script>
  </body>
</html>

Poniższa lista zawiera szczegółowe informacje dotyczące przykładu przedstawionego powyżej:

  1. Tag <div> w tej sekcji wskazuje lokalizację na stronie, w której interfejs IFrame API umieści odtwarzacz wideo. Konstruktor obiektu playera, który jest opisany w sekcji Ładowanie odtwarzacza wideo, identyfikuje tag <div> za pomocą jego id, aby zapewnić, że interfejs API umieści tag <iframe> we właściwym miejscu. W szczególności interfejs IFrame API zastąpi tag <div> tagiem <iframe>.

    Możesz też umieścić element <iframe> bezpośrednio na stronie. W sekcji Wczytywanie odtwarzacza wideo znajdziesz instrukcje.

  2. Kod znajdujący się w tej sekcji wczytuje kod JavaScript interfejsu IFrame Player API. W tym przykładzie do pobrania kodu API jest używana zmodyfikowana specyfikacja DOM, co zapewnia możliwość asynchronicznego pobierania kodu Atrybut async tagu <script>, który umożliwia też pobieranie asynchroniczne, nie jest jeszcze obsługiwany we wszystkich nowoczesnych przeglądarkach, jak wyjaśniono w tej odpowiedzi na Stack Overflow.

  3. Funkcja onYouTubeIframeAPIReady zostanie wykonana, gdy tylko zostanie pobrany kod interfejsu API odtwarzacza. Ten fragment kodu definiuje zmienną globalną player, która odnosi się do odtwarzacza wideo, który umieszczasz, a funkcja tworzy obiekt odtwarzacza wideo.

  4. Funkcja onPlayerReady zostanie wykonana, gdy wystąpi zdarzenie onReady. W tym przykładzie funkcja ta wskazuje, że kiedy odtwarzacz filmów jest gotowy, powinien rozpocząć odtwarzanie.

  5. Gdy stan odtwarzacza ulegnie zmianie, interfejs API wywoła funkcję onPlayerStateChange, co może oznaczać, że odtwarzacz jest w stanie odtwarzania, wstrzymania, zakończenia itp. Funkcja wskazuje, że gdy stan odtwarzacza to 1 (odtwarzanie), odtwarzanie powinno trwać 6 sekund, a potem wywołać funkcję stopVideo, aby zatrzymać film.

Wczytywanie odtwarzacza filmów

Po wczytaniu kodu JavaScript interfejsu API zostanie wywołana funkcja onYouTubeIframeAPIReady, po czym możesz utworzyć obiekt YT.Player, aby wstawić na stronie odtwarzacz wideo. Fragment kodu HTML poniżej zawiera funkcję onYouTubeIframeAPIReady z powyższego przykładu:

var player;
function onYouTubeIframeAPIReady() {
  player = new YT.Player('player', {
    height: '390',
    width: '640',
    videoId: 'M7lc1UVf-VE',
    playerVars: {
      'playsinline': 1
    },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange
    }
  });
}

Konstruktor odtwarzacza filmów określa następujące parametry:

  1. Pierwszy parametr określa element DOM lub id elementu HTML, w którym interfejs API wstawi tag <iframe> zawierający odtwarzacz.

    Interfejs IFrame API zastąpi określony element elementem <iframe> zawierającym odtwarzacz. Może to wpłynąć na układ strony, jeśli zastępowany element ma inny styl wyświetlania niż wstawiony element <iframe>. Domyślnie element <iframe> jest wyświetlany jako element inline-block.

  2. Drugim parametrem jest obiekt określający opcje odtwarzacza. Obiekt zawiera te właściwości:
    • width (liczba) – szerokość odtwarzacza. (wartością domyślną jest 640);
    • height (liczba) – wysokość odtwarzacza. (wartością domyślną jest 390);
    • videoId (ciąg znaków) – identyfikator filmu w YouTube, który identyfikuje film, który odtwarzacz ma wczytać.
    • playerVars (obiekt) – właściwości obiektu identyfikują parametry odtwarzacza, których można używać do dostosowywania odtwarzacza.
    • events (obiekt) – właściwości obiektu wskazują zdarzenia wywoływane przez interfejs API oraz funkcje (słuchacze zdarzeń), które interfejs API wywoła, gdy wystąpią te zdarzenia. W tym przykładzie konstruktor wskazuje, że funkcja onPlayerReady zostanie wykonana po wywołaniu zdarzenia onReady, a funkcja onPlayerStateChange – po wywołaniu zdarzenia onStateChange.

Jak wspomnieliśmy w sekcji Pierwsze kroki, zamiast umieszczać na stronie pusty element <div>, który kod JavaScript interfejsu API odtwarzacza zastąpi elementem <iframe>, możesz utworzyć tag <iframe> samodzielnie. Pierwszy przykład w sekcji Przykłady pokazuje, jak to zrobić.

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

Pamiętaj, że jeśli napiszesz tag <iframe>, podczas tworzenia obiektu YT.Player nie musisz podawać wartości parametrów width i height, które są podawane jako atrybuty tagu <iframe>, ani parametrów videoId i player, które są podawane w adresie URL src. Jako dodatkowy środek bezpieczeństwa dodaj do adresu URL parametr origin, podając jako jego wartość schemat adresu URL (http:// lub https://) i pełną domenę strony hosta. origin jest opcjonalny, ale jego uwzględnienie chroni przed wstrzyknięciem na Twoją stronę złośliwego kodu JavaScript pochodzącego od osób trzecich i przejęciem kontroli nad odtwarzaczem YouTube.

Inne przykłady tworzenia obiektów odtwarzacza wideo znajdziesz w sekcji Przykłady.

Operacje

Aby wywoływać metody interfejsu API odtwarzacza, musisz najpierw uzyskać odniesienie do obiektu odtwarzacza, który chcesz kontrolować. Odniesienie uzyskuje się przez utworzenie obiektu YT.Player, jak opisano w sekcjach Wprowadzenie i Ładowanie odtwarzacza filmów tego dokumentu.

Funkcje

Funkcje kolejkujące

Funkcje kolejkujące umożliwiają wczytanie i odtworzenie filmu, playlisty lub innej listy filmów. Jeśli do wywoływania tych funkcji używasz opisanej poniżej składni obiektu, możesz też umieścić w kolejce lub załadować listę przesłanych przez użytkownika filmów.

Interfejs API obsługuje dwie różne składnie wywoływania funkcji kolejkujących.

  • Składnia argumentów wymaga, by wymienić argumenty funkcji w określonej kolejności.

  • Składnia obiektu umożliwia przekazanie pojedynczego parametru w postaci obiektu o zdefiniowanych właściwościach odpowiadających argumentom funkcji, które chcesz ustawić. Oprócz tego interfejs API może obsłużyć dodatkowe funkcje, których nie obsługuje składnia argumentów.

Na przykład funkcję loadVideoById można wywołać na jeden z tych sposobów. Pamiętaj, że składnia obiektu obsługuje właściwość endSeconds, której nie obsługuje składnia argumentów.

  • Składnia argumentów

    loadVideoById("bHQqvYy5KYo", 5, "large")

  • Składnia obiektu

    loadVideoById({'videoId': 'bHQqvYy5KYo',
               'startSeconds': 5,
               'endSeconds': 60});

Funkcje kolejkujące do obsługi filmów

cueVideoById

  • Składnia argumentów

    player.cueVideoById(videoId:String,
                    startSeconds:Number):Void

  • Składnia obiektu

    player.cueVideoById({videoId:String,
                     startSeconds:Number,
                     endSeconds:Number}):Void

Ta funkcja wczytuje miniaturę określonego filmu i przygotowuje odtwarzacz do jego odtworzenia. Odtwarzacz nie wysyła żądania pliku FLV, dopóki nie zostanie wywołana funkcja playVideo() lub seekTo().

  • Wymagany parametr videoId określa identyfikator filmu w YouTube, który ma zostać odtworzony. W interfejsie YouTube Data API identyfikator określa właściwość video zasobu id.
  • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite i określa czas, od którego film ma się zacząć odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość startSeconds, a następnie wywołasz funkcję seekTo(), odtwarzacz odtwarza od czasu określonego w wywołaniu funkcji seekTo(). Gdy film jest gotowy do odtworzenia, odtwarzacz wyśle do urządzenia sygnał o video cued zdarzeniu (5).
  • Opcjonalny parametr endSeconds, który jest obsługiwany tylko w składni obiektowej, przyjmuje wartość zmiennoprzecinkową lub całkowitą i określa czas, w którym film ma przestać się odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość endSeconds, a potem wywołasz funkcję seekTo(), wartość endSeconds przestanie obowiązywać.

loadVideoById

  • Składnia argumentów

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

  • Składnia obiektu

    player.loadVideoById({videoId:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

Ta funkcja wczytuje i odtwarza określony film.

  • Wymagany parametr videoId określa identyfikator filmu w YouTube, który ma zostać odtworzony. W interfejsie YouTube Data API identyfikator określa właściwość video zasobu id.
  • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite. Jeśli jest określony, odtwarzanie filmu rozpoczyna się od klatki kluczowej znajdującej się najbliżej podanego czasu.
  • Opcjonalny parametr endSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite. Jeśli jest określony, odtwarzanie filmu zatrzymuje się w podanym czasie.

cueVideoByUrl

  • Składnia argumentów

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

  • Składnia obiektu

    player.cueVideoByUrl({mediaContentUrl:String,
                      startSeconds:Number,
                      endSeconds:Number}):Void

Ta funkcja wczytuje miniaturę określonego filmu i przygotowuje odtwarzacz do jego odtworzenia. Odtwarzacz nie wysyła żądania pliku FLV, dopóki nie zostanie wywołana funkcja playVideo() lub seekTo().

  • Wymagany parametr mediaContentUrl określa pełny adres URL odtwarzacza YouTube w formacie http://www.youtube.com/v/VIDEO_ID?version=3.
  • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite i określa czas, od którego film ma się zacząć odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz startSeconds, a następnie wywołasz seekTo(), odtwarzanie rozpocznie się od czasu określonego w wywołaniu seekTo(). Gdy film jest gotowy do odtworzenia, odtwarzacz wyśle sygnał video cued (5).
  • Opcjonalny parametr endSeconds, który jest obsługiwany tylko w składni obiektu, przyjmuje wartość zmiennoprzecinkową lub całkowitą i określa czas, w którym film ma przestać się odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość endSeconds, a potem wywołasz funkcję seekTo(), wartość endSeconds przestanie obowiązywać.

loadVideoByUrl

  • Składnia argumentów

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

  • Składnia obiektu

    player.loadVideoByUrl({mediaContentUrl:String,
                       startSeconds:Number,
                       endSeconds:Number}):Void

Ta funkcja wczytuje i odtwarza określony film.

  • Wymagany parametr mediaContentUrl określa pełny adres URL odtwarzacza YouTube w formacie http://www.youtube.com/v/VIDEO_ID?version=3.
  • Opcjonalny parametr startSeconds może mieć wartość zmiennoprzecinkową lub całkowitą i określa czas, od którego ma się rozpocząć odtwarzanie filmu. Jeśli określona jest wartość startSeconds (może to być liczba zmiennoprzecinkowa), film rozpocznie się od najbliższego kluczowego obrazu do podanego czasu.
  • Opcjonalny parametr endSeconds, który jest obsługiwany tylko w składni obiektu, przyjmuje wartość zmiennoprzecinkową lub całkowitą i określa czas, w którym film ma się zatrzymać.

Funkcje kolejkujące do obsługi list

Funkcje cuePlaylist i loadPlaylist umożliwiają wczytywanie i odtwarzanie playlisty. Jeśli do wywoływania tych funkcji używasz składni obiektu, możesz też umieścić w kolejce (czyli załadować) listę przesłanych przez użytkownika filmów.

Ponieważ funkcje te działają w różny sposób w zależności od tego, czy zostały wywołane za pomocą składni argumentów czy składni obiektu, poniżej znajduje się dokumentacja obydwu metod wywołania.

cuePlaylist

  • Składnia argumentów

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
     Wstawia określoną playlistę do kolejki. Gdy playlista jest gotowa do odtworzenia, odtwarzacz wyśle do odtwarzacza video cued zdarzenie (5).

    • Wymagany parametr playlist określa tablicę identyfikatorów filmów w YouTube. W interfejsie YouTube Data API właściwość id zasobu video identyfikuje identyfikator filmu.

    • Opcjonalny parametr index określa indeks pierwszego filmu na playliście, który zostanie odtworzony. Parametr używa indeksu opartego na 0, a jego domyślna wartość to 0, więc domyślne działanie polega na wczytaniu i odtwarzaniu pierwszego filmu na playliście.

    • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite i określa czas, od którego pierwsze wideo na playliście powinno się zacząć odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość startSeconds, a następnie wywołasz funkcję seekTo(), odtwarzacz odtwarza od czasu określonego w wywołaniu funkcji seekTo(). Jeśli wskażesz playlistę, a następnie wywołasz funkcję playVideoAt(), odtwarzanie rozpocznie się od początku wskazanego filmu.

  • Składnia obiektu

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
     Wstawia do kolejki określoną listę filmów. Lista może być playlistą lub kanałem z przesłanymi przez użytkownika filmami. Możliwość umieszczania w kolejce listy wyników wyszukiwania została wycofana i od 15 listopada 2020 r. nie będzie już obsługiwana.

    Gdy lista jest gotowa do odtworzenia, odtwarzacz wyśle do urządzenia zdarzenie video cued (5).

    • Opcjonalna właściwość listType określa typ pliku danych z wynikami, który pobierasz. Prawidłowe wartości to playlist i user_uploads. Wycofana wartość search nie będzie już obsługiwana od 15 listopada 2020 r. Wartością domyślną jest playlist.

    • Wymagana właściwość list zawiera klucz, który identyfikuje konkretną listę filmów, którą YouTube powinien zwrócić.

      • Jeśli wartość właściwości listType to playlist, właściwość list określa identyfikator playlisty lub tablicę identyfikatorów filmów. W interfejsie YouTube Data API właściwość id zasobu playlist identyfikuje identyfikator playlisty, a właściwość id zasobu video określa identyfikator filmu.
      • Jeśli wartość właściwości listType to user_uploads, właściwość list wskazuje użytkownika, którego przesłane filmy zostaną zwrócone.
      • Jeśli wartość właściwości listType to search, właściwość list określa zapytanie wyszukiwania. Uwaga: ta funkcja została wycofana i nie będzie już obsługiwana od 15 listopada 2020 r.

    • Opcjonalna właściwość index określa indeks pierwszego filmu na liście, który zostanie odtworzony. Parametr używa indeksu opartego na 0, a jego domyślna wartość to 0, więc domyślne działanie polega na wczytaniu i odtwarzaniu pierwszego filmu na liście.

    • Opcjonalna właściwość startSeconds przyjmuje typ float lub integer i określa czas, od którego pierwsze wideo na liście powinno zacząć się odtwarzać po wywołaniu funkcji playVideo(). Jeśli określisz wartość startSeconds, a następnie wywołasz funkcję seekTo(), odtwarzacz odtwarza od czasu określonego w wywołaniu funkcji seekTo(). Jeśli wprowadzisz listę, a następnie wywołasz funkcję playVideoAt(), odtwarzanie rozpocznie się od początku określonego filmu.

loadPlaylist

  • Składnia argumentu

    player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
     Ta funkcja wczytuje określoną playlistę i odtwarza ją.

    • Wymagany parametr playlist określa tablicę identyfikatorów filmów w YouTube. W interfejsie YouTube Data API właściwość id zasobu video określa identyfikator filmu.

    • Opcjonalny parametr index określa indeks pierwszego filmu na playliście, który zostanie odtworzony. Parametr używa indeksu opartego na 0, a jego domyślna wartość to 0, więc domyślne działanie polega na wczytaniu i odtwarzaniu pierwszego filmu na playliście.

    • Opcjonalny parametr startSeconds może przyjmować wartości zmiennoprzecinkowe lub całkowite i określa czas, od którego ma się rozpocząć odtwarzanie pierwszego filmu na playliście.

  • Składnia obiektu

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
     Ta funkcja wczytuje określoną listę i odtwarza ją. Lista może być playlistą lub kanałem z przesłanymi przez użytkownika filmami. Możliwość wczytania listy wyników wyszukiwania została wycofana i od 15 listopada 2020 r. nie będzie już obsługiwana.

    • Opcjonalna właściwość listType określa typ pliku danych z wynikami, który pobierasz. Prawidłowe wartości to playlist i user_uploads. Wycofana wartość search nie będzie już obsługiwana od 15 listopada 2020 r. Wartością domyślną jest playlist.

    • Wymagana właściwość list zawiera klucz, który identyfikuje konkretną listę filmów, którą YouTube powinien zwrócić.

      • Jeśli wartość właściwości listType to playlist, właściwość list określa identyfikator playlisty lub tablicę identyfikatorów filmów. W interfejsie YouTube Data API właściwość id zasobu playlist określa identyfikator playlisty, a właściwość id zasobu video określa identyfikator filmu.
      • Jeśli wartość właściwości listType to user_uploads, właściwość list wskazuje użytkownika, którego przesłane filmy zostaną zwrócone.
      • Jeśli wartość właściwości listType to search, właściwość list określa zapytanie wyszukiwania. Uwaga: ta funkcja została wycofana i nie będzie już obsługiwana od 15 listopada 2020 r.

    • Opcjonalna właściwość index określa indeks pierwszego filmu na liście, który zostanie odtworzony. Parametr używa indeksu opartego na 0, a jego domyślna wartość to 0, więc domyślne działanie polega na wczytaniu i odtwarzaniu pierwszego filmu na liście.

    • Opcjonalna właściwość startSeconds przyjmuje wartość zmiennoprzecinkową lub całkowitą i określa czas, od którego ma się rozpocząć odtwarzanie pierwszego filmu na liście.

Sterowanie odtwarzaniem i ustawienia odtwarzacza

Odtwarzanie filmu

player.playVideo():Void
Odtwarza aktualnie odtwarzany lub wczytywany film. Ostateczny stan odtwarzacza po wykonaniu tej funkcji to playing (1).

Uwaga: odtworzenie filmu jest liczone do oficjalnej liczby wyświetleń tylko wtedy, gdy zostało zainicjowane za pomocą natywnego przycisku odtwarzania w odtwarzaczu.
player.pauseVideo():Void
Wstrzymuje aktualnie odtwarzany film. Ostateczny stan odtwarzacza po wykonaniu tej funkcji będzie wynosił paused (2), chyba że w momencie wywołania funkcji odtwarzacz jest w stanie ended (0), w którym przypadku stan odtwarzacza się nie zmieni.
player.stopVideo():Void
Zatrzymuje i anuluje wczytywanie bieżącego filmu. Ta funkcja powinna być zarezerwowana na specjalne sytuacje, kiedy wiadomo, że użytkownik nie będzie oglądał w odtwarzaczu więcej filmów. Jeśli chcesz wstrzymać film, po prostu wywołaj funkcję pauseVideo. Jeśli chcesz zmienić film odtwarzany przez odtwarzacz, możesz wywołać jedną z funkcji kolejkowania bez wywoływania funkcji stopVideo.

Ważne: w przeciwieństwie do funkcji pauseVideo, która pozostawia odtwarzacz w stanie paused (2), funkcja stopVideo może ustawić odtwarzacz w dowolnym stanie nieodtwarzania, w tym ended (0), paused (2), video cued (5) lub unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Przechodzi do określonego punktu czasowego filmu. Jeśli w momencie wywołania tej funkcji odtwarzacz jest wstrzymany, to w dalszym ciągu pozostaje wstrzymany. Jeśli funkcja jest wywoływana z innego stanu (playing, video cued itp.), odtwarzacz odtworzy film.

  • Parametr seconds określa czas, do którego ma przejść odtwarzacz.

    Odtwarzacz przewinie film do najbliższej klatki kluczowej przed podanym czasem, chyba że pobrał już część, do której użytkownik chce przewinąć film.

  • Parametr allowSeekAhead określa, czy odtwarzacz wyśle nowe żądanie do serwera, jeśli parametr seconds określa czas poza aktualnie buforowanymi danymi wideo.

    Zalecamy ustawienie tego parametru na false, gdy użytkownik przeciąga kursor po pasku postępu filmu, a potem na true, gdy go puści. Takie podejście sprawia, że użytkownik może przewijać film do różnych miejsc bez konieczności zgłaszania żądań nowych strumieni wideo w przypadku przewinięcia poza część filmu, która znajduje się w buforze. Gdy użytkownik zwolni przycisk myszy, odtwarzacz przewinie film do żądanego miejsca i w razie potrzeby zażąda nowego strumienia wideo.

Sterowanie odtwarzaniem filmów 360°

Uwaga: odtwarzanie filmów w 360° jest ograniczone na urządzeniach mobilnych. Na nieobsługiwanych urządzeniach filmy 360° są zniekształcone i nie można zmienić perspektywy oglądania, np. za pomocą interfejsu API, czujników orientacji czy dotyku lub przeciągania na ekranie urządzenia.

player.getSphericalProperties():Object
Pobiera właściwości, które opisują aktualną perspektywę lub widok widza podczas odtwarzania filmu. Dodatkowo:
  • Ten obiekt jest wypełniany tylko w przypadku filmów 360°, które są też nazywane filmami sferycznymi.
  • Jeśli bieżący film nie jest filmem w panoramie 360° lub jeśli funkcja jest wywoływana z nieobsługiwanego urządzenia, zwraca pusty obiekt.
  • Na obsługiwanych urządzeniach mobilnych, jeśli właściwość enableOrientationSensor ma wartość true, ta funkcja zwraca obiekt, w którym właściwość fov zawiera prawidłową wartość, a inne właściwości mają wartość 0.
Obiekt zawiera te właściwości:
Właściwości
yaw Liczba z zakresu [0, 360], która reprezentuje kąt osi poziomej widoku w stopniach. Odzwierciedla ona, jak bardzo użytkownik obraca widok w kierunku lewej lub prawej strony. Pozycja neutralna, skierowana na środek filmu w projekcji równokątnej, odpowiada 0°. Ta wartość rośnie, gdy widz obraca głowę w lewo.
pitch Liczba z zakresu [-90, 90] reprezentująca kąt pionowy widoku w stopniach, który odzwierciedla, jak bardzo użytkownik dostosowuje widok, aby spojrzeć w górę lub w dół. Pozycja neutralna, skierowana na środek filmu w projekcji równokątnokątnej, odpowiada 0°. Ta wartość rośnie, gdy widz patrzy w górę.
roll Liczba z zakresu [-180, 180], która reprezentuje kąt obrotu widoku w zależności od kierunku obrotu (zgodnie z lub przeciwnie do ruchu wskazówek zegara). Pozycja neutralna, w której oś pozioma w projekcji równokątnym jest równoległa do osi poziomej widoku, odpowiada 0°. Wartość rośnie, gdy widok obraca się zgodnie z kierunkiem ruchu wskazówek zegara, i maleje, gdy obraca się przeciwnie do wskazówek zegara.

Pamiętaj, że wbudowany odtwarzacz nie ma interfejsu umożliwiającego obracanie widoku. Przesunięcie można dostosować na 2 sposoby:
  1. Użyj czujnika orientacji w przeglądarce mobilnej, aby wyświetlić widok przechylony. Jeśli czujnik orientacji jest włączony, funkcja getSphericalProperties zawsze zwraca 0 jako wartość właściwości roll.
  2. Jeśli czujnik orientacji jest wyłączony, ustaw przechylenie na wartość niezerową za pomocą tego interfejsu API.
fov Liczba z zakresu [30, 120], która reprezentuje pole widzenia widoku w stopniach mierzonych wzdłuż dłuższego boku widocznego obszaru. Krótsza krawędź jest automatycznie dostosowywana, aby zachować proporcje widoku.

Domyślna wartość to 100 stopni. Zmniejszenie wartości jest jak powiększenie obrazu, a zwiększenie wartości jest jak oddalenie. Wartość tę można dostosować za pomocą interfejsu API lub kółka myszy, gdy film jest w trybie pełnoekranowym.
player.setSphericalProperties(properties:Object):Void
Ustawia orientację filmu do odtwarzania filmu w 360°. (Jeśli bieżący film nie jest sferyczny, metoda nie wykonuje żadnej operacji niezależnie od danych wejściowych).

Widok odtwarzacza reaguje na wywołania tej metody, aktualizując się w sposób odzwierciedlający wartości wszystkich znanych właściwości obiektu properties. Widok zachowuje wartości wszystkich innych znanych właściwości, które nie są zawarte w tym obiekcie.

Dodatkowo:
  • Jeśli obiekt zawiera nieznane lub nieoczekiwane właściwości, odtwarzacz je ignoruje.
  • Jak już wspomnieliśmy na początku tej sekcji, odtwarzanie filmów w 360° nie jest obsługiwane na wszystkich urządzeniach mobilnych.
  • Domyślnie na obsługiwanych urządzeniach mobilnych ta funkcja ustawia tylko właściwość fov i nie wpływa na właściwości yaw, pitch i roll podczas odtwarzania filmów w 360°. Więcej informacji znajdziesz w opisie właściwości enableOrientationSensor.
Obiekt properties przekazany do funkcji zawiera te właściwości:
Właściwości
yaw Patrz definicja powyżej.
pitch Patrz definicja powyżej.
roll Patrz definicja powyżej.
fov Patrz definicja powyżej.
enableOrientationSensor Uwaga: ta właściwość wpływa na wyświetlanie w 360° tylko na obsługiwanych urządzeniach.Wartość logiczna wskazująca, czy element iframe ma reagować na zdarzenia sygnalizujące zmiany orientacji obsługiwanego urządzenia, takie jak DeviceOrientationEvent w przeglądarce mobilnej. Wartością domyślną parametru jest true.

Obsługiwane urządzenia mobilne
  • Jeśli wartość to true, wbudowany odtwarzacz korzysta tylko z ruchu urządzenia, aby dostosować właściwości yaw, pitch i roll do odtwarzania filmów w 360°. Właściwość fov można jednak nadal zmieniać za pomocą interfejsu API, który jest w istocie jedynym sposobem na zmianę tej właściwości na urządzeniu mobilnym.fov Jest to zachowanie domyślne.
  • Jeśli wartość to false, ruch urządzenia nie wpływa na wyświetlanie w 360°, a właściwości yaw, pitch, roll i fov muszą być ustawione za pomocą interfejsu API.

Nieobsługiwane urządzenia mobilne
Wartość właściwości enableOrientationSensor nie ma żadnego wpływu na odtwarzanie.

Odtwarzanie filmu na playliście

player.nextVideo():Void
Ta funkcja wczytuje i odtwarza następny film na playliście.

  • Jeśli wywołanie player.nextVideo() nastąpi podczas oglądania ostatniego filmu na playliście, a playlista jest ustawiona na odtwarzanie ciągłe (loop), odtwarzacz wczyta i odtworzy pierwszy film z listy.

  • Jeśli funkcja player.nextVideo() zostanie wywołana podczas oglądania ostatniego filmu na playliście, a ta nie jest ustawiona na ciągłe odtwarzanie, odtwarzanie zostanie zakończone.

player.previousVideo():Void
Ta funkcja wczytuje i odtwarza poprzedni film na playliście.

  • Jeśli funkcja player.previousVideo() zostanie wywołana podczas oglądania pierwszego filmu na playliście, a playlista jest ustawiona na odtwarzanie ciągłe (loop), odtwarzacz wczyta i odtworzy ostatni film na liście.

  • Jeśli funkcja player.previousVideo() zostanie wywołana podczas oglądania pierwszego filmu na playliście, a playlista nie jest ustawiona na odtwarzanie ciągłe, odtwarzacz ponownie uruchomi pierwszy film z playlisty od początku.

player.playVideoAt(index:Number):Void
Ta funkcja wczytuje i odtwarza określony film na playliście.

  • Wymagany parametr index określa indeks filmu, który chcesz odtworzyć na playliście. Parametr używa indeksu od zera, więc wartość 0 wskazuje pierwszy film na liście. Jeśli playlista została zmiksowana, ta funkcja odtworzy film na określonej pozycji na liście odtwarzania.

Zmiana poziomu głośności odtwarzacza

player.mute():Void
Wyciszanie odtwarzacza.
player.unMute():Void
Wyłącza wyciszenie odtwarzacza.
player.isMuted():Boolean
Zwraca wartość true, jeśli odtwarzacz jest wyciszony, a jeśli nie, to false.
player.setVolume(volume:Number):Void
Ustawia głośność. Akceptuje liczbę całkowitą z zakresu od 0 do 100.
player.getVolume():Number
Zwraca bieżącą głośność odtwarzacza, która jest liczbą całkowitą z zakresu od 0 do 100. Pamiętaj, że getVolume() spowoduje przywrócenie głośności nawet wtedy, gdy odtwarzacz jest wyciszony.

Ustawianie rozmiaru odtwarzacza

player.setSize(width:Number, height:Number):Object
Ustawia rozmiar w pikselach elementu <iframe> zawierającego odtwarzacz.

Ustawianie szybkości odtwarzania

player.getPlaybackRate():Number
Ta funkcja pobiera szybkość odtwarzania aktualnie odtwarzanego filmu. Domyślna szybkość odtwarzania to 1, co oznacza, że film jest odtwarzany z normalną prędkością. Szybkości odtwarzania mogą obejmować wartości takie jak 0.25, 0.5, 1, 1.5 i 2.
player.setPlaybackRate(suggestedRate:Number):Void
Ta funkcja ustawia sugerowaną szybkość odtwarzania bieżącego filmu. Zmiana szybkości odtwarzania wpływa jedynie na film, który został już wskazany lub jest odtwarzany. Jeśli ustawisz szybkość odtwarzania dla filmu z podpowiedzią, ta szybkość będzie nadal obowiązywać, gdy wywołana zostanie funkcja playVideo lub użytkownik rozpocznie odtwarzanie bezpośrednio za pomocą elementów sterujących odtwarzacza. Ponadto wywołanie funkcji wczytywania lub odtwarzania filmów lub playlist (cueVideoById, loadVideoById itp.) spowoduje przywrócenie szybkości odtwarzania do wartości 1.

Wywołanie tej funkcji nie gwarantuje, że szybkość odtwarzania zostanie zmieniona. Jeśli jednak szybkość odtwarzania się zmieni, zostanie wywołane zdarzenie onPlaybackRateChange, a Twój kod powinien reagować na to zdarzenie, a nie na fakt wywołania funkcji setPlaybackRate.

Metoda getAvailablePlaybackRates zwróci możliwe prędkości odtwarzania dla aktualnie odtwarzanego filmu. Jeśli jednak parametr suggestedRate zostanie ustawiony na nieobsługiwaną wartość całkowitą lub zmiennoprzecinkową, odtwarzacz zaokrągli tę wartość w dół do najbliższej obsługiwanej wartości w kierunku 1.
player.getAvailablePlaybackRates():Array
Ta funkcja zwraca zestaw szybkości odtwarzania, w których dostępny jest bieżący film. Wartość domyślna to 1, co oznacza, że film jest odtwarzany z normalną prędkością.

Funkcja zwraca tablicę liczb uporządkowanych od najwolniejszej do najszybszej szybkości odtwarzania. Nawet jeśli odtwarzacz nie obsługuje zmiennych szybkości odtwarzania, tablica powinna zawsze zawierać co najmniej jedną wartość (1).

Ustawianie sposobu odtwarzania playlist

player.setLoop(loopPlaylists:Boolean):Void

Ta funkcja wskazuje, czy odtwarzacz filmów powinien odtwarzać playlistę w sposób ciągły, czy też powinien zatrzymać odtwarzanie po zakończeniu ostatniego filmu playlisty. Działaniem domyślnym jest nieodtwarzanie playlist w pętli.

To ustawienie będzie obowiązywać nawet wtedy, gdy wczytasz lub odtwarzasz inną playlistę. Oznacza to, że jeśli wczytasz playlistę, wywołasz funkcję setLoop z wartością true, a następnie wczytasz drugą playlistę, ta druga również będzie odtwarzana w pętli.

Wymagany parametr loopPlaylists określa sposób odtwarzania w pętli.

  • Jeśli wartość parametru to true, odtwarzacz wideo będzie odtwarzać playlisty w sposób ciągły. Po odtworzeniu ostatniego filmu playlisty odtwarzacz wraca na jej początek i rozpoczyna odtwarzanie od nowa.

  • Jeśli wartość parametru to false, odtwarzanie zakończy się po odtworzeniu ostatniego filmu na playliście.

player.setShuffle(shufflePlaylist:Boolean):Void

Ta funkcja wskazuje, czy filmy z playlisty powinny być odtwarzane w kolejności losowej. Oznacza to, że filmy są odtwarzane w innej kolejności niż wyznaczona przez twórcę playlisty. Jeśli włączysz losową kolejność odtwarzania playlisty już po rozpoczęciu jej odtwarzania, kolejność filmów zostanie zmieniona bez przerywania odtwarzania bieżącego filmu. Następny film do odtworzenia zostanie wybrany na podstawie zmienionej kolejności listy.

To ustawienie nie będzie zachowane, jeśli wczytasz lub odtwarzasz inną playlistę. Oznacza to, że jeśli wczytasz playlistę, wywołasz funkcję setShuffle, a następnie wczytasz drugą playlistę, ta druga nie zostanie odtworzona w trybie losowym.

Wymagany parametr shufflePlaylist wskazuje, czy YouTube ma odtwarzać playlistę losowo.

  • Jeśli wartość parametru to true, YouTube losowo uporządkuje kolejność utworów na playliście. Jeśli wywołasz funkcję ustawienia losowej kolejności odtwarzania playlisty, która już jest odtwarzana w kolejności losowej, YouTube ponownie zmieni kolejność odtwarzania.

  • Jeśli wartość parametru to false, YouTube zmieni kolejność playlisty z powrotem na pierwotną.

Stan odtwarzania

player.getVideoLoadedFraction():Float
Zwraca liczbę z zakresu 0–1, która określa odsetek filmu, który odtwarzacz wyświetla jako buforowany. Ta metoda zwraca bardziej wiarygodną liczbę niż wycofane metody getVideoBytesLoaded i getVideoBytesTotal.
player.getPlayerState():Number
Zwraca stan odtwarzacza. Możliwe wartości:
  • -1 – nie rozpoczęto
  • 0 – ended (zakończono)
  • 1 – playing (odtwarzanie)
  • 2 – paused (wstrzymano)
  • 3 – buffering (buforowanie)
  • 5 – video cued (film został wskazany)
player.getCurrentTime():Number
Zwraca upływający czas w sekundach od rozpoczęcia odtwarzania filmu.
player.getVideoStartBytes():Number
Wycofane 31 października 2012 r. Zwraca liczbę bajtów, od której rozpoczęto wczytywanie pliku z filmem (Ta metoda zawsze zwraca wartość 0). Przykładowy scenariusz: użytkownik przeskakuje do punktu, który nie został jeszcze załadowany, a odtwarzacz wysyła nowe żądanie odtworzenia niewczytanego jeszcze fragmentu filmu.
player.getVideoBytesLoaded():Number
Wycofane 18 lipca 2012 r. Zamiast tego użyj metody getVideoLoadedFraction, aby określić odsetek filmu, który został zbuforowany.

Ta metoda zwraca wartość z zakresu 0–1000, która przybliża wielkość załadowanego filmu. Możesz obliczyć ułamek załadowanego filmu, dzieląc wartość getVideoBytesLoaded przez wartość getVideoBytesTotal.
player.getVideoBytesTotal():Number
Wycofane 18 lipca 2012 r. Zamiast tego użyj metody getVideoLoadedFraction, aby określić odsetek filmu, który został zbuforowany.

Zwraca rozmiar w bajtach aktualnie wczytanego lub odtwarzanego filmu lub przybliżony rozmiar filmu.

Ta metoda zawsze zwraca wartość 1000. Możesz obliczyć ułamek załadowanego filmu, dzieląc wartość getVideoBytesLoaded przez wartość getVideoBytesTotal.

Pobieranie informacji o filmie

player.getDuration():Number
Zwraca czas trwania aktualnie odtwarzanego filmu w sekundach. Pamiętaj, że getDuration() zwróci wartość 0, dopóki nie zostaną załadowane metadane filmu. Zwykle dzieje się to tuż po rozpoczęciu odtwarzania filmu.

Jeśli odtwarzany film jest transmisją na żywo, funkcja getDuration() zwróci upływ czasu od rozpoczęcia transmisji. W szczególności jest to czas, przez który film był transmitowany bez resetowania ani przerywania. Dodatkowo czas ten jest zazwyczaj dłuższy od rzeczywistego czasu trwania wydarzenia, ponieważ transmisja może się rozpocząć przed wydarzeniem.
player.getVideoUrl():String
Zwraca adres URL YouTube.com dla aktualnie wczytanego/odtwarzanego filmu.
player.getVideoEmbedCode():String
Zwraca kod do umieszczania obecnie wczytanego lub odtwarzanego filmu.

Pobieranie informacji o playliście

player.getPlaylist():Array
Ta funkcja zwraca tablicę identyfikatorów filmów na playliście w ich bieżącej kolejności. Domyślnie funkcja ta zwraca identyfikatory filmów uporządkowane w kolejności wyznaczonej przez właściciela playlisty. Jeśli jednak wywołasz funkcję setShuffle, aby losowo zmienić kolejność utworów na playliście, wartość zwracana przez funkcję getPlaylist() będzie odzwierciedlać losową kolejność.
player.getPlaylistIndex():Number
Ta funkcja zwraca indeks filmu z playlisty, który jest obecnie odtwarzany.

  • Jeśli playlista nie jest odtwarzana w kolejności losowej, zwrócona wartość identyfikuje pozycję, pod którą umieścił film twórca playlisty. Wartości indeksu używane w zwracanej wartości są liczone od zera, dlatego wartość 0 identyfikuje pierwszy film playlisty.

  • Jeśli playlista jest odtwarzana w kolejności losowej, zwrócona wartość identyfikuje kolejność filmu na playliście uporządkowanej losowo.

Dodawanie lub usuwanie odbiorników

player.addEventListener(event:String, listener:String):Void
Dodaje funkcję listenera dla określonego elementu event. W sekcji Zdarzenia poniżej znajdziesz różne zdarzenia, które może wywołać odtwarzacz. Parametr listener jest ciągiem znaków określającym funkcję wywoływaną po uruchomieniu określonego zdarzenia.
player.removeEventListener(event:String, listener:String):Void
Usuwanie funkcji listenera w przypadku określonego obiektu event. listener to ciąg znaków identyfikujący funkcję, która nie będzie już wykonywana po wywołaniu określonego zdarzenia.

Uzyskiwanie dostępu do węzłów DOM i ich modyfikowanie

player.getIframe():Object
Ta metoda zwraca węzeł DOM dla osadzonego elementu <iframe>.
player.destroy():Void
Usuwanie <iframe> zawierającego odtwarzacz.

Wydarzenia

Interfejs API uruchamia zdarzenia służące do powiadamiania aplikacji o zmianach, którym podlega osadzony odtwarzacz. Jak wspomniano w poprzedniej sekcji, możesz subskrybować zdarzenia, dodając odbiornik zdarzeń podczas tworzenia obiektu YT.Player. Możesz też użyć funkcji addEventListener.

Interfejs API przekazuje obiekt zdarzenia do każdej z tych funkcji w postaci jedynego argumentu. Obiekt zdarzenia ma następujące właściwości:

  • target zdarzenia identyfikuje odtwarzacz wideo odpowiadający temu zdarzeniu.
  • Parametr data zdarzenia określa wartość odpowiednią do tego zdarzenia. Pamiętaj, że zdarzenia onReady i onAutoplayBlocked nie określają właściwości data.

Poniższa lista zawiera zdarzenia uruchamiane przez interfejs API:

onReady
To zdarzenie jest wywoływane, gdy odtwarzacz zakończy wczytywanie i jest gotowy do odbierania wywołań interfejsu API. Aplikacja powinna implementować tę funkcję, jeśli chcesz automatycznie wykonywać określone operacje, takie jak odtwarzanie filmu lub wyświetlanie informacji o nim, gdy tylko odtwarzacz będzie gotowy.

Przykład poniżej zawiera przykładową funkcję do obsługi tego zdarzenia. Obiekt zdarzenia, który interfejs API przekazuje funkcji, ma właściwość target, która identyfikuje odtwarzacz. Funkcja pobiera kod embedowania dla aktualnie wczytanego filmu, uruchamia odtwarzanie filmu i wyświetla kod embedowania w elemencie strony, którego wartość id to embed-code. 
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
To zdarzenie jest wywoływane, gdy zmienia się stan odtwarzacza. Właściwość data obiektu zdarzenia, który interfejs API przekazuje do funkcji odbiornika zdarzeń, będzie zawierać wartość całkowitą odpowiadającą nowemu stanowi odtwarzacza. Możliwe wartości to:

  • -1 (nierozpoczęty)
  • 0 (ended – zakończono)
  • 1 (playing – odtwarzanie)
  • 2 (wstrzymana)
  • 3 (buffering – buforowanie)
  • 5 (video cued – film wskazany).

Gdy odtwarzacz po raz pierwszy wczyta film, wyśle zdarzenie unstarted (-1). Gdy film jest gotowy do odtworzenia, odtwarzacz wyśle zdarzenie video cued (5). W kodzie możesz podawać wartości w formie liczb całkowitych lub użyć jednej z następujących zmiennych z określoną przestrzenią nazw:

  • YT.PlayerState.ENDED
  • YT.PlayerState.PLAYING
  • YT.PlayerState.PAUSED
  • YT.PlayerState.BUFFERING
  • YT.PlayerState.CUED

onPlaybackQualityChange
To zdarzenie jest wywoływane, gdy zmienia się jakość odtwarzania filmu. Może to oznaczać zmianę środowiska odtwarzania przez widza. Więcej informacji o czynnikach wpływających na warunki odtwarzania lub mogących spowodować wystąpienie zdarzenia znajdziesz w Centrum pomocy YouTube.

Wartość właściwości data obiektu zdarzenia, którą interfejs API przekazuje funkcji odbiornika zdarzeń, będzie ciągiem znaków identyfikującym nową jakość odtwarzania. Możliwe wartości to:

  • small
  • medium
  • large
  • hd720
  • hd1080
  • highres

onPlaybackRateChange
To zdarzenie jest wywoływane, gdy zmienia się szybkość odtwarzania filmu. Jeśli na przykład wywołasz funkcję setPlaybackRate(suggestedRate), to zdarzenie zostanie uruchomione, jeśli szybkość odtwarzania ulegnie zmianie. Aplikacja powinna reagować na zdarzenie i nie może zakładać, że szybkość odtwarzania zmieni się automatycznie, gdy zostanie wywołana funkcja setPlaybackRate(suggestedRate). Podobnie kod nie powinien zakładać, że szybkość odtwarzania filmu zmieni się tylko w wyniku wywołania funkcji setPlaybackRate.

Wartość właściwości data obiektu zdarzenia, którą interfejs API przekazuje funkcji odbiornika zdarzeń, będzie liczbą identyfikującą nową szybkość odtwarzania. Metoda getAvailablePlaybackRates zwraca listę prawidłowych szybkości odtwarzania dla aktualnie odtwarzanego lub wyświetlanego filmu.
onError
To zdarzenie jest wywoływane, gdy w odtwarzaczu wystąpi błąd. Interfejs API przekaże do funkcji detektora zdarzeń obiekt event. Właściwość data tego obiektu będzie zawierać liczbę całkowitą, która określa rodzaj błędu. Możliwe wartości to:

  • 2 – żądanie zawiera nieprawidłową wartość parametru. Ten błąd występuje na przykład wtedy, gdy określisz identyfikator filmu, który nie zawiera 11 znaków, lub identyfikator filmu, który zawiera nieprawidłowe znaki, takie jak wykrzykniki lub gwiazdki.
  • 5 – żądanego materiału nie można odtworzyć w odtwarzaczu HTML5 lub wystąpił inny błąd związany z odtwarzaczem HTML5.
  • 100 – nie znaleziono żądanego filmu. Ten błąd występuje, gdy film został usunięty (z dowolnego powodu) lub został oznaczony jako prywatny.
  • 101 – właściciel żądanego filmu nie zezwala, by był on odtwarzany w odtwarzaczach umieszczanych na stronach.
  • 150 – ten błąd jest taki sam, jak 101. To tylko błąd 101 w przebraniu.
onApiChange
To zdarzenie jest wywoływane, aby wskazać, że odtwarzacz załadował (lub usunął) moduł z metodami interfejsu API. Aplikacja może nasłuchiwać tego zdarzenia, a następnie wysondować odtwarzacz w celu określenia opcji ujawnionych na potrzeby ostatnio wczytanego modułu. Aplikacja może następnie pobrać lub zaktualizować istniejące ustawienia tych opcji.

Poniższe polecenie pobiera tablicę nazw modułów, dla których możesz ustawić opcje dotyczące gracza:
player.getOptions();
Obecnie jedynym modułem, którego opcje możesz ustawiać, jest moduł captions, który obsługuje napisy w odtwarzaczu. Po otrzymaniu zdarzenia onApiChange aplikacja może użyć tego polecenia, aby określić, które opcje można ustawić dla modułu captions:
player.getOptions('captions');
 Wysyłając to zapytanie do odtwarzacza, możesz sprawdzić, czy opcje, do których chcesz uzyskać dostęp, są dostępne. Opcje modułu można pobierać i aktualizować za pomocą tych poleceń:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
 Tabela poniżej zawiera listę opcji obsługiwanych przez interfejs API:

Moduł Opcja Opis
napisy fontSize Ta opcja dostosowuje rozmiar czcionki napisów wyświetlanych w odtwarzaczu.

Dozwolone wartości to -1, 0, 1, 2 i 3. Domyślny rozmiar to 0, a najmniejszy – -1. Ustawienie tej opcji na liczbę całkowitą mniejszą niż -1 spowoduje wyświetlenie napisy w najmniejszym rozmiarze, natomiast ustawienie tej opcji na liczbę całkowitą większą niż -1 spowoduje wyświetlenie napisów w największym rozmiarze.3
napisy reload Ta opcja powoduje ponowne wczytanie napisów dla odtwarzanego filmu. Jeśli pobierzesz wartość opcji, będzie ona wynosić null. Aby ponownie załadować dane napisów, ustaw wartość na true.
onAutoplayBlocked
To zdarzenie jest wywoływane za każdym razem, gdy przeglądarka blokuje automatyczne odtwarzanie lub funkcje odtwarzania wideo ze skryptem. W zbiorze nazywane jest „automatycznym odtwarzaniem”. Obejmuje to odtwarzanie za pomocą dowolnego z tych interfejsów API odtwarzacza:

Większość przeglądarek ma zasady, które mogą blokować autoodtwarzanie na komputerach, urządzeniach mobilnych i w innych środowiskach, jeśli spełnione są określone warunki. Ta zasada może zostać uruchomiona, gdy odtwarzanie bez wyciszenia odbywa się bez interakcji użytkownika lub gdy nie została określona zasada dotycząca uprawnień zezwalająca na automatyczne odtwarzanie w ramce iframe w innej domenie.

Szczegółowe informacje znajdziesz w zasadach dotyczących poszczególnych przeglądarek (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) oraz w przewodniku Mozilli dotyczącym automatycznego odtwarzania.

Przykłady

Tworzenie obiektów YT.Player

  • Przykład 1. Używanie interfejsu API z dotychczasowym tagiem <iframe>

    W tym przykładzie element <iframe> na stronie już definiuje odtwarzacz, z którym będzie używany interfejs API. Pamiętaj, że parametr src w adresie URL odtwarzacza musi mieć wartość enablejsapi lub atrybut enablejsapi elementu <iframe> musi mieć wartość true.1

    Funkcja onPlayerReady zmienia kolor obramowania wokół odtwarzacza na pomarańczowy, gdy odtwarzacz jest gotowy. Funkcja onPlayerStateChange zmienia kolor obramowania wokół odtwarzacza w zależności od jego bieżącego stanu. Na przykład kolor jest zielony, gdy odtwarzacz odtwarza, czerwony, gdy jest wstrzymany, niebieski, gdy buforuje, itd.

    W tym przykładzie użyto tego kodu:

    <iframe id="existing-iframe-example"
        width="640" height="360"
        src="https://www.youtube.com/embed/M7lc1UVf-VE?enablejsapi=1"
        frameborder="0"
        style="border: solid 4px #37474F"
></iframe>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var player;
  function onYouTubeIframeAPIReady() {
    player = new YT.Player('existing-iframe-example', {
        events: {
          'onReady': onPlayerReady,
          'onStateChange': onPlayerStateChange
        }
    });
  }
  function onPlayerReady(event) {
    document.getElementById('existing-iframe-example').style.borderColor = '#FF6D00';
  }
  function changeBorderColor(playerStatus) {
    var color;
    if (playerStatus == -1) {
      color = "#37474F"; // unstarted = gray
    } else if (playerStatus == 0) {
      color = "#FFFF00"; // ended = yellow
    } else if (playerStatus == 1) {
      color = "#33691E"; // playing = green
    } else if (playerStatus == 2) {
      color = "#DD2C00"; // paused = red
    } else if (playerStatus == 3) {
      color = "#AA00FF"; // buffering = purple
    } else if (playerStatus == 5) {
      color = "#FF6DOO"; // video cued = orange
    }
    if (color) {
      document.getElementById('existing-iframe-example').style.borderColor = color;
    }
  }
  function onPlayerStateChange(event) {
    changeBorderColor(event.data);
  }
</script>

  • Przykład 2. Odtwarzanie z wysoką głośnością

    W tym przykładzie tworzony jest odtwarzacz filmów o rozmiarach 1280 na 720 pikseli. Detektor zdarzenia onReady wywołuje następnie funkcję setVolume, aby dostosować głośność do najwyższego ustawienia.

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

  • Przykład 3: w tym przykładzie ustawiamy parametry odtwarzacza, aby automatycznie odtwarzał film po jego załadowaniu, i ukryć przyciski odtwarzacza. Dodaje też detektory zdarzeń dla kilku zdarzeń, które interfejs API przekazuje.

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    videoId: 'M7lc1UVf-VE',
    playerVars: { 'autoplay': 1, 'controls': 0 },
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

Sterowanie filmami sferycznymi

W tym przykładzie użyto tego kodu:

<style>
  .current-values {
    color: #666;
    font-size: 12px;
  }
</style>
<!-- The player is inserted in the following div element -->
<div id="spherical-video-player"></div>

<!-- Display spherical property values and enable user to update them. -->
<table style="border: 0; width: 640px;">
  <tr style="background: #fff;">
    <td>
      <label for="yaw-property">yaw: </label>
      <input type="text" id="yaw-property" style="width: 80px"><br>
      <div id="yaw-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="pitch-property">pitch: </label>
      <input type="text" id="pitch-property" style="width: 80px"><br>
      <div id="pitch-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="roll-property">roll: </label>
      <input type="text" id="roll-property" style="width: 80px"><br>
      <div id="roll-current-value" class="current-values"> </div>
    </td>
    <td>
      <label for="fov-property">fov: </label>
      <input type="text" id="fov-property" style="width: 80px"><br>
      <div id="fov-current-value" class="current-values"> </div>
    </td>
    <td style="vertical-align: bottom;">
      <button id="spherical-properties-button">Update properties</button>
    </td>
  </tr>
</table>

<script type="text/javascript">
  var tag = document.createElement('script');
  tag.id = 'iframe-demo';
  tag.src = 'https://www.youtube.com/iframe_api';
  var firstScriptTag = document.getElementsByTagName('script')[0];
  firstScriptTag.parentNode.insertBefore(tag, firstScriptTag);

  var PROPERTIES = ['yaw', 'pitch', 'roll', 'fov'];
  var updateButton = document.getElementById('spherical-properties-button');

  // Create the YouTube Player.
  var ytplayer;
  function onYouTubeIframeAPIReady() {
    ytplayer = new YT.Player('spherical-video-player', {
        height: '360',
        width: '640',
        videoId: 'FAtdv94yzp4',
    });
  }

  // Don't display current spherical settings because there aren't any.
  function hideCurrentSettings() {
    for (var p = 0; p < PROPERTIES.length; p++) {
      document.getElementById(PROPERTIES[p] + '-current-value').innerHTML = '';
    }
  }

  // Retrieve current spherical property values from the API and display them.
  function updateSetting() {
    if (!ytplayer || !ytplayer.getSphericalProperties) {
      hideCurrentSettings();
    } else {
      let newSettings = ytplayer.getSphericalProperties();
      if (Object.keys(newSettings).length === 0) {
        hideCurrentSettings();
      } else {
        for (var p = 0; p < PROPERTIES.length; p++) {
          if (newSettings.hasOwnProperty(PROPERTIES[p])) {
            currentValueNode = document.getElementById(PROPERTIES[p] +
                                                       '-current-value');
            currentValueNode.innerHTML = ('current: ' +
                newSettings[PROPERTIES[p]].toFixed(4));
          }
        }
      }
    }
    requestAnimationFrame(updateSetting);
  }
  updateSetting();

  // Call the API to update spherical property values.
  updateButton.onclick = function() {
    var sphericalProperties = {};
    for (var p = 0; p < PROPERTIES.length; p++) {
      var propertyInput = document.getElementById(PROPERTIES[p] + '-property');
      sphericalProperties[PROPERTIES[p]] = parseFloat(propertyInput.value);
    }
    ytplayer.setSphericalProperties(sphericalProperties);
  }
</script>

Integracja interfejsu Media Integrity API w WebView na Androida

YouTube rozszerzył interfejs API Android WebView Media Integrity, aby umożliwić umieszczanie odtwarzaczy multimediów, w tym odtwarzacza YouTube w aplikacjach na Androida, oraz weryfikację autentyczności aplikacji do umieszczania. Dzięki tej zmianie aplikacje do wklejania automatycznie wysyłają do YouTube poświadczony identyfikator aplikacji. Dane zbierane podczas korzystania z tego interfejsu API to metadane aplikacji (nazwa pakietu, numer wersji i certyfikat podpisywania) oraz token uwierzytelniający urządzenie wygenerowany przez usługi Google Play.

Dane te służą do weryfikacji integralności aplikacji i urządzenia. Jest on zaszyfrowany, nie jest udostępniany osobom trzecim i usuwany po określonym okresie przechowywania. Deweloperzy aplikacji mogą konfigurować tożsamość aplikacji w interfejsie WebView Media Integrity API. Konfiguracja obsługuje opcję rezygnacji.

Historia zmian

June 24, 2024

The documentation has been updated to note that YouTube has extended the Android WebView Media Integrity API to enable embedded media players, including YouTube player embeds in Android applications, to verify the embedding app's authenticity. With this change, embedding apps automatically send an attested app ID to YouTube.

November 20, 2023

The new onAutoplayBlocked event API is now available. This event notifies your application if the browser blocks autoplay or scripted playback. Verification of autoplay success or failure is an established paradigm for HTMLMediaElements, and the onAutoplayBlocked event now provides similar functionality for the IFrame Player API.

April 27, 2021

The Getting Started and Loading a Video Player sections have been updated to include examples of using a playerVars object to customize the player.

October 13, 2020

Note: This is a deprecation announcement for the embedded player functionality that lets you configure the player to load search results. This announcement affects the IFrame Player API's queueing functions for lists, cuePlaylist and loadPlaylist.

This change will become effective on or after 15 November 2020. After that time, calls to the cuePlaylist or loadPlaylist functions that set the listType property to search will generate a 4xx response code, such as 404 (Not Found) or 410 (Gone). This change also affects the list property for those functions as that property no longer supports the ability to specify a search query.

As an alternative, you can use the YouTube Data API's search.list method to retrieve search results and then load selected videos in the player.

October 24, 2019

The documentation has been updated to reflect the fact that the API no longer supports functions for setting or retrieving playback quality. As explained in this YouTube Help Center article, to give you the best viewing experience, YouTube adjusts the quality of your video stream based on your viewing conditions.

The changes explained below have been in effect for more than one year. This update merely aligns the documentation with current functionality:

  • The getPlaybackQuality, setPlaybackQuality, and getAvailableQualityLevels functions are no longer supported. In particular, calls to setPlaybackQuality will be no-op functions, meaning they will not actually have any impact on the viewer's playback experience.
  • The queueing functions for videos and playlists -- cueVideoById, loadVideoById, etc. -- no longer support the suggestedQuality argument. Similarly, if you call those functions using object syntax, the suggestedQuality field is no longer supported. If suggestedQuality is specified, it will be ignored when the request is handled. It will not generate any warnings or errors.
  • The onPlaybackQualityChange event is still supported and might signal a change in the viewer's playback environment. See the Help Center article referenced above for more information about factors that affect playback conditions or that might cause the event to fire.

May 16, 2018

The API now supports features that allow users (or embedders) to control the viewing perspective for 360° videos:

  • The getSphericalProperties function retrieves the current orientation for the video playback. The orientation includes the following data:
    • yaw - represents the horizontal angle of the view in degrees, which reflects the extent to which the user turns the view to face further left or right
    • pitch - represents the vertical angle of the view in degrees, which reflects the extent to which the user adjusts the view to look up or down
    • roll - represents the rotational angle (clockwise or counterclockwise) of the view in degrees.
    • fov - represents the field-of-view of the view in degrees, which reflects the extent to which the user zooms in or out on the video.
  • The setSphericalProperties function modifies the view to match the submitted property values. In addition to the orientation values described above, this function supports a Boolean field that indicates whether the IFrame embed should respond to DeviceOrientationEvents on supported mobile devices.

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

  • Documentation for the YouTube Flash Player API and YouTube JavaScript Player API has been removed and redirected to this document. The deprecation announcement for the Flash and JavaScript players was made on January 27, 2015. If you haven't done so already, please migrate your applications to use IFrame embeds and the IFrame Player API.

August 11, 2016

This update contains the following changes:

  • The newly published YouTube API Services Terms of Service ("the Updated Terms"), discussed in detail on the YouTube Engineering and Developers Blog, provides a rich set of updates to the current Terms of Service. In addition to the Updated Terms, which will go into effect as of February 10, 2017, this update includes several supporting documents to help explain the policies that developers must follow.

    The full set of new documents is described in the revision history for the Updated Terms. In addition, future changes to the Updated Terms or to those supporting documents will also be explained in that revision history. You can subscribe to an RSS feed listing changes in that revision history from a link in that document.

June 29, 2016

This update contains the following changes:

  • The documentation has been corrected to note that the onApiChange method provides access to the captions module and not the cc module.

June 24, 2016

The Examples section has been updated to include an example that demonstrates how to use the API with an existing <iframe> element.

January 6, 2016

The clearVideo function has been deprecated and removed from the documentation. The function no longer has any effect in the YouTube player.

December 18, 2015

European Union (EU) laws require that certain disclosures must be given to and consents obtained from end users in the EU. Therefore, for end users in the European Union, you must comply with the EU User Consent Policy. We have added a notice of this requirement in our YouTube API Terms of Service.

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.

July 23, 2013

This update contains the following changes:

  • The Overview now includes a video of a 2011 Google I/O presentation that discusses the iframe player.

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 22, 2012

This update contains the following changes:

  • The example in the Loading a video player section that demonstrates how to manually create the <iframe> tag has been updated to include a closing </iframe> tag since the onYouTubeIframeAPIReady function is only called if the closing </iframe> element is present.

August 6, 2012

This update contains the following changes:

  • The Operations section has been expanded to list all of the supported API functions rather than linking to the JavaScript Player API Reference for that list.

  • The API supports several new functions and one new event that can be used to control the video playback speed:

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

  • The new getVideoLoadedFraction method replaces the now-deprecated getVideoBytesLoaded and getVideoBytesTotal methods. The new method returns the percentage of the video that the player shows as buffered.

  • The onError event may now return an error code of 5, which indicates that the requested content cannot be played in an HTML5 player or another error related to the HTML5 player has occurred.

  • The Requirements section has been updated to indicate that any web page using the IFrame API must also implement the onYouTubeIframeAPIReady function. Previously, the section indicated that the required function was named onYouTubePlayerAPIReady. Code samples throughout the document have also been updated to use the new name.

    Note: To ensure that this change does not break existing implementations, both names will work. If, for some reason, your page has an onYouTubeIframeAPIReady function and an onYouTubePlayerAPIReady function, both functions will be called, and the onYouTubeIframeAPIReady function will be called first.

  • The code sample in the Getting started section has been updated to reflect that the URL for the IFrame Player API code has changed to http://www.youtube.com/iframe_api. To ensure that this change does not affect existing implementations, the old URL (http://www.youtube.com/player_api) will continue to work.

July 16, 2012

This update contains the following changes:

  • The Operations section now explains that the API supports the setSize() and destroy() methods. The setSize() method sets the size in pixels of the <iframe> that contains the player and the destroy() method removes the <iframe>.

June 6, 2012

This update contains the following changes:

  • We have removed the experimental status from the IFrame Player API.

  • The Loading a video player section has been updated to point out that when inserting the <iframe> element that will contain the YouTube player, the IFrame API replaces the element specified in the constructor for the YouTube player. This documentation change does not reflect a change in the API and is intended solely to clarify existing behavior.

    In addition, that section now notes that the insertion of the <iframe> element could affect the layout of your page if the element being replaced has a different display style than the inserted <iframe> element. By default, an <iframe> displays as an inline-block element.

March 30, 2012

This update contains the following changes:

  • The Operations section has been updated to explain that the IFrame API supports a new method, getIframe(), which returns the DOM node for the IFrame embed.

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size.