YouTube Player API Reference for iframe Embeds

API trình phát IFrame cho phép bạn nhúng trình phát video trên YouTube vào trang web của mình và điều khiển trình phát bằng JavaScript.

Khi sử dụng các chức năng JavaScript của API, bạn có thể đưa video vào hàng đợi để phát lại, phát, tạm dừng hoặc dừng các video đó; điều chỉnh âm lượng của trình phát hoặc truy xuất thông tin về video đã phát. Bạn cũng có thể thêm trình nghe sự kiện sẽ thực thi để phản hồi một số sự kiện nhất định của người chơi, chẳng hạn như thay đổi trạng thái của người chơi.

Hướng dẫn này giải thích cách sử dụng API IFrame. Hướng dẫn này xác định các loại sự kiện mà API có thể gửi và giải thích cách viết trình nghe sự kiện để phản hồi những sự kiện đó. Hướng dẫn này cũng nêu chi tiết các hàm JavaScript khác nhau mà bạn có thể gọi để điều khiển trình phát video cũng như các thông số trình phát mà bạn có thể sử dụng để tùy chỉnh thêm trình phát.

Yêu cầu

Trình duyệt của người dùng phải hỗ trợ tính năng HTML5 postMessage. Hầu hết các trình duyệt hiện đại đều hỗ trợ postMessage.

Trình phát được nhúng phải có khung nhìn tối thiểu là 200px x 200px. Nếu trình phát hiển thị các nút điều khiển thì màn hình đó phải đủ lớn để hiển thị đầy đủ các nút điều khiển mà không cần thu nhỏ khung nhìn xuống dưới kích thước tối thiểu. Trình phát 16:9 nên có chiều rộng tối thiểu là 480 pixel và chiều cao tối thiểu là 270 pixel.

Bất kỳ trang web nào sử dụng API IFrame cũng phải triển khai hàm JavaScript sau:

  • onYouTubeIframeAPIReady – API sẽ gọi hàm này khi trang đã tải xong JavaScript xuống cho API trình phát, cho phép bạn sau đó sử dụng API trên trang của mình. Do đó, hàm này có thể tạo các đối tượng trình phát mà bạn muốn hiển thị khi trang tải.

Bắt đầu

Trang HTML mẫu dưới đây tạo một trình phát được nhúng sẽ tải video, phát video trong 6 giây rồi dừng phát. Các nhận xét được đánh số trong HTML được giải thích trong danh sách bên dưới ví dụ.

<!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>

Danh sách sau đây cung cấp thêm thông tin chi tiết về mẫu ở trên:

  1. Thẻ <div> trong phần này xác định vị trí trên trang nơi API IFrame sẽ đặt trình phát video. Hàm khởi tạo cho đối tượng trình phát, được mô tả trong phần Tải trình phát video, xác định thẻ <div> bằng id để đảm bảo rằng API đặt <iframe> ở vị trí thích hợp. Cụ thể, API IFrame sẽ thay thế thẻ <div> bằng thẻ <iframe>.

    Ngoài ra, bạn cũng có thể đặt phần tử <iframe> ngay trên trang. Phần Tải trình phát video giải thích cách thực hiện việc này.

  2. Mã trong phần này tải mã JavaScript của API Trình phát IFrame. Ví dụ này sử dụng tính năng sửa đổi DOM để tải mã API xuống nhằm đảm bảo mã được truy xuất không đồng bộ. (Thuộc tính async của thẻ <script>, cũng cho phép tải xuống không đồng bộ, chưa được hỗ trợ trong tất cả các trình duyệt hiện đại như được thảo luận trong câu trả lời về Stack Overflow này.

  3. Hàm onYouTubeIframeAPIReady sẽ thực thi ngay khi tải mã API trình phát xuống. Phần mã này xác định một biến toàn cục player, biến này đề cập đến trình phát video mà bạn đang nhúng, sau đó hàm này sẽ tạo đối tượng trình phát video.

  4. Hàm onPlayerReady sẽ thực thi khi sự kiện onReady kích hoạt. Trong ví dụ này, hàm cho biết rằng khi trình phát video đã sẵn sàng, video sẽ bắt đầu phát.

  5. API sẽ gọi hàm onPlayerStateChange khi trạng thái của người chơi thay đổi. Hàm này có thể cho biết người chơi đang chơi, tạm dừng, đã kết thúc, v.v. Hàm này cho biết khi trạng thái của trình phát là 1 (đang phát), trình phát sẽ phát trong 6 giây rồi gọi hàm stopVideo để dừng video.

Tải trình phát video

Sau khi mã JavaScript của API tải, API sẽ gọi hàm onYouTubeIframeAPIReady, tại thời điểm đó bạn có thể tạo đối tượng YT.Player để chèn trình phát video trên trang của mình. Đoạn trích HTML dưới đây hiển thị hàm onYouTubeIframeAPIReady từ ví dụ trên:

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

Hàm tạo cho trình phát video chỉ định các thông số sau:

  1. Tham số đầu tiên chỉ định phần tử DOM hoặc id của phần tử HTML, trong đó API sẽ chèn thẻ <iframe> chứa trình phát.

    API IFrame sẽ thay thế phần tử được chỉ định bằng phần tử <iframe> chứa trình phát. Điều này có thể ảnh hưởng đến bố cục của trang nếu phần tử được thay thế có kiểu hiển thị khác với phần tử <iframe> được chèn. Theo mặc định, <iframe> hiển thị dưới dạng phần tử inline-block.

  2. Tham số thứ hai là một đối tượng chỉ định các tùy chọn trình phát. Đối tượng này chứa các thuộc tính sau:
    • width (số) – Chiều rộng của trình phát video. Giá trị mặc định là 640.
    • height (số) – Chiều cao của trình phát video. Giá trị mặc định là 390.
    • videoId (chuỗi) – Mã nhận dạng video trên YouTube giúp xác định video mà trình phát sẽ tải.
    • playerVars (đối tượng) – Các thuộc tính của đối tượng xác định tham số trình phát có thể dùng để tuỳ chỉnh trình phát.
    • events (đối tượng) – Các thuộc tính của đối tượng xác định các sự kiện mà API kích hoạt và các hàm (trình nghe sự kiện) mà API sẽ gọi khi các sự kiện đó xảy ra. Trong ví dụ này, hàm khởi tạo cho biết hàm onPlayerReady sẽ thực thi khi sự kiện onReady kích hoạt và hàm onPlayerStateChange sẽ thực thi khi sự kiện onStateChange kích hoạt.

Như đã đề cập trong phần Bắt đầu, thay vì viết một phần tử <div> trống trên trang mà sau đó mã JavaScript của API trình phát sẽ thay thế bằng phần tử <iframe>, bạn có thể tự tạo thẻ <iframe>. Ví dụ đầu tiên trong phần Ví dụ cho thấy cách thực hiện việc này.

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

Xin lưu ý rằng nếu ghi thẻ <iframe>, thì khi tạo đối tượng YT.Player, bạn không cần chỉ định giá trị cho widthheight, được chỉ định làm thuộc tính của thẻ <iframe>, hoặc videoId và tham số trình phát được chỉ định trong URL src. Để tăng cường bảo mật, bạn cũng nên thêm tham số origin vào URL, chỉ định lược đồ URL (http:// hoặc https://) và toàn bộ miền của trang lưu trữ làm giá trị tham số. Mặc dù origin là không bắt buộc, nhưng mã này giúp bảo vệ chống lại JavaScript độc hại của bên thứ ba được chèn vào trang của bạn và chiếm quyền kiểm soát trình phát YouTube của bạn.

Phần Ví dụ cũng trình bày một số ví dụ khác về cách tạo đối tượng trình phát video.

Hoạt động tính toán

Để gọi các phương thức API trình phát, trước tiên, bạn phải lấy thông tin tham chiếu đến đối tượng trình phát mà bạn muốn điều khiển. Bạn lấy tệp đối chiếu bằng cách tạo đối tượng YT.Player như đã thảo luận trong các phần Bắt đầuTải trình phát video của tài liệu này.

Hàm

Các hàm xếp hàng

Chức năng xếp hàng đợi cho phép bạn tải và phát một video, danh sách phát hoặc một danh sách video khác. Nếu đang sử dụng cú pháp đối tượng được mô tả dưới đây để gọi các hàm này thì bạn cũng có thể đưa vào hàng đợi hoặc tải danh sách video đã tải lên của người dùng.

API hỗ trợ 2 cú pháp để gọi các hàm xếp hàng.

  • Cú pháp đối số yêu cầu liệt kê các đối số của hàm theo thứ tự quy định.

  • Cú pháp đối tượng cho phép bạn truyền một đối tượng dưới dạng tham số và xác định các thuộc tính đối tượng cho các đối số của hàm mà bạn muốn đặt. Ngoài ra, API có thể hỗ trợ thêm chức năng mà cú pháp đối số không hỗ trợ.

Ví dụ: phương thức gọi hàm loadVideoById có thể là một trong những cách sau. Lưu ý rằng cú pháp đối tượng hỗ trợ thuộc tính endSeconds mà cú pháp đối số không hỗ trợ.

  • Cú pháp đối số

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • Cú pháp đối tượng

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

Các chức năng xếp video vào hàng đợi

cueVideoById
  • Cú pháp đối số

    player.cueVideoById(videoId:String,
                        startSeconds:Number):Void
  • Cú pháp đối tượng

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

Hàm này tải hình thu nhỏ của video được chỉ định và chuẩn bị trình phát phát video. Trình phát không yêu cầu FLV cho đến khi playVideo() hoặc seekTo() được gọi.

  • Tham số videoId bắt buộc chỉ định mã video trên YouTube của video sẽ phát. Trong YouTube Data API, thuộc tính id của tài nguyên video sẽ chỉ định mã nhận dạng.
  • Tham số startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video khi playVideo() được gọi. Nếu bạn chỉ định một giá trị startSeconds rồi gọi seekTo(), thì trình phát sẽ chơi từ thời điểm được chỉ định trong lệnh gọi seekTo(). Khi video đã được dừng và sẵn sàng phát, trình phát sẽ phát sóng một sự kiện video cued (5).
  • Tham số endSeconds không bắt buộc (chỉ được hỗ trợ trong cú pháp đối tượng) chấp nhận số thực/số nguyên và chỉ định thời gian video sẽ ngừng phát khi playVideo() được gọi. Nếu bạn chỉ định một giá trị endSeconds rồi gọi seekTo(), thì giá trị endSeconds sẽ không còn hiệu lực.

loadVideoById

  • Cú pháp đối số

    player.loadVideoById(videoId:String,
                         startSeconds:Number):Void
  • Cú pháp đối tượng

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

Hàm này tải và phát video được chỉ định.

  • Tham số videoId bắt buộc chỉ định mã video trên YouTube của video sẽ phát. Trong YouTube Data API, thuộc tính id của tài nguyên video sẽ chỉ định mã nhận dạng.
  • Tham số startSeconds không bắt buộc chấp nhận số thực/số nguyên. Nếu được chỉ định thì video sẽ bắt đầu từ khung hình chính gần nhất với thời gian được chỉ định.
  • Tham số endSeconds không bắt buộc chấp nhận số thực/số nguyên. Nếu bạn chỉ định chế độ này thì video sẽ ngừng phát tại thời điểm đã chỉ định.

cueVideoByUrl

  • Cú pháp đối số

    player.cueVideoByUrl(mediaContentUrl:String,
                         startSeconds:Number):Void
  • Cú pháp đối tượng

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

Hàm này tải hình thu nhỏ của video được chỉ định và chuẩn bị trình phát phát video. Trình phát không yêu cầu FLV cho đến khi playVideo() hoặc seekTo() được gọi.

  • Tham số mediaContentUrl bắt buộc chỉ định một URL trình phát YouTube đủ điều kiện ở định dạng http://www.youtube.com/v/VIDEO_ID?version=3.
  • Tham số startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video khi playVideo() được gọi. Nếu bạn chỉ định startSeconds rồi gọi seekTo(), thì trình phát sẽ chơi từ thời điểm được chỉ định trong lệnh gọi seekTo(). Khi video đã được dừng và sẵn sàng phát, trình phát sẽ phát đi một sự kiện video cued (5).
  • Tham số endSeconds không bắt buộc (chỉ được hỗ trợ trong cú pháp đối tượng) chấp nhận số thực/số nguyên và chỉ định thời gian video sẽ ngừng phát khi playVideo() được gọi. Nếu bạn chỉ định một giá trị endSeconds rồi gọi seekTo(), thì giá trị endSeconds sẽ không còn hiệu lực.

loadVideoByUrl

  • Cú pháp đối số

    player.loadVideoByUrl(mediaContentUrl:String,
                          startSeconds:Number):Void
  • Cú pháp đối tượng

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

Hàm này tải và phát video được chỉ định.

  • Tham số mediaContentUrl bắt buộc chỉ định một URL trình phát YouTube đủ điều kiện ở định dạng http://www.youtube.com/v/VIDEO_ID?version=3.
  • Tham số startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video. Nếu bạn chỉ định startSeconds (số có thể là số thực) thì video sẽ bắt đầu từ khung hình chính gần nhất với thời gian đã chỉ định.
  • Tham số endSeconds không bắt buộc (chỉ được hỗ trợ trong cú pháp đối tượng) chấp nhận số thực/số nguyên và chỉ định thời gian ngừng phát video.

Hàm xếp hàng cho danh sách

Hàm cuePlaylistloadPlaylist cho phép bạn tải và phát danh sách phát. Nếu đang sử dụng cú pháp đối tượng để gọi các hàm này, bạn cũng có thể đưa vào hàng đợi (hoặc tải) danh sách các video đã tải lên của người dùng.

Vì các hàm hoạt động theo cách khác nhau tuỳ thuộc vào việc các hàm này được gọi bằng cú pháp đối số hay cú pháp đối tượng, nên cả hai phương thức gọi đều được ghi lại dưới đây.

cuePlaylist
  • Cú pháp đối số

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number):Void
    Thêm danh sách phát được chỉ định vào hàng đợi. Khi danh sách phát được dừng và sẵn sàng phát, trình phát sẽ phát một sự kiện video cued (5).
    • Tham số playlist bắt buộc chỉ định một mảng mã video trên YouTube. Trong YouTube Data API, thuộc tính id của tài nguyên video sẽ xác định mã nhận dạng của video đó.

    • Tham số index không bắt buộc chỉ định chỉ mục của video đầu tiên trong danh sách phát sẽ phát. Tham số này sử dụng chỉ mục dựa trên 0 và giá trị tham số mặc định là 0, vì vậy, hành vi mặc định là tải và phát video đầu tiên trong danh sách phát.

    • Tham số startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video đầu tiên trong danh sách phát khi hàm playVideo() được gọi. Nếu bạn chỉ định một giá trị startSeconds rồi gọi seekTo(), thì trình phát sẽ chơi từ thời điểm được chỉ định trong lệnh gọi seekTo(). Nếu bạn đưa ra một danh sách phát rồi gọi hàm playVideoAt(), trình phát sẽ bắt đầu phát ở đầu video được chỉ định.

  • Cú pháp đối tượng

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number}):Void
    Xếp danh sách các video được chỉ định vào hàng đợi. Danh sách này có thể là danh sách phát hoặc nguồn cấp dữ liệu video đã tải lên của người dùng. Tính năng thêm danh sách kết quả tìm kiếm vào danh sách chờ không dùng nữa và sẽ không được hỗ trợ nữa kể từ ngày 15 tháng 11 năm 2020.

    Khi danh sách được tổng hợp và sẵn sàng phát, trình phát sẽ phát đi một sự kiện video cued (5).

    • Thuộc tính listType không bắt buộc chỉ định loại nguồn cấp dữ liệu kết quả mà bạn đang truy xuất. Các giá trị hợp lệ là playlistuser_uploads. Kể từ ngày 15 tháng 11 năm 2020, một giá trị search đã ngừng hoạt động sẽ không được hỗ trợ nữa. Giá trị mặc định là playlist.

    • Thuộc tính list bắt buộc chứa khoá xác định danh sách cụ thể các video mà YouTube sẽ trả về.

      • Nếu giá trị thuộc tính listTypeplaylist thì thuộc tính list chỉ định mã nhận dạng danh sách phát hoặc một mảng mã video. Trong YouTube Data API, thuộc tính id của tài nguyên playlist chỉ định một mã nhận dạng của danh sách phát, còn thuộc tính id của tài nguyên video chỉ định một mã video.
      • Nếu giá trị thuộc tính listTypeuser_uploads thì thuộc tính list xác định người dùng có video đã tải lên sẽ được trả về.
      • Nếu giá trị thuộc tính listTypesearch, thì thuộc tính list sẽ chỉ định cụm từ tìm kiếm. Lưu ý: Chức năng này không dùng nữa và không được hỗ trợ nữa kể từ ngày 15 tháng 11 năm 2020.

    • Thuộc tính index không bắt buộc chỉ định chỉ mục của video đầu tiên trong danh sách sẽ phát. Tham số này sử dụng chỉ mục dựa trên 0 và giá trị tham số mặc định là 0, vì vậy, hành vi mặc định là tải và phát video đầu tiên trong danh sách.

    • Thuộc tính startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video đầu tiên trong danh sách khi hàm playVideo() được gọi. Nếu bạn chỉ định một giá trị startSeconds rồi gọi seekTo(), thì trình phát sẽ chơi từ thời điểm được chỉ định trong lệnh gọi seekTo(). Nếu bạn đưa ra một danh sách rồi gọi hàm playVideoAt(), trình phát sẽ bắt đầu phát tại đầu video đã chỉ định.

loadPlaylist
  • Cú pháp đối số

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number):Void
    Hàm này tải danh sách phát đã chỉ định và phát danh sách phát đó.
    • Tham số playlist bắt buộc chỉ định một mảng mã video trên YouTube. Trong YouTube Data API, thuộc tính id của tài nguyên video chỉ định một mã video.

    • Tham số index không bắt buộc chỉ định chỉ mục của video đầu tiên trong danh sách phát sẽ phát. Tham số này sử dụng chỉ mục dựa trên 0 và giá trị tham số mặc định là 0, vì vậy, hành vi mặc định là tải và phát video đầu tiên trong danh sách phát.

    • Tham số startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video đầu tiên trong danh sách phát.

  • Cú pháp đối tượng

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number}):Void
    Hàm này tải danh sách đã chỉ định và phát danh sách. Danh sách này có thể là danh sách phát hoặc nguồn cấp dữ liệu video đã tải lên của người dùng. Tính năng tải danh sách kết quả tìm kiếm không dùng nữa và sẽ không được hỗ trợ nữa kể từ ngày 15 tháng 11 năm 2020.
    • Thuộc tính listType không bắt buộc chỉ định loại nguồn cấp dữ liệu kết quả mà bạn đang truy xuất. Các giá trị hợp lệ là playlistuser_uploads. Kể từ ngày 15 tháng 11 năm 2020, một giá trị search đã ngừng hoạt động sẽ không được hỗ trợ nữa. Giá trị mặc định là playlist.

    • Thuộc tính list bắt buộc chứa khoá xác định danh sách cụ thể các video mà YouTube sẽ trả về.

      • Nếu giá trị thuộc tính listTypeplaylist, thì thuộc tính list chỉ định một mã nhận dạng danh sách phát hoặc một mảng mã video. Trong YouTube Data API, thuộc tính id của tài nguyên playlist chỉ định một mã nhận dạng của danh sách phát và thuộc tính id của tài nguyên video chỉ định một mã video.
      • Nếu giá trị thuộc tính listTypeuser_uploads thì thuộc tính list xác định người dùng có video đã tải lên sẽ được trả về.
      • Nếu giá trị thuộc tính listTypesearch, thì thuộc tính list sẽ chỉ định cụm từ tìm kiếm. Lưu ý: Chức năng này không dùng nữa và không được hỗ trợ nữa kể từ ngày 15 tháng 11 năm 2020.

    • Thuộc tính index không bắt buộc chỉ định chỉ mục của video đầu tiên trong danh sách sẽ phát. Tham số này sử dụng chỉ mục dựa trên 0 và giá trị tham số mặc định là 0, vì vậy, hành vi mặc định là tải và phát video đầu tiên trong danh sách.

    • Thuộc tính startSeconds không bắt buộc chấp nhận số thực/số nguyên và chỉ định thời gian bắt đầu phát video đầu tiên trong danh sách.

Các nút điều khiển chế độ phát và các chế độ cài đặt của trình phát

Phát video

player.playVideo():Void
Phát video hiện được dừng/tải lên. Trạng thái của trình phát cuối cùng sau khi hàm này thực thi sẽ là playing (1).

Lưu ý: Một lượt phát lại chỉ được tính vào số lượt xem chính thức của video nếu video đó bắt đầu thông qua nút phát gốc trong trình phát.
player.pauseVideo():Void
Tạm dừng video hiện đang phát. Trạng thái cuối cùng của người chơi sau khi hàm này thực thi sẽ là paused (2), trừ phi người chơi đang ở trạng thái ended (0) khi hàm được gọi. Trong trường hợp này, trạng thái của người chơi sẽ không thay đổi.
player.stopVideo():Void
Dừng và huỷ quá trình tải video hiện tại. Chức năng này nên dành riêng cho những trường hợp hiếm gặp khi bạn biết rằng người dùng sẽ không xem thêm video trong trình phát. Nếu ý định của bạn là tạm dừng video, bạn chỉ cần gọi hàm pauseVideo. Nếu muốn thay đổi video mà trình phát đang phát, bạn có thể gọi một trong các chức năng xếp hàng mà không cần gọi stopVideo trước.

Lưu ý quan trọng: Không giống như hàm pauseVideo, để trình phát ở trạng thái paused (2), hàm stopVideo có thể đưa người chơi vào bất kỳ trạng thái nào không phát, bao gồm ended (0), paused (2), video cued (5) hoặc unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Tìm kiếm đến một thời điểm cụ thể trong video. Nếu trình phát bị tạm dừng khi hàm được gọi, thì trình phát sẽ vẫn tạm dừng. Nếu hàm được gọi từ một trạng thái khác (playing, video cued, v.v.), trình phát sẽ phát video.
  • Tham số seconds xác định thời gian mà người chơi sẽ chuyển đến.

    Trình phát sẽ chuyển đến khung hình chính gần nhất trước thời điểm đó, trừ phi trình phát đã tải xuống phần video mà người dùng đang tìm kiếm.

  • Tham số allowSeekAhead xác định liệu trình phát có gửi một yêu cầu mới đến máy chủ hay không nếu tham số seconds chỉ định thời gian ngoài dữ liệu video hiện được lưu vào bộ đệm.

    Bạn nên đặt tham số này thành false trong khi người dùng kéo chuột dọc theo thanh tiến trình video, sau đó đặt thành true khi người dùng thả chuột. Phương pháp này cho phép người dùng cuộn đến các điểm khác nhau của video mà không cần yêu cầu luồng video mới bằng cách cuộn qua các điểm không có bộ đệm trong video. Khi người dùng thả nút chuột, trình phát sẽ chuyển đến điểm mong muốn trong video và yêu cầu một luồng video mới nếu cần.

Kiểm soát tính năng phát video 360°

Lưu ý: Trải nghiệm phát video 360° chỉ được hỗ trợ hạn chế trên thiết bị di động. Trên các thiết bị không được hỗ trợ, video 360° bị méo hình và không có cách nào được hỗ trợ để thay đổi góc nhìn, kể cả thông qua API, sử dụng cảm biến hướng hoặc phản hồi với thao tác chạm/kéo trên màn hình của thiết bị.

player.getSphericalProperties():Object
Truy xuất các thuộc tính mô tả góc nhìn hiện tại của người xem hoặc chế độ xem để phát video. Ngoài ra:
  • Đối tượng này chỉ được điền sẵn cho video 360°, còn được gọi là video hình cầu.
  • Nếu video hiện tại không phải là video 360° hoặc nếu hàm được gọi từ một thiết bị không được hỗ trợ, thì hàm sẽ trả về một đối tượng trống.
  • Trên thiết bị di động được hỗ trợ, nếu thuộc tính enableOrientationSensor được đặt thành true, thì hàm này sẽ trả về một đối tượng trong đó thuộc tính fov chứa giá trị chính xác và các thuộc tính khác được đặt thành 0.
Đối tượng này chứa các thuộc tính sau:
Thuộc tính
yaw Số trong phạm vi [0, 360) đại diện cho góc ngang của chế độ xem theo độ, phản ánh phạm vi mà người dùng quay chế độ xem sang trái hoặc sang phải hơn nữa. Vị trí trung tính, đối diện với tâm video trong hình chiếu hình cầu toàn cảnh, biểu thị 0° và giá trị này tăng lên khi người xem quay sang trái.
pitch Số trong phạm vi [-90, 90] đại diện cho góc dọc của chế độ xem theo độ, phản ánh phạm vi mà người dùng điều chỉnh chế độ xem để nhìn lên hoặc xuống. Vị trí trung tính, đối diện với tâm video trong hình chiếu hình cầu toàn cảnh, biểu thị 0° và giá trị này tăng lên khi người xem nhìn lên.
roll Số trong phạm vi [-180, 180] biểu thị góc xoay theo chiều kim đồng hồ hoặc ngược chiều kim đồng hồ của chế độ xem tính theo độ. Vị trí trung tính, với trục ngang trong hình chiếu hình cầu toàn cảnh song song với trục hoành của chế độ xem, biểu thị 0°. Giá trị này tăng khi chế độ xem xoay theo chiều kim đồng hồ và giảm khi chế độ xem xoay ngược chiều kim đồng hồ.

Xin lưu ý rằng trình phát được nhúng không có giao diện người dùng để điều chỉnh thao tác cuộn của chế độ xem. Bạn có thể điều chỉnh cách đổ xúc xắc theo một trong những cách loại trừ lẫn nhau sau đây:
  1. Sử dụng cảm biến hướng trong trình duyệt cho thiết bị di động để cuộn cho chế độ xem. Nếu bật cảm biến hướng, thì hàm getSphericalProperties luôn trả về 0 là giá trị của thuộc tính roll.
  2. Nếu cảm biến hướng bị tắt, hãy đặt giá trị cuộn thành giá trị khác 0 bằng cách sử dụng API này.
fov Một số trong phạm vi [30, 120] đại diện cho trường nhìn của chế độ xem theo độ khi được đo dọc theo cạnh dài hơn của khung nhìn. Cạnh ngắn hơn sẽ tự động được điều chỉnh cho tỷ lệ với tỷ lệ khung hình của khung nhìn.

Giá trị mặc định là 100 độ. Việc giảm giá trị giống như phóng to nội dung video và tăng giá trị giống như thu nhỏ. Bạn có thể điều chỉnh giá trị này bằng API hoặc con lăn chuột khi video ở chế độ toàn màn hình.
player.setSphericalProperties(properties:Object):Void
Đặt hướng video để phát video 360°. (Nếu video hiện tại không phải là hình cầu, thì phương thức này sẽ không hoạt động bất kể đầu vào là gì.)

Chế độ xem trình phát phản hồi các lệnh gọi phương thức này bằng cách cập nhật để phản ánh giá trị của mọi thuộc tính đã biết trong đối tượng properties. Khung hiển thị này giữ nguyên các giá trị cho những thuộc tính đã biết khác không có trong đối tượng đó.

Ngoài ra:
  • Nếu đối tượng chứa các thuộc tính không xác định và/hoặc không mong muốn, trình chơi sẽ bỏ qua các thuộc tính đó.
  • Như đã lưu ý ở đầu phần này, trải nghiệm phát video 360° không được hỗ trợ trên tất cả các thiết bị di động.
  • Theo mặc định, trên thiết bị di động được hỗ trợ, hàm này chỉ đặt thuộc tính fov và không ảnh hưởng đến các thuộc tính yaw, pitchroll đối với phát lại video 360°. Hãy xem thuộc tính enableOrientationSensor ở bên dưới để biết thêm thông tin.
Đối tượng properties được truyền đến hàm chứa các thuộc tính sau:
Thuộc tính
yaw Xem định nghĩa ở trên.
pitch Xem định nghĩa ở trên.
roll Xem định nghĩa ở trên.
fov Xem định nghĩa ở trên.
enableOrientationSensor Lưu ý: Thuộc tính này chỉ ảnh hưởng đến trải nghiệm xem 360° trên các thiết bị được hỗ trợ.Giá trị boolean cho biết liệu thành phần nhúng IFrame có phản hồi các sự kiện báo hiệu sự thay đổi về hướng của thiết bị được hỗ trợ hay không, chẳng hạn như DeviceOrientationEvent của trình duyệt dành cho thiết bị di động. Giá trị tham số mặc định là true.

Thiết bị di động được hỗ trợ
  • Khi giá trị là true, trình phát được nhúng chỉ dựa vào chuyển động của thiết bị để điều chỉnh các thuộc tính yaw, pitchroll cho lượt phát video 360°. Tuy nhiên, bạn vẫn có thể thay đổi thuộc tính fov thông qua API và trên thực tế, API là cách duy nhất để thay đổi thuộc tính fov trên thiết bị di động. Đây là hành vi mặc định.
  • Khi giá trị là false, chuyển động của thiết bị sẽ không ảnh hưởng đến trải nghiệm xem 360° và các thuộc tính yaw, pitch, rollfov đều phải được đặt qua API.

Thiết bị di động không được hỗ trợ
Giá trị thuộc tính enableOrientationSensor không ảnh hưởng đến trải nghiệm phát.

Phát video trong danh sách phát

player.nextVideo():Void
Chức năng này tải và phát video tiếp theo trong danh sách phát.
  • Nếu player.nextVideo() được gọi trong khi video cuối cùng trong danh sách phát đang được xem và danh sách phát đó được đặt để phát liên tục (loop), thì trình phát sẽ tải và phát video đầu tiên trong danh sách.

  • Nếu player.nextVideo() được gọi trong khi video cuối cùng trong danh sách phát đang được xem và danh sách phát không được đặt để phát liên tục, thì quá trình phát sẽ kết thúc.

player.previousVideo():Void
Chức năng này tải và phát video trước trong danh sách phát.
  • Nếu player.previousVideo() được gọi trong khi video đầu tiên trong danh sách phát đang được xem và danh sách phát được đặt để phát liên tục (loop), thì trình phát sẽ tải và phát video cuối cùng trong danh sách.

  • Nếu player.previousVideo() được gọi trong khi video đầu tiên trong danh sách phát đang được xem và danh sách phát đó không được đặt để phát liên tục, thì trình phát sẽ bắt đầu lại video đầu tiên trong danh sách phát từ đầu.

player.playVideoAt(index:Number):Void
Hàm này tải và phát video đã chỉ định trong danh sách phát.
  • Tham số index bắt buộc chỉ định chỉ mục của video mà bạn muốn phát trong danh sách phát. Tham số này sử dụng chỉ mục bắt đầu từ 0, do đó, giá trị của 0 sẽ xác định video đầu tiên trong danh sách. Nếu bạn đã xáo trộn danh sách phát, chức năng này sẽ phát video ở vị trí đã chỉ định trong danh sách phát ngẫu nhiên.

Thay đổi âm lượng của trình phát

player.mute():Void
Tắt tiếng trình phát.
player.unMute():Void
Bật tiếng người chơi.
player.isMuted():Boolean
Trả về true nếu trình phát bị tắt tiếng, false nếu trình phát không bị tắt tiếng.
player.setVolume(volume:Number):Void
Đặt âm lượng. Chấp nhận số nguyên từ 0 đến 100.
player.getVolume():Number
Trả về âm lượng hiện tại của người chơi, một số nguyên từ 0 đến 100. Lưu ý rằng getVolume() sẽ trả về âm lượng ngay cả khi trình phát bị tắt tiếng.

Đặt kích thước trình phát

player.setSize(width:Number, height:Number):Object
Đặt kích thước bằng pixel của <iframe> chứa trình phát.

Đặt tốc độ phát

player.getPlaybackRate():Number
Chức năng này truy xuất tốc độ phát của video hiện đang phát. Tốc độ phát mặc định là 1, cho biết video đang phát ở tốc độ bình thường. Tốc độ phát có thể bao gồm các giá trị như 0.25, 0.5, 1, 1.52.
player.setPlaybackRate(suggestedRate:Number):Void
Hàm này đặt tốc độ phát đề xuất cho video hiện tại. Nếu tốc độ phát thay đổi thì tốc độ này sẽ chỉ thay đổi đối với video đã được phát hoặc đang phát. Nếu bạn đặt tốc độ phát cho một video dừng, tốc độ đó sẽ vẫn có hiệu lực khi hàm playVideo được gọi hoặc khi người dùng bắt đầu phát trực tiếp thông qua các nút điều khiển trình phát. Ngoài ra, các chức năng gọi tín hiệu hoặc tải video hoặc danh sách phát (cueVideoById, loadVideoById, v.v.) sẽ đặt lại tốc độ phát về 1.

Việc gọi hàm này không đảm bảo rằng tốc độ phát sẽ thực sự thay đổi. Tuy nhiên, nếu tốc độ phát thay đổi, thì sự kiện onPlaybackRateChange sẽ kích hoạt và mã của bạn phải phản hồi sự kiện này thay vì thực tế gọi hàm setPlaybackRate.

Phương thức getAvailablePlaybackRates sẽ trả về tốc độ phát có thể có của video hiện đang phát. Tuy nhiên, nếu bạn đặt tham số suggestedRate thành một số nguyên hoặc giá trị số thực không được hỗ trợ, trình phát sẽ làm tròn giá trị đó xuống giá trị được hỗ trợ gần nhất theo hướng 1.
player.getAvailablePlaybackRates():Array
Hàm này trả về tập hợp tốc độ phát của video hiện tại. Giá trị mặc định là 1, cho biết video đang phát ở tốc độ bình thường.

Hàm trả về một mảng số được sắp xếp theo thứ tự từ tốc độ phát chậm nhất đến nhanh nhất. Ngay cả khi trình phát không hỗ trợ tốc độ phát biến thiên, mảng này vẫn phải luôn chứa ít nhất một giá trị (1).

Đặt hoạt động phát cho danh sách phát

player.setLoop(loopPlaylists:Boolean):Void

Chức năng này cho biết trình phát video sẽ phát liên tục danh sách phát hay nên dừng phát sau khi video cuối cùng trong danh sách phát kết thúc. Chế độ mặc định là danh sách phát không lặp lại.

Chế độ cài đặt này sẽ vẫn duy trì ngay cả khi bạn tải hoặc đưa ra một danh sách phát khác, nghĩa là nếu bạn tải một danh sách phát, hãy gọi hàm setLoop với giá trị true rồi tải danh sách phát thứ hai, danh sách phát thứ hai cũng sẽ lặp lại.

Tham số loopPlaylists bắt buộc sẽ xác định hành vi lặp lại.

  • Nếu giá trị thông số là true thì trình phát video sẽ liên tục phát danh sách phát. Sau khi phát video cuối cùng trong danh sách phát, trình phát video sẽ quay lại đầu danh sách phát và phát lại video đó.

  • Nếu giá trị thông số là false thì lượt phát sẽ kết thúc sau khi trình phát video phát video cuối cùng trong danh sách phát.

player.setShuffle(shufflePlaylist:Boolean):Void

Chức năng này cho biết liệu các video trong danh sách phát có nên được trộn lẫn để phát theo thứ tự khác với thứ tự mà người tạo danh sách phát chỉ định hay không. Nếu bạn phát ngẫu nhiên một danh sách phát sau khi danh sách phát đó đã bắt đầu phát, thì danh sách phát sẽ được sắp xếp lại trong lúc video đang phát tiếp tục phát. Video phát tiếp theo sẽ được chọn dựa trên danh sách đã sắp xếp lại.

Chế độ cài đặt này sẽ không duy trì nếu bạn tải hoặc đặt một danh sách phát khác, tức là nếu bạn tải một danh sách phát, gọi hàm setShuffle rồi tải danh sách phát thứ hai, thì danh sách phát thứ hai sẽ không bị trộn lẫn.

Tham số shufflePlaylist bắt buộc cho biết YouTube có nên phát ngẫu nhiên danh sách phát hay không.

  • Nếu giá trị thông số là true thì YouTube sẽ trộn thứ tự danh sách phát. Nếu bạn ra lệnh cho chức năng phát ngẫu nhiên một danh sách phát đã được trộn, thì YouTube sẽ xáo trộn thứ tự đó một lần nữa.

  • Nếu giá trị thông số là false thì YouTube sẽ thay đổi thứ tự danh sách phát về thứ tự ban đầu.

Trạng thái phát

player.getVideoLoadedFraction():Float
Trả về một số từ 0 đến 1 chỉ định tỷ lệ phần trăm video mà trình phát hiển thị dưới dạng vùng đệm. Phương thức này trả về một số liệu đáng tin cậy hơn so với các phương thức getVideoBytesLoadedgetVideoBytesTotal hiện không còn được dùng nữa.
player.getPlayerState():Number
Trả về trạng thái của trình phát. Các giá trị có thể sử dụng là:
  • -1 – chưa bắt đầu
  • 0 – đã kết thúc
  • 1 – đang phát
  • 2 – đã tạm dừng
  • 3 – tải vào bộ đệm
  • 5 – video được dừng
player.getCurrentTime():Number
Trả về thời gian đã trôi qua (tính bằng giây) kể từ khi video bắt đầu phát.
player.getVideoStartBytes():Number
Không dùng nữa kể từ ngày 31 tháng 10 năm 2012. Trả về số lượng byte mà tệp video bắt đầu tải. (Phương thức này hiện luôn trả về giá trị 0.) Trường hợp ví dụ: người dùng tìm kiếm tới một điểm vẫn chưa tải và trình phát đưa ra yêu cầu mới để phát một đoạn của video chưa tải.
player.getVideoBytesLoaded():Number
Không dùng nữa kể từ ngày 18 tháng 7 năm 2012. Thay vào đó, hãy sử dụng phương thức getVideoLoadedFraction để xác định tỷ lệ phần trăm video đã lưu vào bộ đệm.

Phương thức này trả về một giá trị trong khoảng từ 0 đến 1000 gần đúng với thời lượng video đã được tải. Bạn có thể tính tỷ lệ phần trăm của video đã tải bằng cách chia giá trị getVideoBytesLoaded cho giá trị getVideoBytesTotal.
player.getVideoBytesTotal():Number
Không dùng nữa kể từ ngày 18 tháng 7 năm 2012. Thay vào đó, hãy sử dụng phương thức getVideoLoadedFraction để xác định tỷ lệ phần trăm video đã lưu vào bộ đệm.

Trả về kích thước theo đơn vị byte của video hiện đang tải/đang phát, hoặc kích thước gần đúng của video.

Phương thức này luôn trả về giá trị 1000. Bạn có thể tính tỷ lệ phần trăm của video đã tải bằng cách chia giá trị getVideoBytesLoaded cho giá trị getVideoBytesTotal.

Truy xuất thông tin video

player.getDuration():Number
Trả về thời lượng tính bằng giây của video hiện đang phát. Xin lưu ý rằng getDuration() sẽ trả về 0 cho đến khi siêu dữ liệu của video được tải. Quá trình này thường xảy ra ngay sau khi video bắt đầu phát.

Nếu video đang phát là một sự kiện trực tiếp, thì hàm getDuration() sẽ trả về thời gian đã trôi qua kể từ khi video phát trực tiếp bắt đầu. Cụ thể, đây là thời lượng video phát trực tuyến mà không bị đặt lại hoặc gián đoạn. Ngoài ra, thời lượng này thường dài hơn thời gian diễn ra sự kiện thực tế vì quá trình phát trực tiếp có thể bắt đầu trước thời gian bắt đầu sự kiện.
player.getVideoUrl():String
Trả về URL YouTube.com cho video hiện đang được tải/đang phát.
player.getVideoEmbedCode():String
Trả về mã nhúng cho video hiện được tải/đang phát.

Truy xuất thông tin danh sách phát

player.getPlaylist():Array
Hàm này trả về một mảng gồm các mã video trong danh sách phát theo thứ tự hiện tại. Theo mặc định, hàm này sẽ trả về mã video theo thứ tự mà chủ sở hữu danh sách phát chỉ định. Tuy nhiên, nếu bạn đã gọi hàm setShuffle để xáo trộn thứ tự danh sách phát, thì giá trị trả về của hàm getPlaylist() sẽ phản ánh thứ tự xáo trộn.
player.getPlaylistIndex():Number
Hàm này trả về chỉ mục của video trong danh sách phát hiện đang phát.
  • Nếu bạn chưa trộn danh sách phát, giá trị trả về sẽ xác định vị trí mà người tạo danh sách phát đã đặt video. Giá trị trả về sử dụng chỉ mục dựa trên 0, do đó giá trị 0 xác định video đầu tiên trong danh sách phát.

  • Nếu bạn đã trộn danh sách phát, giá trị trả về sẽ xác định thứ tự của video trong danh sách phát đã trộn.

Thêm hoặc xoá trình nghe sự kiện

player.addEventListener(event:String, listener:String):Void
Thêm hàm trình nghe cho event đã chỉ định. Phần Sự kiện dưới đây xác định những sự kiện mà trình phát có thể kích hoạt. Trình nghe là một chuỗi chỉ định hàm sẽ thực thi khi sự kiện được chỉ định kích hoạt.
player.removeEventListener(event:String, listener:String):Void
Xoá hàm trình nghe của event đã chỉ định. listener là một chuỗi xác định hàm sẽ không còn thực thi khi sự kiện được chỉ định kích hoạt.

Truy cập và sửa đổi nút DOM

player.getIframe():Object
Phương thức này trả về nút DOM cho <iframe> được nhúng.
player.destroy():Void
Xoá <iframe> chứa trình phát.

Sự kiện

API kích hoạt các sự kiện để thông báo cho ứng dụng của bạn về các thay đổi đối với trình phát được nhúng. Như đã lưu ý trong phần trước, bạn có thể đăng ký nhận sự kiện bằng cách thêm trình nghe sự kiện khi tạo đối tượng YT.Player. Ngoài ra, bạn cũng có thể sử dụng hàm addEventListener.

API sẽ truyền một đối tượng sự kiện dưới dạng đối số duy nhất cho từng hàm đó. Đối tượng sự kiện có các thuộc tính sau:

  • target của sự kiện giúp xác định trình phát video tương ứng với sự kiện đó.
  • data của sự kiện chỉ định một giá trị có liên quan đến sự kiện. Xin lưu ý rằng các sự kiện onReadyonAutoplayBlocked không chỉ định thuộc tính data.

Danh sách sau đây xác định các sự kiện mà API kích hoạt:

onReady
Sự kiện này sẽ kích hoạt bất cứ khi nào người chơi tải xong và sẵn sàng bắt đầu nhận lệnh gọi API. Ứng dụng của bạn nên triển khai hàm này nếu bạn muốn tự động thực thi một số thao tác, chẳng hạn như phát video hoặc hiện thông tin về video, ngay khi trình phát sẵn sàng.

Ví dụ dưới đây cho thấy một hàm mẫu để xử lý sự kiện này. Đối tượng sự kiện mà API truyền vào hàm có một thuộc tính target, giúp nhận dạng trình phát. Hàm này truy xuất mã nhúng cho video hiện được tải, bắt đầu phát video và hiển thị mã nhúng trong phần tử trang có giá trị idembed-code.
function onPlayerReady(event) {
  var embedCode = event.target.getVideoEmbedCode();
  event.target.playVideo();
  if (document.getElementById('embed-code')) {
    document.getElementById('embed-code').innerHTML = embedCode;
  }
}
onStateChange
Sự kiện này sẽ kích hoạt bất cứ khi nào trạng thái của người chơi thay đổi. Thuộc tính data của đối tượng sự kiện mà API truyền đến hàm trình nghe sự kiện sẽ chỉ định một số nguyên tương ứng với trạng thái của trình phát mới. Các giá trị có thể là:

  • -1 (chưa bắt đầu)
  • 0 (đã kết thúc)
  • 1 (đang phát)
  • 2 (tạm dừng)
  • 3 (đang lưu vào bộ đệm)
  • 5 (video được dừng lại).

Khi tải một video lần đầu tiên, trình phát sẽ phát đi sự kiện unstarted (-1). Khi một video được dừng và sẵn sàng phát, trình phát sẽ phát sóng một sự kiện video cued (5). Trong mã của mình, bạn có thể chỉ định giá trị số nguyên hoặc sử dụng một trong các biến có vùng chứa tên sau:

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

onPlaybackQualityChange
Sự kiện này sẽ kích hoạt bất cứ khi nào chất lượng phát video thay đổi. Đó có thể là tín hiệu về một thay đổi trong môi trường phát của người xem. Hãy xem Trung tâm trợ giúp của YouTube để biết thêm thông tin về những yếu tố ảnh hưởng đến điều kiện phát hoặc có thể khiến sự kiện đó kích hoạt.

Giá trị thuộc tính data của đối tượng sự kiện mà API truyền đến hàm trình nghe sự kiện sẽ là một chuỗi xác định chất lượng phát mới. Các giá trị có thể là:

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

onPlaybackRateChange
Sự kiện này sẽ kích hoạt bất cứ khi nào tốc độ phát của video thay đổi. Ví dụ: nếu bạn gọi hàm setPlaybackRate(suggestedRate), sự kiện này sẽ kích hoạt nếu tốc độ phát thực sự thay đổi. Ứng dụng của bạn phải phản hồi sự kiện và không nên giả định rằng tốc độ phát sẽ tự động thay đổi khi hàm setPlaybackRate(suggestedRate) được gọi. Tương tự, mã của bạn không nên giả định rằng tốc độ phát video sẽ chỉ thay đổi do có lệnh gọi rõ ràng đến setPlaybackRate.

Giá trị thuộc tính data của đối tượng sự kiện mà API truyền đến hàm trình nghe sự kiện sẽ là một số xác định tốc độ phát mới. Phương thức getAvailablePlaybackRates trả về danh sách tỷ lệ phát hợp lệ cho video hiện đang phát hoặc đang phát.
onError
Sự kiện này sẽ kích hoạt nếu trình phát xảy ra lỗi. API sẽ chuyển một đối tượng event đến hàm trình nghe sự kiện. Thuộc tính data của đối tượng đó sẽ chỉ định một số nguyên xác định loại lỗi đã xảy ra. Các giá trị có thể là:

  • 2 – Yêu cầu chứa giá trị thông số không hợp lệ. Ví dụ: lỗi này xảy ra nếu bạn chỉ định một mã video không có 11 ký tự hoặc nếu mã video chứa các ký tự không hợp lệ, chẳng hạn như dấu chấm than hoặc dấu hoa thị.
  • 5 – Không thể phát nội dung được yêu cầu trong trình phát HTML5 hoặc đã xảy ra một lỗi khác liên quan đến trình phát HTML5.
  • 100 – Không tìm thấy video được yêu cầu. Lỗi này xảy ra khi video đã bị xoá (vì bất kỳ lý do gì) hoặc đã được đánh dấu là riêng tư.
  • 101 – Chủ sở hữu của video được yêu cầu không cho phép phát video trong trình phát được nhúng.
  • 150 – Lỗi này giống với 101. Đó chỉ là một lỗi 101 nguỵ trang!
onApiChange
Sự kiện này được kích hoạt để cho biết trình phát đã tải (hoặc huỷ tải) một mô-đun có các phương thức API hiển thị. Ứng dụng của bạn có thể theo dõi sự kiện này rồi thăm dò trình phát để xác định tuỳ chọn nào hiển thị cho mô-đun được tải gần đây. Sau đó, ứng dụng của bạn có thể truy xuất hoặc cập nhật các chế độ cài đặt hiện có cho các tuỳ chọn đó.

Lệnh sau đây truy xuất một mảng tên mô-đun mà bạn có thể đặt tuỳ chọn của trình phát:
player.getOptions();
Hiện tại, mô-đun duy nhất mà bạn có thể đặt tuỳ chọn là mô-đun captions, mô-đun này xử lý phụ đề chi tiết trong trình phát. Khi nhận được sự kiện onApiChange, ứng dụng của bạn có thể sử dụng lệnh sau đây để xác định tuỳ chọn nào có thể đặt cho mô-đun captions:
player.getOptions('captions');
Bằng cách thăm dò trình phát bằng lệnh này, bạn có thể xác nhận rằng các tuỳ chọn mà bạn muốn truy cập thực sự có thể truy cập được. Các lệnh sau đây truy xuất và cập nhật tuỳ chọn mô-đun:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
Bảng dưới đây liệt kê các tuỳ chọn mà API hỗ trợ:

Mô-đun Lựa chọn Nội dung mô tả
phụ đề fontSize Lựa chọn này sẽ điều chỉnh cỡ chữ của phụ đề trong trình phát.

Các giá trị hợp lệ là -1, 0, 1, 23. Kích thước mặc định là 0 và kích thước nhỏ nhất là -1. Nếu bạn đặt tuỳ chọn này thành một số nguyên dưới -1, kích thước phụ đề nhỏ nhất sẽ hiển thị, còn nếu đặt tuỳ chọn này thành số nguyên trên 3 thì kích thước phụ đề lớn nhất sẽ hiển thị.
phụ đề reload Tùy chọn này sẽ tải lại dữ liệu phụ đề cho video đang phát. Giá trị sẽ là null nếu bạn truy xuất giá trị của tuỳ chọn. Đặt giá trị thành true để tải lại dữ liệu phụ đề.
onAutoplayBlocked
Sự kiện này sẽ kích hoạt bất cứ khi nào trình duyệt chặn các tính năng tự động phát hoặc phát video theo tập lệnh, gọi chung là "tự động phát". Điều này bao gồm cả nỗ lực phát bằng bất kỳ API trình phát nào sau đây:

Hầu hết các trình duyệt đều có chính sách chặn tính năng tự động phát trên máy tính, thiết bị di động và các môi trường khác nếu bạn đáp ứng một số điều kiện nhất định. Các trường hợp mà chính sách này có thể được kích hoạt sẽ bao gồm việc phát nội dung có bật tiếng mà không có sự tương tác của người dùng, hoặc khi bạn chưa thiết lập Chính sách quyền để cho phép tự động phát trên một iframe nhiều nguồn gốc.

Để biết toàn bộ thông tin chi tiết, hãy tham khảo các chính sách dành riêng cho từng trình duyệt (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) và hướng dẫn tự động phát của Mozilla.

Ví dụ

Tạo đối tượng YT.Player

  • Ví dụ 1: Sử dụng API với <iframe> hiện có

    Trong ví dụ này, một phần tử <iframe> trên trang đã xác định trình phát sẽ được sử dụng API. Xin lưu ý rằng URL src của người chơi phải đặt tham số enablejsapi thành 1 hoặc thuộc tính enablejsapi của phần tử <iframe> phải được đặt thành true.

    Hàm onPlayerReady thay đổi màu của đường viền xung quanh trình phát thành màu cam khi trình phát sẵn sàng. Sau đó, hàm onPlayerStateChange sẽ thay đổi màu của đường viền xung quanh trình phát dựa trên trạng thái hiện tại của người chơi. Ví dụ: màu sắc có màu xanh lục khi trình phát đang chơi, màu đỏ khi tạm dừng, màu xanh dương khi lưu vào bộ đệm, v.v.

    Ví dụ này sử dụng mã sau:

    <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>
    
  • Ví dụ 2: Phát âm thanh lớn

    Ví dụ này sẽ tạo một trình phát video có kích thước 1280px x 720px. Sau đó, trình nghe sự kiện cho sự kiện onReady sẽ gọi hàm setVolume để điều chỉnh âm lượng lên mức cài đặt cao nhất.

    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();
    }
    
  • Ví dụ 3: Ví dụ này đặt các tham số trình phát để tự động phát video khi video tải và để ẩn các nút điều khiển của trình phát video. API này cũng thêm trình nghe sự kiện cho một số sự kiện mà API thông báo.

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

Kiểm soát video 360°

Ví dụ này sử dụng mã sau:

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

Nhật ký sửa đổi

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.