YouTube Player API Reference for iframe Embeds

API pemutar IFrame memungkinkan Anda menyematkan pemutar video YouTube di situs web 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. API 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 yang disematkan harus memiliki area pandang yang berukuran setidaknya 200 x 200 piksel. Jika pemutar menampilkan kontrol, kontrol tersebut 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 mengimplementasikan fungsi JavaScript berikut:

  • onYouTubeIframeAPIReady – API akan memanggil fungsi ini saat halaman selesai mendownload JavaScript untuk API pemutar, 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, 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> dengan id untuk memastikan API menempatkan <iframe> di lokasi yang tepat. Secara khusus, IFrame API akan menggantikan 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 kode tersebut diambil secara asinkron. (Atribut async tag <script>, yang juga mengaktifkan 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 membuat objek pemutar video.

  4. Fungsi onPlayerReady akan dijalankan saat peristiwa onReady diaktifkan. Dalam contoh ini, fungsi menunjukkan bahwa pemutar video akan siap diputar setelah siap.

  5. API akan memanggil fungsi onPlayerStateChange saat status pemain berubah, yang mungkin menunjukkan bahwa pemutar sedang diputar, dijeda, selesai, dan seterusnya. Fungsi ini menunjukkan bahwa jika status pemutar adalah 1 (diputar), 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, sehingga 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 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 menggantikan 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 ini 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. Pada contoh, konstruktor menunjukkan bahwa fungsi onPlayerReady akan dieksekusi saat peristiwa onReady aktif dan bahwa fungsi onPlayerStateChange akan dieksekusi saat peristiwa onStateChange diaktifkan.

Seperti yang disebutkan di bagian Memulai, alih-alih menulis elemen <div> kosong di halaman Anda, yang akan diganti dengan kode JavaScript API pemain 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 di URL src. Sebagai tindakan 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, termasuk melindungi dari JavaScript pihak ketiga yang berbahaya yang dimasukkan ke halaman Anda dan kontrol pembajakan pemutar YouTube Anda.

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

Operasional

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 pada dokumen ini.

Functions

Fungsi antrean

Fungsi antrean dapat digunakan untuk memuat dan memutar video, playlist, atau daftar video lainnya. Jika Anda 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 berbeda untuk memanggil fungsi antrean.

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

  • Sintaksis objek memungkinkan Anda meneruskan objek sebagai parameter tunggal dan menentukan properti objek untuk argumen fungsi yang ingin ditetapkan. Selain itu, API ini mungkin 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 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 sampai 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 dari mana video harus mulai diputar saat playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video ditandai dan siap diputar, pemutar akan menyiarkan peristiwa video cued (5).
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/integer 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 yang terdekat dengan waktu yang ditentukan.
  • Parameter endSeconds opsional menerima float/bilangan bulat. Jika sudah 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 sampai 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 dari mana video harus mulai diputar saat playVideo() dipanggil. Jika Anda menentukan startSeconds, lalu memanggil seekTo(), maka pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video diberi tanda dan siap diputar, pemutar akan menyiarkan peristiwa video cued (5).
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/integer 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 dari mana video harus mulai diputar. Jika startSeconds (angka dapat berupa float) ditentukan, video akan dimulai dari keyframe terdekat hingga waktu yang ditentukan.
  • Parameter endSeconds opsional, yang hanya didukung dalam sintaksis objek, menerima float/integer dan menentukan waktu saat video harus berhenti diputar.

Fungsi antrean untuk daftar

Fungsi cuePlaylist dan loadPlaylist memungkinkan Anda untuk memuat dan memutar playlist. Jika Anda menggunakan sintaksis objek untuk memanggil fungsi ini, Anda juga dapat memasukkan (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 ini.

cuePlaylist

  • Sintaksis argumen

    player.cuePlaylist(playlist:String|Array,
                   index:Number,
                   startSeconds:Number):Void
    Mengantrekan playlist yang ditentukan. Saat playlist ditandai 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 defaultnya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam playlist.

    • Parameter startSeconds opsional menerima float/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 mengisyaratkan playlist, lalu memanggil fungsi playVideoAt(), pemutar tersebut 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 ini 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 tanda 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 defaultnya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam daftar.

    • Properti startSeconds opsional menerima float/bilangan bulat dan menentukan waktu dari mana video pertama dalam daftar harus mulai diputar ketika fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Jika Anda mengisyaratkan 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 defaultnya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam playlist.

    • Parameter startSeconds opsional menerima float/bilangan bulat dan menentukan waktu dari mana video pertama dalam playlist harus mulai diputar.

  • Sintaksis objek

    player.loadPlaylist({list:String,
                     listType:String,
                     index:Number,
                     startSeconds:Number}):Void
    Fungsi ini memuat daftar yang ditentukan dan memutarnya. Daftar ini 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 defaultnya adalah 0, sehingga perilaku default-nya adalah memuat dan memutar video pertama dalam daftar.

    • Properti startSeconds opsional menerima float/bilangan bulat dan menentukan waktu dari mana video pertama dalam daftar harus mulai diputar.

Kontrol pemutaran dan setelan pemutar

Memutar video

player.playVideo():Void
Memutar video yang sedang/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 pemutar akhir setelah fungsi ini dieksekusi adalah paused (2) kecuali jika pemutar 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 jika Anda mengetahui bahwa pengguna tidak akan menonton video tambahan di pemutar. Jika Anda ingin menjeda video, Anda cukup memanggil fungsi pauseVideo. Jika ingin mengubah video yang sedang diputar oleh pemutar, Anda dapat memanggil salah satu fungsi antrean tanpa memanggil stopVideo terlebih dahulu.

Penting: Berbeda dengan fungsi pauseVideo, yang membuat pemain dalam status paused (2), fungsi stopVideo dapat mengubah status pemutar menjadi tidak diputar, termasuk ended (0), paused (2), video cued (5) atau unstarted (-1).
player.seekTo(seconds:Number, allowSeekAhead:Boolean):Void
Mencari waktu tertentu 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 untuk melanjutkan pemutar.

    Pemutar akan maju ke bingkai utama terdekat sebelum waktu tersebut, kecuali jika pemutar sudah 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 Anda menyetel parameter ini ke false saat pengguna menarik mouse di sepanjang status progres video, lalu menyetelnya ke true saat pengguna melepaskan mouse. Dengan pendekatan ini, pengguna dapat men-scroll ke titik video yang berbeda tanpa meminta streaming video baru dengan men-scroll melewati titik yang tidak buffering dalam video. Saat pengguna melepaskan tombol mouse, pemutar 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 menonton sama sekali, termasuk melalui API, menggunakan sensor orientasi, atau merespons tindakan sentuh/tarik di layar perangkat.

player.getSphericalProperties():Object
Mengambil properti yang menjelaskan perspektif penonton, atau tampilan, 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.
  • Pada perangkat seluler yang didukung, jika properti enableOrientationSensor ditetapkan ke true, fungsi ini akan menampilkan objek yang berisi properti fov yang berisi nilai yang benar dan properti lain yang ditetapkan ke 0.
Objek tersebut berisi properti berikut:
Properti
yaw Angka dalam rentang [0, 360) yang mewakili sudut horizontal tampilan dalam derajat, yang mencerminkan sejauh mana pengguna mengubah tampilan untuk menghadap ke kiri atau kanan. Posisi netral, menghadap ke tengah video dalam proyeksi equirectangular, 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 bawah. Posisi netral, menghadap ke tengah video dalam proyeksi equirectangular, 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 equirectangular sejajar dengan sumbu horizontal tampilan, mewakili 0°. Nilai ini akan meningkat saat tampilan berputar searah jarum jam dan menurun saat tampilan berputar berlawanan arah jarum jam.

Perhatikan bahwa pemutar sematan tidak menampilkan antarmuka pengguna untuk menyesuaikan tampilan. Roll dapat disesuaikan dengan salah satu cara yang saling eksklusif ini:
  1. Gunakan sensor orientasi di browser seluler untuk menyediakan rotasi tampilan. Jika sensor orientasi diaktifkan, fungsi getSphericalProperties selalu menampilkan 0 sebagai nilai properti roll.
  2. Jika sensor orientasi dinonaktifkan, setel nilai ke nilai bukan nol menggunakan API ini.
fov Angka dalam rentang [30, 120] yang mewakili ruang pandang dalam derajat seperti yang diukur di sepanjang tepi area pandang yang lebih panjang. Tepi yang lebih pendek secara otomatis disesuaikan dengan rasio lebar tinggi tampilan.

Nilai defaultnya adalah 100 derajat. Menurunkan nilai itu seperti memperbesar konten video, dan meningkatkan nilainya 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
Menetapkan orientasi video untuk pemutaran video 360°. (Jika video saat ini tidak bulat, metodenya adalah tanpa pengoperasian terlepas dari input.)

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

Selain itu:
  • Jika objek berisi properti yang tidak diketahui dan/atau tidak terduga, pemain akan mengabaikannya.
  • Seperti yang disebutkan di awal bagian ini, pengalaman pemutaran video 360° tidak didukung di semua perangkat seluler.
  • Secara default, pada 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-nya adalah true.

Perangkat seluler yang didukung
  • Jika nilainya true, pemutar tersemat hanya bergantung pada gerakan perangkat untuk menyesuaikan properti yaw, pitch, dan roll untuk pemutaran video 360°. Namun, properti fov masih 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, maka pergerakan perangkat tidak memengaruhi pengalaman menonton 360°, dan 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 dalam playlist

player.nextVideo():Void
Fungsi ini memuat dan memutar video berikutnya di playlist.

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

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

player.previousVideo():Void
Fungsi ini memuat dan memutar video sebelumnya di playlist.

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

  • Jika player.previousVideo() dipanggil saat video pertama dalam playlist ditonton, dan playlist tidak disetel untuk terus diputar, 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 akan mengidentifikasi video pertama dalam daftar. Jika Anda telah mengacak playlist, fungsi ini akan memutar video pada posisi yang ditentukan di playlist yang diacak.

Mengubah volume pemutar

player.mute():Void
Membisukan audio pemutar.
player.unMute():Void
Membunyikan audio pemain.
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 pemain saat ini, bilangan bulat antara 0 dan 100. Perlu diketahui 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 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 menyetel rasio pemutaran yang disarankan untuk video saat ini. Jika kecepatan pemutaran berubah, kecepatan pemutaran hanya akan berubah untuk video yang telah diproses atau sedang diputar. Jika Anda menetapkan kecepatan pemutaran untuk video bertanda, rasio tersebut akan tetap berlaku saat fungsi playVideo dipanggil atau pengguna memulai pemutaran langsung melalui kontrol pemutar. Selain itu, memanggil fungsi untuk menandai atau memuat video atau playlist (cueVideoById, loadVideoById, dll.) akan mereset kecepatan pemutaran ke 1.

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

Metode getAvailablePlaybackRates akan menampilkan kemungkinan rasio 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 ke arah 1.
player.getAvailablePlaybackRates():Array
Fungsi ini menampilkan serangkaian rasio pemutaran yang menyediakan video saat ini. Nilai defaultnya adalah 1, yang menunjukkan bahwa video diputar dalam kecepatan normal.

Fungsi ini menampilkan array angka yang diurutkan dari kecepatan pemutaran paling lambat ke yang paling cepat. 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 apakah akan berhenti diputar setelah video terakhir dalam playlist berakhir. Perilaku defaultnya adalah playlist tidak melakukan loop.

Setelan ini akan tetap ada meskipun Anda memuat atau menandai playlist lain, yang berarti bahwa jika Anda memuat playlist, panggil fungsi setLoop dengan nilai true, lalu muat playlist kedua, playlist kedua juga akan diputar ulang.

Parameter loopPlaylists yang diperlukan mengidentifikasi perilaku loop.

  • Jika nilai parameternya 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 agar diputar dalam urutan yang berbeda dengan urutan yang ditentukan oleh kreator playlist. Jika Anda mengacak playlist setelah mulai diputar, daftar tersebut 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 menandai playlist yang berbeda, yang berarti jika Anda memuat playlist, panggil fungsi setShuffle, lalu muat playlist kedua, playlist kedua tidak akan diacak.

Parameter shufflePlaylist yang diperlukan menunjukkan apakah YouTube harus mengacak playlist.

  • Jika nilai parameternya adalah true, YouTube akan mengacak urutan playlist. Jika Anda memerintahkan fungsi untuk mengacak playlist yang telah diacak, YouTube akan mengacak urutannya 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 pemain sebagai buffering. Metode ini menampilkan angka yang lebih andal daripada metode getVideoBytesLoaded dan getVideoBytesTotal yang sekarang tidak digunakan lagi.
player.getPlayerState():Number
Menampilkan status pemutar. Nilai yang memungkinkan adalah:
  • -1 – belum dimulai
  • 0 – berakhir
  • 1 – sedang diputar
  • 2 – dijeda
  • 3 – buffering
  • 5 – tanda video
player.getCurrentTime():Number
Menampilkan waktu yang berlalu dalam detik sejak video mulai diputar.
player.getVideoStartBytes():Number
Tidak digunakan lagi mulai 31 Oktober 2012. Menampilkan jumlah byte dari file video yang mulai dimuat. (Metode ini sekarang selalu menampilkan nilai 0.) Contoh skenario: pengguna mengarah 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 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 telah di-buffer.

Menampilkan ukuran dalam byte dari video yang saat ini 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 dalam detik video yang sedang diputar. Perlu diperhatikan bahwa getDuration() akan menampilkan 0 hingga metadata video dimuat, yang biasanya terjadi tepat setelah video mulai diputar.

Jika video yang sedang diputar adalah acara live, fungsi getDuration() akan menampilkan waktu berlalu sejak streaming video live dimulai. Secara khusus, ini adalah jumlah waktu streaming video tanpa direset atau terganggu. Selain itu, durasi ini biasanya lebih lama daripada waktu acara yang 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 dimuat/diputar saat ini.

Mengambil informasi playlist

player.getPlaylist():Array
Fungsi ini menampilkan array ID video dalam playlist sesuai urutannya. 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 fungsi getPlaylist() akan mencerminkan urutan yang diacak.
player.getPlaylistIndex():Number
Fungsi ini menampilkan indeks video playlist yang sedang diputar.

  • Jika Anda tidak mengacak playlist, nilai yang ditampilkan akan mengidentifikasi posisi pembuat video dalam menempatkan video. Nilai yang ditampilkan menggunakan indeks berbasis nol, sehingga nilai 0 akan 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 dijalankan lagi saat peristiwa yang ditentukan diaktifkan.

Mengakses dan memodifikasi node DOM

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

Peristiwa

API mengaktifkan 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 argumen tunggal 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 tidak menentukan properti data.

Daftar berikut menentukan peristiwa yang diaktifkan API:

onReady
Peristiwa ini dipicu setiap kali pemain selesai memuat dan siap mulai menerima panggilan API. Aplikasi harus menerapkan 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 fungsi contoh 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 dalam 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 dipicu setiap kali status pemutar berubah. Properti data dari 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 (sedang diputar)
  • 2 (dihentikan sebentar)
  • 3 (buffering)
  • 5 (tanda video).

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 dapat menggunakan salah satu variabel namespace berikut:

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

onPlaybackQualityChange
Peristiwa ini dipicu setiap kali kualitas pemutaran video berubah. Hal ini mungkin menandakan perubahan dalam lingkungan pemutaran penonton. Buka Pusat Bantuan YouTube untuk mengetahui informasi lebih lanjut tentang faktor yang memengaruhi kondisi pemutaran atau yang mungkin menyebabkan peristiwa diaktifkan.

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

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

onPlaybackRateChange
Peristiwa ini dipicu 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 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 objek peristiwa yang diteruskan API ke fungsi pemroses peristiwa adalah angka yang mengidentifikasi kecepatan pemutaran yang baru. Metode getAvailablePlaybackRates menampilkan daftar rasio pemutaran yang valid untuk video yang saat ini ditetapkan atau diputar.
onError
Peristiwa ini dipicu 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 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 terjadi error lain terkait pemutar HTML5.
  • 100 – Video yang diminta tidak ditemukan. Error ini terjadi saat video telah dihapus (karena alasan apa pun) atau telah ditandai sebagai pribadi.
  • 101 – Pemilik video yang diminta tidak mengizinkan video tersebut untuk diputar di pemutar tersemat.
  • 150 – Error ini sama dengan 101. Hanya kesalahan 101 yang disamarkan!
onApiChange
Peristiwa ini diaktifkan 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 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 opsi pemutarnya dapat Anda tetapkan:
player.getOptions();
Saat ini, satu-satunya modul yang dapat Anda setel 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 disetel untuk modul captions:
player.getOptions('captions');
Dengan melakukan polling pada pemain 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 ini mencantumkan opsi yang didukung API:

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

Nilai yang valid adalah -1, 0, 1, 2, dan 3. Ukuran default-nya adalah 0, dan yang terkecil adalah -1. Menyetel 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.
captions muat ulang Opsi ini akan memuat ulang data teks tertutup untuk video yang sedang diputar. Nilainya adalah null jika Anda mengambil nilai opsi. Setel nilai ke true untuk memuat ulang data teks tertutup.

Pertimbangan Seluler

Putar Otomatis dan Pemutaran Bernaskah

Elemen <video> HTML5, di browser seluler tertentu (seperti Chrome dan Safari), hanya memungkinkan pemutaran yang terjadi jika dimulai oleh interaksi pengguna (seperti mengetuk pemutar). Berikut adalah kutipan dari dokumentasi Apple:

"Peringatan: Untuk mencegah download yang tidak diinginkan melalui jaringan seluler atas biaya pengguna, media tersemat tidak dapat diputar secara otomatis di Safari pada iOS — pengguna selalu memulai pemutaran."

Karena batasan ini, fungsi dan parameter seperti autoplay, playVideo(), loadVideoById() tidak akan berfungsi di semua lingkungan seluler.

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. Perlu diketahui bahwa URL src pemain harus menetapkan parameter enablejsapi ke 1 atau atribut enablejsapi elemen <iframe> harus disetel ke true.

    Fungsi onPlayerReady mengubah warna batas di sekitar pemutar menjadi oranye saat pemutar siap. Fungsi onPlayerStateChange kemudian mengubah warna batas di sekeliling pemutar berdasarkan status pemutar saat ini. Misalnya, warna 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 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. API ini juga menambahkan pemroses peristiwa untuk beberapa peristiwa yang disiarkan oleh 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

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.