YouTube JavaScript Player API Reference

JavaScript API を使用すると、JavaScript を介して、YouTube クロムレス プレーヤーや埋め込み動画プレーヤーを制御できます。関数を呼び出すことで、再生、一時停止、指定した動画位置のシーク、音量の調整、ミュートなどさまざまな操作が可能になります。

要件

適切に表示するためには、エンドユーザーは Flash Player 10.1 以上をインストールする必要があります。したがって、SWFObject を使用して SWF を埋め込み、ユーザーが使用している Flash Player のバージョンを検出することをお勧めします。

また、YouTube プレーヤーが組み込まれた HTML ページすべてに JavaScript 関数 onYouTubePlayerReady を実装する必要があります。プレーヤーの読み込みが完了し、API で呼び出しを受け取れるようになると、API によりこの関数が呼び出されます。詳しくは、イベント ハンドラのセクションを参照してください。

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.

はじめに

: Flash Player ではローカル ファイルとインターネット間での呼び出しが制限されているため、これらの呼び出しをテストするには、Web サーバー上でファイルを実行する必要があります。

クロムレス プレーヤーや埋め込みプレーヤーを使用するには、JavaScript API ハンドラを有効化します。あるプレーヤーで使用する JavaScript API を有効にするには、そのプレーヤーの URL に URL パラメータ enablejsapi=1 を追加します。

  • クロムレス プレーヤーで使用する JavaScript API を有効にする

    アプリケーションがクロムレス プレーヤーを使用している場合は、次の URL を使用して、アプリケーションにプレーヤーを読み込み、このプレーヤーで JavaScript API ハンドラを有効にします。その後、JavaScript を使用して、独自にカスタム プレーヤー コントロールを構築します。

    http://www.youtube.com/apiplayer?enablejsapi=1&version=3
  • 埋め込みプレーヤーで使用する JavaScript API を有効にする

    次の URL を使用して、埋め込み動画プレーヤーを読み込みます。この URL の文字列 VIDEO_ID は、プレーヤーで再生される動画を表す 11 文字の YouTube 動画 ID で置き換えてください。

    http://www.youtube.com/v/VIDEO_ID?version=3&enablejsapi=1

プレーヤーの準備ができると、API により onYouTubePlayerReady コールバック関数が呼び出されます。プレーヤーの URL に playerapiid パラメータ(省略可能)を指定すると、コールバック関数にプレーヤー ID などの値を渡すことができます。

http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&version=3&playerapiid=ytplayer

プレーヤー SWF が読み込まれると、cueVideoById()loadVideoById()cueVideoByUrl()loadVideoByUrl()cuePlaylist()loadPlaylist() などのキュー関数を使用して、特定の YouTube 動画や再生リストを読み込めるようになります。

Player API デモでは、クロムレス プレーヤーと埋め込み動画プレーヤーを比較できます。下のは、YouTube プレーヤー SWF をページに埋め込む方法を詳しく説明しています。また、プレーヤー パラメータを使用して、プレーヤーのさまざまなタイプの動作をコントロールし、ユーザーの利便性をカスタマイズすることもできます。

動作

プレーヤー API メソッドを呼び出すには、まず制御するプレーヤー オブジェクトへの参照を取得する必要があります。プレーヤー SWF の埋め込みに SWFObject を使用している場合は、プレーヤー SWF を含む getElementById() または <object> タグで <embed> を呼び出して、プレーヤー オブジェクトへの参照を取得することができます。

関数

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

Poznámka: Ačkoli přehrávač AS3 podporuje ovládání rychlosti přehrávání, proměnlivou rychlost přehrávání aktuálně podporuje pouze přehrávač HTML5.

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.

Vrací počet bajtů načtených pro aktuální video.
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.

Přesněji řečeno, tato funkce odhadne přibližnou velikost videa v případě, že hodnota player.getVideoStartBytes() je větší než nula. Funkce musí velikost odhadovat, protože skutečnou velikost videa zná přehrávač pouze v případě, že přehrávání videa začalo od začátku.

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.

イベント

onStateChange
Událost se vyšle, když se změní stav přehrávače. Hodnota, kterou 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, kterou rozhraní API předá funkci posluchače událostí, bude obsahovat ř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, kterou rozhraní API předá funkci posluchače 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á.

Poznámka: i přes to, že přehrávač AS3 tuto událost podporuje, proměnné rychlosti momentálně podporuje pouze přehrávač HTML5.

onError
Tato událost se vyšle, dojde-li v přehrávači k chybě. Hodnota, kterou rozhraní API předá posluchači událostí, bude 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.
  • 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.

イベント ハンドラ

クロムレス プレーヤーが表示される HTML ページには、コールバック関数 onYouTubePlayerReady の実装が必要です。プレーヤーの読み込みが完了し、API で呼び出しを受け取ることができるようになると、API により、この関数が呼び出されます。

onYouTubePlayerReady(playerid)
プレーヤーの読み込みが完了し、API で呼び出しを受け取ることができるようになると呼び出されます。playerapiid が URL 引数を介してプレーヤーに渡された場合、この ID はその後、この関数に渡されます。

SWFObject を使用した YouTube プレーヤーの埋め込み

JavaScript API を使用してアクセスされるプレーヤーの埋め込みには、SWFObject の使用を推奨します。これにより、エンドユーザーが使用している Flash Player のバージョン(JavaScript API では Flash Player 8 以降が必要)を検出できるだけでなく、Internet Explorer でプレーヤーを表示する際に [このコントロールを有効にする] ボックスが表示されなくなります。 SWF でこの API を有効にするには、パラメータ enablejsapi=1 を渡す必要があります。

以下のコードは、JavaScript API を有効にし、ytplayerplayerapiid を指定した YouTube プレーヤーを埋め込むスクリプトの使用例です。

  <script type="text/javascript" src="swfobject.js"></script>
  <div id="ytapiplayer">
    You need Flash player 8+ and JavaScript enabled to view this video.
  </div>

  <script type="text/javascript">

    var params = { allowScriptAccess: "always" };
    var atts = { id: "myytplayer" };
    swfobject.embedSWF("http://www.youtube.com/v/VIDEO_ID?enablejsapi=1&playerapiid=ytplayer&version=3",
                       "ytapiplayer", "425", "356", "8", null, null, params, atts);

  </script>

プレーヤーと埋め込み先 HTML ページは異なるドメインでホストされているため、このコードで allowScriptAccess パラメータを指定して、プレーヤー SWF から HTML ページ上の関数を呼び出せるようにする必要があります。

ここで渡している唯一の属性は、埋め込みオブジェクトの id で、この例では myytplayer です。この id は、getElementById() を使用してプレーヤーへの参照を取得する際に使用されます。

swfobject.embedSWF は YouTube からプレーヤーを読み込み、HTML ページに埋め込みます。

swfobject.embedSWF(swfUrlStr, replaceElemIdStr, widthStr, heightStr, swfVersionStr, xiSwfUrlStr, flashvarsObj, parObj, attObj)

  • swfUrlStr - これは SWF の URL です。標準の YouTube SWF URL に enablejsapiplayerapiid パラメータを追加して、JavaScript API 呼び出しを有効にしている点に注意してください。
  • replaceElemIdStr - 埋め込みコンテンツで置き換えられる HTML DIV ID です。上記の例では、ytapiplayer です。
  • widthStr - プレーヤーの幅。
  • heightStr - プレーヤーの高さ。
  • swfVersionStr - コンテンツを表示するために必要な最低限のバージョンです。この場合、バージョン 8 以上が必要です。ユーザー側に 8 以降のバージョンがインストールされていない場合は、HTML DIV に指定されているデフォルトのテキスト行が表示されます。
  • xiSwfUrlStr - (省略可能)SWF を高速インストールするための URL を指定します。この例では使用されていません。
  • flashVarsObj - (省略可能)FlashVars を名前と値の組で指定します。この例では使用されていません。
  • parObj - (省略可能)埋め込みオブジェクトのパラメータです。この例では、allowScriptAccess に設定されています。
  • AttObj - (省略可能)埋め込みオブジェクトの属性です。この例では、ID は myytplayer に設定されています。

詳しくは、SWFObject マニュアルを参照してください。

プレーヤー参照の取得

準備ができると、プレーヤーは onYouTubePlayerReady を呼び出します。

プレーヤーへの参照を取得するには、getElementById() を使用します。オブジェクトを取得したら、API への呼び出しを開始できます。

    function onYouTubePlayerReady(playerId) {
      ytplayer = document.getElementById("myytplayer");
    }

呼び出しの発行

これでプレーヤー参照を使用して、関数を呼び出すことができるようになりました。たとえば、ユーザーがリンクをクリックしたときに動画を再生するには、次のように記述します。

function play() {
  if (ytplayer) {
    ytplayer.playVideo();
  }
}

<a href="javascript:void(0);" onclick="play();">Play</a>

または次のように簡単に記述することもできます。

<a href="javascript:ytplayer.playVideo()">Play</a>

イベントへの登録

イベントへ登録するには、プレーヤー参照にイベント リスナーを追加します。たとえば、プレーヤーの状態が変わったときに通知を受け取るには、onStateChange に対するイベント リスナーを追加し、コールバック関数を組み込みます。

function onYouTubePlayerReady(playerId) {
  ytplayer = document.getElementById("myytplayer");
  ytplayer.addEventListener("onStateChange", "onytplayerStateChange");
}

function onytplayerStateChange(newState) {
   alert("Player's new state: " + newState);
}

ライブデモ

YouTube プレーヤーデモを使用して、埋め込みプレーヤー、またはクロムレス プレーヤーで JavaScript API の機能をテストすることができます。

改訂履歴

このセクションでは、YouTube JavaScript Player API の変更点とドキュメントの更新履歴をまとめます。この変更履歴を定期購読してください定期購読

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.

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

This update contains the following changes:

  • The API supports several new functions and one new event that can be used to control the video playback speed. However, note that variable playback speeds are currently only supported in the HTML5 player.

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

March 26, 2012

This update contains the following changes:

  • The Requirements section has been updated to note the minimum player size. 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.

December 21, 2011

This update contains the following changes:

  • The Requirements section has been updated to note that the end user must have Flash Player 10.1 or higher installed for the player to display everything correctly.

December 19, 2011

This update contains the following changes:

  • The AS3 Player API now supports an object syntax for calling the cuePlaylist and loadPlaylist functions.

    The object syntax lets you pass an object as the only argument to a function. The object's properties specify the function arguments that you wish to set.

  • The cuePlaylist and loadPlaylist functions both support additional functionality when called using the object syntax. Specifically, when using the object syntax, you can use both functions to retrieve either a playlist, a list of search results, or a list of a user's uploaded videos. If you are using the argument syntax, you can only retrieve a playlist.

    To support this functionality, the object syntax defines a listType property that can be used to specify whether the player is retrieving a playlist, a list of search results, or a list of a user's uploaded videos. The object's list property then specifies the playlist ID, search query, or username that identifies the desired feed.

    To properly reflect this functionality, the Queueing functions for playlists section has been renamed to Queueing functions for lists. Within that section, the cuePlaylist and loadPlaylist functions are each defined twice to explain how to call each function using either the argument syntax or the object syntax.

December 5, 2011

This update contains the following changes:

  • The definition of the seekTo function has been updated to indicate that if the player is paused when the function is called, the player will remain paused after the function executes.

November 17, 2011

This update contains the following changes:

  • The definitions of the cueVideoByUrl and loadVideoByUrl functions have been updated in two ways:

    • The definition of the mediaContentUrl argument for each function has been updated to note that the value must specify the version parameter. As such, the argument's value must be a fully qualified YouTube player URL in the format http://www.youtube.com/v/VIDEO_ID?version=3.
    • Both functions support a suggestedQuality parameter. This parameter specifies the suggested playback quality for the video.
  • The definition of the setSize function has been removed from the documentation. If you are using the JavaScript Player API, the player will automatically resize if the height and width properties of the containing elements in the embed code are modified. Since the setSize function does not currently alter the size of those containing elements, it is unlikely to have the expected effect.

  • The definition of the getDuration function has been updated to explain that if the currently playing video is a live event, the function will return the elapsed time since the video stream began.

July 29, 2011

This update contains the following changes:

  • The following API functions have been added to support playlist players:

    • The cuePlaylist function loads the thumbnail image for the first video in the specified playlist and prepares the player to play the playlist. However, the player does not request the video until your application calls either the playVideo, playVideoAt, or seekTo function.

    • The loadPlaylist function loads and plays the specified playlist.

    • The getPlaylist function plays the currently cued playlist. The final player state after this function executes will be playing (1).

    • The getPlaylistIndex function returns the position in which the current video appears in the playlist. The first video will have a position of 1, the second video will have a position of 2, and so forth.

    • The nextVideo function instructs the player to load and play the next video in the playlist.

    • The previousVideo function instructs the player to load and play the previous video in the playlist.

    • The playVideoAt function instructs the player to load and play a specific video in the playlist.

    • The setLoop function lets you dynamically instruct the player to continuously play the playlist or, alternately, to sto playing after the playlist has played all of the videos in the playlist.

    • The setShuffle function instructs YouTube to play the videos in the playlist in random order (or to play them in their designated order.

February 17, 2011

This update contains the following changes:

  • If you link to the Player Parameters document from this document, the page will now display parameters supported in any version of the player. You can use the pulldown menu in the Overview section of that document to only see parameters supported in the AS3 player (or in the HTML5 or AS2) players.

February 3, 2011

This update contains the following changes:

  • The definition of the playVideo function has been updated to note that YouTube only counts playbacks that are initiated through a native play button in either the embedded or chromeless player.

  • If you link to the Player Parameters document from either the link in the Getting started section or from this paragraph, the page will initially only display parameters supported in the AS3 player. You can use the pulldown menu in the Overview section of that document to see parameters supported in other players (HTML5 or AS2) or all parameters.