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 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 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 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 đang 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. Tài liệu 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 các sự kiện đó. Tài liệu này cũng trình bày chi tiết các hàm JavaScript mà bạn có thể gọi để kiểm soát trình phát video cũng như các tham số trình phát mà bạn có thể sử dụng để tuỳ 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 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ố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ì trình phát phải đủ lớn để hiển thị đầy đủ các nút điều khiển mà không làm thu nhỏ khung nhìn xuống dưới kích thước tối thiểu. Bạn nên sử dụng trình phát 16:9 có chiều rộng tối thiểu 480 pixel và chiều cao tối thiểu 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, 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 người chơi mà bạn muốn hiển thị khi trang tải.

Bắt đầu

Trang HTML mẫu bên dưới sẽ tạo một trình phát được nhúng để 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:

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ị 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.
Mã trong phần này sẽ 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 rằng 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ộ, nhưng chưa được hỗ trợ trong tất cả trình duyệt hiện đại như đã thảo luận trong câu trả lời trên Stack Overflow này.
Hàm onYouTubeIframeAPIReady sẽ thực thi ngay khi mã API của người chơi tải xuống. Phần mã này xác định một biến toàn cục, player, tham chiếu đế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.
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 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, 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 rằng 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 tải mã JavaScript của API, API sẽ gọi hàm onYouTubeIframeAPIReady. Tại thời điểm này, bạn có thể tạo một đối tượng YT.Player để chèn trình phát video trên 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 tham 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ử đã 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> đã chèn. Theo mặc định, <iframe> hiển thị dưới dạng phần tử inline-block.
Tham số thứ hai là một đối tượng chỉ định các tuỳ chọn của 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) – Mã 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, 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 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. Đây là các giá trị được chỉ định dưới dạng thuộc tính của thẻ <iframe> hoặc tham số videoId và 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 giao thức URL (http:// hoặc https://) và miền đầy đủ của trang lưu trữ làm giá trị tham số. Mặc dù origin không bắt buộc, nhưng việc thêm tệp này sẽ giúp bảo vệ khỏi JavaScript độc hại của bên thứ ba được chèn vào trang của bạn và xâm nhập vào quyền kiểm soát trình phát YouTube.

Để biết các ví dụ khác về cách tạo đối tượng trình phát video, hãy xem phần Ví dụ.

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

Để gọi các phương thức API của người chơi, trước tiên, bạn phải tham chiếu đến đối tượng người chơi mà bạn muốn điều khiển. Bạn có thể lấy thông tin tham chiếu bằng cách tạo đố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

Các hàm xếp hàng cho phép bạn tải và phát một video, danh sách phát hoặc 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, thì bạn cũng có thể xếp hàng hoặc tải danh sách video mà người dùng đã tải lên.

API này hỗ trợ hai 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 đối số 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ụ: bạn có thể gọi hàm loadVideoById theo một trong hai cách sau. Xin lưu ý rằng cú pháp đối tượng hỗ trợ thuộc tính endSeconds, trong khi cú pháp đối số thì không.

Cú pháp đối số

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

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

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

Hàm xếp hàng 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

Hàm này tải hình thu nhỏ của video đã 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 cần 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 điểm video bắt đầu phát khi playVideo() được gọi. Nếu bạn chỉ định giá trị startSeconds rồi gọi seekTo(), thì trình phát sẽ phát từ thời điểm được chỉ định trong lệnh gọi seekTo(). Khi video được đánh dấu và sẵn sàng phát, trình phát sẽ truyền phát 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 điểm video sẽ ngừng phát khi playVideo() được gọi. Nếu bạn chỉ định 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 đã chỉ định.

Tham số videoId bắt buộc chỉ định Mã video trên YouTube của video cần 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 bạn chỉ định thời gian bắt đầu, 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ấp nhận số thực/số nguyên. Nếu bạn chỉ định thời gian kết thúc, video sẽ dừng phát tại thời điểm đó.

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 số thực/số nguyên và chỉ định thời điểm video 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ừ thời điểm được chỉ định trong lệnh gọi seekTo(). Khi video được tạo điểm chèn 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 điểm video sẽ ngừng phát khi playVideo() được gọi. Nếu bạn chỉ định 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 đã 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 điểm video bắt đầu phát. Nếu bạn chỉ định startSeconds (số có thể là số thực), video sẽ bắt đầu từ khung hình chính gần nhất với thời gian được chỉ định.
Thông 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 điểm video sẽ ngừng phát.

Đặt các hàm vào hàng đợi cho danh sách

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

Vì các hàm hoạt động 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 bên dưới.

cuePlaylist

Cú pháp đối số
```
player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
```
Thêm danh sách phát đã chỉ định vào hàng đợi. Khi danh sách phát được tạo và sẵn sàng phát, trình phát sẽ truyền 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 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. Thông số này sử dụng chỉ mục dựa trên 0 và giá trị thông số mặc định là 0, do đó, 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 điểm video đầu tiên trong danh sách phát bắt đầu phát khi hàm playVideo() được gọi. Nếu bạn chỉ định giá trị startSeconds rồi gọi seekTo(), thì trình phát sẽ phát từ thời điểm được chỉ định trong lệnh gọi seekTo(). Nếu bạn đưa một danh sách phát vào hàng đợi 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 đã 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 do người dùng tải lên. Khả năng đưa danh sách kết quả tìm kiếm vào hàng đợi không còn được 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ạo 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à playlist và user_uploads. Giá trị không dùng nữa, search, sẽ không còn được hỗ trợ kể từ ngày 15 tháng 11 năm 2020. Giá trị mặc định là playlist.
- Thuộc tính list bắt buộc chứa một 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 listType là playlist, thì thuộc tính list sẽ chỉ định mã 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ã danh sách phát và 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ị 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 còn được 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 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 điểm video đầu tiên trong danh sách bắt đầu phát khi hàm playVideo() được gọi. Nếu bạn chỉ định giá trị startSeconds rồi gọi seekTo(), thì trình phát sẽ phát từ thời điểm được chỉ định trong lệnh gọi seekTo(). Nếu bạn tạo 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 đã chỉ định.
- 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ã 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. Thông số này sử dụng chỉ mục dựa trên 0 và giá trị thông số mặc định là 0, do đó, 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 điểm 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 do người dùng tải lên. Khả năng tải danh sách kết quả tìm kiếm không còn được 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à playlist và user_uploads. Giá trị không dùng nữa, search, sẽ không còn được hỗ trợ kể từ ngày 15 tháng 11 năm 2020. Giá trị mặc định là playlist.
- Thuộc tính list bắt buộc chứa một 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 listType là playlist, thì thuộc tính list sẽ chỉ định mã 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ã danh sách phát và 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ị 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 còn được 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 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 điểm bắt đầu phát video đầu tiên trong danh sách.

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

Phát video

player.playVideo():Void: Phát video đang được đánh dấu/tải. Trạng thái 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 chỉ được tính vào số lượt xem chính thức của video nếu lượt phát đó đượ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 người chơi cuối cùng sau khi hàm này thực thi sẽ là paused (2) trừ phi người chơi ở trạng thái ended (0) khi hàm được gọi, trong trường hợp này trạng thái người chơi sẽ không thay đổi.

player.stopVideo():Void: Dừng và huỷ tải video hiện tại. Bạn nên dành hàm này cho những trường hợp hiếm hoi khi biết rằng người dùng sẽ không xem video bổ sung trong trình phát. Nếu muốn 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 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, hàm này sẽ để trình phát ở trạng thái paused (2), hàm stopVideo có thể đưa trình phát vào bất kỳ trạng thái không phát nào, bao gồm cả ended (0), paused (2), video cued (5) hoặc unstarted (-1).

player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void

Tua đến một thời điểm đã chỉ định 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 ở trạng thái 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.), thì trình phát sẽ phát video.

Tham số seconds xác định thời điểm người chơi nên tiến lê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 tua đến.
Tham số allowSeekAhead xác định xem trình phát có gửi 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 đang đượ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 của video, sau đó đặt thành true khi người dùng nhả 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 chưa được lưu vào bộ đệm trong video. Khi người dùng nhả nút chuột, trình phát sẽ chuyển đến điểm mong muốn trong video và yêu cầu luồng video mới nếu cần.

Điều khiển chế độ phát video 360°

Lưu ý: Trải nghiệm phát video 360 độ 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 và không có cách nào được hỗ trợ để thay đổi góc nhìn, bao gồm cả thông qua API, sử dụng cảm biến hướng hoặc phản hồi các 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 hoặc chế độ xem 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 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 các 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`	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 thành phần hiển thị để hướng sang trái hoặc phải hơn. Vị trí trung lập, hướng về trung tâm của video trong phép chiếu hình chữ nhật đồng dạng, biểu thị 0° và giá trị này tăng lên khi người xem xoay sang trái.
`pitch`	Một số trong phạm vi [-90, 90] biểu thị góc dọc của thành phần hiển thị theo độ, phản ánh mức độ người dùng điều chỉnh thành phần hiển thị để nhìn lên hoặc xuống. Vị trí trung lập, hướng về trung tâm của video trong phép chiếu hình chữ nhật đồng dạng, thể hiện góc 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] biểu thị góc xoay theo chiều kim đồng hồ hoặc ngược chiều kim đồng hồ của thành phần hiển thị theo độ. Vị trí trung lập, với trục ngang trong phép chiếu hình chữ nhật đồng đều song song với trục ngang của thành phần hiển thị, biểu thị 0°. Giá trị này tăng lên khi thành phần hiển thị xoay theo chiều kim đồng hồ và giảm khi thành phần hiển thị xoay ngược chiều kim đồng hồ. Xin lưu ý rằng trình phát được nhúng không hiển thị giao diện người dùng để điều chỉnh độ nghiêng của thành phần hiển thị. Bạn có thể điều chỉnh cuộn theo một trong hai cách loại trừ lẫn nhau sau: Sử dụng cảm biến hướng trong trình duyệt di động để cung cấp độ nghiêng 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 độ nghiêng thành một giá trị khác 0 bằng API này.
`fov`	Một số trong phạm vi [30, 120] biểu thị trường nhìn của thành phần hiển thị theo độ, đượ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 theo tỷ lệ khung hình của thành phần hiển thị. Giá trị mặc định là 100 độ. Việc giảm giá trị này giống như việc phóng to nội dung video và tăng giá trị này giống như việc thu nhỏ. Bạn có thể điều chỉnh giá trị này bằng cách sử dụng API hoặc bằng cách sử dụng 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 hình cầu, thì phương thức này sẽ không hoạt động bất kể dữ liệu đầu vào là gì.)

Khung hiển thị 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 các giá trị của mọi thuộc tính đã biết trong đối tượng properties. Khung hiển thị sẽ lưu giữ các giá trị cho 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 video 360° không được hỗ trợ trên một số 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 chế độ phát video 360 độ. Hãy xem thuộc tính enableOrientationSensor ở bên dưới để biết thêm thông tin chi tiết.

Đối tượng properties được truyền vào 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ợ.Một giá trị boolean cho biết liệu tính năng nhúng IFrame có nên phản hồi các sự kiện báo hiệu 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 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` cho việc 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`, thì chuyển động của thiết bị không ảnh hưởng đến trải nghiệm xem 360° và bạn phải đặt tất cả thuộc tính `yaw`, `pitch`, `roll` và `fov` thông 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 mộ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 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 được đặt thành 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 đặt chế độ 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 trong khi người dùng đang xem video đầu tiên trong danh sách phát và danh sách phát được đặt thành 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 người dùng đ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ẽ 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 dựa trên 0, vì vậy, giá trị 0 sẽ xác định video đầu tiên trong danh sách. Nếu bạn đã đánh ngẫu nhiên danh sách phát, thì hàm này sẽ phát video ở vị trí đã chỉ định trong danh sách phát đã đánh 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 trình phát.

player.isMuted():Boolean: Trả về true nếu trình phát bị tắt tiếng, false nếu khô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 trình phát, một số nguyên trong khoảng từ 0 đến 100. Xin 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 tính 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 độ phát đó sẽ chỉ thay đổi đối với video đã được đánh dấu hoặc đang phát. Nếu bạn đặt tốc độ phát cho một video được đánh dấu, tốc độ đó vẫn sẽ 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, việc gọi các hàm để phát hoặc tải video hoặc danh sách phát (cueVideoById, loadVideoById, v.v.) sẽ đặt lại tốc độ phát thành 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à mã đã gọi hàm setPlaybackRate.

Phương thức getAvailablePlaybackRates sẽ trả về các tốc độ phát có thể có cho video đang phát. Tuy nhiên, nếu bạn đặt tham số suggestedRate thành một giá trị số nguyên hoặc số thực không được hỗ trợ, thì 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ó trong 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 này trả về một mảng các số được sắp xếp 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, thì 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

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

Chế độ cài đặt này sẽ vẫn tồn tại ngay cả khi bạn tải hoặc đưa một danh sách phát khác vào danh sách chờ. Tức là nếu bạn tải một danh sách phát, gọi hàm setLoop với giá trị là true, sau đó tải một 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 xác định hành vi lặp lại.

Nếu giá trị tham 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 danh sách phát đó.
Nếu giá trị thông số là false, thì quá trình 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

Hàm này cho biết liệu các video trong danh sách phát có được xáo trộ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, danh sách sẽ được sắp xếp lại trong khi video đang phát vẫn tiếp tục phát. Sau đó, video 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 tồn tại nếu bạn tải hoặc phá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 một danh sách phát thứ hai, thì danh sách phát thứ hai sẽ không được phát ngẫu nhiên.

Tham số shufflePlaylist bắt buộc cho biết liệu 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ẽ xáo trộn thứ tự danh sách phát. Nếu bạn hướng dẫn hàm phát ngẫu nhiên một danh sách phát đã được phát ngẫu nhiên, YouTube sẽ phát ngẫu nhiên lại thứ tự.
Nếu giá trị tham 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 đã lưu vào bộ đệm. Phương thức này trả về một con 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 người chơ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 – lưu vào bộ đệm
5 – video được đánh dấu

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: Ngừng hoạt động kể từ ngày 31 tháng 10 năm 2012. Trả về số 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.) Ví dụ: người dùng tua đến một điểm chưa tải và trình phát tạo một yêu cầu mới để phát một đoạn video chưa tải.

player.getVideoBytesLoaded():Number: Ngừng hoạt động 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 đã được lưu vào bộ đệm.

Phương thức này trả về một giá trị nằm trong khoảng từ 0 đến 1000, gần đúng với lượng video đã tải. Bạn có thể tính toán tỷ lệ phần trăm video đã tải bằng cách chia giá trị getVideoBytesLoaded cho giá trị getVideoBytesTotal.

player.getVideoBytesTotal():Number: Ngừng hoạt động 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 đã được lưu vào bộ đệm.

Trả về kích thước tính bằng byte của video đang tải/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 toán tỷ lệ phần trăm video đã tải bằng cách chia giá trị getVideoBytesLoaded cho giá trị getVideoBytesTotal.

Đang 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 tải siêu dữ liệu của video. Quá trình này thường diễn ra ngay sau khi video bắt đầu phát.

Nếu video đang phát là một sự kiện phát trực tiếp, thì hàm getDuration() sẽ trả về thời gian đã trôi qua kể từ khi luồng video phát trực tiếp bắt đầu. Cụ thể, đây là khoảng thời gian video được phát trực tuyến mà không bị đặt lại hoặc bị 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 tuyến có thể bắt đầu trước thời gian bắt đầu sự kiện.

player.getVideoUrl():String: Trả về URL YouTube.com của video đang tải/đang phát.

player.getVideoEmbedCode():String: Trả về mã nhúng cho video đang tải/đang phát.

Đang 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ự 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 xáo trộn danh sách phát, thì giá trị trả về sẽ cho biết vị trí mà nhà sáng tạo danh sách phát đã đặt video đó. Giá trị trả về sử dụng chỉ mục bắt đầu từ 0, vì vậy, giá trị 0 sẽ xác định video đầu tiên trong danh sách phát.
Nếu bạn đã xáo trộn danh sách phát, thì giá trị trả về sẽ xác định thứ tự của video trong danh sách phát đã xáo 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 bên dưới xác định các sự kiện 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á 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 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 của bạn 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ý 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 từng 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 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 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 nhất định, 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ụ bên dưới 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ó thuộc tính target giúp xác định 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 là 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 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 (lưu vào bộ đệm)
5 (video được đánh dấu).

Trong lần đầu tiên tải video, trình phát sẽ truyền sự kiện unstarted (-1). Khi một video được đánh dấu và sẵn sàng phát, trình phát sẽ truyền phát một sự kiện video cued (5). Trong mã, bạn có thể chỉ định các giá trị số nguyên hoặc sử dụng một trong các biến có 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 kích hoạt bất cứ khi nào chất lượng phát video thay đổi. Điều này có thể báo hiệu sự 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ề các yếu tố ảnh hưởng đến điều kiện phát hoặc có thể kích hoạt sự kiện.

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 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 được 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 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ố nhận dạng 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 đang được phát hoặc đang chờ phát.

onError

Sự kiện này sẽ 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 – Không thể phát nội dung được yêu cầu trong trình phát HTML5 hoặc đã xảy ra 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 một 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. Đây chỉ là lỗi 101 ngụy 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 có các phương thức API được hiển thị. Ứng dụng của bạn có thể nghe sự kiện này, sau đó thăm dò ý kiến người chơi để xác định những tuỳ chọn nào được hiển thị cho mô-đun mới 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 truy xuất một mảng tên mô-đun mà bạn có thể đặt 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. Mô-đun này xử lý phụ đề 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 để xác định những tuỳ chọn có thể được đặt cho mô-đun captions:

player.getOptions('captions');

Bằng cách thăm dò ý kiến 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 truy xuất và cập nhật các 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	Phương thức	Mô tả
phụ đề	fontSize	Tuỳ 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`. Việc đặt tuỳ chọn này thành một số nguyên dưới `-1` sẽ hiển thị kích thước phụ đề nhỏ nhất, trong khi việc đặt tuỳ chọn này thành một số nguyên trên `3` sẽ hiển thị kích thước phụ đề lớn nhất.
phụ đề	tải lại	Lựa 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 kích hoạt bất cứ khi nào trình duyệt chặn 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 thử 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 trình duyệt đều có cá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 một số điều kiện nhất định được đáp ứng. Các trường hợp có thể kích hoạt chính sách này bao gồm việc phát không tắ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 đặt Chính sách quyền để cho phép tự động phát trên iframe trên nhiều nguồn gốc.

Để biết thông tin đầy đủ, 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 về tính năng 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, phần tử <iframe> trên trang đã xác định trình phát sẽ sử dụng API. Xin lưu ý rằng URL src của trình phát 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 sẽ thay đổi màu đườ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 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 xanh lục khi trình phát đang phát, màu đỏ khi tạm dừng, màu xanh dương khi đang 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 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 thành 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 thiết lập các thông số của trình phát để tự động phát video khi tải và ẩn các nút điều khiển của trình phát video. Tệp 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 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 nội dung nghe nhìn của WebView Android

YouTube đã mở rộng API Tính toàn vẹn nội dung nghe nhìn của WebView trên Android để cho phép trình phát nội dung nghe nhìn được nhúng, bao gồm cả trình phát YouTube được nhúng trong các ứng dụng Android, 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 một mã ứng dụng được chứng thực đến YouTube. 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 được 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 được 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 danh tính ứng dụng trong API Tính toàn vẹn nội dung nghe nhìn của WebView. Cấu hình hỗ trợ tuỳ chọn chọn không sử dụng.

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

Tải trình phát video

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

Hàm

Hàm xếp hàng

Hàm xếp hàng cho video

Đặt các hàm vào hàng đợi cho danh sách

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

Phát video

Điều khiển chế độ phát video 360°

Phát mộ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

Đang truy xuất thông tin video

Đang 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 nút DOM

Sự kiện

Ví dụ

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

Điều khiển video 360 độ

Tích hợp API Tính toàn vẹn nội dung nghe nhìn của WebView 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

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