YouTube Player API Reference for iframe Embeds

IFrame 播放器 API 可讓您將 YouTube 影片播放器嵌入您的網站，並利用 JavaScript 控製播放器。

您可以使用 API 的 JavaScript 函式，將影片排入播放佇列、播放、暫停或停止影片、調整播放器音量，或擷取所播放影片的相關資訊。您也可以新增事件監聽器，以便在回應特定玩家事件 (例如玩家狀態變更) 時執行。

本指南說明如何使用 IFrame API。它會識別 API 可傳送的不同類型的事件，並說明如何撰寫事件監聽器來回應這些事件。其中也詳細說明您可以呼叫的各種 JavaScript 函式，以便控制影片播放器，以及可用來進一步自訂播放器的播放器參數。

需求條件

使用者的瀏覽器必須支援 HTML5 postMessage 功能。大多數的新式瀏覽器都支援 postMessage。

內嵌播放器的可視區域不得小於 200 x 200 像素。如果播放器顯示控制項，必須夠大才能完整顯示控制項，且不會將可視區域縮減到最小尺寸以下。我們建議 16:9 的播放器寬度至少為 480 像素，高度至少為 270 像素。

凡是使用 IFrame API 的網頁，都必須導入下列 JavaScript 函式：

  • onYouTubeIframeAPIReady – 網頁完成下載 Player API 所需的 JavaScript 後，API 會呼叫此函式，讓您能在頁面上使用 API。因此，這個函式可能會建立要在網頁載入時顯示的播放器物件。

開始使用

下方的範例 HTML 網頁會建立一個嵌入式播放器，其中會載入影片，播放六秒後停止播放。以下範例下方清單會說明 HTML 中加上編號的註解。

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

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

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

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

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

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

下列清單提供上述範例的更多詳細資料：

  1. 本節中的 <div> 標記會指明 IFrame API 在網頁上放置影片播放器的位置。如「載入影片播放器」一節所述，播放器物件的建構函式會由其 id 識別 <div> 標記，確保 API 將 <iframe> 放置在正確的位置。具體來說，IFrame API 會將 <div> 標記替換成 <iframe> 標記。

    或者，您也可以直接在網頁上放置 <iframe> 元素。做法請參閱「載入影片播放器」一節。

  2. 這個部分的程式碼會載入 IFrame Player API JavaScript 程式碼。這個範例使用 DOM 修改功能下載 API 程式碼，確保系統以非同步方式擷取程式碼。(所有新式瀏覽器都不支援 <script> 標記的 async 屬性 (可以啟用非同步下載)，詳情請參閱這個 Stack Overflow 解答。

  3. 下載玩家 API 程式碼後，onYouTubeIframeAPIReady 函式就會立即執行。這部分程式碼會定義 player 全域變數，也就是您要嵌入的影片播放器，接著函式會建構影片播放器物件。

  4. onReady 事件觸發時，系統會執行 onPlayerReady 函式。在此範例中，函式表示影片播放器準備就緒後，應該就會開始播放。

  5. 玩家狀態變更時，API 會呼叫 onPlayerStateChange 函式，這可能表示玩家正在播放、暫停、結束等。函式會指出播放器狀態為 1 (播放) 時，播放器應播放 6 秒，然後呼叫 stopVideo 函式以停止影片。

載入影片播放器

API 的 JavaScript 程式碼載入後，API 會呼叫 onYouTubeIframeAPIReady 函式，讓您建立 YT.Player 物件，將影片播放器插入網頁中。以下 HTML 摘錄顯示上述範例中的 onYouTubeIframeAPIReady 函式：

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

影片播放器的建構函式會指定下列參數：

  1. 第一個參數會指定 DOM 元素或 HTML 元素的 id，讓 API 在其中插入包含播放器的 <iframe> 標記。

    IFrame API 會將指定元素替換成包含播放器的 <iframe> 元素。如果所取代元素的顯示樣式與插入的 <iframe> 元素不同，這可能會影響網頁的版面配置。根據預設，<iframe> 會顯示為 inline-block 元素。

  2. 第二個參數是指定玩家選項的物件。且內含下列屬性：
    • width (數字)：影片播放器的寬度。預設值為 640。
    • height (數字)：影片播放器的高度。預設值為 390。
    • videoId (字串)：用於識別播放器將載入的影片的 YouTube 影片 ID。
    • playerVars (物件)：物件的屬性可識別可用於自訂播放器的播放器參數。
    • events (物件)：物件的屬性可識別 API 觸發的事件，以及 API 會在發生事件時呼叫的函式 (事件監聽器)。在範例中，建構函式表示 onPlayerReady 函式會在 onReady 事件觸發時執行，且 onPlayerStateChange 函式會在 onStateChange 事件觸發時執行。

如「開始使用」一節所述，您可以自行建立 <iframe> 標記，不要在網頁上編寫空白的 <div> 元素，讓玩家 API 的 JavaScript 程式碼取代為 <iframe> 元素。「範例」一節中的第一個範例說明如何進行這項操作。

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

請注意，如果您要編寫 <iframe> 標記，則在建構 YT.Player 物件時，您不需要指定 width 和 height 的值，這些參數會指定為 <iframe> 標記的屬性，或是 videoId 和玩家參數 (在 src 網址中指定)。為了提供額外的安全保障，您也應該在網址中加入 origin 參數，並在參數值中指定網址配置 (http:// 或 https://)，以及代管網頁的完整網域做為參數值。雖然 origin 是選用項目，但可以防止有心人士在應用程式中插入惡意第三方 JavaScript，並防止 YouTube 播放器遭到盜用。

「範例」部分也提供其他建構影片播放器物件的範例。

作業套件

如要呼叫播放器 API 方法，您必須先取得要控制的玩家物件的參照。如要取得參考資料，請按照本文的入門指南和載入影片播放器一節所述，建立 YT.Player 物件。

函式

將函式排入佇列

佇列功能可讓您載入和播放影片、播放清單或其他影片清單。如果您使用下述物件語法呼叫這些函式，您也可以將使用者上傳的影片排入佇列或載入清單。

API 支援兩種不同的語法來呼叫佇列函式。

  • 引數語法規定函式引數必須以指定順序列出。

  • 物件語法可讓您將物件做為單一參數傳遞，以及為您要設定的函式引數定義物件屬性。此外，這個 API 還可支援引數語法不支援的其他功能。

舉例來說，您可以透過下列任一方式呼叫 loadVideoById 函式。請注意，物件語法支援 endSeconds 屬性，但引數語法不支援該屬性。

  • 引數語法

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

  • 物件語法

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

影片佇列功能

cueVideoById

  • 引數語法

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

  • 物件語法

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

這個函式會載入指定影片的縮圖，並將播放器準備播放。除非呼叫 playVideo() 或 seekTo()，播放器才會請求 FLV。

  • 必要的 videoId 參數可指定所要播放影片的 YouTube 影片 ID。在 YouTube Data API 中，video 資源的 id 屬性會指定 ID。
  • 選用的 startSeconds 參數接受浮點值/整數，並指定在呼叫 playVideo() 時，影片應開始播放的時間。如果您指定 startSeconds 值並呼叫 seekTo()，則玩家會從 seekTo() 呼叫中指定的時間播放。當影片經裁剪並可供播放時，播放器將會播送 video cued 事件 (5)。
  • 選用的 endSeconds 參數 (只有物件語法支援) 接受浮點/整數，並指定在呼叫 playVideo() 時，影片停止播放的時間。如果您指定 endSeconds 值並呼叫 seekTo()，endSeconds 值將會失效。

loadVideoById

  • 引數語法

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

  • 物件語法

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

這個函式會載入並播放指定影片。

  • 必要的 videoId 參數可指定所要播放影片的 YouTube 影片 ID。在 YouTube Data API 中，video 資源的 id 屬性會指定 ID。
  • 選用的 startSeconds 參數接受浮點值/整數。如果指定了時間，影片會從最接近的主要畫面到指定時間開始播放。
  • 選用的 endSeconds 參數接受浮點值/整數。如果指定了這項設定，影片就會在指定時間停止播放。

cueVideoByUrl

  • 引數語法

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

  • 物件語法

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

這個函式會載入指定影片的縮圖，並將播放器準備播放。除非呼叫 playVideo() 或 seekTo()，播放器才會請求 FLV。

  • 必要的 mediaContentUrl 參數會指定完整的 YouTube 播放器網址，格式為 http://www.youtube.com/v/VIDEO_ID?version=3。
  • 選用的 startSeconds 參數接受浮點值/整數，並指定在呼叫 playVideo() 時，影片應開始播放的時間。如果指定 startSeconds 並呼叫 seekTo()，則玩家會從 seekTo() 呼叫中指定的時間開始播放。影片經裁剪且可供播放時，播放器將會播送 video cued 事件 (5)。
  • 選用的 endSeconds 參數 (只有物件語法支援) 接受浮點/整數，並指定在呼叫 playVideo() 時，影片停止播放的時間。如果您指定 endSeconds 值並呼叫 seekTo()，endSeconds 值將會失效。

loadVideoByUrl

  • 引數語法

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

  • 物件語法

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

這個函式會載入並播放指定影片。

  • 必要的 mediaContentUrl 參數會指定完整的 YouTube 播放器網址，格式為 http://www.youtube.com/v/VIDEO_ID?version=3。
  • 選用的 startSeconds 參數接受浮點值/整數，並指定影片開始播放的時間。如果指定 startSeconds (數字可以是浮點值)，影片會從最接近指定時間的主要畫面格開始計算。
  • 選用的 endSeconds 參數僅適用於物件語法，可接受浮點/整數，並指定影片停止播放的時間。

將函式排入清單

cuePlaylist 和 loadPlaylist 函式可讓您載入並播放播放清單。如果您使用物件語法呼叫這些函式，您也可以將使用者上傳的影片清單排入佇列 (或載入) 清單。

由於函式的使用方式取決於引數語法還是物件語法來呼叫，因此運作方式會有所不同，以下說明這兩種呼叫方法。

cuePlaylist

  • 引數語法

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
    將指定的播放清單排入佇列。播放清單經適當顯示並可供播放時，播放器將會播送 video cued 事件 (5)。

    • 必要的 playlist 參數會指定 YouTube 影片 ID 的陣列。在 YouTube Data API 中，video 資源的 id 屬性會識別影片 ID。

    • 選用的 index 參數可指定播放清單中第一部影片的索引。該參數使用從 0 開始的索引，而預設參數值為 0，因此預設行為是載入並播放播放清單中的第一部影片。

    • 選用的 startSeconds 參數接受浮點值/整數，並指定在呼叫 playVideo() 函式時，播放清單中第一部影片的開始播放時間。如果您指定 startSeconds 值並呼叫 seekTo()，則玩家會從 seekTo() 呼叫中指定的時間播放。如果選擇播放清單並呼叫 playVideoAt() 函式，玩家會開始播放指定影片的開頭處。

  • 物件語法

    player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
    將指定的影片清單排入佇列。清單可以是播放清單或使用者上傳的影片動態消息。搜尋結果清單的佇列功能已淘汰，自 2020 年 11 月 15 日起不再支援。

    清單獲選可播放時，播放器將會播送 video cued 事件 (5)。

    • 選用的 listType 屬性會指定您要擷取的結果動態饋給類型。有效值為 playlist 和 user_uploads。自 2020 年 11 月 15 日起，系統將不再支援已淘汰的值 search。預設值為 playlist。

    • 必要的 list 屬性含有一個鍵，能指定 YouTube 應傳回的特定影片清單。

      • 如果 listType 屬性值為 playlist，則 list 屬性會指定播放清單 ID 或影片 ID 陣列。在 YouTube Data API 中，playlist 資源的 id 屬性會識別播放清單的 ID，而 video 資源的 id 屬性會指定影片 ID。
      • 如果 listType 屬性值為 user_uploads，則 list 屬性會識別上傳影片的使用者。
      • 如果 listType 屬性值為 search，則 list 屬性會指定搜尋查詢。注意：這項功能已淘汰，自 2020 年 11 月 15 日起不再支援。

    • 選用的 index 屬性可指定清單中要播放的第一部影片的索引。該參數使用從 0 開始的索引，而預設值為 0，因此預設行為是載入並播放清單中的第一部影片。

    • 選用的 startSeconds 屬性接受浮點/整數，並指定在呼叫 playVideo() 函式時，清單中第一部影片應開始播放的時間。如果您指定 startSeconds 值並呼叫 seekTo()，則玩家會從 seekTo() 呼叫中指定的時間播放。如果選擇清單，然後呼叫 playVideoAt() 函式，播放器就會開始播放指定影片的開頭。

loadPlaylist

  • 引數語法

    player.loadPlaylist(playlist:String|Array,
                    index:Number,
                    startSeconds:Number):Void
    這個函式會載入並播放指定的播放清單。

    • 必要的 playlist 參數會指定 YouTube 影片 ID 的陣列。在 YouTube Data API 中，video 資源的 id 屬性會指定影片 ID。

    • 選用的 index 參數可指定播放清單中第一部影片的索引。該參數使用從 0 開始的索引，而預設參數值為 0，因此預設行為是載入並播放播放清單中的第一部影片。

    • 選用的 startSeconds 參數接受浮點值/整數，並指定播放清單中第一部影片的開始播放時間。

  • 物件語法

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
    這個函式會載入並播放指定清單。清單可以是播放清單或使用者上傳的影片動態消息。系統已淘汰搜尋結果清單的載入功能，自 2020 年 11 月 15 日起不再支援。

    • 選用的 listType 屬性會指定您要擷取的結果動態饋給類型。有效值為 playlist 和 user_uploads。自 2020 年 11 月 15 日起，系統將不再支援已淘汰的值 search。預設值為 playlist。

    • 必要的 list 屬性含有一個鍵，能指定 YouTube 應傳回的特定影片清單。

      • 如果 listType 屬性值為 playlist，則 list 屬性可指定播放清單 ID 或影片 ID 陣列。在 YouTube Data API 中，playlist 資源的 id 屬性會指定播放清單的 ID，video 資源的 id 屬性則會指定影片 ID。
      • 如果 listType 屬性值為 user_uploads，則 list 屬性會識別上傳影片的使用者。
      • 如果 listType 屬性值為 search，則 list 屬性會指定搜尋查詢。注意：這項功能已淘汰，自 2020 年 11 月 15 日起不再支援。

    • 選用的 index 屬性可指定清單中要播放的第一部影片的索引。該參數使用從 0 開始的索引，而預設值為 0，因此預設行為是載入並播放清單中的第一部影片。

    • 選用的 startSeconds 屬性接受浮點值/整數，並指定清單中第一部影片的開始播放時間。

播放控制項和播放器設定

播放影片

player.playVideo():Void
播放目前建議/載入的影片。執行此函式之後的最終播放器狀態會是 playing (1)。

注意：只有透過播放器中原生播放按鈕啟動的影片，才算是播放該影片的官方觀看次數。
player.pauseVideo():Void
暫停目前正在播放的影片。除非玩家在呼叫函式時處於 ended (0) 狀態，否則此函式執行後的最終玩家狀態將會是 paused (2)，在這種情況下，玩家狀態不會變更。
player.stopVideo():Void
停止並取消載入目前的影片。如果您知道使用者不會在播放器中觀看其他影片，就應該保留此函式。如果您要暫停影片，只要呼叫 pauseVideo 函式即可。如要變更播放器正在播放的影片，您可以先呼叫其中一個佇列函式，不必先呼叫 stopVideo。

重要事項：與會讓玩家處於 paused (2) 狀態的 pauseVideo 函式不同，stopVideo 函式可以將玩家設為任何非播放狀態的狀態，包括 ended (0)、paused (2)、video cued (5) 或 unstarted (-1)。
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
跳轉到影片中的指定時間。如果在呼叫函式時暫停播放器，播放器會維持暫停狀態。如果函式從其他狀態 (playing、video cued 等) 呼叫，播放器就會播放影片。

  • seconds 參數會指定玩家應前進的時間。

    除非播放器已經下載使用者要尋找的影片部分，否則播放器會在該時間點之前移至最接近的主要畫面格。

  • allowSeekAhead 參數會決定播放器是否會向伺服器發出新要求，但前提是 seconds 參數指定的時間不在目前緩衝處理的影片資料中。

    建議您在使用者沿著影片進度列拖曳滑鼠時，將這個參數設為 false，然後在使用者放開滑鼠時，將參數設為 true。這個方法可讓使用者捲動至影片的不同點，不必要求新的影片串流，只要捲動過去影片中未緩衝的時間點即可。使用者放開滑鼠按鈕後，播放器就會前往影片中的所需時間點，並在必要時請求新的影片串流。

控制 360 度影片的播放功能

注意：360 度影片播放體驗僅適用於行動裝置。在不支援的裝置上，360 度影片的畫面變形會變形，而且沒有任何支援方法可變更視角，包括透過 API、螢幕方向感應器，或是回應裝置螢幕上輕觸/拖曳的動作。

player.getSphericalProperties():Object
擷取用來描述觀眾目前視角或觀看影片的屬性。此外：
  • 這個物件只會填入 360 度影片 (又稱為球形影片)。
  • 如果目前的影片不是 360 度影片，或者函式是透過不支援的裝置呼叫，則函式會傳回空白物件。
  • 在支援的行動裝置上，如果 enableOrientationSensor 屬性設為 true，則這個函式會傳回 fov 屬性包含正確值且其他屬性設為 0 的物件。
物件包含下列屬性：
屬性
yaw 範圍 [0, 360] 以度為單位的數字，代表使用者將檢視畫面轉向向左或向右的程度。中立位置 (面向影片中心的等距長方投影) 表示 0°，當觀眾向左轉動時，這個值也會增加。
pitch 範圍 [-90, 90] 範圍中的數字，代表檢視畫面的垂直角度 (以度為單位)，反映使用者調整檢視畫面的程度。中立位置 (面向影片中心點，在等長方形投影中) 為 0°，表示觀眾抬頭時，這個值會增加。
roll 範圍 [-180, 180] 之間的數字，代表以順時針或逆時針旋轉的角度，以度為單位。中立位置的水平軸與檢視的水平軸平行，代表 0°。值會隨著檢視畫面順時針旋轉，並隨著檢視畫面逆時針旋轉而減少。

請注意，嵌入式播放器不會顯示可調整檢視畫面擲骰子的使用者介面。你可以透過下列任一種互斥方式調整擲骰子的結果：
  1. 使用行動瀏覽器中的方向感應器為檢視畫面提供擲骰子。如果啟用方向感應器，則 getSphericalProperties 函式一律會傳回 0 做為 roll 屬性的值。
  2. 如果方向感應器已停用，請使用這個 API 將旋轉作業設為非零的值。
fov 範圍 [30, 120] 以內的數字，代表沿著可視區域長邊測量的角度 (以度為單位)，短邊會自動調整為與檢視畫面的顯示比例成正比。

預設值為 100 度。降低這個值就像縮放影片內容一樣，增加值就像縮小內容一樣。您可以使用 API 或在影片處於全螢幕模式時，使用滑鼠滾輪調整這個值。
player.setSphericalProperties(properties:Object):Void
設定 360 度影片的播放方向。(如果目前的影片不是球型，則無論輸入內容為何，此方法都屬於免人工管理方法)。

播放器檢視畫面會更新以反映 properties 物件中任何已知屬性的值，藉此回應對此方法呼叫。檢視畫面會保留該物件未包含的任何其他已知屬性值。

此外：
  • 如果物件包含不明和/或非預期的屬性，播放器會忽略這些屬性。
  • 如本節開頭所述，部分行動裝置不支援 360 度影片播放體驗。
  • 根據預設，在支援的行動裝置上，這個函式只會設定 fov 屬性，不會影響播放 360 度影片播放的 yaw、pitch 和 roll 屬性。詳情請參閱下方的 enableOrientationSensor 屬性。
傳遞至函式的 properties 物件包含下列屬性：
屬性
yaw 請參閱上方的定義。
pitch 請參閱上方的定義。
roll 請參閱上方的定義。
fov 請參閱上方的定義。
enableOrientationSensor 注意：這個屬性只會影響支援的裝置上的 360 度觀看體驗。布林值，指出 IFrame 嵌入是否應回應表示支援裝置方向變更的事件，例如行動瀏覽器的 DeviceOrientationEvent。預設參數值為 true。

支援的行動裝置
  • 如果值為 true，嵌入播放器「只」只需根據裝置移動，即可調整播放 360 度影片的 yaw、pitch 和 roll 屬性。不過，你還是可以透過 API 變更 fov 屬性，而 API 實際上是在行動裝置上變更 fov 屬性的唯一方式。此為預設行為。
  • 如果值為 false，則裝置的動作不會影響 360° 觀看體驗，且 yaw、pitch、roll 和 fov 屬性都必須透過 API 設定。

不支援的行動裝置
enableOrientationSensor 屬性值不會影響播放體驗。

播放播放清單中的影片

player.nextVideo():Void
這個函式會載入並播放播放清單中的下一部影片。

  • 如果在播放播放清單中的最後一部影片時呼叫 player.nextVideo()，而且播放清單設為持續播放 (loop)，則播放器就會載入並播放清單中的第一部影片。

  • 如果在播放播放清單中的最後一部影片時呼叫 player.nextVideo()，而且播放清單並未設定連續播放，則播放將會結束。

player.previousVideo():Void
這個函式會載入並播放播放清單中的上一部影片。

  • 如果在正在觀看播放清單中的第一部影片時呼叫 player.previousVideo()，而且播放清單設為持續播放 (loop)，則播放器就會載入並播放清單中最後一部影片。

  • 如果在播放播放清單中的第一部影片時呼叫 player.previousVideo()，而且播放清單並未設為連續播放，播放器就會從頭開始播放第一部影片。

player.playVideoAt(index:Number):Void
這個函式會載入並播放播放清單中的指定影片。

  • 必要的 index 參數可指定要在播放清單中播放的影片索引。此參數使用從 0 開始的索引，因此 0 值表示清單中的第一部影片。如果選擇「隨機播放」播放清單，這個函式將會在隨機播放清單中的指定位置播放影片。

變更播放器音量

player.mute():Void
忽略播放器。
player.unMute():Void
取消靜音播放器。
player.isMuted():Boolean
如果玩家設為靜音，會傳回 true，否則傳回 false。
player.setVolume(volume:Number):Void
設定音量。系統接受 0 至 100 之間的整數。
player.getVolume():Number
傳回玩家目前的音量，這是介於 0 和 100 之間的整數。請注意，即使播放器設為靜音，getVolume() 仍會傳回音量。

設定播放器大小

player.setSize(width:Number, height:Number):Object
設定包含播放器的 <iframe> 大小 (以像素為單位)。

設定播放速率

player.getPlaybackRate():Number
這個函式會擷取目前播放影片的播放速率。預設的播放速率為 1，表示影片是以正常速度播放。播放率可能包含 0.25、0.5、1、1.5 和 2 等值。
player.setPlaybackRate(suggestedRate:Number):Void
這個函式會為目前影片設定建議的播放速率。如果播放率有所變化，只會影響已緩衝或播放中的影片。如果您為已提示影片設定播放率，則當呼叫 playVideo 函式或使用者直接透過播放器控制項開始播放播放時，該速率仍然有效。此外，呼叫函式來 提示或載入影片或播放清單 (cueVideoById、loadVideoById 等)，會將播放速率重設為 1。

呼叫此函式並不保證播放速率會實際變更。不過，如果播放率改變，onPlaybackRateChange 事件就會觸發，程式碼也應回應該事件，而不是只呼叫 setPlaybackRate 函式。

getAvailablePlaybackRates 方法會傳回目前播放的影片可能的播放速率。不過，如果將 suggestedRate 參數設為不支援的整數或浮點值，播放器會按照 1 方向，將該值四捨五入至最接近的支援值。
player.getAvailablePlaybackRates():Array
這個函式會傳回目前影片可用的播放速率組合。預設值為 1，表示影片以正常速度播放。

這個函式會傳回播放速度 (從最慢到最快) 的數字陣列。即使播放器不支援可變的播放速度，陣列仍應至少包含一個值 (1)。

設定播放清單的播放行為

player.setLoop(loopPlaylists:Boolean):Void

這個函式可以指出影片播放器是否應繼續播放播放清單，或是在播放清單的最後一部影片結束後停止播放。預設行為是播放清單不會循環播放。

即使載入或顯示其他播放清單，這項設定仍會保持不變；也就是說，如果載入播放清單、呼叫 setLoop 函式的值為 true，然後載入第二個播放清單，第二個播放清單也會循環播放。

必要的 loopPlaylists 參數可識別迴圈行為。

  • 如果參數值是 true，影片播放器會持續播放播放清單。播放播放清單中的最後一部影片後，影片播放器就會回到播放清單的開頭，再次播放。

  • 如果參數值是 false，系統就會在影片播放器播放播放清單中的最後一部影片後停止播放。

player.setShuffle(shufflePlaylist:Boolean):Void

這個函式可指出是否要隨機播放播放清單的影片，讓影片按照播放清單創作者指定的順序播放。如果選擇在播放清單開始播放後才隨機播放，則在影片繼續播放時，系統會重新排列這份清單。因此會根據重新排序的清單選取下一部播放的影片。

如果您載入或顯示其他播放清單，這項設定不會保留；也就是說，如果您載入播放清單、呼叫 setShuffle 函式，然後載入第二個播放清單，系統就不會隨機播放第二個播放清單。

必要的 shufflePlaylist 參數會指出 YouTube 是否應隨機播放播放清單。

  • 如果參數值為 true，YouTube 就會隨機調整播放清單順序。如果您指示函式隨機播放已經隨機播放的播放清單，YouTube 會再次隨機播放順序。

  • 如果參數值為 false，YouTube 會將播放清單順序改回原本的順序。

播放狀態

player.getVideoLoadedFraction():Float
傳回 0 和 1 之間的數字，指定播放器會在緩衝處理期間顯示的影片百分比。這個方法傳回的數字比現已淘汰的 getVideoBytesLoaded 和 getVideoBytesTotal 方法更可靠。
player.getPlayerState():Number
傳回播放器的狀態。可能的值包括：
  • -1 - 尚未開始
  • 0 – 已結束
  • 1 – 播放中
  • 2 - 已暫停
  • 3 – 緩衝處理中
  • 5 - 已剪輯的影片
player.getCurrentTime():Number
傳回影片開始播放以來的經過時間 (以秒為單位)。
player.getVideoStartBytes():Number
已自 2012 年 10 月 31 日起淘汰。傳回影片檔案開始載入的位元組數。(這個方法現在一律會傳回 0 值)。範例情境：使用者跳轉至尚未載入的點，且播放器發出新的要求，來播放尚未載入的影片片段。
player.getVideoBytesLoaded():Number
自 2012 年 7 月 18 日起淘汰。請改用 getVideoLoadedFraction 方法來判斷影片已緩衝處理的百分比。

這個方法會傳回 0 到 1000 之間的值，以估算載入的影片量，您可以將 getVideoBytesLoaded 值除以 getVideoBytesTotal 值，藉此計算已載入的影片比例。
player.getVideoBytesTotal():Number
自 2012 年 7 月 18 日起淘汰。請改用 getVideoLoadedFraction 方法來判斷影片已緩衝處理的百分比。

傳回目前載入/正在播放的影片大小 (以位元組為單位)，或是影片的概略大小。

這個方法一律會傳回 1000 的值。您可以將 getVideoBytesLoaded 值除以 getVideoBytesTotal 值，藉此計算已載入的影片比例。

擷取影片資訊

player.getDuration():Number
傳回目前播放中影片的持續時間 (以秒為單位)。請注意，getDuration() 會傳回 0，直到影片中繼資料載入為止，通常會在影片開始播放後發生。

如果目前正在播放的影片是現場直播，getDuration() 函式就會傳回即時影像串流開始後經過的時間。具體來說，這是影片串流中不會重設或中斷的時間長度。此外，這個時間長度通常比實際活動時間長，因為直播可能在活動開始時間之前開始。
player.getVideoUrl():String
傳回目前載入/播放影片的 YouTube.com 網址。
player.getVideoEmbedCode():String
傳回目前載入/播放影片的嵌入程式碼。

擷取播放清單資訊

player.getPlaylist():Array
這個函式會按照目前順序，傳回播放清單中影片 ID 的陣列。根據預設，這個函式會依照播放清單擁有者指定的順序傳回影片 ID。不過，如果您呼叫 setShuffle 函式來隨機決定播放清單順序，則 getPlaylist() 函式的傳回值會反映重組順序。
player.getPlaylistIndex():Number
這個函式會傳回目前正在播放的播放清單影片索引。

  • 如果還沒隨機播放播放清單，回傳值會指出播放清單創作者將影片放在哪個位置。傳回值使用從 0 開始的索引，所以 0 值表示播放清單中的第一部影片。

  • 若您選擇隨機播放播放清單，傳回的值即可識別在隨機播放清單中的影片順序。

新增或移除事件監聽器

player.addEventListener(event:String, listener:String):Void
為指定的 event 新增事件監聽器函式。下方的「事件」一節說明播放器可能觸發的不同事件。事件監聽器是一組字串，用來指定特定事件觸發時，系統將執行的函式。
player.removeEventListener(event:String, listener:String):Void
移除指定 event 的事件監聽器函式。listener 字串可識別指定事件觸發時將不再執行的函式。

存取及修改 DOM 節點

player.getIframe():Object
這個方法會傳回內嵌 <iframe> 的 DOM 節點。
player.destroy():Void
移除包含玩家的 <iframe>。

活動

API 會啟動事件，通知應用程式嵌入式播放器發生變更。如上一節所述，您可以在建構 YT.Player 物件時新增事件監聽器來訂閱事件，也可以使用 addEventListener 函式。

API 會將事件物件做為單一引數傳遞至每個函式。事件物件的屬性如下：

  • 事件的 target 會識別與事件對應的影片播放器。
  • 事件的 data 指定與事件相關的值。請注意，onReady 和 onAutoplayBlocked 事件不會指定 data 屬性。

以下清單定義 API 所觸發的事件：

onReady
每當玩家完成載入並準備好開始接收 API 呼叫時，就會觸發此事件。如果您想在播放器準備就緒後立即執行特定作業 (例如播放影片或顯示影片相關資訊)，您的應用程式應實作這個函式。

以下範例顯示用於處理這個事件的函式範例。API 傳遞至函式的事件物件具有用於識別玩家的 target 屬性。這個函式會擷取目前載入影片的嵌入程式碼，開始播放影片，並在 id 值為 embed-code 的網頁元素中顯示嵌入程式碼。 
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
每當玩家的狀態變更，就會觸發這個事件。API 傳遞至事件監聽器函式的事件物件的 data 屬性，會指定與新玩家狀態對應的整數。 可能的值包括：

  • -1 (未開始)
  • 0 (已結束)
  • 1 (播放中)
  • 2 (暫停)
  • 3 (緩衝處理)
  • 5 (影片已剪輯)。

播放器首次載入影片時，會播送 unstarted (-1) 事件。當影片已提示且可以播放時，播放器將會播送 video cued (5) 事件。在程式碼中，您可以指定整數值，或使用下列其中一個命名空間變數：

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

onPlaybackQualityChange
每當影片播放品質變更時，就會觸發這個事件。可能表示觀眾的播放環境發生變化。如要進一步瞭解會影響播放條件或可能導致事件觸發的因素，請參閱 YouTube 說明中心。

API 傳遞至事件監聽器函式的事件物件的 data 屬性值會是一個字串，用於識別新的播放品質。 可能的值包括：

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

onPlaybackRateChange
每當影片播放速率變更，就會觸發這個事件。舉例來說，如果您呼叫 setPlaybackRate(suggestedRate) 函式，當播放率實際變更時，就會觸發此事件。應用程式應回應事件，且不應假設在呼叫 setPlaybackRate(suggestedRate) 函式時，播放率會自動變更。同樣地，您的程式碼不應假設影片播放率只會因為明確呼叫 setPlaybackRate 而改變。

API 傳遞至事件監聽器函式的事件物件的 data 屬性值，是一組用於識別新播放速率的數字。 getAvailablePlaybackRates 方法會傳回目前提示或正在播放影片的有效播放率清單。
onError
如果播放器發生錯誤，就會觸發這個事件。API 會將 event 物件傳遞至事件監聽器函式。該物件的 data 屬性會指定一個整數，用來識別發生的錯誤類型。 可能的值包括：

  • 2：要求包含無效的參數值。舉例來說，如果指定的影片 ID 不超過 11 個字元，或是影片 ID 含有無效字元 (例如驚嘆號或星號)，就會發生這類錯誤。
  • 5：無法在 HTML5 播放器中播放要求的內容，或是發生其他與 HTML5 播放器相關的錯誤。
  • 100 - 找不到要求的影片。當影片因故遭移除或標示為私人影片時，就會發生這個錯誤。
  • 101：要求影片的擁有者不允許影片在嵌入式播放器中播放。
  • 150 - 這個錯誤與 101 相同。這只是一個 101 錯誤。
onApiChange
系統會觸發此事件，表示玩家已載入 (或卸載) 含有公開 API 方法的模組。您的應用程式可以監聽此事件，然後輪詢播放器來判斷最近載入的模組要顯示哪些選項。接著，應用程式即可擷取或更新這些選項的現有設定。

下列指令會擷取模組名稱陣列，方便您設定玩家選項：
player.getOptions();
目前，唯一可設定選項的模組是 captions 模組，這個模組會處理播放器中的隱藏式輔助字幕。收到 onApiChange 事件後，應用程式可以使用下列指令，判斷 captions 模組可以設定的選項：
player.getOptions('captions');
透過這個指令輪詢玩家，您可以確認想存取的選項確實可供存取。下列指令會擷取及更新模組選項：
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
下表列出 API 支援的選項：

Module 選項 說明
captions fontSize 這個選項會調整播放器中顯示的字幕字型大小。

有效值為 -1、0、1、2 和 3。預設大小為 0，最小大小為 -1。如果將這個選項設為低於 -1 的整數，系統就會顯示最小的字幕大小，而將這個選項設為 3 以上的整數時，系統會顯示最大的字幕大小。
captions 重新載入 這個選項會重新載入正在播放的影片的隱藏式輔助字幕資料。如果您擷取選項的值，這個值會是 null。將值設為 true，即可重新載入隱藏式輔助字幕資料。
onAutoplayBlocked
當瀏覽器封鎖自動播放或已有指令碼的影片播放功能時，就會觸發這個事件 (統稱為「自動播放」)。這包括嘗試透過下列任一播放器 API 播放的情形：

大部分瀏覽器都有政策禁止在電腦、行動裝置和其他環境 (如果符合特定條件) 封鎖自動播放功能。可能觸發這項政策的執行個體，包括在沒有使用者互動的情況下取消靜音播放，或未設定權限政策的允許在跨來源 iframe 上自動播放。

如需完整詳細資料，請參閱瀏覽器專屬政策 (Apple Safari / Webkit、Google Chrome、Mozilla Firefox) 和 Mozilla 的自動播放指南。

示例

正在建立 YT.Player 個物件

  • 示例 1：將 API 與現有 <iframe> 搭配使用

    在這個範例中，網頁上的 <iframe> 元素已定義要用於 API 的播放器。請注意，玩家的 src 網址必須將 enablejsapi 參數設為 1，或者 <iframe> 元素的 enablejsapi 屬性必須設為 true。

    播放器準備就緒時，onPlayerReady 函式會將播放器周圍的邊框顏色變更為橘色。onPlayerStateChange 函式會根據目前的玩家狀態變更玩家周圍的邊框顏色。舉例來說，播放器會在播放時顯示綠色、暫停時呈現紅色，緩衝處理時則為藍色等。

    本範例使用下列程式碼：

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

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

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

  • 示例 2：播放音量過大

    本範例會建立 1280 x 720 像素的影片播放器。onReady 事件的事件監聽器會呼叫 setVolume 函式，將音量調整為最高設定。

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

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

  • 範例 3： 這個範例將設定播放器參數設為在載入影片時自動播放影片，並隱藏影片播放器的控制項。也會為 API 廣播的多個事件新增事件監聽器。

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

控制 360 度影片

本範例使用下列程式碼：

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

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

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

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

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

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

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

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

Android WebView Media Integrity API 整合

YouTube 已擴充 Android WebView Media Integrity API，以便啟用嵌入式媒體播放器 (包括 Android 應用程式中的 YouTube 播放器嵌入功能)，以便驗證嵌入應用程式的真實性。在這項變更之後，嵌入應用程式會自動將已驗證的應用程式 ID 傳送至 YouTube。透過這個 API 使用收集到的資料，是應用程式中繼資料 (套件名稱、版本號碼和簽署憑證) 以及 Google Play 服務產生的裝置認證權杖。

這項資料會用於驗證應用程式和裝置完整性。加密資料不會與第三方共用，而且會在固定的保留期限後刪除。應用程式開發人員可以在 WebView Media Integrity API 中設定應用程式身分。這項設定支援選擇不採用選項。

修訂版本記錄

June 24, 2024

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

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

  • The Requirements section has been updated to note that embedded players must have a viewport that is at least 200px by 200px. If a player displays controls, it must be large enough to fully display the controls without shrinking the viewport below the minimum size. We recommend 16:9 players be at least 480 pixels wide and 270 pixels tall.

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

  • The Queueing functions section has been updated to explain that you can use either argument syntax or object syntax to call all of those functions. Note that the API may support additional functionality in object syntax that the argument syntax does not support.

    In addition, the descriptions and examples for each of the video queueing functions have been updated to reflect the newly added support for object syntax. (The API's playlist queueing functions already supported object syntax.)

  • When called using object syntax, each of the video queueing functions supports an endSeconds property, which accepts a float/integer and specifies the time when the video should stop playing when playVideo() is called.

  • The getVideoStartBytes method has been deprecated. The method now always returns a value of 0.

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

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

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

    • Functions

      • getAvailablePlaybackRates – Retrieve the supported playback rates for the cued or playing video. Note that variable playback rates are currently only supported in the HTML5 player.
      • getPlaybackRate – Retrieve the playback rate for the cued or playing video.
      • setPlaybackRate – Set the playback rate for the cued or playing video.

    • Events

July 19, 2012

This update contains the following changes:

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

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

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

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

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

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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