YouTube Player API Reference for iframe Embeds

API pemutar IFrame memungkinkan Anda menyematkan pemutar video YouTube di situs dan mengontrol pemutar menggunakan JavaScript.

Dengan menggunakan fungsi JavaScript API, Anda dapat membuat antrean video untuk pemutaran; memutar, menjeda, atau menghentikan video tersebut; menyesuaikan volume pemutar; atau mendapatkan informasi tentang video yang sedang diputar. Anda juga dapat menambahkan pemroses peristiwa yang akan dieksekusi sebagai respons terhadap peristiwa pemain tertentu, seperti perubahan status pemutar.

Panduan ini menjelaskan cara menggunakan API IFrame. Ini mengidentifikasi berbagai jenis peristiwa yang dapat dikirim API dan menjelaskan cara menulis pemroses peristiwa untuk merespons peristiwa tersebut. Panduan ini juga menjelaskan berbagai fungsi JavaScript yang dapat Anda panggil untuk mengontrol pemutar video serta parameter pemutar yang dapat digunakan untuk menyesuaikan pemutar lebih lanjut.

Persyaratan

Browser pengguna harus mendukung fitur postMessage HTML5. Sebagian besar browser modern mendukung postMessage.

Pemutar tersemat harus memiliki area pandang yang berukuran minimal 200 x 200 piksel. Jika pemutar menampilkan kontrol, pemutar harus cukup besar untuk menampilkan kontrol sepenuhnya tanpa mengecilkan area pandang di bawah ukuran minimum. Sebaiknya pemutar berukuran 16:9 berukuran minimal lebar 480 piksel dan tinggi 270 piksel.

Laman web apa pun yang menggunakan IFrame API juga harus menerapkan fungsi JavaScript berikut:

  • onYouTubeIframeAPIReady – API akan memanggil fungsi ini setelah halaman selesai mendownload JavaScript untuk player API, yang memungkinkan Anda menggunakan API di halaman Anda. Dengan demikian, fungsi ini dapat membuat objek pemutar yang ingin Anda tampilkan saat halaman dimuat.

Memulai

Contoh halaman HTML di bawah membuat pemutar tersemat yang akan memuat video, memutarnya selama enam detik, kemudian menghentikan pemutaran. Komentar bernomor pada HTML dijelaskan dalam daftar di bawah contoh.

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

Daftar berikut memberikan detail selengkapnya tentang contoh di atas:

  1. Tag <div> di bagian ini mengidentifikasi lokasi di halaman tempat IFrame API akan menempatkan pemutar video. Konstruktor untuk objek pemutar, yang dijelaskan di bagian Memuat pemutar video, mengidentifikasi tag <div> berdasarkan id-nya untuk memastikan bahwa API menempatkan <iframe> di lokasi yang tepat. Secara khusus, IFrame API akan mengganti tag <div> dengan tag <iframe>.

    Sebagai alternatif, Anda juga dapat menempatkan elemen <iframe> langsung di halaman. Bagian Memuat pemutar video menjelaskan cara melakukannya.

  2. Kode di bagian ini memuat kode JavaScript IFrame Player API. Contoh ini menggunakan modifikasi DOM untuk mendownload kode API guna memastikan kode diambil secara asinkron. (Atribut async milik tag <script>, yang juga memungkinkan download asinkron, belum didukung di semua browser modern seperti yang dibahas dalam jawaban Stack Overflow ini.

  3. Fungsi onYouTubeIframeAPIReady akan dijalankan segera setelah kode API pemutar didownload. Bagian dari kode ini menentukan variabel global, player, yang mengacu pada pemutar video yang Anda sematkan, dan fungsi tersebut kemudian membuat objek pemutar video.

  4. Fungsi onPlayerReady akan dieksekusi saat peristiwa onReady diaktifkan. Dalam contoh ini, fungsi tersebut menunjukkan bahwa saat pemutar video sudah siap, pemutar video akan mulai diputar.

  5. API akan memanggil fungsi onPlayerStateChange saat status pemutar berubah, yang dapat menunjukkan bahwa pemutar sedang diputar, dijeda, selesai, dan sebagainya. Fungsi ini menunjukkan bahwa saat status pemutar adalah 1 (diputar), pemutar akan diputar selama enam detik, lalu memanggil fungsi stopVideo untuk menghentikan video.

Memuat pemutar video

Setelah kode JavaScript API dimuat, API akan memanggil fungsi onYouTubeIframeAPIReady, yang pada saat itu Anda dapat membuat objek YT.Player untuk menyisipkan pemutar video di halaman Anda. Kutipan HTML di bawah menunjukkan fungsi onYouTubeIframeAPIReady dari contoh di atas:

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

Konstruktor untuk pemutar video menetapkan parameter berikut:

  1. Parameter pertama menentukan elemen DOM atau id dari elemen HTML tempat API akan menyisipkan tag <iframe> yang berisi pemutar.

    IFrame API akan mengganti elemen yang ditentukan dengan elemen <iframe> yang berisi pemutar. Hal ini dapat memengaruhi tata letak halaman Anda jika elemen yang diganti memiliki gaya tampilan yang berbeda dengan elemen <iframe> yang disisipkan. Secara default, <iframe> ditampilkan sebagai elemen inline-block.

  2. Parameter kedua adalah objek yang menentukan opsi pemutar. Objek berisi properti berikut:
    • width (angka) – Lebar pemutar video. Nilai defaultnya adalah 640.
    • height (angka) – Tinggi pemutar video. Nilai defaultnya adalah 390.
    • videoId (string) – ID video YouTube yang mengidentifikasi video yang akan dimuat oleh pemutar.
    • playerVars (objek) – Properti objek mengidentifikasi parameter pemutar yang dapat digunakan untuk menyesuaikan pemutar.
    • events (objek) – Properti objek mengidentifikasi peristiwa yang diaktifkan API dan fungsi (pemroses peristiwa) yang akan dipanggil API saat peristiwa tersebut terjadi. Dalam contoh, konstruktor menunjukkan bahwa fungsi onPlayerReady akan dieksekusi saat peristiwa onReady diaktifkan dan bahwa fungsi onPlayerStateChange akan dieksekusi saat peristiwa onStateChange diaktifkan.

Seperti yang disebutkan di bagian Memulai, daripada menulis elemen <div> kosong di halaman Anda, yang kemudian akan diganti oleh kode JavaScript API pemutar dengan elemen <iframe>, Anda dapat membuat tag <iframe> sendiri. Contoh pertama di bagian Contoh menunjukkan cara melakukannya.

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

Perhatikan bahwa jika Anda menulis tag <iframe>, saat membuat objek YT.Player, Anda tidak perlu menentukan nilai untuk width dan height, yang ditentukan sebagai atribut tag <iframe>, atau parameter videoId dan pemutar, yang ditentukan dalam URL src. Sebagai langkah keamanan tambahan, Anda juga harus menyertakan parameter origin ke URL, yang menentukan skema URL (http:// atau https://) dan domain lengkap halaman host Anda sebagai nilai parameter. Meskipun origin bersifat opsional, menyertakan hal ini akan melindungi dari injeksi JavaScript pihak ketiga berbahaya yang dimasukkan ke halaman Anda dan kontrol pembajakan pemutar YouTube Anda.

Bagian Contoh juga menampilkan beberapa contoh lain untuk membuat objek pemutar video.

Operasi

Untuk memanggil metode API pemutar, Anda harus terlebih dahulu mendapatkan referensi ke objek pemutar yang ingin dikontrol. Anda mendapatkan referensi dengan membuat objek YT.Player seperti yang dibahas di bagian Memulai dan Memuat pemutar video dalam dokumen ini.

Fungsi

Fungsi antrean

Fungsi antrean memungkinkan Anda memuat dan memutar video, playlist, atau daftar video lainnya. Jika menggunakan sintaksis objek yang dijelaskan di bawah untuk memanggil fungsi ini, Anda juga dapat mengantrekan atau memuat daftar video yang diupload pengguna.

API ini mendukung dua sintaksis yang berbeda untuk memanggil fungsi antrean.

  • Sintaksis argumen mengharuskan argumen fungsi dicantumkan dalam urutan yang ditentukan.

  • Sintaksis objek memungkinkan Anda meneruskan objek sebagai parameter tunggal dan menentukan properti objek untuk argumen fungsi yang ingin Anda tetapkan. Selain itu, API dapat mendukung fungsi tambahan yang tidak didukung oleh sintaksis argumen.

Misalnya, fungsi loadVideoById dapat dipanggil dengan salah satu cara berikut. Perhatikan bahwa sintaksis objek mendukung properti endSeconds, yang tidak didukung sintaksis argumen.

  • Sintaksis argumen

    loadVideoById("bHQqvYy5KYo", 5, "large")
  • Sintaksis objek

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

Fungsi antrean untuk video

cueVideoById
  • Sintaksis argumen

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

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

Fungsi ini memuat thumbnail video yang ditentukan dan menyiapkan pemutar untuk memutar video. Pemutar tidak meminta FLV hingga playVideo() atau seekTo() dipanggil.

  • Parameter videoId yang diperlukan menentukan ID Video YouTube dari video yang akan diputar. Di YouTube Data API, properti id dari resource video menentukan ID.
  • Parameter startSeconds opsional menerima bilangan bulat/float dan menentukan waktu mulai diputarnya video saat playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Setelah video diberi sinyal dan siap diputar, pemutar akan menyiarkan acara video cued (5).
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/bilangan bulat dan menentukan waktu kapan video harus berhenti diputar saat playVideo() dipanggil. Jika Anda menentukan nilai endSeconds, lalu memanggil seekTo(), nilai endSeconds tidak akan berlaku lagi.

loadVideoById

  • Sintaksis argumen

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

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

Fungsi ini memuat dan memutar video yang ditentukan.

  • Parameter videoId yang diperlukan menentukan ID Video YouTube dari video yang akan diputar. Di YouTube Data API, properti id dari resource video menentukan ID.
  • Parameter startSeconds opsional menerima bilangan bulat/float. Jika ditentukan, video akan dimulai dari keyframe yang terdekat dengan waktu yang ditentukan.
  • Parameter endSeconds opsional menerima bilangan bulat/float. Jika ditentukan, video akan berhenti diputar pada jangka waktu yang ditentukan.

cueVideoByUrl

  • Sintaksis argumen

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

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

Fungsi ini memuat thumbnail video yang ditentukan dan menyiapkan pemutar untuk memutar video. Pemutar tidak meminta FLV hingga playVideo() atau seekTo() dipanggil.

  • Parameter mediaContentUrl yang diperlukan menentukan URL pemutar YouTube yang sepenuhnya memenuhi syarat dalam format http://www.youtube.com/v/VIDEO_ID?version=3.
  • Parameter startSeconds opsional menerima bilangan bulat/float dan menentukan waktu mulai diputarnya video saat playVideo() dipanggil. Jika Anda menentukan startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video diberi sinyal dan siap diputar, pemutar akan menyiarkan acara video cued (5).
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/bilangan bulat dan menentukan waktu kapan video harus berhenti diputar saat playVideo() dipanggil. Jika Anda menentukan nilai endSeconds, lalu memanggil seekTo(), nilai endSeconds tidak akan berlaku lagi.

loadVideoByUrl

  • Sintaksis argumen

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

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

Fungsi ini memuat dan memutar video yang ditentukan.

  • Parameter mediaContentUrl yang diperlukan menentukan URL pemutar YouTube yang sepenuhnya memenuhi syarat dalam format http://www.youtube.com/v/VIDEO_ID?version=3.
  • Parameter startSeconds opsional menerima bilangan bulat/bilangan bulat dan menentukan waktu mulai diputarnya video. Jika startSeconds (angka dapat berupa float) ditentukan, video akan dimulai dari keyframe yang terdekat hingga waktu yang ditentukan.
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima bilangan bulat/bilangan bulat dan menentukan waktu berhenti diputarnya video.

Fungsi antrean untuk daftar

Fungsi cuePlaylist dan loadPlaylist memungkinkan Anda memuat dan memutar playlist. Jika menggunakan sintaksis objek untuk memanggil fungsi ini, Anda juga dapat mengantrekan (atau memuat) daftar video yang diupload pengguna.

Karena fungsi bekerja secara berbeda bergantung pada apakah fungsi dipanggil menggunakan sintaksis argumen atau sintaksis objek, kedua metode pemanggilan didokumentasikan di bawah ini.

cuePlaylist
  • Sintaksis argumen

    player.cuePlaylist(playlist:String|Array,
                       index:Number,
                       startSeconds:Number):Void
    Mengantrekan playlist yang ditentukan. Saat playlist diberi sinyal dan siap diputar, pemutar akan menyiarkan acara video cued (5).
    • Parameter playlist yang diperlukan menentukan array ID video YouTube. Di YouTube Data API, properti id resource video mengidentifikasi ID video tersebut.

    • Parameter index opsional menentukan indeks video pertama dalam playlist yang akan diputar. Parameter ini menggunakan indeks berbasis nol, dan nilai parameter default-nya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam playlist.

    • Parameter startSeconds opsional menerima bilangan bulat/bilangan bulat dan menentukan waktu dari mana video pertama dalam playlist harus mulai diputar saat fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Jika Anda memberi isyarat playlist, lalu memanggil fungsi playVideoAt(), pemutar akan mulai diputar di awal video yang ditentukan.

  • Sintaksis objek

    player.cuePlaylist({listType:String,
                        list:String,
                        index:Number,
                        startSeconds:Number}):Void
    Mengantrekan daftar video yang ditentukan. Daftar tersebut dapat berupa playlist atau feed video yang diupload pengguna. Kemampuan untuk memasukkan daftar hasil penelusuran ke dalam antrean tidak digunakan lagi dan tidak akan didukung lagi mulai 15 November 2020.

    Setelah daftar diberi sinyal dan siap diputar, pemutar akan menyiarkan acara video cued (5).

    • Properti listType opsional menentukan jenis feed hasil yang Anda ambil. Nilai yang valid adalah playlist dan user_uploads. Nilai yang tidak digunakan lagi, search, tidak akan didukung lagi mulai 15 November 2020. Nilai defaultnya adalah playlist.

    • Properti list yang diperlukan berisi kunci yang mengidentifikasi daftar video tertentu yang harus ditampilkan YouTube.

      • Jika nilai properti listType adalah playlist, properti list akan menentukan ID playlist atau array ID video. Di YouTube Data API, properti id resource playlist mengidentifikasi ID playlist, dan properti id pada resource video menentukan ID video.
      • Jika nilai properti listType adalah user_uploads, properti list mengidentifikasi pengguna yang video yang diupload akan ditampilkan.
      • Jika nilai properti listType adalah search, properti list akan menentukan kueri penelusuran. Catatan: Fungsi ini tidak digunakan lagi dan tidak akan didukung lagi mulai 15 November 2020.

    • Properti index opsional menentukan indeks video pertama dalam daftar yang akan diputar. Parameter ini menggunakan indeks berbasis nol, dan nilai parameter default-nya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam daftar.

    • Properti startSeconds opsional menerima bilangan bulat/bilangan bulat dan menentukan waktu dari mana video pertama dalam daftar harus mulai diputar saat fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Jika Anda memberi isyarat daftar, lalu memanggil fungsi playVideoAt(), pemutar akan mulai diputar di awal video yang ditentukan.

loadPlaylist
  • Sintaksis argumen

    player.loadPlaylist(playlist:String|Array,
                        index:Number,
                        startSeconds:Number):Void
    Fungsi ini memuat playlist yang ditentukan dan memutarnya.
    • Parameter playlist yang diperlukan menentukan array ID video YouTube. Di YouTube Data API, properti id dari resource video menentukan ID video.

    • Parameter index opsional menentukan indeks video pertama dalam playlist yang akan diputar. Parameter ini menggunakan indeks berbasis nol, dan nilai parameter default-nya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam playlist.

    • Parameter startSeconds opsional menerima bilangan bulat/bilangan bulat dan menentukan waktu mulai diputarnya video pertama dalam playlist.

  • Sintaksis objek

    player.loadPlaylist({list:String,
                         listType:String,
                         index:Number,
                         startSeconds:Number}):Void
    Fungsi ini memuat daftar yang ditentukan dan memutarnya. Daftar tersebut dapat berupa playlist atau feed video yang diupload pengguna. Kemampuan untuk memuat daftar hasil penelusuran tidak digunakan lagi dan tidak akan didukung lagi mulai 15 November 2020.
    • Properti listType opsional menentukan jenis feed hasil yang Anda ambil. Nilai yang valid adalah playlist dan user_uploads. Nilai yang tidak digunakan lagi, search, tidak akan didukung lagi mulai 15 November 2020. Nilai defaultnya adalah playlist.

    • Properti list yang diperlukan berisi kunci yang mengidentifikasi daftar video tertentu yang harus ditampilkan YouTube.

      • Jika nilai properti listType adalah playlist, properti list akan menentukan ID playlist atau array ID video. Di YouTube Data API, properti id resource playlist menentukan ID playlist, dan properti id pada resource video menentukan ID video.
      • Jika nilai properti listType adalah user_uploads, properti list mengidentifikasi pengguna yang video yang diupload akan ditampilkan.
      • Jika nilai properti listType adalah search, properti list akan menentukan kueri penelusuran. Catatan: Fungsi ini tidak digunakan lagi dan tidak akan didukung lagi mulai 15 November 2020.

    • Properti index opsional menentukan indeks video pertama dalam daftar yang akan diputar. Parameter ini menggunakan indeks berbasis nol, dan nilai parameter default-nya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam daftar.

    • Properti startSeconds opsional menerima bilangan bulat/bilangan bulat dan menentukan waktu mulai diputarnya video pertama dalam daftar.

Kontrol pemutaran dan setelan pemutar

Memutar video

player.playVideo():Void
Memutar video yang saat ini sedang dibunyikan/dimuat. Status pemutar akhir setelah fungsi ini dijalankan adalah playing (1).

Catatan: Pemutaran hanya dihitung dalam jumlah penayangan resmi video jika dimulai melalui tombol putar native di pemutar.
player.pauseVideo():Void
Menjeda video yang sedang diputar. Status pemutar terakhir setelah fungsi ini dieksekusi adalah paused (2) kecuali jika pemutar berada dalam status ended (0) saat fungsi dipanggil, dalam hal ini status pemutar tidak akan berubah.
player.stopVideo():Void
Menghentikan dan membatalkan pemuatan video saat ini. Fungsi ini harus dicadangkan untuk situasi yang jarang terjadi ketika Anda tahu bahwa pengguna tidak akan menonton video tambahan di pemutar. Jika tujuan Anda adalah menjeda video, cukup panggil fungsi pauseVideo. Jika ingin mengubah video yang diputar oleh pemutar, Anda dapat memanggil salah satu fungsi antrean tanpa memanggil stopVideo terlebih dahulu.

Penting: Tidak seperti fungsi pauseVideo, yang membuat pemutar berada dalam status paused (2), fungsi stopVideo dapat menempatkan pemain dalam status tidak bermain, termasuk ended (0), paused (2), video cued (5) atau unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Mencari waktu yang ditentukan dalam video. Jika pemutar dijeda saat fungsi dipanggil, pemutar akan tetap dijeda. Jika fungsi dipanggil dari status lain (playing, video cued, dll.), pemutar akan memutar video.
  • Parameter seconds mengidentifikasi waktu saat pemain harus maju.

    Pemutar akan maju ke keyframe terdekat sebelum waktu tersebut, kecuali jika pemutar telah mendownload bagian video yang dicari pengguna.

  • Parameter allowSeekAhead menentukan apakah pemutar akan membuat permintaan baru ke server jika parameter seconds menentukan waktu di luar data video yang saat ini di-buffer.

    Sebaiknya tetapkan parameter ini ke false saat pengguna menarik mouse di sepanjang status progres video, lalu tetapkan ke true saat pengguna melepaskan mouse. Pendekatan ini memungkinkan pengguna men-scroll ke berbagai titik video tanpa meminta streaming video baru dengan men-scroll melewati titik yang tidak di-buffer di video. Saat pengguna melepaskan tombol mouse, pemutar akan maju ke titik yang diinginkan dalam video dan meminta streaming video baru jika perlu.

Mengontrol pemutaran video 360°

Catatan: Pengalaman pemutaran video 360° memiliki dukungan terbatas di perangkat seluler. Pada perangkat yang tidak didukung, video 360° tampak terdistorsi dan tidak ada cara yang didukung untuk mengubah perspektif tampilan sama sekali, termasuk melalui API, menggunakan sensor orientasi, atau merespons tindakan sentuh/tarik di layar perangkat.

player.getSphericalProperties():Object
Mengambil properti yang mendeskripsikan perspektif atau tampilan penonton saat ini untuk pemutaran video. Selain itu:
  • Objek ini hanya diisi untuk video 360°, yang juga disebut video sferikal.
  • Jika video saat ini bukan video 360° atau jika fungsi dipanggil dari perangkat yang tidak didukung, fungsi akan menampilkan objek kosong.
  • Di perangkat seluler yang didukung, jika properti enableOrientationSensor disetel ke true, fungsi ini akan menampilkan objek yang properti fov-nya berisi nilai yang benar dan properti lainnya disetel ke 0.
Objek ini berisi properti berikut:
Properti
yaw Angka dalam rentang [0, 360) yang mewakili sudut horizontal tampilan dalam derajat, yang mencerminkan sejauh mana pengguna memutar tampilan ke menghadap lebih ke kiri atau kanan. Posisi netral, yang menghadap ke bagian tengah video dalam proyeksi equirectangular, mewakili 0°, dan nilai ini akan meningkat saat penonton belok kiri.
pitch Angka dalam rentang [-90, 90] yang mewakili sudut vertikal tampilan dalam derajat, yang mencerminkan sejauh mana pengguna menyesuaikan tampilan untuk melihat ke atas atau ke bawah. Posisi netral, yang menghadap ke bagian tengah video dalam proyeksi equirectangular, mewakili 0°, dan nilai ini akan meningkat saat penonton melihat ke atas.
roll Angka dalam rentang [-180, 180] yang mewakili sudut rotasi tampilan searah jarum jam atau berlawanan arah jarum jam dalam derajat. Posisi netral, dengan sumbu horizontal dalam proyeksi equirectangular yang sejajar dengan sumbu horizontal tampilan, menyatakan 0°. Nilainya akan bertambah saat tampilan diputar searah jarum jam dan menurun saat tampilan diputar berlawanan arah jarum jam.

Perhatikan bahwa pemutar yang disematkan tidak menyediakan antarmuka pengguna untuk menyesuaikan rol tampilan. Rolls dapat disesuaikan dengan salah satu cara yang tidak saling berhubungan berikut ini:
  1. Gunakan sensor orientasi di browser seluler untuk memberikan lemparan pada tampilan. Jika sensor orientasi diaktifkan, fungsi getSphericalProperties akan selalu menampilkan 0 sebagai nilai properti roll.
  2. Jika sensor orientasi dinonaktifkan, tetapkan lemparan ke nilai bukan nol menggunakan API ini.
fov Angka dalam rentang [30, 120] yang mewakili ruang pandang tampilan dalam derajat yang diukur di sepanjang tepi area pandang yang lebih panjang. Tepi yang lebih pendek otomatis disesuaikan agar proporsional dengan rasio aspek tampilan.

Nilai default-nya adalah 100 derajat. Menurunkan nilai seperti memperbesar konten video, dan menambah nilainya sama seperti memperkecil. Nilai ini dapat disesuaikan dengan menggunakan API atau dengan menggunakan roda mouse saat video berada dalam mode layar penuh.
player.setSphericalProperties(properties:Object):Void
Menyetel orientasi video untuk pemutaran video 360°. (Jika video saat ini tidak sferikal, metode ini tidak akan beroperasi, terlepas dari input-nya.)

Tampilan pemutar merespons panggilan ke metode ini dengan mengupdate untuk mencerminkan nilai properti yang diketahui dalam objek properties. Tampilan mempertahankan nilai untuk properti lain yang diketahui yang tidak disertakan dalam objek tersebut.

Selain itu:
  • Jika objek berisi properti yang tidak diketahui dan/atau tidak diharapkan, pemutar akan mengabaikannya.
  • Seperti yang disebutkan di awal bagian ini, pengalaman pemutaran video 360° hanya didukung di perangkat seluler tertentu.
  • Secara default, di perangkat seluler yang didukung, fungsi ini hanya menyetel properti fov dan tidak memengaruhi properti yaw, pitch, dan roll untuk pemutaran video 360°. Lihat properti enableOrientationSensor di bawah untuk detail selengkapnya.
Objek properties yang diteruskan ke fungsi berisi properti berikut:
Properti
yaw Lihat definisi di atas.
pitch Lihat definisi di atas.
roll Lihat definisi di atas.
fov Lihat definisi di atas.
enableOrientationSensor Catatan: Properti ini memengaruhi pengalaman menonton 360° hanya di perangkat yang didukung.Nilai boolean yang menunjukkan apakah sematan IFrame harus merespons peristiwa yang menandakan perubahan dalam orientasi perangkat yang didukung, seperti DeviceOrientationEvent browser seluler. Nilai parameter default adalah true.

Perangkat seluler yang didukung
  • Jika nilainya true, pemutar tersemat hanya bergantung pada gerakan perangkat untuk menyesuaikan properti yaw, pitch, dan roll bagi pemutaran video 360°. Namun, properti fov tetap dapat diubah melalui API, dan API tersebut sebenarnya adalah satu-satunya cara untuk mengubah properti fov di perangkat seluler. Ini merupakan perilaku default.
  • Jika nilainya false, gerakan perangkat tidak akan memengaruhi pengalaman menonton 360°, dan properti yaw, pitch, roll, dan fov harus disetel melalui API.

Perangkat seluler yang tidak didukung
Nilai properti enableOrientationSensor tidak berpengaruh pada pengalaman pemutaran.

Memutar video dalam playlist

player.nextVideo():Void
Fungsi ini memuat dan memutar video berikutnya dalam playlist.
  • Jika player.nextVideo() dipanggil saat video terakhir dalam playlist sedang ditonton, dan playlist disetel untuk diputar secara terus-menerus (loop), pemutar akan memuat dan memutar video pertama dalam daftar.

  • Jika player.nextVideo() dipanggil saat video terakhir dalam playlist sedang ditonton, dan playlist tidak disetel untuk diputar secara terus-menerus, pemutaran akan berakhir.

player.previousVideo():Void
Fungsi ini memuat dan memutar video sebelumnya dalam playlist.
  • Jika player.previousVideo() dipanggil saat video pertama dalam playlist sedang ditonton, dan playlist disetel untuk diputar secara terus-menerus (loop), pemutar akan memuat dan memutar video terakhir dalam daftar.

  • Jika player.previousVideo() dipanggil saat video pertama dalam playlist sedang ditonton, dan playlist tidak disetel untuk diputar secara terus-menerus, pemutar akan memulai ulang video playlist pertama dari awal.

player.playVideoAt(index:Number):Void
Fungsi ini memuat dan memutar video yang ditentukan dalam playlist.
  • Parameter index yang diperlukan menentukan indeks video yang ingin Anda putar di playlist. Parameter ini menggunakan indeks berbasis nol, sehingga nilai 0 mengidentifikasi video pertama dalam daftar. Jika Anda telah mengacak playlist, fungsi ini akan memutar video pada posisi yang ditentukan dalam playlist yang diacak.

Mengubah volume pemutar

player.mute():Void
Membisukan pemutar.
player.unMute():Void
Membunyikan pemutar.
player.isMuted():Boolean
Menampilkan true jika pemutar dibisukan, false jika tidak.
player.setVolume(volume:Number):Void
Menyetel volume. Menerima bilangan bulat antara 0 dan 100.
player.getVolume():Number
Menampilkan volume pemutar saat ini, bilangan bulat antara 0 dan 100. Perhatikan bahwa getVolume() akan menampilkan volume meskipun pemutar dibisukan.

Menyetel ukuran pemutar

player.setSize(width:Number, height:Number):Object
Menetapkan ukuran dalam piksel <iframe> yang berisi pemutar.

Menyetel laju pemutaran

player.getPlaybackRate():Number
Fungsi ini mengambil kecepatan pemutaran video yang sedang diputar. Kecepatan pemutaran default adalah 1, yang menunjukkan bahwa video diputar dengan kecepatan normal. Kecepatan pemutaran dapat mencakup nilai seperti 0.25, 0.5, 1, 1.5, dan 2.
player.setPlaybackRate(suggestedRate:Number):Void
Fungsi ini menyetel kecepatan pemutaran yang disarankan untuk video saat ini. Jika kecepatan pemutaran berubah, itu hanya akan berubah untuk video yang sudah diberi isyarat atau sedang diputar. Jika Anda menyetel laju pemutaran untuk video isyarat, laju tersebut akan tetap berlaku ketika fungsi playVideo dipanggil atau pengguna memulai pemutaran secara langsung melalui kontrol pemutar. Selain itu, memanggil fungsi untuk memberi tanda atau memuat video atau playlist (cueVideoById, loadVideoById, dll.) akan mereset kecepatan pemutaran ke 1.

Memanggil fungsi ini tidak menjamin bahwa kecepatan pemutaran akan benar-benar berubah. Namun, jika kecepatan pemutaran berubah, peristiwa onPlaybackRateChange akan diaktifkan, dan kode Anda harus merespons peristiwa, bukan fakta bahwa peristiwa memanggil fungsi setPlaybackRate.

Metode getAvailablePlaybackRates akan menampilkan kemungkinan laju pemutaran untuk video yang sedang diputar. Namun, jika Anda menetapkan parameter suggestedRate ke nilai bilangan bulat atau nilai float yang tidak didukung, pemutar akan membulatkan nilai tersebut ke nilai terdekat yang didukung ke arah 1.
player.getAvailablePlaybackRates():Array
Fungsi ini menampilkan kumpulan kecepatan pemutaran tempat video saat ini tersedia. Nilai defaultnya adalah 1, yang menunjukkan bahwa video diputar dalam kecepatan normal.

Fungsi ini menampilkan array angka yang diurutkan dari kecepatan pemutaran paling lambat hingga tercepat. Meskipun pemutar tidak mendukung kecepatan pemutaran variabel, array harus selalu berisi setidaknya satu nilai (1).

Menyetel perilaku pemutaran untuk playlist

player.setLoop(loopPlaylists:Boolean):Void

Fungsi ini menunjukkan apakah pemutar video harus terus memutar playlist, atau akan berhenti diputar setelah video terakhir dalam playlist berakhir. Perilaku default-nya adalah playlist tidak diputar berulang.

Setelan ini akan tetap ada meskipun Anda memuat atau memberi isyarat playlist berbeda. Artinya, jika Anda memuat playlist, memanggil fungsi setLoop dengan nilai true, lalu memuat playlist kedua, playlist kedua juga akan diulang.

Parameter loopPlaylists yang diperlukan mengidentifikasi perilaku loop.

  • Jika nilai parameter adalah true, pemutar video akan terus memutar playlist. Setelah memutar video terakhir dalam playlist, pemutar video akan kembali ke bagian awal playlist dan memutarnya lagi.

  • Jika nilai parameternya adalah false, pemutaran akan berakhir setelah pemutar video memutar video terakhir dalam playlist.

player.setShuffle(shufflePlaylist:Boolean):Void

Fungsi ini menunjukkan apakah video playlist harus diacak sehingga dapat diputar kembali dalam urutan yang berbeda dari yang ditentukan oleh kreator playlist. Jika Anda mengacak playlist setelah mulai diputar, daftar akan disusun ulang sementara video yang sedang diputar terus diputar. Video berikutnya yang diputar kemudian akan dipilih berdasarkan daftar yang diurutkan ulang.

Setelan ini tidak akan dipertahankan jika Anda memuat atau memberi isyarat playlist berbeda. Artinya, jika Anda memuat playlist, memanggil fungsi setShuffle, lalu memuat playlist kedua, playlist kedua tidak akan diacak.

Parameter shufflePlaylist yang diperlukan menunjukkan apakah YouTube akan mengacak playlist.

  • Jika nilai parameternya adalah true, YouTube akan mengacak urutan playlist. Jika Anda menginstruksikan fungsi untuk mengacak playlist yang telah diacak, YouTube akan mengacak urutan lagi.

  • Jika nilai parameternya adalah false, YouTube akan mengubah urutan playlist kembali ke urutan aslinya.

Status pemutaran

player.getVideoLoadedFraction():Float
Menampilkan angka antara 0 dan 1 yang menentukan persentase video yang ditampilkan oleh pemutar sebagai buffering. Metode ini menampilkan angka yang lebih andal daripada metode getVideoBytesLoaded dan getVideoBytesTotal yang sudah tidak digunakan lagi.
player.getPlayerState():Number
Mengembalikan status pemutar. Kemungkinan nilainya adalah:
  • -1 – tidak dimulai
  • 0 – berakhir
  • 1 – bermain
  • 2 – dijeda
  • 3 – buffering
  • 5 – sinyal video
player.getCurrentTime():Number
Menampilkan waktu berlalu dalam detik sejak video mulai diputar.
player.getVideoStartBytes():Number
Tidak digunakan lagi mulai 31 Oktober 2012. Menampilkan jumlah byte tempat file video mulai dimuat. (Metode ini sekarang selalu menampilkan nilai 0.) Contoh skenario: pengguna mencari di depan ke titik yang belum dimuat, dan pemutar membuat permintaan baru untuk memutar segmen video yang belum dimuat.
player.getVideoBytesLoaded():Number
Tidak digunakan lagi mulai 18 Juli 2012. Sebagai gantinya, gunakan metode getVideoLoadedFraction untuk menentukan persentase video yang mengalami buffering.

Metode ini menampilkan nilai antara 0 dan 1000 yang memperkirakan jumlah video yang telah dimuat. Anda dapat menghitung bagian video yang telah dimuat dengan membagi nilai getVideoBytesLoaded dengan nilai getVideoBytesTotal.
player.getVideoBytesTotal():Number
Tidak digunakan lagi mulai 18 Juli 2012. Sebagai gantinya, gunakan metode getVideoLoadedFraction untuk menentukan persentase video yang mengalami buffering.

Menampilkan ukuran dalam byte dari video yang sedang dimuat/diputar atau perkiraan ukuran video.

Metode ini selalu menampilkan nilai 1000. Anda dapat menghitung bagian video yang telah dimuat dengan membagi nilai getVideoBytesLoaded dengan nilai getVideoBytesTotal.

Mengambil informasi video

player.getDuration():Number
Menampilkan durasi video yang sedang diputar dalam detik. Perhatikan bahwa getDuration() akan menampilkan 0 hingga metadata video dimuat, yang biasanya terjadi tepat setelah video mulai diputar.

Jika video yang sedang diputar adalah live streaming, fungsi getDuration() akan menampilkan waktu yang berlalu sejak streaming video live dimulai. Secara khusus, ini adalah durasi streaming video tanpa direset atau terganggu. Selain itu, durasi ini biasanya lebih lama daripada waktu acara sebenarnya karena streaming dapat dimulai sebelum waktu mulai acara.
player.getVideoUrl():String
Menampilkan URL YouTube.com untuk video yang saat ini dimuat/diputar.
player.getVideoEmbedCode():String
Menampilkan kode sematan untuk video yang saat ini dimuat/diputar.

Mengambil informasi playlist

player.getPlaylist():Array
Fungsi ini menampilkan array ID video dalam playlist sesuai urutannya saat ini. Secara default, fungsi ini akan menampilkan ID video dalam urutan yang ditentukan oleh pemilik playlist. Namun, jika Anda telah memanggil fungsi setShuffle untuk mengacak urutan playlist, nilai yang ditampilkan dari fungsi getPlaylist() akan mencerminkan urutan yang diacak.
player.getPlaylistIndex():Number
Fungsi ini menampilkan indeks video playlist yang sedang diputar.
  • Jika Anda belum mengacak playlist, nilai hasil akan mengidentifikasi posisi video yang ditempatkan kreator playlist. Nilai hasil menggunakan indeks berbasis nol, sehingga nilai 0 mengidentifikasi video pertama dalam playlist.

  • Jika Anda telah mengacak playlist, nilai hasil akan mengidentifikasi urutan video dalam playlist yang diacak.

Menambahkan atau menghapus pemroses peristiwa

player.addEventListener(event:String, listener:String):Void
Menambahkan fungsi pemroses untuk event yang ditentukan. Bagian Peristiwa di bawah mengidentifikasi berbagai peristiwa yang mungkin dipicu pemain. Pemroses adalah string yang menentukan fungsi yang akan dieksekusi ketika peristiwa yang ditentukan diaktifkan.
player.removeEventListener(event:String, listener:String):Void
Menghapus fungsi pemroses untuk event yang ditentukan. listener adalah string yang mengidentifikasi fungsi yang tidak akan lagi dijalankan saat peristiwa yang ditentukan diaktifkan.

Mengakses dan mengubah node DOM

player.getIframe():Object
Metode ini menampilkan node DOM untuk <iframe> tersemat.
player.destroy():Void
Menghapus <iframe> yang berisi pemutar.

Peristiwa

API memicu peristiwa untuk memberi tahu aplikasi Anda tentang perubahan pada pemutar tersemat. Seperti yang telah disebutkan di bagian sebelumnya, Anda dapat berlangganan peristiwa dengan menambahkan pemroses peristiwa saat membuat objek YT.Player, dan Anda juga dapat menggunakan fungsi addEventListener.

API akan meneruskan objek peristiwa sebagai satu-satunya argumen ke setiap fungsi tersebut. Objek peristiwa memiliki properti berikut:

  • target peristiwa mengidentifikasi pemutar video yang sesuai dengan acara.
  • data peristiwa menentukan nilai yang relevan dengan peristiwa. Perhatikan bahwa peristiwa onReady dan onAutoplayBlocked tidak menentukan properti data.

Daftar berikut menentukan peristiwa yang diaktifkan API:

onReady
Peristiwa ini aktif setiap kali pemain selesai memuat dan siap untuk mulai menerima panggilan API. Aplikasi Anda harus mengimplementasikan fungsi ini jika ingin otomatis menjalankan operasi tertentu, seperti memutar video atau menampilkan informasi tentang video, segera setelah pemutar siap.

Contoh di bawah menunjukkan contoh fungsi untuk menangani peristiwa ini. Objek peristiwa yang diteruskan API ke fungsi memiliki properti target, yang mengidentifikasi pemutar. Fungsi ini mengambil kode sematan untuk video yang saat ini dimuat, mulai memutar video, dan menampilkan kode sematan di elemen halaman yang memiliki nilai 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
Peristiwa ini aktif setiap kali status pemain berubah. Properti data objek peristiwa yang diteruskan API ke fungsi pemroses peristiwa Anda akan menentukan bilangan bulat yang sesuai dengan status pemutar baru. Nilai yang dimungkinkan adalah:

  • -1 (tidak dimulai)
  • 0 (berakhir)
  • 1 (sedang diputar)
  • 2 (dihentikan sebentar)
  • 3 (buffering)
  • 5 (petunjuk video).

Saat pemutar pertama kali memuat video, pemutar akan menyiarkan acara unstarted (-1). Setelah video diberi sinyal dan siap diputar, pemutar akan menyiarkan acara video cued (5). Dalam kode, Anda dapat menentukan nilai bilangan bulat atau menggunakan salah satu variabel dengan namespace berikut:

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

onPlaybackQualityChange
Peristiwa ini aktif setiap kali kualitas pemutaran video berubah. Perubahan ini mungkin menandakan perubahan dalam lingkungan pemutaran penonton. Baca Pusat Bantuan YouTube untuk mengetahui informasi selengkapnya mengenai faktor yang memengaruhi kondisi pemutaran atau yang dapat menyebabkan peristiwa diaktifkan.

Nilai properti data objek peristiwa yang diteruskan API ke fungsi pemroses peristiwa akan menjadi string yang mengidentifikasi kualitas pemutaran baru. Nilai yang dimungkinkan adalah:

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

onPlaybackRateChange
Peristiwa ini aktif setiap kali kecepatan pemutaran video berubah. Misalnya, jika Anda memanggil fungsi setPlaybackRate(suggestedRate), peristiwa ini akan diaktifkan jika kecepatan pemutaran benar-benar berubah. Aplikasi Anda harus merespons peristiwa dan tidak boleh berasumsi bahwa kecepatan pemutaran akan berubah secara otomatis saat fungsi setPlaybackRate(suggestedRate) dipanggil. Demikian pula, kode Anda tidak boleh mengasumsikan bahwa kecepatan pemutaran video hanya akan berubah sebagai hasil dari panggilan eksplisit ke setPlaybackRate.

Nilai properti data objek peristiwa yang diteruskan API ke fungsi pemroses peristiwa akan berupa angka yang mengidentifikasi kecepatan pemutaran baru. Metode getAvailablePlaybackRates akan menampilkan daftar kecepatan pemutaran yang valid untuk video yang sedang diperingatkan atau diputar.
onError
Peristiwa ini aktif jika terjadi error pada pemutar. API akan meneruskan objek event ke fungsi pemroses peristiwa. Properti data objek tersebut akan menentukan bilangan bulat yang mengidentifikasi jenis error yang terjadi. Nilai yang dimungkinkan adalah:

  • 2 – Permintaan berisi nilai parameter yang tidak valid. Misalnya, error ini terjadi jika Anda menetapkan ID video yang tidak memiliki 11 karakter, atau jika ID video berisi karakter yang tidak valid, seperti tanda seru atau tanda bintang.
  • 5 – Konten yang diminta tidak dapat diputar di pemutar HTML5 atau terjadi error lain yang terkait dengan pemutar HTML5.
  • 100 – Video yang diminta tidak ditemukan. Error ini terjadi jika video telah dihapus (karena alasan apa pun) atau telah ditandai sebagai pribadi.
  • 101 – Pemilik video yang diminta tidak mengizinkan video diputar di pemutar tersemat.
  • 150 – Error ini sama dengan 101. Ini hanya error 101 yang disamarkan.
onApiChange
Peristiwa ini dipicu untuk menunjukkan bahwa pemutar telah memuat (atau menghapus muatan) modul dengan metode API yang terekspos. Aplikasi Anda dapat memproses peristiwa ini, lalu melakukan polling pada pemutar untuk menentukan opsi mana yang diekspos untuk modul yang baru dimuat. Aplikasi Anda kemudian dapat mengambil atau memperbarui setelan yang ada untuk opsi tersebut.

Perintah berikut mengambil array nama modul yang dapat Anda tetapkan opsi pemutarnya:
player.getOptions();
Saat ini, satu-satunya modul yang dapat Anda setel opsinya adalah modul captions, yang menangani teks tertutup pada pemutar. Setelah menerima peristiwa onApiChange, aplikasi Anda dapat menggunakan perintah berikut untuk menentukan opsi mana yang dapat disetel untuk modul captions:
player.getOptions('captions');
Dengan melakukan polling pada pemutar menggunakan perintah ini, Anda dapat mengonfirmasi bahwa opsi yang ingin Anda akses memang dapat diakses. Perintah berikut mengambil dan memperbarui opsi modul:
Retrieving an option:
player.getOption(module, option);

Setting an option
player.setOption(module, option, value);
Tabel di bawah ini mencantumkan opsi yang didukung API:

Modul Opsi Deskripsi
captions fontSize Opsi ini menyesuaikan ukuran font teks yang ditampilkan di pemutar.

Nilai yang valid adalah -1, 0, 1, 2, dan 3. Ukuran defaultnya adalah 0, dan ukuran terkecil adalah -1. Menyetel opsi ini ke bilangan bulat di bawah -1 akan menyebabkan ukuran teks terkecil ditampilkan, sedangkan menyetel opsi ini ke bilangan bulat di atas 3 akan menyebabkan ukuran teks terbesar ditampilkan.
captions muat ulang Opsi ini memuat ulang data teks tertutup untuk video yang sedang diputar. Nilainya akan menjadi null jika Anda mengambil nilai opsi. Setel nilai ke true untuk memuat ulang data teks tertutup.
onAutoplayBlocked
Peristiwa ini aktif setiap kali browser memblokir fitur putar otomatis atau pemutaran video dengan skrip, secara kolektif disebut sebagai "putar otomatis". Hal ini mencakup upaya pemutaran dengan salah satu API pemutar berikut:

Sebagian besar browser memiliki kebijakan yang dapat memblokir putar otomatis di lingkungan desktop, seluler, dan lainnya jika kondisi tertentu terpenuhi. Contoh tempat kebijakan ini mungkin dipicu termasuk pemutaran yang dibunyikan tanpa interaksi pengguna, atau saat Kebijakan Izin untuk mengizinkan putar otomatis di iframe lintas origin belum ditetapkan.

Untuk detail selengkapnya, lihat kebijakan khusus browser (Apple Safari / Webkit, Google Chrome, Mozilla Firefox) dan panduan putar otomatis Mozilla.

Contoh

Membuat objek YT.Player

  • Contoh 1: Gunakan API dengan <iframe> yang ada

    Dalam contoh ini, elemen <iframe> di halaman sudah menentukan pemutar yang akan digunakan API. Perhatikan bahwa URL src pemain harus menetapkan parameter enablejsapi ke 1 atau atribut enablejsapi elemen <iframe> harus ditetapkan ke true.

    Fungsi onPlayerReady mengubah warna batas di sekitar pemutar menjadi oranye saat pemutar sudah siap. Fungsi onPlayerStateChange kemudian mengubah warna batas di sekitar pemutar berdasarkan status pemutar saat ini. Misalnya, warnanya hijau saat pemutar sedang diputar, merah saat dijeda, biru saat buffering, dan sebagainya.

    Contoh ini menggunakan kode berikut:

    <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>
    
  • Contoh 2: Pemutaran keras

    Contoh ini membuat pemutar video berukuran 1280px kali 720px. Pemroses peristiwa untuk peristiwa onReady kemudian memanggil fungsi setVolume untuk menyesuaikan volume ke setelan tertinggi.

    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();
    }
    
  • Contoh 3: Contoh ini menetapkan parameter pemutar agar otomatis memutar video saat dimuat dan untuk menyembunyikan kontrol pemutar video. API ini juga menambahkan pemroses peristiwa untuk beberapa peristiwa yang disiarkan API.

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

Mengontrol video 360°

Contoh ini menggunakan kode berikut:

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

Histori revisi

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

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

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

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

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

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

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

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

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

    • Functions

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

    • Events

July 19, 2012

This update contains the following changes:

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

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

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

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

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

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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