Trang này được dịch bởi Cloud Translation API.

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 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 hàm JavaScript của API, bạn có thể thêm video vào hàng đợi để phát; phát, tạm dừng hoặc dừng những video đó; điều chỉnh âm lượng của trình phát hoặc truy xuất thông tin về video đang được 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 trình phát, 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. API 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 ghi trình nghe sự kiện để phản hồi những sự kiện đó. Bài viết 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 postMessage của HTML5. 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 nhất là 200px x 200px. Nếu trình phát hiện các nút điều khiển thì trình phát phải đủ lớn để hiện đầy đủ các nút điều khiển mà không thu nhỏ khung nhìn 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.

Mọi trang web 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 cho API trình phát, điều này cho phép bạn 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 tải trang.

Bắt đầu

Trang HTML mẫu bên dưới tạo một trình phát được nhúng sẽ tải video, phát video trong 6 giây, sau đó dừng phát. 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 về mẫu ở trên:

Thẻ <div> trong phần này xác định vị trí trên trang mà 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ào đúng vị trí. Cụ thể, API IFrame sẽ thay thế thẻ <div> bằng thẻ <iframe>.

Ngoài ra, bạn cũng có thể đặt trực tiếp phần tử <iframe> trên trang. Phần Tải trình phát video giải thích cách thực hiện.
Mã trong phần này tải mã JavaScript 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 này của Stack Overflow.
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, đề cập đến trình phát video mà bạn đang nhúng, sau đó hàm này xây dựng đối tượng trình phát video.
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, trình phát video sẽ bắt đầu phát.
API sẽ gọi hàm onPlayerStateChange khi trạng thái của người chơi thay đổi. Điều này có thể cho biết rằng 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.

Đang 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 vào trang của mình. Phần trích dẫn HTML bên dưới cho thấy hàm onYouTubeIframeAPIReady trong 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 khởi tạo cho trình phát video chỉ định các thông số sau:

Tham số đầu tiên chỉ định phần tử DOM hoặc id của phần tử HTML mà 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ử đang được thay thế có kiểu hiển thị khác với kiểu hiển thị của phần tử <iframe> đã chèn. Theo mặc định, <iframe> xuất hiện dưới dạng phần tử inline-block.
Tham số thứ hai là một đối tượng chỉ định các lựa chọn cho người chơi. Đố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) – ID video YouTube 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 các tham số của người chơi có thể dùng để tuỳ chỉnh trình phát.
- events (đối tượng) – Thuộc tính của đối tượng xác định những 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 những 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 của bạn (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 bạn viết thẻ <iframe>, thì khi tạo đối tượng YT.Player, bạn không cần chỉ định giá trị cho width và height (đượ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, trong đó chỉ định giao thứ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ù bạn không bắt buộc phải sử dụng origin, nhưng mã này giúp ngăn chặn JavaScript độc hại của bên thứ ba được chèn vào trang của bạn và khả năng chiếm quyền kiểm soát trình phát của bạn trên YouTube.

Phần Ví dụ cũng cho thấy một vài 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 kiểm soát. Bạn lấy thông tin tham chiếu bằng cách tạo một đối tượng YT.Player như thảo luận trong phần Bắt đầu và Tải trình phát video của tài liệu này.

Hàm

Hàm xếp hàng

Chức năng xếp hàng cho phép bạn tải và phá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ả bên dưới để gọi các hàm này, bạn cũng có thể thêm video vào danh sách chờ hoặc tải danh sách video đã tải lên của người dùng.

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

Cú pháp đối số yêu cầu các đối số hàm phải được liệt kê 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 một tham số duy nhất và xác định các thuộc tính đối tượng cho các đối số hàm mà bạn muốn đặt. Ngoài ra, API này có thể hỗ trợ chức năng khác mà cú pháp đối số không hỗ trợ.

Ví dụ: bạn có thể gọi hàm loadVideoById theo một trong các cách sau. Xin 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});

Chức năng xếp hàng đợi cho video

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

Chức năng này tải hình thu nhỏ của video được chỉ định và chuẩn bị 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 ID video YouTube của video sẽ được phát. Trong API Dữ liệu YouTube, thuộc tính id của tài nguyên video chỉ định mã nhận dạng.
Tham số startSeconds (không bắt buộc) chấp nhận một số thực/số nguyên và chỉ định thời lượng video sẽ bắt đầu phát 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ẽ phát từ khoảng thời gian được chỉ định trong lệnh gọi seekTo(). Khi video được gợi ý và sẵn sàng phát, trình phát sẽ truyền 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ố có độ chính xác đơn/số nguyên và chỉ định thời điểm video nên dừ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 ID video YouTube của video sẽ được phát. Trong API Dữ liệu YouTube, thuộc tính id của tài nguyên video chỉ định mã nhận dạng.
Tham số startSeconds không bắt buộc chấp nhận một 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 đến thời gian được chỉ định.
Tham số endSeconds không bắt buộc chấp nhận một số thực/số nguyên. Nếu bạn chỉ định chính sách này, video sẽ ngừng phát tại thời điểm được 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

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 một số thực/số nguyên và chỉ định thời lượng video sẽ bắt đầu phát khi playVideo() được gọi. Nếu bạn chỉ định startSeconds rồi gọi seekTo(), thì trình phát sẽ phát từ khoảng thời gian được chỉ định trong lệnh gọi seekTo(). Khi video được gợi ý và sẵn sàng phát, trình phát sẽ truyền 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ố có độ chính xác đơn/số nguyên và chỉ định thời điểm video nên dừ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 một số thực/số nguyên và chỉ định thời lượng video sẽ bắt đầu phát. 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 đến 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ố có độ chính xác đơn/số nguyên và chỉ định thời điểm video nên dừng phát.

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

Các hàm cuePlaylist và loadPlaylist 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ể thêm (hoặc tải) danh sách các video mà người dùng đã tải lên vào hàng đợi.

Vì các hàm hoạt động theo cách khác nhau tuỳ thuộc vào việc chúng đượ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 danh sách phát. Khi danh sách phát được gợi ý và sẵn sàng phát, trình phát sẽ truyền 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 API dữ liệu YouTube, thuộc tính id của tài nguyên video sẽ xác định mã 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 chế độ 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 một số thực/số nguyên và chỉ định thời lượng video đầu tiên trong danh sách phát sẽ bắt đầu 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ẽ phát từ khoảng thời gian được chỉ định trong lệnh gọi seekTo(). Nếu bạn dừng 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 đã chỉ định.
Cú pháp đối tượng
```
player.cuePlaylist({listType:String,
                    list:String,
                    index:Number,
                    startSeconds:Number}):Void
```
Thêm danh sách video được chỉ định vào danh sách 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. Kể từ ngày 15 tháng 11 năm 2020, tính năng xếp danh sách kết quả tìm kiếm vào danh sách chờ đã không còn được dùng và không còn được hỗ trợ nữa.
Khi danh sách được gợi ý và sẵn sàng chơi, người chơi sẽ truyền 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à playlist và user_uploads. Kể từ ngày 15 tháng 11 năm 2020, chúng tôi sẽ không hỗ trợ một giá trị không dùng nữa là search. Giá trị mặc định là playlist.
- Thuộc tính list bắt buộc chứa khoá giúp xác định danh sách video cụ thể mà YouTube trả về.
  - Nếu giá trị thuộc tính listType là playlist thì thuộc tính list sẽ 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 xác định 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ã video.
  - Nếu giá trị thuộc tính listType là user_uploads thì thuộc tính list sẽ xác định người dùng có video đã tải lên sẽ được trả về.
  - Nếu giá trị của thuộc tính listType là search 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òn được hỗ trợ 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ố có độ chính xác đơn/số nguyên và chỉ định thời gian mà video đầu tiên trong danh sách sẽ bắt đầu 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ẽ phát từ khoảng thời gian được chỉ định trong lệnh gọi seekTo(). Nếu bạn dừng một danh sách rồi gọi hàm playVideoAt(), trình phát sẽ bắt đầu phát ở đầ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 và phát danh sách phát được chỉ định.
- Tham số playlist bắt buộc chỉ định một mảng mã video trên YouTube. Trong API dữ liệu YouTube, 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 chế độ 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 một số thực/số nguyên và chỉ định thời lượng video đầu tiên trong danh sách phát sẽ bắt đầu 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 được 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 còn được dùng và không còn được hỗ trợ 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à playlist và user_uploads. Kể từ ngày 15 tháng 11 năm 2020, chúng tôi sẽ không hỗ trợ một giá trị không dùng nữa là search. Giá trị mặc định là playlist.
- Thuộc tính list bắt buộc chứa khoá giúp xác định danh sách video cụ thể mà YouTube trả về.
  - Nếu giá trị thuộc tính listType là playlist thì thuộc tính list sẽ chỉ định một mã nhận dạng danh sách phát hoặc một mảng mã video. Trong API dữ liệu YouTube, thuộc tính id của tài nguyên playlist chỉ định 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ã video.
  - Nếu giá trị thuộc tính listType là user_uploads thì thuộc tính list sẽ xác định người dùng có video đã tải lên sẽ được trả về.
  - Nếu giá trị của thuộc tính listType là search 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òn được hỗ trợ 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 một số thực/số nguyên và chỉ định thời lượng video đầu tiên trong danh sách sẽ bắt đầu phát.

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

Phát một video

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

Lưu ý: Một lượt phát chỉ được tính vào số lượt xem chính thức của một video nếu hoạt động này được 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 đ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 này được gọi. Trong trường hợp đó, trạng thái của người chơi sẽ không thay đổi.

player.stopVideo():Void: Dừng và hủy quá trình tải video hiện tại. Chức năng này nên dành riêng cho các 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ỉ nê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 hàm 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 khiến người chơi ở trạng thái paused (2), hàm stopVideo có thể đưa người chơi sang trạng thái 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 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ừ trạng thái khác (playing, video cued, v.v.), thì trình phát sẽ phát video.

Tham số seconds xác định thời điểm mà người chơi nên 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 phần video mà người dùng đang tìm kiếm xuống.
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 nằm ngoài dữ liệu video hiện được lưu vào vùng đệ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 trong 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 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 việc phát video 360°

Lưu ý: Tính năng 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° sẽ bị méo hình và không có cách nào được hỗ trợ để thay đổi phối cảnh xem, 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 góc nhìn hiện tại của người xem khi 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 bạn đặt thuộc tính enableOrientationSensor 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`	Một số trong phạm vi [0, 360) biểu thị góc ngang của thành phần hiển thị theo độ, phản ánh mức độ người dùng xoay chế độ xem sang trái hoặc phải. Vị trí trung tính, đối diện với tâm của video trong phép chiếu hình cầu toàn cảnh, thể hiện 0° và giá trị này tăng lên khi người xem quay sang trái.
`pitch`	Một số trong phạm vi [-90, 90] biểu thị góc dọc của chế độ xem theo độ, phản ánh mức độ 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 của video trong phép chiếu hình cầu toàn cảnh, thể hiện 0° và giá trị này tăng lên khi người xem nhìn lên.
`roll`	Một số trong phạm vi [-180, 180] đại diện cho góc quay theo chiều kim đồng hồ hoặc ngược chiều kim đồng hồ của chế độ xem theo độ. Vị trí trung lập, với trục hoành trong hình chiếu hình cầu toàn song song với trục hoành của khung nhìn, thể hiện 0°. Giá trị tăng khi khung nhìn quay theo chiều kim đồng hồ và giảm khi khung nhìn quay 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 hiệu ứng cuộn của khung hiển thị. Bạn có thể điều chỉnh điểm giới thiệu theo một trong những cách sau đây và loại trừ lẫn nhau: Sử dụng cảm biến hướng trong trình duyệt dành cho thiết bị di động để cung cấp hiệu ứng cuộn cho chế độ xem. Nếu cảm biến hướng được bật, thì hàm `getSphericalProperties` sẽ luôn trả về `0` làm giá trị của thuộc tính `roll`. Nếu cảm biến hướng bị tắt, hãy đặt giá trị cuộn thành một giá trị khác 0 bằng API này.
`fov`	Một số trong phạm vi [30, 120] thể hiện 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ương ứng với tỷ lệ khung hình của chế độ xem. 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 cách sử dụ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 ở dạng hình cầu, thì phương thức này là 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 đến phương thức này bằng cách cập nhật để phản ánh giá trị của bất kỳ thuộc tính đã biết nào trong đối tượng properties. Chế độ xem này giữ nguyên các giá trị của mọi 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, thì người 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 lại 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 các 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, pitch và roll đối với việc phát video 360°. Hãy xem thuộc tính enableOrientationSensor dưới đây để biết thêm thông tin.

Đối tượng properties được truyền vào hàm này 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ợ.Một giá trị boolean cho biết liệu nội dung nhúng IFrame có phản hồi các sự kiện báo hiệu thay đổi theo 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 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`, `pitch` và `roll` để 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 này 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ị không ảnh hưởng đến trải nghiệm xem 360°, đồng thời các thuộc tính `yaw`, `pitch`, `roll` và `fov` đều phải được đặt thông qua API. Thiết bị di động không được hỗ trợ Giá trị của 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

Hàm này tải và phát video tiếp theo trong danh sách phát.

Nếu player.nextVideo() được gọi khi đang xem video cuối cùng trong danh sách phát 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 người dùng đang xem video cuối cùng trong danh sách phát và danh sách phát không được thiết lập để phát liên tục thì quá trình phát sẽ kết thúc.

player.previousVideo():Void

Hàm này tải và phát video trước trong danh sách phát.

Nếu player.previousVideo() được gọi khi đang xem video đầu tiên trong danh sách phát 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 khi đang xem video đầu tiên trong danh sách phát và danh sách phát không được đặt để phát liên tục, thì trình phát sẽ khởi động 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 được 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 dựa trên 0, vì vậy, 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 được trộn bài.

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

player.mute():Void: Tắt tiếng người chơi.

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, trả về false nếu không trình phát.

player.setVolume(volume:Number):Void: Đặt âm lượng. Chấp nhận một 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 ý 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: Hàm này truy xuất tốc độ phát của video đ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.5 và 2.

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 gợi ý hoặc đang phát. Nếu bạn đặt tốc độ phát cho một video có tín hiệu, thì tốc độ đó sẽ vẫn có hiệu lực khi hàm playVideo được gọi hoặc 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 hàm gọi để đưa ra gợi ý 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, sự kiện onPlaybackRateChange sẽ kích hoạt và mã của bạn sẽ phản hồi sự kiện đó thay vì thực tế là nó đã gọi hàm setPlaybackRate.

Phương thức getAvailablePlaybackRates sẽ trả về tốc độ phát có thể có của video đ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ị gần nhất được hỗ trợ 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ố theo thứ tự tốc độ phát theo thứ tự từ chậm nhất đến nhanh nhất. Ngay cả khi trình phát không hỗ trợ nhiều tốc độ phát, mảng phải luôn chứa ít nhất một giá trị (1).

Đặt hành vi 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 có cần phát liên tục danh sách phát hay không hoặc liệu trình phát có 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ẽ duy trì ngay cả khi bạn tải hoặc chỉ định 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, sau đó tải danh sách phát thứ hai thì 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 các 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.
Nếu giá trị thông số là false thì các 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ó nên xáo trộn video trong danh sách phát để các video này phát lại 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 khi video đang phát tiếp tục phát. Sau đó, video tiếp theo để phát sẽ được chọn dựa trên danh sách được sắp xếp lại.

Chế độ cài đặt này sẽ không được duy trì nếu bạn tải hoặc chỉ định 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 setShuffle, sau đó tải danh sách phát thứ hai, thì danh sách phát thứ hai sẽ không bị xáo trộn.

Thông 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 yêu cầu hàm này phát ngẫu nhiên một danh sách phát đã phát ngẫu nhiên, thì YouTube sẽ phát ngẫu nhiên thứ tự đó.
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. Mã này chỉ định tỷ lệ phần trăm của video mà trình phát hiển thị ở vùng đệm. Phương thức này trả về một số đáng tin cậy hơn so với các phương thức getVideoBytesLoaded và getVideoBytesTotal hiện không 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 – đang lưu vào bộ đệm
5 – tín hiệu video

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ố byte mà tệp video bắt đầu tải từ đó. (Phương thức này hiện luôn trả về giá trị 0.) Tình huống ví dụ: người dùng tìm kiếm một điểm chưa tải và trình phát đưa ra một 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 vùng đệm.

Phương thức này sẽ trả về một giá trị từ 0 đến 1000. Giá trị này ước tính thời lượng video đã được tải. Bạn có thể tính tỷ lệ phần trăm 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 vùng đệm.

Trả về kích thước tính bằng byte của video đang tải/đang phát hoặc kích thước gần đúng của kích thước 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 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 đ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. Việc 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à khoảng thời gian phát trực tiếp video 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 thực tế của sự kiện vì hoạt động 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 đang tải/đang phát.

player.getVideoEmbedCode():String: Trả về mã nhúng cho video đang 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 mã video trong danh sách phát theo thứ tự hiện tại của các mã này. Theo mặc định, hàm này sẽ trả về mã video theo thứ tự do 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 đang phát.

Nếu bạn chưa phát ngẫu nhiên danh sách phát, thì giá trị trả về sẽ xác định vị trí mà nhà sáng tạo danh sách phát đã đặt video vào. 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 đã phát ngẫu nhiê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 đã phát ngẫu nhiên.

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

player.addEventListener(event:String, listener:String):Void: Thêm một hàm trình nghe cho event được chỉ định. Phần Sự kiện dưới đây xác định các sự kiện khác nhau mà người chơi 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á một hàm trình nghe cho 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 các 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 này sẽ kích hoạt các sự kiện để thông báo cho ứng dụng về những 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ý các sự kiện bằng cách thêm trình nghe sự kiện khi tạo đối tượng YT.Player và bạn cũng có thể sử dụng hàm addEventListener.

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

target của sự kiện 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ị liên quan đến sự kiện. Xin lưu ý rằng các sự kiện onReady và onAutoplayBlocked 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ị thông tin về video ngay khi trình phát sẵn sàng.

Ví dụ dưới đây minh hoạ một hàm mẫu để xử lý sự kiện này. Đối tượng sự kiện mà API truyền đến hàm này có thuộc tính target giúp nhận dạng người chơi. Hàm này truy xuất mã nhúng cho video đang tải, bắt đầu phát video và hiển thị mã nhúng trong phần tử trang có giá trị 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

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 người chơi 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 (quảng cáo dựa trên video).

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 gợi ý và sẵn sàng phát, trình phát sẽ truyền 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 không gian 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. Đây có thể là dấu hiệu cho thấy môi trường phát của người xem đã thay đổi. Hãy truy cập vào 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 video hoặc những yếu tố 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 này 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 được giả định rằng tốc độ phát video sẽ chỉ thay đổi do một 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ốc độ phát hợp lệ cho video hiện đang được chèn hoặc đang phát.

onError

Sự kiện này kích hoạt nếu có lỗi xảy ra trong trình phát. API sẽ truyề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ị tham số không hợp lệ. Ví dụ: lỗi này xảy ra nếu bạn chỉ định 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 – Nội dung được yêu cầu không thể phát trong trình phát HTML5 hoặc một lỗi khác liên quan đến trình phát HTML5 đã xảy ra.
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 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. Đây chỉ là lỗi 101 về hành vi nguỵ trang!

onApiChange

Sự kiện này được kích hoạt để cho biết rằng người chơi đã tải (hoặc huỷ tải) một mô-đun bằng 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, sau đó thăm dò trình phát để xác định tuỳ chọn nào sẽ hiện đối với 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 tại cho những lựa chọn đó.

Lệnh sau đây truy xuất một mảng tên mô-đun mà bạn có thể đặt các tuỳ chọn cho người chơi:

player.getOptions();

Hiện tại, mô-đun duy nhất mà bạn có thể đặt tuỳ chọn là mô-đun captions, giúp 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ể dùng lệnh sau để xác định những tuỳ chọn có thể đặt cho mô-đun captions:

player.getOptions('captions');

Bằng cách thăm dò người chơi bằng lệnh này, bạn có thể xác nhận rằng các tuỳ chọn bạn muốn truy cập thực sự có thể truy cập được. Các lệnh sau đây dành cho việc truy xuất và cập nhật 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 này hỗ trợ:

Mô-đun	Phương thức	Nội dung mô tả
phụ đề	fontSize	Lựa chọn này điều chỉnh cỡ chữ của phụ đề hiển thị trong trình phát. Các giá trị hợp lệ là `-1`, `0`, `1`, `2` và `3`. 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 nhỏ hơn `-1`, thì kích thước phụ đề nhỏ nhất sẽ xuất hiện. Trong khi đó, việc đặt tuỳ chọn này thành số nguyên lớn hơn `3` sẽ khiến kích thước phụ đề lớn nhất hiển thị.
phụ đề	reload	Lựa chọn này sẽ tải lại dữ liệu phụ đề của video đang phát. Giá trị sẽ là `null` nếu bạn truy xuất giá trị của tuỳ chọn này. Thiết lập 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ả việc phát bằng bất kỳ API trình phát nào sau đây:

Tham số autoplay
Hàm loadPlaylist
Hàm loadVideoById
Hàm loadVideoByUrl
Hàm playVideo

Hầu hết các trình duyệt đều có chính sách có thể 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 đáp ứng một số điều kiện nhất định. Những trường hợp mà chính sách này có thể được kích hoạt bao gồm cả việc phát ở chế độ bật tiếng mà không cần người dùng tương tác hoặc khi bạn chưa đặt Chính sách về quyền cho phép tự động phát trên iframe trên nhiều nguồn gốc.

Để biết đầy đủ thông tin chi tiết, hãy tham khảo các chính sách dành riêng cho 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ụ

Đang 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, phần tử <iframe> trên trang đã xác định trình phát mà API sẽ được sử dụng. 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 người chơi đã sẵn sàng. Sau đó, hàm onPlayerStateChange thay đổi màu của đường viền xung quanh người chơi dựa trên trạng thái hiện tại của người chơi. Ví dụ: màu có màu xanh lục khi trình phát đang phát, 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 đoạn 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 lượng lớn

Ví dụ này tạo ra một trình phát video 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 ở chế độ 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 thông số của 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 truyền tin.

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

Điều khiển video 360°

Ví dụ này sử dụng đoạn 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>

Tích hợp API Tính toàn vẹn của nội dung đa phương tiện WebView cho Android

YouTube đã mở rộng API Tính toàn vẹn của nội dung nghe nhìn WebView trên Android để cho phép các trình phát nội dung nghe nhìn được nhúng (bao gồm cả nội dung được nhúng của trình phát YouTube trong ứng dụng Android) nhằm xác minh tính xác thực của ứng dụng nhúng. Với thay đổi này, các ứng dụng nhúng sẽ tự động gửi cho YouTube một mã ứng dụng đã được chứng thực. Dữ liệu được thu thập thông qua việc sử dụng API này là siêu dữ liệu ứng dụng (tên gói, số phiên bản và chứng chỉ ký) và mã thông báo chứng thực thiết bị do Dịch vụ Google Play tạo ra.

Dữ liệu này dùng để xác minh tính toàn vẹn của ứng dụng và thiết bị. Dữ liệu này được mã hoá, không chia sẻ với bên thứ ba và bị xoá sau một khoảng thời gian lưu giữ cố định. Nhà phát triển ứng dụng có thể định cấu hình thông tin nhận dạng ứng dụng trong API Tính toàn vẹn của nội dung đa phương tiện WebView. Cấu hình này hỗ trợ lựa chọn không tham gia.

Nhật ký sửa đổi

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:

The new removeEventListener function lets you remove a listener for a specified event.

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
  - onPlaybackRateChange – This event fires when the video's playback rate changes.

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.

YouTube Player API Reference for iframe Embeds

Yêu cầu

Bắt đầu

Đang tải trình phát video

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

Hàm

Hàm xếp hàng

Chức năng xếp hàng đợi cho video

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

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

Phát một video

Kiểm soát việc phát video 360°

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

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

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

Đặt tốc độ phát

Đặt hành vi phát cho danh sách phát

Trạng thái phát

Truy xuất thông tin video

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

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

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

Sự kiện

Ví dụ

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

Điều khiển video 360°

Tích hợp API Tính toàn vẹn của nội dung đa phương tiện WebView cho Android

Nhật ký sửa đổi

June 24, 2024

November 20, 2023

April 27, 2021

October 13, 2020

October 24, 2019

May 16, 2018

June 19, 2017

August 11, 2016

June 29, 2016

June 24, 2016

January 6, 2016

December 18, 2015

April 28, 2014

March 25, 2014

July 23, 2013

October 31, 2012

August 22, 2012

August 6, 2012

July 19, 2012

July 16, 2012

June 6, 2012

March 30, 2012

March 26, 2012

Đang tạo đối tượng `YT.Player`