YouTube Player API Reference for iframe Embeds

Rozhraní API přehrávače v prvku iframe povoluje vkládat videa z YouTube do webových stránek a řídit přehrávač pomocí JavaScriptu. Na rozdíl od rozhraní API přehrávačů Flash a JavaScript, které oba vkládají do vašich stránek objekt Flash, rozhraní API přehrávače v prvku iframe odesílá obsah do tagu <iframe> vaší stránky. Tento přístup je flexibilnější než předchozí rozhraní API, protože umožňuje službě YouTube předávat mobilním zařízením, která nepodporují Flash, přehrávač HTML5 namísto přehrávače Flash.

Pomocí funkcí JavaScript rozhraní API můžete zařazovat videa k přehrání do fronty, přehrát, pozastavit, nebo zastavit přehrávání videí, upravit hlasitost přehrávače a získávat informace o přehrávaném videu. Můžete přidat i posluchače událostí, které se budou spouštět na základě určených událostí, jako je změna stavu přehrávače nebo změna kvality přehrávání.

V této příručce vysvětlujeme používání rozhraní API prvku iframe. Příručka popisuje typy událostí, které může API odesílat, a vysvětluje způsob psaní posluchačů událostí tak, aby na události reagovaly. Také podrobně popisuje funkce JavaScript, které se volají při ovládání videopřehrávače, a parametry přehrávače použitelné k dalšímu vlastnímu nastavení přehrávače.

Požadavky

Koncový uživatel musí používat prohlížeč s podporou funkce HTML5 postMessage. Většina moderních přehrávačů podporuje funkci postMessage, ovšem Internet Explorer 7 ji nepodporuje.

Embedded players must have a viewport that is at least 200px by 200px. If the 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.

Každá webová stránka používající rozhraní API prvku iframe musí implementovat i následující funkci JavaScript:

  • onYouTubeIframeAPIReady – rozhraní API bude funkci volat, když stránka dokončí stahování JavaScriptu pro API přehrávače, který vám potom umožní použít API na vaší stránce. Tato funkce může tedy vytvářet objekty přehrávače, které chcete zobrazit po načtení stránky.

Začínáme

Následující vzorová stránka HTML vytvoří vložený přehrávač, který načte video, přehraje z něj 6 sekund a potom přehrávání zastaví. Očíslované poznámky v kódu HTML jsou vysvětleny v seznamu pod příkladem.

<!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: '360',
          width: '640',
          videoId: 'M7lc1UVf-VE',
          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>

Následující seznam obsahuje podrobnosti o uvedeném příkladu:

  1. Tag <div> v této části identifikuje místo na webové stránce, kam rozhraní API prvku iframe umístí videopřehrávač. Konstruktor objektu přehrávače popsaný v části Načtení videopřehrávače, identifikuje tag <div> podle id a tím zajistí, že rozhraní API umístí tag <iframe> na správné místo. Přesně řečeno, rozhraní API prvku iframe nahradí tag <div> tagem <iframe>.

    Další možností je použít prvek <iframe> přímo ve stránce. Pokyny najdete v části Načtení videopřehrávače.

  2. Kód uvedený v této části načte kód JavaScript rozhraní API přehrávače v prvku iframe. V příkladu je ke stažení kódu API použita modifikace DOM, což zajišťuje asynchronní vyvolání kódu. (Atribut async tagu <script>, který také umožňuje asynchronní stahování, není dosud podporován ve všech moderních prohlížečích. Podrobnosti najdete v odpovědi Přetečení zásobníku.

  3. Funkce onYouTubeIframeAPIReady se spustí ihned po dokončení stahování kódu API. V této části kódu se definuje globální proměnná player odkazující na videopřehrávač, který vkládáte. Funkce potom konstruuje objekt videopřehrávače.

  4. Funkce onPlayerReady se spustí po vyslání události onReady. Funkce v tomto příkladu indikuje, že ve chvíli, kdy je videopřehrávač připraven, se má zahájit přehrávání.

  5. Rozhraní API vyvolá funkci onPlayerStateChange při změně stavu přehrávače, která může indikovat, že přehrávač začal přehrávat, byl pozastaven, dokončil přehrávání apod. Funkce indikuje, že když je přehrávač ve stavu 1 (přehrává se), přehrávač má pokračovat v přehrávání po dobu 6 sekund a potom vyvolat funkci stopVideo, která video zastaví.

Načtení videopřehrávače

Po načtení kódu JavaScript rozhraní API vyvolá rozhraní API funkci onYouTubeIframeAPIReady. V tom okamžiku můžete zkonstruovat objekt YT.Player, který do vaší stránky vloží videopřehrávač. Následující úryvek HTML ukazuje funkci onYouTubeIframeAPIReady z výše uvedeného příkladu:

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

Konstruktor videopřehrávače specifikuje následující parametry:

  1. První parametr specifikuje buď prvek DOM nebo id prvku HTML, kam rozhraní API vloží tag <iframe> obsahující přehrávač.

    Rozhraní API prvku iframe nahradí specifikovaný prvek prvkem <iframe>, který obsahuje přehrávač. To může v případě, že nahrazovaný prvek má jiný styl zobrazení než vložený prvek <iframe>, ovlivnit rozvržení stránky. Ve výchozím nastavení se prvek <iframe> zobrazuje jako prvek inline-block.

  2. Druhý parametr je objekt specifikující možnosti přehrávače. Objekt obsahuje následující vlastnosti:
    • width (číslo) – šířka přehrávače videa. Výchozí hodnota je 640.
    • height (číslo) – výška videopřehrávače. Výchozí hodnota je 360.
    • videoId (řetězec) – ID videa na YouTube, které identifikuje video, které má přehrávač načíst.
    • playerVars (objekt) – vlastnosti objektu identifikují parametry přehrávače používané k vlastnímu nastavení přehrávače.
    • events (objekt) – vlastnosti objektu identifikují události, které rozhraní API spouští, a funkce (posluchače událostí), které bude rozhraní API volat, když k událostem dojde. V našem příkladu konstruktor indikuje, že funkce onPlayerReady se provede po vyslání události onReady a funkce onPlayerStateChange se provede po vyslání události onStateChange.

Jak zmiňujeme v části Začínáme, namísto toho, abyste pro svou stránku psali prázdný prvek <div>, který potom kód JavaScript rozhraní API nahradí prvkem <iframe>, můžete vytvořit tag <iframe> sami.

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

Pokud zapíšete tag <iframe>, nebudete potom při konstrukci objektu YT.Player muset zadávat hodnoty width a height, které se zadávají jako atributy tagu <iframe> nebo jako parametry videoId a přehrávače, které jsou zadány v adrese URL src. Jako dodatečné bezpečnostní opatření byste měli do adresy URL vložit i parametr origin, který určuje schéma URL (http:// nebo https://) s kompletní doménou hostitele v hodnotě parametru. I když je parametr origin nepovinný, jeho použitím chráníte stránku před injektováním škodlivého kódu JavaScript třetích stran a napadením vašeho ovládání přehrávače YouTube.

V části Příklady najdete několik dalších příkladů konstrukce objektů videopřehrávače.

Provoz

Před voláním metod rozhraní API přehrávače musíte nejprve získat odkaz na objekt přehrávače, který chcete ovládat. Odkaz získáte vytvořením objektu YT.Player podle pokynů v částech Začínáme a Načtení videopřehrávače tohoto dokumentu.

Funkce

Funkce zařazování do fronty

Funkce zařazování do fronty umožňují načítání a přehrávání videa, seznamu videí nebo jiného seznamu obsahujícího videa. Pokud k vyvolání těchto funkcí použijete syntaxi objektu popsanou dále, můžete také načíst seznam výsledků vyhledávání nebo seznam nahraných videí uživatele, nebo videa a seznamy zařadit do fronty.

V rozhraní API můžete k volání funkcí zařazování do fronty použít dvě různé syntaxe.

  • Syntaxe argumentů vyžaduje, aby byly argumenty funkce uvedeny v předepsaném pořadí.

  • Syntaxe objektu vám umožní předat objekt jako jediný parametr a pro argumenty funkce, které chcete nastavit, definovat vlastnosti objektu. Kromě toho může rozhraní API podporovat dodatečné funkce, které syntaxe argumentu nepodporuje.

Například funkci loadVideoById lze volat následujícími dvěma způsoby. Všimněte si, že syntaxe objektu podporuje vlastnost endSeconds, kterou syntaxe argumentu nepodporuje.

  • Syntaxe argumentu

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • Syntaxe objektu

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

Funkce zařazování videí do fronty

cueVideoById
  • Syntaxe argumentu

    player.cueVideoById(videoId:String,
                        startSeconds:Number,
                        suggestedQuality:String):Void
  • Syntaxe objektu

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

Tato funkce načítá náhled zadaného videa a připravuje přehrávač na přehrání videa. Přehrávač nepožaduje soubor FLV až do vyvolání funkce playVideo() nebo seekTo().

  • Povinný parametr videoId specifikuje ID videa na YouTube pro video, které se má přehrát. Ve zdrojích videí YouTube Data API specifikuje tag <yt:videoid> identifikátor.
  • Nepovinný parametr startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a specifikuje čas, od kterého se má video po volání funkce playVideo() přehrát. Zadáte-li hodnotu startSeconds a potom voláte funkci seekTo(), přehrávač zahájí přehrávání od času zadaného ve volání funkce seekTo(). Když je video zařazeno a připraveno k přehrání, přehrávač vyšle událost video cued (5).
  • Nepovinný parametr endSeconds podporovaný pouze v syntaxi objektu přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a specifikuje čas, kdy se má video přestat přehrávat po volání funkce playVideo(). Pokud zadáte hodnotu endSeconds a potom voláte funkci seekTo(), hodnota endSeconds již nebude mít vliv.
  • Nepovinný parametr suggestedQuality specifikuje navrhovanou kvalitu přehrávání videa. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

loadVideoById

  • Argument syntax

    player.loadVideoById(videoId:String,
                         startSeconds:Number,
                         suggestedQuality:String):Void
  • Object syntax

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

Funkce načte a přehraje zadané video.

  • Povinný parametr videoId specifikuje ID videa YouTube, které se má přehrát. Ve zdrojích videí YouTube Data API tag <yt:videoid> specifikuje identifikátor.
  • Nepovinný parametr startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou. Pokud je zadaný, přehrávání videa bude zahájeno klíčovým snímkem, který je zadanému času nejbližší.
  • Nepovinný parametr endSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou. Pokud je zadaný, přehrávání videa skončí v zadaný čas.
  • Nepovinný parametr suggestedQuality určuje navrhovanou kvalitu přehrávání videa. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

cueVideoByUrl

  • Argument syntax

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number,
                         suggestedQuality:String):Void
  • Object syntax

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

Tato funkce načítá náhled zadaného videa a připravuje přehrávač na přehrání videa. Přehrávač nepožaduje soubor FLV až do vyvolání funkce playVideo() nebo seekTo().

  • Povinný parametr mediaContentUrl specifikuje plně kvalifikovanou adresu URL přehrávače YouTube ve formátu http://www.youtube.com/v/VIDEO_ID?version=3. Má-li atribut format tagu hodnotu 5, obsahuje atribut url tagu <media:content> ve zdrojích videí YouTube Data API plně kvalifikovanou adresu URL přehrávače,
  • Nepovinný parametr startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a specifikuje čas, od něhož se má zahájit přehrávání videa po volání funkce playVideo(). Zadáte-li hodnotu startSeconds a potom voláte funkci seekTo(), přehrávač zahájí přehrávání od času zadaného ve volání funkce seekTo(). Když je video zařazeno a připraveno k přehrání, přehrávač vyšle událost video cued (5).
  • Nepovinný parametr endSeconds podporovaný pouze syntaxí objektu přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, kdy se má po volání funkce playVideo() zastavit přehrávání videa. Pokud zadáte hodnotu endSeconds a potom voláte funkci seekTo(), hodnota endSeconds již nebude mít vliv.
  • Nepovinný parametr suggestedQuality určuje navrhovanou kvalitu přehrávání videa. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

loadVideoByUrl

  • Argument syntax

    player.loadVideoByUrl(mediaContentUrl:String,
                          startSeconds:Number,
                          suggestedQuality:String):Void
  • Object syntax

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

Funkce načte a přehraje zadané video.

  • Povinný parametr mediaContentUrl specifikuje plně kvalifikovanou adresu URL přehrávače YouTube ve formátu http://www.youtube.com/v/VIDEO_ID?version=3. Má-li atribut tagu format hodnotu 5, obsahuje atribut url tagu <media:content> ve zdrojích videí YouTube Data API plně kvalifikovanou adresu URL přehrávače.
  • Nepovinný parametr startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, od něhož se má video začít přehrávat. Je-li zadána hodnota startSeconds (může jít o číslo s plovoucí desetinnou čárkou), přehrávání videa začne klíčovým snímkem, který je zadanému času nejbližší.
  • Nepovinný parametr endSeconds podporovaný pouze syntaxí objektu přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, kdy má být přehrávání videa ukončeno.
  • Nepovinný parametr suggestedQuality určuje navrhovanou kvalitu přehrávání videa. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

Funkce zařazování seznamů videí do fronty

Funkce cuePlaylist a loadPlaylist umožňují načíst a přehrát seznam videí (playlist) nebo jiný seznam videí. Používáte-li k volání těchto funkcí syntaxi objektu, můžete zařadit do fronty (nebo načíst) seznam výsledků vyhledávání nebo seznam videí, které uživatel nahrál.

Protože chování funkcí se liší podle toho, zda byly volány pomocí syntaxe argumentu nebo syntaxe objektu, dokumentujeme dále obě metody volání.

cuePlaylist
  • Argument syntax

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number,
                       suggestedQuality:String):Void
    Zařazuje zadaný seznam videí do fronty. Když je seznam zařazený a připravený k přehrání, přehrávač vyšle událost video cued (5).
    • Povinný parametr playlist specifikuje pole identifikátorů videí na YouTube. Ve zdrojích videí YouTube Data API specifikuje tag <yt:videoid> ID videa.

    • Nepovinný parametr index specifikuje index prvního videa v seznamu videí, které se přehraje. Parametr používá index číslovaný od nuly a výchozí hodnotou parametru je 0, výchozím chováním funkce je tedy načtení a spuštění prvního videa ze seznamu.

    • Nepovinný parametr startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, od něhož se má první video ze seznamu videí po volání funkce playVideo() začít přehrávat. Zadáte-li hodnotu startSeconds a potom voláte funkci seekTo(), přehrávač zahájí přehrávání od času zadaného ve volání funkce seekTo(). Pokud zařadíte seznam videí a potom voláte funkci playVideoAt(), přehrávač začne přehrávat zadané video od začátku.

    • Nepovinný parametr suggestedQuality určuje navrhovanou kvalitu přehrávání videa. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

  • Syntaxe objektu

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number,
                        suggestedQuality:String}):Void
    Zařazuje zadaný seznam videí do fronty. Může jít o seznam videí, zdroj výsledků vyhledávání nebo zdroj nahraných videí uživatele. Když je seznam zařazen a připraven k přehrání, přehrávač vyšle událost video cued (5).
    • Nepovinná vlastnost listType specifikuje typ zdroje výsledků, který vyvoláváte. Platné hodnoty jsou playlist, search a user_uploads. Výchozí hodnota je playlist.

    • Povinná vlastnost list obsahuje klíč identifikující konkrétní seznam videí, který má služba YouTube vrátit.

      • Pokud má vlastnost listType hodnotu playlist, potom vlastnost list specifikuje identifikátor seznamu videí nebo pole identifikátorů videí. Ve zdrojích videí YouTube Data API specifikuje tag <yt:playlistid> identifikátor seznamu videí a tag <yt:videoid> specifikuje ID videa.
      • Má-li vlastnost listType hodnotu search, vlastnost list specifikuje vyhledávací dotaz.
      • Má-li vlastnost listType hodnotu user_uploads, potom vlastnost list identifikuje uživatele, jehož nahraná videa se mají vrátit.

    • Nepovinná vlastnost index specifikuje index prvního videa v seznamu, který se přehraje. Parametr používá index číslovaný od nuly a výchozí hodnota parametru je 0, takže ve výchozím nastavení funkce načte a přehraje první video ze seznamu.

    • Nepovinná vlastnost startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, od něhož se má první video v seznamu začít přehrávat po volání funkce playVideo(). Zadáte-li hodnotu startSeconds a potom voláte funkci seekTo(), přehrávač zahájí přehrávání od času zadaného ve volání funkce seekTo(). Pokud seznam zařadíte a potom voláte funkci playVideoAt(), přehrávač začne přehrávat zadané video od začátku.

    • Nepovinná vlastnost suggestedQuality specifikuje navrhovanou kvalitu přehrávání pro seznam videí. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

loadPlaylist
  • Argument syntax

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number,
                        suggestedQuality:String):Void
    Funkce načte zadaný seznam videí a přehraje ho.
    • Povinný parametr playlist specifikuje pole identifikátorů videí na YouTube. Ve zdrojích videí YouTube Data API specifikuje tag <yt:videoid> ID videa.

    • Nepovinný parametr index specifikuje index prvního videa v seznamu videí, které se přehraje. Parametr používá index číslovaný od nuly a výchozí hodnotou parametru je 0, výchozím chováním funkce je tedy načtení a spuštění prvního videa ze seznamu.

    • Nepovinný parametr startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, od něhož se má první video ze seznamu videí začít přehrávat.

    • Nepovinný parametr suggestedQuality určuje navrhovanou kvalitu přehrávání videa. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

  • Object syntax

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number,
                         suggestedQuality:String}):Void
    Tato funkce načte zadaný seznam a přehraje ho. Může jít o seznam videí, zdroj výsledků vyhledávání nebo zdroj nahraných videí uživatele.
    • Nepovinná vlastnost listType specifikuje typ zdroje výsledků, který vyvoláváte. Platné hodnoty jsou playlist, search a user_uploads. Výchozí hodnota je playlist.

    • Povinná vlastnost list obsahuje klíč identifikující konkrétní seznam videí, který má služba YouTube vrátit.

      • Má-li vlastnost listType hodnotu playlist, potom vlastnost list specifikuje identifikátor seznamu videí nebo pole identifikátorů seznamů videí. Ve zdrojích videí YouTube Data API specifikuje tag <yt:playlistid> identifikátor seznamu videí a tag <yt:videoid> specifikuje ID videa.
      • Má-li vlastnost listType hodnotu search, vlastnost list specifikuje vyhledávací dotaz.
      • Má-li vlastnost listType hodnotu user_uploads, potom vlastnost list identifikuje uživatele, jehož nahraná videa se mají vrátit.

    • Nepovinná vlastnost index specifikuje index prvního videa v seznamu, který se přehraje. Parametr používá index číslovaný od nuly a výchozí hodnota parametru je 0, takže ve výchozím nastavení funkce načte a přehraje první video ze seznamu.

    • Nepovinná vlastnost startSeconds přijímá celé číslo nebo číslo s plovoucí desetinnou čárkou a určuje čas, od něhož se má první video v seznamu začít přehrávat.

    • Nepovinná vlastnost suggestedQuality specifikuje navrhovanou kvalitu přehrávání pro seznam videí. Další informace o kvalitě přehrávání najdete v definici funkce setPlaybackQuality.

Ovládací prvky přehrávání a nastavení přehrávače

Přehrávání videa

player.playVideo():Void
Přehraje aktuálně zařazené nebo načtené video. Koncový stav přehrávače po provedení funkce bude playing (1).

Poznámka: Přehrání se započítává do oficiálního počtu zhlédnutí videa, je-li iniciováno z přehrávače nativním tlačítkem přehrání.
player.pauseVideo():Void
Pozastaví přehrávání aktuálně přehrávaného videa. Koncový stav přehrávače po provedení této funkce bude paused (2). Pokud ovšem bude při volání funkce přehrávač ve stavu ended (0), funkce stav přehrávače nezmění.
player.stopVideo():Void
Zastaví a zruší načítání aktuálního videa. Tato funkce by měla být rezervována pro zřídka nastávající situaci, kdy víte, že uživatel nebude sledovat v přehrávači další video. Je-li vaším záměrem pozastavit přehrávání videa, použijte funkci pauseVideo. Chcete-li změnit video, které přehrávač přehrává, můžete volat jednu z funkcí zařazení do fronty, není třeba nejprve volat funkci stopVideo.

Důležité: Na rozdíl od funkce pauseVideo, která ponechá přehrávač ve stavu paused (2), funkce stopVideo může změnit stav přehrávače na libovolný stav jiný než přehrávání, například ended (0), paused (2), video cued (5) nebo unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Vyhledá ve videu specifikovaný čas. Pokud je přehrávání při volání funkce pozastaveno, zůstane pozastaveno. Je-li funkce volána z jiného stavu (playing, video cued, apod.), přehrávač přehraje video.
  • Parametr seconds (sekundy) identifikuje čas, na který se má přehrávač posunout.

    Pokud přehrávač zatím nestáhl část videa, kterou uživatel hledá, přehrávač se posune na nejbližší klíčový snímek před zadaným časem. Je-li již část stažená, přehrávač se posune na nejbližší klíčový snímek před nebo po specifikovaném čase tak, jak určuje metoda seek() objektu NetStream přehrávače Flash. (Další informace najdete v dokumentaci společnosti Adobe.)

  • Parametr allowSeekAhead určuje, zda přehrávač provede nový požadavek na server, pokud parametr seconds specifikuje čas mimo rozsah dat aktuálně načtených ve vyrovnávací paměti.

    Doporučujeme, abyste tento parametr nastavili v době, kdy uživatel pohybuje myší po ukazateli postupu videa, na hodnotu false. Potom, když uživatel uvolní tlačítko myši, nastavte parametr na hodnotu true. Tak bude uživatel moci přecházet posuvníkem k různým místům videa nenačtených do vyrovnávací paměti, aniž by došlo k vyžádání nových streamů videa. Když uživatel uvolní tlačítko myši, přehrávač se posune na požadované místo ve videu a je-li to nutné, vyžádá si nový videostream.

player.clearVideo():Void
Vymaže zobrazení videa. Tato funkce je užitečná k vymazání zbývajícího obrazu po volání funkce stopVideo(). Poznámka: Podpora funkce byla ukončena v ActionScript 3.0 Player API.

Přehrání videa v seznamu videí

player.nextVideo():Void
Tato funkce načte a přehraje další video ze seznamu videí.
  • Pokud dojde k volání funkce player.nextVideo() v průběhu sledování posledního videa ze seznamu videí, a pokud je v seznamu nastaveno nepřetržité přehrávání (loop), přehrávač načte a přehraje první video ze seznamu.

  • Pokud dojde k volání funkce player.nextVideo() v průběhu sledování posledního videa ze seznamu videí, a pokud v seznamu není nastaveno nepřetržité přehrávání, přehrávání se ukončí.

player.previousVideo():Void
Tato funkce načte a přehraje předcházející video ze seznamu videí.
  • Pokud dojde k volání funkce player.previousVideo() v průběhu sledování prvního videa ze seznamu videí, a pokud je v seznamu nastaveno nepřetržité přehrávání (loop), přehrávač načte a přehraje poslední video ze seznamu.

  • Pokud dojde k volání funkce player.previousVideo() v průběhu sledování prvního videa ze seznamu videí, a pokud v seznamu není nastaveno nepřetržité přehrávání, přehrávač restartuje první video ze seznamu od začátku.

player.playVideoAt(index:Number):Void
Tato funkce načte a přehraje zadané video ze seznamu videí.
  • Povinný parametr index specifikuje index videa, které chcete ze seznamu přehrát. Parametr používá index číslovaný od nuly, takže hodnota 0 identifikuje první video ze seznamu. Pokud jste zadali náhodné přehrávání seznamu videí, tato funkce přehraje video na zadané pozici v náhodně uspořádaném seznamu.

Změna hlasitosti přehrávače

player.mute():Void
Ztlumí přehrávač.
player.unMute():Void
Zruší ztlumení přehrávače.
player.isMuted():Boolean
Je-li přehrávač ztlumený, vrací hodnotu true, není-li ztlumený, vrací hodnotu false.
player.setVolume(volume:Number):Void
Nastavuje hlasitost. Přijímá celé číslo od 0 do 100.
player.getVolume():Number
Vrací aktuálně nastavenou hlasitost přehrávače, celé číslo od 0 do 100. Všimněte si, že funkce getVolume() vrátí hodnotu i v případě, že je přehrávač ztlumený.

Nastavení velikosti přehrávače

player.setSize(width:Number, height:Number):Object
Nastavte velikost prvku <iframe>, který obsahuje přehrávač, v pixelech.

Nastavení rychlosti přehrávání

player.getPlaybackRate():Number
Tato funkce načte rychlost přehrávání aktuálně přehrávaného videa. Výchozí rychlost přehrávání je 1, což znamená, že video se přehrává normální rychlostí. Rychlost přehrávání může být nastavena na hodnoty typu 0.25, 0.5, 1, 1.5 a 2.
player.setPlaybackRate(suggestedRate:Number):Void
Funkce nastavuje navrhovanou rychlost přehrávání aktuálního videa. Když se změní rychlost přehrávání, změní se pouze pro aktuálně přehrávané nebo zařazené video. Pokud nastavíte rychlost přehrávání zařazeného videa, rychlost zůstane v platnosti i po volání funkce playVideo nebo po vyvolání přehrávání uživatelem přímo přes ovládací prvky přehrávače. Dále si uvědomte, že voláním funkcí pro zařazení nebo načtení videa nebo seznamu videí (cueVideoById, loadVideoById, apod.) resetujete rychlost přehrávání na 1.

Volání této funkce nezaručuje, že se rychlost přehrávání skutečně změní. Pokud se ale změní, vyšle se událost onPlaybackRateChange, na kterou by váš kód měl reagovat spíše než na skutečnost, že byla volána funkce setPlaybackRate.

Metoda getAvailablePlaybackRates vrátí přípustné rychlosti přehrávání pro aktuálně přehrávané video. Pokud ovšem nastavíte parametr suggestedRate na nepodporované celé číslo nebo na číslo s plovoucí desetinnou čárkou, přehrávač hodnotu zaokrouhlí dolů na nejbližší podporovanou hodnotu směrem k 1.
player.getAvailablePlaybackRates():Array
Tato funkce vrací sadu rychlostí přehrávání dostupných pro aktuálně přehrávané video. Výchozí hodnota je 1, která znamená, že video se přehraje normální rychlostí.

Funkce vrací pole čísel seřazených od nejpomalejší rychlosti přehrávání po nejrychlejší. I v případě, že přehrávač nepodporuje proměnlivou rychlost přehrávání, pole musí obsahovat alespoň jednu hodnotu (1).

Nastavení chování přehrávání pro seznamy videí

player.setLoop(loopPlaylists:Boolean):Void

Tato funkce určuje, zda se má seznam nepřetržitě přehrávat, nebo zda se má přehrávání po přehrání posledního videa ze seznamu ukončit. Ve výchozím nastavení se přehrávání videí po posledním videu ukončí.

Toto nastavení přetrvá i při zařazení nebo načtení jiného seznamu videí. To znamená, že pokud načtete seznam videí, zavoláte funkci setLoop s hodnotou true a potom načtete jiný seznam videí, bude se i ten přehrávat nepřetržitě.

Povinný parametr loopPlaylists identifikuje nepřetržité přehrávání.

  • Je-li hodnota parametru true, videopřehrávač bude přehrávat nepřetržitě. Po přehrání posledního videa ze seznamu videí přejde videopřehrávač zpět na začátek seznamu a začne ho přehrávat znovu.

  • Je-li hodnota parametru false, přehrávání se ukončí po přehrání posledního videa ze seznamu.

player.setShuffle(shufflePlaylist:Boolean):Void

Tato funkce určuje, zda se mají videa ze seznamu přehrávat v náhodném pořadí, tedy v jiném pořadí, než jak je sestavil autor seznamu. Pokud nastavíte náhodné přehrávání až po zahájení přehrávání videí ze seznamu, seznam se přeskupí, ale aktuálně přehrávané video se nepřeruší. Další video, které se přehraje, se vybere ze seznamu se změněným pořadím.

Při zařazení nebo načtení jiného seznamu videí se toto nastavení zruší. To znamená, že pokud načtete seznam videí, zavoláte funkci setShuffle a potom načtete jiný seznam videí, nový seznam videí se nebude přehrávat náhodně.

Povinný parametr shufflePlaylist určuje, zda má YouTube přehrávat seznam videí náhodně.

  • Je-li hodnota parametru true, YouTube změní pořadí přehrávání na náhodné. Pokud funkci zadáte náhodné přehrání seznamu, jehož pořadí přehrávání je již nastaveno na náhodné, YouTube změní pořadí znovu.

  • Je-li hodnota parametru false, YouTube změní pořadí přehrávání zpět na původní nastavení autora seznamu.

Stav přehrávání

player.getVideoLoadedFraction():Float
Vrací číslo mezi 0 a 1, které určuje procento videa, jež se v přehrávači zobrazuje jako načtené. Tato metoda zobrazuje spolehlivější číslo než metody getVideoBytesLoaded a getVideoBytesTotal, jejichž podpora již byla ukončena.
player.getPlayerState():Number
Vrací stav přehrávače. Může nabývat jedné z následujících hodnot:
  • -1 – nezahájeno
  • 0 – ukončeno
  • 1 – hraje
  • 2 – pozastaveno
  • 3 – načítání
  • 5 – video zařazeno
player.getCurrentTime():Number
Vrací čas, který uplynul od zahájení přehrávání videa, v sekundách.
player.getVideoStartBytes():Number
Podpora byla ukončena 31. října 2012. Vrací počet bajtů od zahájení načítání videa. (Tato metoda nyní vždy vrací hodnotu 0.) Příklad situace: Uživatel přejde dopředu na místo, které dosud nebylo načteno, a přehrávač provede nový požadavek na přehrání segmentu videa, který se dosud nenačetl.
player.getVideoBytesLoaded():Number
Podpora byla ukončena 18. července 2012. K určení procenta videa, které bylo načteno do vyrovnávací paměti, nyní používejte metodu getVideoLoadedFraction.

Tato metoda vrací hodnotu mezi 0 a 1000, která odhaduje velikost již načtené části videa. Poměrnou část videa, která je již načtena, můžete vypočítat vydělením hodnoty getVideoBytesLoaded hodnotou getVideoBytesTotal.
player.getVideoBytesTotal():Number
Podpora byla ukončena 18. července 2012. K určení procenta videa, které bylo načteno do vyrovnávací paměti, nyní používejte metodu getVideoLoadedFraction.

Vrací velikost aktuálně načteného nebo přehrávaného videa v bajtech nebo přibližný odhad velikosti videa.

Tato metoda vždy vrací hodnotu 1000. Poměrnou část videa, která je již načtena, můžete vypočítat vydělením hodnoty getVideoBytesLoaded hodnotou getVideoBytesTotal.

Kvalita přehrávání

player.getPlaybackQuality():String
Tato funkce načte skutečnou kvalitu obrazu aktuálního videa. Vrací hodnoty highres, hd1080, hd720, large, medium a small. Pokud neexistuje žádné aktuální video, vrací hodnotu undefined.
player.setPlaybackQuality(suggestedQuality:String):Void
Tato funkce nastavuje doporučenou kvalitu přehrávání videa. Funkce způsobí opakované načtení videa od aktuální pozice v nově nastavené kvalitě. Pokud se kvalita přehrávání změní, změní se pouze pro aktuálně přehrávané video. Volání této funkce nezaručuje, že se kvalita přehrávání skutečně změní. Pokud se ovšem kvalita přehrávání změní, vyšle se událost onPlaybackQualityChange a váš kód by měl reagovat na tuto událost spíše než na fakt, že došlo k volání funkce setPlaybackQuality.

Parametr suggestedQuality může nabývat hodnot small, medium, large, hd720, hd1080, highres a default. Doporučujeme, abyste hodnotu parametru nastavili na default, což dá pokyn službě YouTube, aby vybrala nejvhodnější kvalitu přehrávání, která se liší pro různé uživatele, videa, systémy a další podmínky přehrávání.

Když doporučíte kvalitu přehrávání pro video, doporučená kvalita se použije pouze pro dané video. Měli byste vybrat kvalitu přehrávání, která odpovídá velikosti vašeho přehrávače. Pokud vaše stránka například zobrazuje přehrávač ve velikosti 1280 x 720 pixelů, bude lépe vypadat video kvality hd720 než video kvality hd1080. Abyste určili, jaká nastavení kvality přehrávání jsou pro video k dispozici, doporučujeme volat funkci getAvailableQualityLevels().

V následujícím seznamu uvádíme úrovně kvality přehrávání, které odpovídají standardním velikostem přehrávače. Doporučujeme, abyste výšku přehrávače videa nastavili na jednu z hodnot v seznamu a nastavili poměr stran přehrávače na 16:9. Jak je uvedeno výše, i v případě, že vyberete standardní velikost přehrávače, doporučujeme nastavit hodnotu parametru suggestedQuality na default, aby služba YouTube mohla vybrat nejvhodnější kvalitu přehrávání.

  • Úroveň kvality small: výška přehrávače je 240 pixelů a rozměry přehrávače jsou pro poměr stran 4:3 nejméně 320 x 240 pixelů.
  • Úroveň kvality medium: výška přehrávače je 360 pixelů a rozměry přehrávače jsou 640 x 360 pixelů (pro poměr stran 16:9) nebo 480 x 360 pixelů (pro poměr stran 4:3).
  • Úroveň kvality large: výška přehrávače je 480 pixelů a rozměry přehrávače jsou 853 x 480 pixelů (pro poměr stran 16:9) nebo 640 x 480 pixelů (pro poměr stran 4:3)
  • Úroveň kvality hd720: výška přehrávače je 720 pixelů a rozměry přehrávače jsou 1280 x 720 pixelů (pro poměr stran 16:9) nebo 960 x 720 pixelů (pro poměr stran 4:3).
  • Úroveň kvality hd1080: výška přehrávače je 1080 pixelů a rozměry přehrávače jsou 1920 x 1080 pixelů (pro poměr stran 16:9) nebo 1440 x 1080 pixelů (pro poměr stran 4:3).
  • Úroveň kvality highres: výška přehrávače je větší než 1080px, což znamená, že poměr stran přehrávače je větší než 1920 x 1080 pixelů.
  • Úroveň kvality default: služba YouTube vybere vhodnou kvalitu přehrávání. Toto nastavení efektivně vrátí úroveň kvality do výchozího stavu a vynuluje všechny předchozí pokusy o nastavení kvality přehrávání pomocí funkcí cueVideoById, loadVideoById nebo setPlaybackQuality.

Dojde-li k volání funkce setPlaybackQuality s úrovní suggestedQuality, která není pro video k dispozici, kvalita bude nastavena na nejbližší nižší úroveň, která je k dispozici. Pokud například vyžádáte úroveň kvality large, která není k dispozici, kvalita bude nastavena na medium (pokud je tato úroveň kvality k dispozici).

Navíc nastavení doporučené kvality suggestedQuality na hodnotu, která není rozpoznána jako úroveň kvality, odpovídá nastavení možnosti suggestedQuality na default.
player.getAvailableQualityLevels():Array
Funkce vrací sadu formátů kvality, v nichž je aktuální video k dispozici. Tato funkce slouží k určení, zda je video k dispozici ve vyšší kvalitě, než v jaké ho uživatel aktuálně sleduje, a zda přehrávač může zobrazit tlačítko nebo jiný ovládací prvek, aby mohl uživatel upravit kvalitu.

Funkce vrací pole řetězců seřazených od nejvyšší kvality po nejnižší. Možné prvky v poli jsou highres, hd1080, hd720, large, medium a small. Neexistuje-li žádné aktuální video, funkce vrací prázdné pole.

Klient by neměl automaticky přepínat na použití nejvyšší (nebo nejnižší) kvality videa nebo na jakýkoli název neznámého formátu. YouTube rozšiřuje seznam úrovní kvality tak, aby obsahoval formáty, které nemusejí být vhodné v kontextu vašeho přehrávače. Podobně může služba YouTube odebrat možnosti nastavení kvality, které by narušovaly pohodlí uživatele. Když zajistíte, aby klient přepínal pouze na známé dostupné formáty, nebude chování klientu ovlivněno přidáváním nových úrovní kvality ani odebráním úrovní kvality, které nejsou vhodné pro kontext vašeho přehrávače.

Získávání informací o videu

player.getDuration():Number
Vrací dobu trvání aktuálně přehrávaného videa v sekundách. Poznámka: Funkce getDuration() bude vracet 0 do načtení metadat videa, což obvykle nastane ihned po spuštění přehrávání videa.

Je-li aktuálně přehrávané video přímý přenos, vrátí funkce getDuration() čas, který vypršel od zahájení živého streamování videa. Přesněji řečeno, jedná se o dobu, po kterou je video streamováno od posledního resetu nebo přerušení. Kromě toho je tato doba trvání často větší než skutečná délka přenášené události, protože streamování může být zahájeno před začátkem události.
player.getVideoUrl():String
Vrací adresu URL aktuálně načteného nebo přehrávaného videa na YouTube.com.
player.getVideoEmbedCode():String
Vrací kód pro vložení aktuálně načteného nebo přehrávaného videa.

Získávání informací o seznamu videí

player.getPlaylist():Array
Tato funkce vrací pole identifikátorů videa v seznamu videí v aktuálním pořadí. Ve výchozím nastavení vrací funkce pořadí videí stanovené autorem seznamu. Pokud ovšem došlo k volání funkce setShuffle, která změní pořadí přehrávání na náhodné, návratová hodnota funkce getPlaylist() bude v náhodně změněném pořadí.
player.getPlaylistIndex():Number
Tato funkce vrací index aktuálně přehrávaného videa ze seznamu videí.
  • Pokud jste nenastavili náhodné přehrávání seznamu, návratová hodnota identifikuje pozici, na kterou video umístil autor seznamu. Vrácená hodnota používá index číslovaný od nuly, takže hodnota 0 identifikuje první video v seznamu.

  • Pokud jste nenastavili náhodné přehrávání seznamu, návratová hodnota identifikuje pořadí videa v náhodně nastaveném seznamu.

Přidání nebo odebrání posluchače událostí

player.addEventListener(event:String, listener:String):Void
Přidává funkci posluchače pro zadanou událost event. V části Události uvádíme jednotlivé události, které přehrávač může vysílat. Posluchač je řetězec, který určuje funkci, která se spustí při vyslání určené události.
player.removeEventListener(event:String, listener:String):Void
Odebere funkci posluchače pro zadanou událost event. Posluchač listener je řetězec identifikující funkci, která se již při vyslání určené události nemá spouštět.

Přístup k uzlům DOM a jejich úpravy

player.getIframe():Object
Tato metoda vrací uzel DOM vloženého prvku <iframe>.
player.destroy():Void
Odebírá prvek <iframe>, který obsahuje přehrávač.

Události

Rozhraní API vysílá události, aby vaší aplikaci oznámilo změny vloženého přehrávače. Jak jsme již psali v předchozí části, události můžete odebírat pomocí posluchače událostí, který přidáte při konstruování objektu YT.Player. Můžete použít i funkci addEventListener.

Rozhraní API předá objekt události každé z těchto funkcí jako jediný argument. Objekt události má následující vlastnosti:

  • Vlastnost target (cíl) objektu identifikuje videopřehrávač, který s událostí souvisí.
  • Vlastnost data události specifikuje hodnotu podle dané události. Poznámka: Vlastnost onReady události nespecifikuje vlastnost data.

V následujícím seznamu definujeme události, které rozhraní API vysílá:

onReady
Tato událost se vyšle ve chvíli, kdy přehrávač dokončil načítání a je připraven přijímat volání rozhraní API. V aplikaci potřebujete tuto funkci implementovat, chcete-li automaticky provádět určité operace, například přehrát video nebo zobrazit informace o videu ve chvíli, kdy je přehrávač připraven.

Uvádíme příklad vzorové funkce, která tuto událost zpracovává. Objekt události, který rozhraní API předává funkci, má vlastnost target identifikující daného hráče. Funkce vyvolá vložený kód pro aktuálně načtené video, spustí přehrávání videa a v prvku stránky s hodnotou id vlastnosti embed-code zobrazí vložený kód.
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
Událost se vyšle, když se změní stav přehrávače. Vlastnost data objektu události, který rozhraní API předává vaší funkci posluchače událostí, bude obsahovat celé číslo odpovídající novému stavu přehrávače. Může nabývat jedné z následujících hodnot:

  • -1 (nezahájeno)
  • 0 (ukončeno)
  • 1 (přehrává se)
  • 2 (pozastaveno)
  • 3 (načítá se)
  • 5 (video zařazeno).

Když hráč video načte poprvé, video vyšle událost unstarted (-1). Když je video zařazeno a je připraveno k přehrání, přehrávač vyšle událost video cued (5). V rámci kódu můžete zadat vlastní celočíselné hodnoty, nebo můžete použít jednu z následujících proměnných z jmenného prostoru:

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

onPlaybackQualityChange
Tato událost se vyšle vždy, když se změní kvalita přehrávání videa. Pokud například voláte funkci setPlaybackQuality(suggestedQuality), událost se vyšle v případě, že se kvalita přehrávání skutečně změnila. Vaše aplikace by na funkci měla reagovat a nepředpokládat automaticky, že se při volání funkce setPlaybackQuality(suggestedQuality) kvalita přehrávání změní. Váš kód by také neměl předpokládat, že kvalita přehrávání videa se může změnit pouze v důsledku explicitního volání funkce setPlaybackQuality nebo jakékoli jiné funkce, která umožňuje nastavit navrhovanou kvalitu přehrávání.

Hodnota vlastnosti data objektu události, který rozhraní API předá funkci posluchače událostí, bude řetězec identifikující novou kvalitu přehrávání. Může nabývat jedné z následujících hodnot:

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

onPlaybackRateChange
Tato událost se vyšle vždy, když dojde ke změně snímkové frekvence přehrávání videa. Příklad: při volání funkce setPlaybackRate(suggestedRate) se tato událost vyšle, pokud se snímková frekvence přehrávání skutečně změní. Vaše aplikace by na funkci měla reagovat a nepředpokládat automaticky, že se při volání funkce setPlaybackRate(suggestedRate) snímková frekvence přehrávání skutečně změní. Váš kód by také neměl předpokládat, že snímková kvalita přehrávání videa se změní pouze v důsledku explicitního volání funkce setPlaybackRate.

Hodnota vlastnosti data objektu události, který rozhraní API předá posluchači událostí, bude číslo identifikující novou snímkovou frekvenci přehrávání. Metoda getAvailablePlaybackRates vrací seznam platných snímkových frekvencí přehrávání pro video, které bylo aktuálně zařazeno nebo se přehrává.
onError
Tato událost se vyšle, dojde-li v přehrávači k chybě. Rozhraní API předá funkci posluchače událostí objekt event. Vlastnost tohoto objektu data bude obsahovat celé číslo identifikující typ chyby, k níž došlo. Může nabývat jedné z následujících hodnot:

  • 2 – požadavek obsahuje neplatnou hodnotu parametru. Chyba se vyskytne například v případě, že specifikujete ID videa, které není složeno z 11 znaků nebo obsahuje neplatné znaky, jako je vykřičník nebo hvězdička.
  • 5 – požadovaný obsah nelze přehrát v přehrávači HTML5, nebo došlo k jiné chybě přehrávače HTML5.
  • 100 – požadované video nebylo nalezeno. K chybě dojde v případě, že video bylo odebráno (z jakéhokoli důvodu) nebo bylo označeno jako soukromé.
  • 101 – vlastník požadovaného videa nepovolil přehrávání videa ve vložených přehrávačích.
  • 150 – stejná chyba jako 101. Je to jen převlečená chyba 101!

onApiChange
Tato událost se vyšle jako indikace, že přehrávač načetl modul s exponovanými metodami API (nebo načtení zrušil). Vaše aplikace bude naslouchat této události a potom prozkoumá přehrávač, aby určila, které možnosti jsou exponované v aktuálně načteném modulu. Vaše aplikace může vyvolat nebo aktualizovat existující nastavení těchto možností.

Následující příkaz vyvolá pole názvů modulů, pro něž lze nastavit možnosti přehrávače:
player.getOptions();
Momentálně je jediným modulem, pro který lze nastavit možnosti, modul cc zpracovávající titulkování v přehrávači. Po přijetí události onApiChange může vaše aplikace pomocí následujícího příkazu určit, které možnosti lze pro modul cc nastavit:
player.getOptions('cc');
Prozkoumáním přehrávače tímto příkazem můžete ověřit, zda máte skutečně přístup k možnostem, které potřebujete. Následující příkazy vyvolají a aktualizují možnosti modulu:
Vyvolání možnosti:
player.getOption(module, option);

Nastavení možnosti:
player.setOption(module, option, value);
V následující tabulce najdete možnosti, které rozhraní API podporuje:

Modul Možnost Popis
cc fontSize Tato možnost upravuje velikost písma titulků zobrazených v přehrávači.

Platné hodnoty jsou -1, 0, 1, 2, a 3. Výchozí velikost je 0 a nejmenší velikost je -1. Při nastavení této možnosti na celé číslo menší než -1 se titulky zobrazí písmem nejmenší velikosti, při nastavení celého čísla většího než 3 se použije největší velikost.
cc reload Tato možnost způsobí opětovné načtení dat titulků přehrávaného videa. Pokud vyvoláte hodnotu této možnosti, hodnota bude null. Chcete-li znovu načíst data titulků, nastavte hodnotu na true.

Úvahy k mobilním zařízením

Automatické přehrávání a přehrávání pomocí skriptu

Prvek HTML5 <video> umožňuje v některých mobilních prohlížečích (jako je Chrome a Safari) vyvolaných interakcí uživatele (například klepnutím na přehrávač) pouze přehrávání. Uvádíme úryvek z dokumentace společnosti Apple:

„Upozornění: Abychom zabránili nevyžádanému stahování v mobilních sítích, za která by uživatel musel zaplatit, vložená média nelze v prohlížeči Safari v systému iOS přehrát automaticky – uživatel musí vždy přehrávání vyvolat.“

Kvůli tomuto omezení nebudou parametry autoplay, playVideo(), loadVideoById() v některých mobilních prostředích fungovat.

Příklady

Vytváření objektů YT.Player

  • Příklad 1: Hlasité přehrávání

    V tomto příkladu vytvoříme přehrávač 1280 x 720 pixelů. Posluchač událostí pro událost onReady potom vyvolá funkci setVolume upravující hlasitost na nejvyšší úroveň.

    function onYouTubeIframeAPIReady() {
      var player;
      player = new YT.Player('player', {
        width: 1280,
        height: 720,
        videoId: 'M7lc1UVf-VE',
        events: {
          'onReady': onPlayerReady,
          'onPlaybackQualityChange': onPlayerPlaybackQualityChange,
          'onStateChange': onPlayerStateChange,
          'onError': onPlayerError
        }
      });
    }
    
    function onPlayerReady(event) {
      event.target.setVolume(100);
      event.target.playVideo();
    }
  • Příklad 2: V tomto příkladu se parametry přehrávače nastaví tak, aby se video po načtení automaticky přehrálo a skrylo ovládací prvky přehrávače. Přidá i posluchače událostí pro všechny události, které rozhraní API vysílá.

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

Historie změn

V této části najdete seznam všech změn a aktualizací dokumentace rozhraní API přehrávače v prvku iframe YouTube. Přihlaste se k odběru protokolu změn. Přihlásit se k odběru

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.