YouTube Player API Reference for iframe Embeds

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

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

Panduan ini menjelaskan cara menggunakan IFrame API. Panduan ini mengidentifikasi berbagai jenis peristiwa yang dapat dikirim API dan menjelaskan cara menulis pemroses peristiwa untuk merespons peristiwa tersebut. Bagian ini juga menjelaskan berbagai fungsi JavaScript yang dapat Anda panggil untuk mengontrol pemutar video serta parameter pemutar yang dapat Anda gunakan 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 minimal 200x200 piksel. Jika pemutar menampilkan kontrol, pemutar harus cukup besar untuk menampilkan kontrol sepenuhnya tanpa memperkecil area pandang di bawah ukuran minimum. Sebaiknya pemutar 16:9 memiliki lebar minimal 480 piksel dan tinggi 270 piksel.

Setiap halaman web yang menggunakan IFrame API juga harus menerapkan fungsi JavaScript berikut:

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

Memulai

Contoh halaman HTML di bawah membuat pemutar tersemat yang akan memuat video, memutarnya selama enam detik, lalu menghentikan pemutaran. Komentar bernomor dalam 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>.

    Atau, 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 bahwa kode diambil secara asinkron. (Atribut async 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 dieksekusi segera setelah kode API pemutar didownload. Bagian kode ini menentukan variabel global, player, yang merujuk ke pemutar video yang Anda sematkan, lalu fungsi tersebut akan membuat objek pemutar video.

  4. Fungsi onPlayerReady akan dijalankan saat peristiwa onReady diaktifkan. Dalam contoh ini, fungsi menunjukkan bahwa saat pemutar video siap, pemutar 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 (memutar), pemutar harus diputar selama enam detik, lalu memanggil fungsi stopVideo untuk menghentikan video.

Memuat pemutar video

Setelah kode JavaScript API dimuat, API akan memanggil fungsi onYouTubeIframeAPIReady, pada saat itu Anda dapat membuat objek YT.Player untuk menyisipkan pemutar video di halaman. Cuplikan 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 menentukan parameter berikut:

  1. Parameter pertama menentukan elemen DOM atau id 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 pemain. 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 pemutar.
    • playerVars (objek) – Properti objek mengidentifikasi parameter pemutar yang dapat digunakan untuk menyesuaikan pemutar.
    • events (objek) – Properti objek mengidentifikasi peristiwa yang dipicu 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 fungsi onPlayerStateChange akan dieksekusi saat peristiwa onStateChange diaktifkan.

Seperti yang disebutkan di bagian Memulai, Anda dapat membuat tag <iframe> sendiri, bukan menulis elemen <div> kosong di halaman, yang kemudian akan diganti dengan elemen <iframe> oleh kode JavaScript API pemutar. 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 pemain, yang ditentukan di 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, menyertakannya akan melindungi dari JavaScript pihak ketiga berbahaya yang dimasukkan ke halaman Anda dan membajak kontrol pemutar YouTube Anda.

Untuk contoh lain tentang cara membuat objek pemutar video, lihat Contoh.

Operasi

Untuk memanggil metode API pemain, Anda harus mendapatkan referensi ke objek pemain yang ingin dikontrol terlebih dahulu. 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 satu parameter dan menentukan properti objek untuk argumen fungsi yang ingin Anda tetapkan. Selain itu, API dapat mendukung fungsi tambahan yang tidak didukung sintaksis argumen.

Misalnya, fungsi loadVideoById dapat dipanggil dengan salah satu cara berikut. Perhatikan bahwa sintaksis objek mendukung properti endSeconds, yang tidak didukung oleh 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 resource video menentukan ID.
  • Parameter startSeconds opsional menerima float/bilangan bulat dan menentukan waktu mulai pemutaran video saat playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemain akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video diberi isyarat dan siap diputar, pemutar akan menyiarkan peristiwa video cued (5).
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/bilangan bulat dan menentukan waktu saat 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 resource video menentukan ID.
  • Parameter startSeconds opsional menerima float/bilangan bulat. Jika ditentukan, video akan dimulai dari keyframe terdekat ke waktu yang ditentukan.
  • Parameter endSeconds opsional menerima float/bilangan bulat. Jika ditentukan, video akan berhenti diputar pada 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 float/bilangan bulat dan menentukan waktu mulai pemutaran video saat playVideo() dipanggil. Jika Anda menentukan startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video diberi isyarat dan siap diputar, pemutar akan menyiarkan peristiwa video cued (5).
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/bilangan bulat dan menentukan waktu saat 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 float/bilangan bulat dan menentukan waktu mulai pemutaran video. Jika startSeconds (angka dapat berupa float) ditentukan, video akan dimulai dari keyframe terdekat ke waktu yang ditentukan.
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/bilangan bulat dan menentukan waktu saat video harus berhenti diputar.

Membuat antrean fungsi 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 berfungsi secara berbeda bergantung pada apakah fungsi tersebut dipanggil menggunakan sintaksis argumen atau sintaksis objek, kedua metode panggilan didokumentasikan di bawah.

cuePlaylist

  • Sintaksis argumen

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
     Menambahkan playlist yang ditentukan ke antrean. Saat playlist diputar dan siap diputar, pemutar akan menyiarkan peristiwa 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 float/bilangan bulat dan menentukan waktu mulai pemutaran video pertama dalam playlist saat fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemain 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 mengantrekan daftar hasil penelusuran tidak digunakan lagi dan tidak akan didukung lagi mulai 15 November 2020.

    Saat daftar diberi isyarat dan siap diputar, pemutar akan menyiarkan peristiwa 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 resource video menentukan ID video.
      • Jika nilai properti listType adalah user_uploads, properti list akan mengidentifikasi pengguna yang video yang diuploadnya 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 float/bilangan bulat dan menentukan waktu mulai pemutaran video pertama dalam daftar saat fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemain 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 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 float/bilangan bulat dan menentukan waktu mulai pemutaran 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 resource video menentukan ID video.
      • Jika nilai properti listType adalah user_uploads, properti list akan mengidentifikasi pengguna yang video yang diuploadnya 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 float/bilangan bulat dan menentukan waktu mulai pemutaran video pertama dalam daftar.

Kontrol pemutaran dan setelan pemutar

Memutar video

player.playVideo():Void
Memutar video yang saat ini diputar/dimuat. Status pemutar akhir setelah fungsi ini dieksekusi 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 pemain akhir setelah fungsi ini dieksekusi akan menjadi paused (2) kecuali jika pemain berada dalam status ended (0) saat fungsi dipanggil, dalam hal ini status pemain tidak akan berubah.
player.stopVideo():Void
Menghentikan dan membatalkan pemuatan video saat ini. Fungsi ini harus dicadangkan untuk situasi yang jarang terjadi saat Anda tahu bahwa pengguna tidak akan menonton video tambahan di pemutar. Jika niat Anda adalah menjeda video, Anda hanya perlu memanggil fungsi pauseVideo. Jika ingin mengubah video yang diputar pemutar, Anda dapat memanggil salah satu fungsi antrean tanpa memanggil stopVideo terlebih dahulu.

Penting: Tidak seperti fungsi pauseVideo, yang membuat pemutar tetap dalam status paused (2), fungsi stopVideo dapat menempatkan pemutar ke status tidak diputar, termasuk ended (0), paused (2), video cued (5), atau unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Mencari ke waktu yang ditentukan dalam video. Jika 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 yang harus dilalui pemain.

    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 dalam video. Saat pengguna melepaskan tombol mouse, pemutar akan maju ke titik yang diinginkan dalam video dan meminta streaming video baru jika diperlukan.

Mengontrol pemutaran video 360°

Catatan: Pengalaman pemutaran video 360° memiliki dukungan terbatas di perangkat seluler. Pada perangkat yang tidak didukung, video 360° akan 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 sferis.
  • Jika video saat ini bukan video 360° atau jika fungsi dipanggil dari perangkat yang tidak didukung, fungsi akan menampilkan objek kosong.
  • Pada 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 berisi properti berikut:
Properti
yaw Angka dalam rentang [0, 360) yang mewakili sudut horizontal tampilan dalam derajat, yang mencerminkan sejauh mana pengguna memutar tampilan untuk menghadap lebih ke kiri atau kanan. Posisi netral, yang menghadap ke tengah video dalam proyeksi ekuadrangular, mewakili 0°, dan nilai ini meningkat saat penonton berbelok ke 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 tengah video dalam proyeksi ekuadrangular, mewakili 0°, dan nilai ini meningkat saat penonton melihat ke atas.
roll Angka dalam rentang [-180, 180] yang mewakili sudut rotasi searah jarum jam atau berlawanan arah jarum jam dari tampilan dalam derajat. Posisi netral, dengan sumbu horizontal dalam proyeksi ekuadrangular yang sejajar dengan sumbu horizontal tampilan, mewakili 0°. Nilainya meningkat saat tampilan diputar searah jarum jam dan menurun saat tampilan diputar berlawanan arah jarum jam.

Perhatikan bahwa pemutar sematan tidak menampilkan antarmuka pengguna untuk menyesuaikan roll tampilan. Roll dapat disesuaikan dengan salah satu cara berikut yang saling eksklusif:
  1. Gunakan sensor orientasi di browser seluler untuk memberikan roll untuk tampilan. Jika sensor orientasi diaktifkan, fungsi getSphericalProperties akan selalu menampilkan 0 sebagai nilai properti roll.
  2. Jika sensor orientasi dinonaktifkan, tetapkan roll ke nilai non-nol menggunakan API ini.
fov Angka dalam rentang [30, 120] yang mewakili bidang pandang tampilan dalam derajat seperti yang diukur di sepanjang tepi yang lebih panjang dari area pandang. Sisi yang lebih pendek akan otomatis disesuaikan agar sebanding dengan rasio aspek tampilan.

Nilai defaultnya adalah 100 derajat. Menurunkan nilainya seperti memperbesar konten video, dan menaikkan nilainya seperti memperkecil. Nilai ini dapat disesuaikan dengan menggunakan API atau dengan menggunakan roda mouse saat video dalam mode layar penuh.
player.setSphericalProperties(properties:Object):Void
Menetapkan orientasi video untuk pemutaran video 360°. (Jika video saat ini tidak berbentuk bulat, metode ini tidak akan berfungsi, terlepas dari inputnya.)

Tampilan pemutar merespons panggilan ke metode ini dengan memperbarui 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 terduga, pemutar akan mengabaikannya.
  • Seperti yang disebutkan di awal bagian ini, pengalaman pemutaran video 360° tidak didukung di semua perangkat seluler.
  • Secara default, di perangkat seluler yang didukung, fungsi ini hanya menetapkan properti fov dan tidak memengaruhi properti yaw, pitch, dan roll untuk pemutaran video 360°. Lihat properti enableOrientationSensor di bawah untuk mengetahui 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 hanya memengaruhi pengalaman menonton 360° di perangkat yang didukung.Nilai boolean yang menunjukkan apakah penyematan IFrame harus merespons peristiwa yang menandakan perubahan pada orientasi perangkat yang didukung, seperti DeviceOrientationEvent browser seluler. Nilai parameter default-nya adalah true.

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

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

Memutar video di playlist

player.nextVideo():Void
Fungsi ini memuat dan memutar video berikutnya di 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
Mbisukan pemutar.
player.unMute():Void
Membunyikan audio pemutar.
player.isMuted():Boolean
Menampilkan true jika pemutar dibisukan, false jika tidak.
player.setVolume(volume:Number):Void
Menetapkan 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.

Menetapkan ukuran pemutar

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

Menetapkan kecepatan 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 menetapkan kecepatan pemutaran yang disarankan untuk video saat ini. Jika kecepatan pemutaran berubah, perubahan tersebut hanya akan berlaku untuk video yang sudah diputar atau sedang diputar. Jika Anda menetapkan kecepatan pemutaran untuk video yang diberi isyarat, kecepatan tersebut akan tetap berlaku saat fungsi playVideo dipanggil atau pengguna memulai pemutaran langsung melalui kontrol pemutar. Selain itu, memanggil fungsi untuk memberi isyarat 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 tersebut, bukan fakta bahwa kode tersebut memanggil fungsi setPlaybackRate.

Metode getAvailablePlaybackRates akan menampilkan kemungkinan kecepatan pemutaran untuk video yang sedang diputar. Namun, jika Anda menetapkan parameter suggestedRate ke nilai bilangan bulat atau float yang tidak didukung, pemutar akan membulatkan nilai tersebut ke bawah ke nilai terdekat yang didukung dalam 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 dengan 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 minimal satu nilai (1).

Menetapkan perilaku pemutaran untuk playlist

player.setLoop(loopPlaylists:Boolean):Void

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

Setelan ini akan tetap ada meskipun Anda memuat atau memicu playlist lain, yang berarti jika Anda memuat playlist, memanggil fungsi setLoop dengan nilai true, lalu memuat playlist kedua, playlist kedua juga akan diputar berulang.

Parameter loopPlaylists yang diperlukan mengidentifikasi perilaku looping.

  • Jika nilai parameternya adalah true, pemutar video akan terus memutar playlist. Setelah memutar video terakhir dalam playlist, pemutar video akan kembali ke 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 agar diputar dalam urutan yang berbeda dengan urutan yang ditetapkan oleh pembuat playlist. Jika Anda mengacak playlist setelah playlist tersebut mulai diputar, daftar akan diurutkan ulang saat 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 mengantrekan playlist lain, yang berarti jika Anda memuat playlist, memanggil fungsi setShuffle, lalu memuat playlist kedua, playlist kedua tidak akan diacak.

Parameter shufflePlaylist yang diperlukan menunjukkan apakah YouTube harus mengacak playlist atau tidak.

  • Jika nilai parameternya adalah true, YouTube akan mengacak urutan playlist. Jika Anda menginstruksikan fungsi untuk mengacak playlist yang sudah 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 pemutar sebagai di-buffer. Metode ini menampilkan angka yang lebih andal daripada metode getVideoBytesLoaded dan getVideoBytesTotal yang sekarang tidak digunakan lagi.
player.getPlayerState():Number
Menampilkan status pemutar. Kemungkinan nilainya adalah:
  • -1 – belum dimulai
  • 0 – berakhir
  • 1 – sedang diputar
  • 2 – dijeda
  • 3 – buffering
  • 5 – video diberi isyarat
player.getCurrentTime():Number
Menampilkan waktu yang telah 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 ke 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 telah di-buffer.

Metode ini menampilkan nilai antara 0 dan 1000 yang mendekati jumlah video yang telah dimuat. Anda dapat menghitung fraksi 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 telah di-buffer.

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

Metode ini selalu menampilkan nilai 1000. Anda dapat menghitung fraksi 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 peristiwa live, fungsi getDuration() akan menampilkan waktu yang telah berlalu sejak streaming video live dimulai. Secara khusus, ini adalah jumlah waktu video di-streaming tanpa direset atau terganggu. Selain itu, durasi ini biasanya lebih lama dari waktu acara sebenarnya karena streaming dapat dimulai sebelum waktu mulai acara.
player.getVideoUrl():String
Menampilkan URL YouTube.com untuk video yang sedang dimuat/diputar.
player.getVideoEmbedCode():String
Menampilkan kode sematan untuk video yang sedang dimuat/diputar.

Mengambil informasi playlist

player.getPlaylist():Array
Fungsi ini menampilkan array ID video dalam playlist sesuai urutan saat ini. Secara default, fungsi ini akan menampilkan ID video dalam urutan yang ditetapkan oleh pemilik playlist. Namun, jika Anda telah memanggil fungsi setShuffle untuk mengacak urutan playlist, nilai yang ditampilkan 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 yang ditampilkan akan mengidentifikasi posisi tempat kreator playlist menempatkan video. Nilai yang ditampilkan menggunakan indeks berbasis nol, sehingga nilai 0 mengidentifikasi video pertama dalam playlist.

  • Jika Anda telah mengacak playlist, nilai yang ditampilkan 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 diaktifkan pemain. Pemroses adalah string yang menentukan fungsi yang akan dieksekusi saat 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 dieksekusi 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.

Acara

API memicu peristiwa untuk memberi tahu aplikasi Anda tentang perubahan pada pemutar tersemat. Seperti yang 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 peristiwa.
  • data peristiwa menentukan nilai yang relevan dengan peristiwa. Perhatikan bahwa peristiwa onReady dan onAutoplayBlocked tidak menentukan properti data.

Daftar berikut menentukan peristiwa yang dipicu API:

onReady
Peristiwa ini dipicu setiap kali pemutar selesai dimuat dan siap untuk mulai menerima panggilan API. Aplikasi Anda harus mengimplementasikan fungsi ini jika Anda ingin menjalankan operasi tertentu secara otomatis, 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 sedang 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 diaktifkan setiap kali status pemutar 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 (belum dimulai)
  • 0 (berakhir)
  • 1 (memutar)
  • 2 (dihentikan sebentar)
  • 3 (buffering)
  • 5 (video diberi isyarat).

Saat pertama kali memuat video, pemutar akan menyiarkan peristiwa unstarted (-1). Saat video diberi isyarat dan siap diputar, pemutar akan menyiarkan peristiwa 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 diaktifkan setiap kali kualitas pemutaran video berubah. Hal ini mungkin menandakan perubahan pada lingkungan pemutaran penonton. Lihat Pusat Bantuan YouTube untuk mengetahui informasi selengkapnya tentang faktor yang memengaruhi kondisi pemutaran atau yang dapat menyebabkan peristiwa diaktifkan.

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

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

onPlaybackRateChange
Peristiwa ini diaktifkan 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 mengasumsikan bahwa kecepatan pemutaran akan otomatis berubah 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 dari objek peristiwa yang diteruskan API ke fungsi pemroses peristiwa akan berupa angka yang mengidentifikasi kecepatan pemutaran baru. Metode getAvailablePlaybackRates menampilkan daftar kecepatan pemutaran yang valid untuk video yang sedang diputar atau di-cue.
onError
Peristiwa ini dipicu jika terjadi error di 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 menentukan 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 error lain yang terkait dengan pemutar HTML5 telah terjadi.
  • 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 tersebut diputar di pemutar tersemat.
  • 150 – Error ini sama dengan 101. Ini hanyalah error 101 yang menyamar.
onApiChange
Peristiwa ini diaktifkan untuk menunjukkan bahwa pemutar telah memuat (atau membongkar muatan) modul dengan metode API yang diekspos. Aplikasi Anda dapat memproses peristiwa ini, lalu melakukan polling pada pemutar untuk menentukan opsi mana yang ditampilkan 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 gunakan untuk menetapkan opsi pemutar:
player.getOptions();
 Saat ini, satu-satunya modul yang dapat Anda tetapkan opsinya adalah modul captions, yang menangani teks tertutup di pemutar. Setelah menerima peristiwa onApiChange, aplikasi Anda dapat menggunakan perintah berikut untuk menentukan opsi yang dapat ditetapkan untuk modul captions:
player.getOptions('captions');
 Dengan melakukan polling pada pemutar dengan perintah ini, Anda dapat mengonfirmasi bahwa opsi yang ingin diakses 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 mencantumkan opsi yang didukung API:

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

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

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

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

Contoh

Membuat objek YT.Player

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

    Dalam contoh ini, elemen <iframe> di halaman sudah menentukan pemutar yang akan digunakan API. Perhatikan bahwa URL src pemutar 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 siap. Fungsi onPlayerStateChange kemudian mengubah warna batas di sekitar pemutar berdasarkan status pemutar saat ini. Misalnya, warnanya hijau saat pemutar 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 1280x720 piksel. 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 untuk memutar video secara otomatis saat dimuat dan menyembunyikan kontrol pemutar video. Class 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>

Integrasi Android WebView Media Integrity API

YouTube telah memperluas Android WebView Media Integrity API untuk mengaktifkan pemutar media tersemat, termasuk penyematan pemutar YouTube di aplikasi Android, guna memverifikasi keaslian aplikasi penyematan. Dengan perubahan ini, aplikasi penyematan akan otomatis mengirimkan ID aplikasi yang diautentikasi ke YouTube. Data yang dikumpulkan melalui penggunaan API ini adalah metadata aplikasi (nama paket, nomor versi, dan sertifikat penandatanganan) serta token pengesahan perangkat yang dihasilkan oleh layanan Google Play.

Data ini digunakan untuk memverifikasi integritas aplikasi dan perangkat. Data ini dienkripsi, tidak dibagikan kepada pihak ketiga, dan dihapus setelah periode retensi data tetap. Developer aplikasi dapat mengonfigurasi identitas aplikasi mereka di WebView Media Integrity API. Konfigurasi mendukung opsi keikutsertaan.

Histori revisi

June 24, 2024

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

November 20, 2023

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

April 27, 2021

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

October 13, 2020

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

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

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

October 24, 2019

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

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

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

May 16, 2018

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

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

This example demonstrates and lets you test these new features.

June 19, 2017

This update contains the following changes:

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

August 11, 2016

This update contains the following changes:

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

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

June 29, 2016

This update contains the following changes:

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

June 24, 2016

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

January 6, 2016

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

December 18, 2015

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

April 28, 2014

This update contains the following changes:

March 25, 2014

This update contains the following changes:

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

July 23, 2013

This update contains the following changes:

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

October 31, 2012

This update contains the following changes:

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

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

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

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

August 22, 2012

This update contains the following changes:

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

August 6, 2012

This update contains the following changes:

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

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

    • Functions

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

    • Events

July 19, 2012

This update contains the following changes:

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

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

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

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

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

July 16, 2012

This update contains the following changes:

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

June 6, 2012

This update contains the following changes:

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

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

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

March 30, 2012

This update contains the following changes:

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

March 26, 2012

This update contains the following changes:

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