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 membuat antrean video untuk diputar, memutar, menjeda, atau menghentikan video tersebut; menyesuaikan volume pemutar; atau mengambil informasi tentang video yang sedang diputar. Anda juga bisa menambahkan pemroses kejadian 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. Halaman 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 berukuran setidaknya 200 x 200 piksel. Jika pemutar menampilkan kontrol, ukuran harus cukup besar agar kontrol dapat ditampilkan sepenuhnya tanpa mengecilkan area pandang di bawah ukuran minimum. Sebaiknya pemutar berukuran 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, sehingga Anda dapat menggunakan API tersebut di halaman. 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 lebih lanjut 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 untuk memastikan bahwa API menempatkan <iframe> di lokasi yang tepat. Secara khusus, IFrame API akan mengganti tag <div> dengan tag <iframe>.

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

  2. Kode di bagian ini memuat kode JavaScript IFrame Player API. Contoh ini menggunakan modifikasi DOM untuk mendownload kode API guna memastikan bahwa kode tersebut diambil secara asinkron. (Atribut async dari 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 mengacu pada pemutar video yang Anda sematkan, dan fungsi tersebut kemudian membuat objek pemutar video.

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

  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 jika status pemutar adalah 1 (sedang 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. 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 pemain yang dapat digunakan untuk menyesuaikan pemutar.
    • events (objek) – Properti objek mengidentifikasi peristiwa yang diaktifkan API dan fungsi (pemroses peristiwa) yang akan dipanggil API saat peristiwa tersebut terjadi. Dalam contoh, konstruktor menunjukkan bahwa fungsi onPlayerReady akan dieksekusi saat peristiwa onReady diaktifkan dan bahwa fungsi onPlayerStateChange akan dieksekusi saat peristiwa onStateChange diaktifkan.

Seperti yang disebutkan di bagian Memulai, Anda dapat membuat tag <iframe> sendiri, bukan menulis elemen <div> kosong di halaman Anda, yang kemudian akan diganti oleh kode JavaScript API pemutar dengan elemen <iframe>. 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 videoId dan parameter pemutar, yang ditentukan di URL src. Sebagai langkah keamanan tambahan, Anda juga harus menyertakan parameter origin ke URL, dengan menentukan skema URL (http:// atau https://) dan domain lengkap halaman host Anda sebagai nilai parameter. Meskipun bersifat opsional, menyertakan origin ini akan melindungi Anda dari masuknya JavaScript pihak ketiga yang berbahaya ke halaman Anda dan kontrol pembajakan pemutar YouTube Anda.

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

Operations

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

Fungsi

Fungsi antrean

Fungsi antrean memungkinkan Anda 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 yang berbeda untuk memanggil fungsi antrean.

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

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

Misalnya, fungsi loadVideoById dapat dipanggil dengan salah satu cara berikut. Perlu diperhatikan 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 diputarnya video saat playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan memutar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video dibaca 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/integer. Jika ditentukan, maka video akan dimulai dari keyframe yang terdekat dengan waktu yang ditentukan.
  • Parameter endSeconds opsional menerima float/integer. Jika sudah ditentukan, maka video akan berhenti diputar pada waktu yang telah 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 diputarnya video saat playVideo() dipanggil. Jika Anda menentukan startSeconds, lalu memanggil seekTo(), pemutar akan diputar dari waktu yang ditentukan dalam panggilan seekTo(). Saat video dibaca 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 mulai pemutaran video. Jika startSeconds (angka dapat berupa float) ditentukan, video akan dimulai dari keyframe yang terdekat dengan 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 memuat dan memutar playlist. Jika menggunakan sintaksis objek untuk memanggil fungsi ini, Anda juga dapat membuat antrean (atau memuat) daftar video yang diupload pengguna.

Karena fungsi bekerja 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 berbunyi dan siap diputar, pemutar akan menyiarkan acara video cued (5).

    • Parameter playlist yang diperlukan menentukan array ID video YouTube. Di YouTube Data API, properti id resource video mengidentifikasi ID video tersebut.

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

    • Parameter startSeconds opsional menerima float/bilangan bulat dan menentukan waktu mulai diputarnya video pertama dalam playlist saat fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan memutar dari waktu yang ditentukan dalam panggilan seekTo(). Jika Anda memberikan isyarat ke 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 berbunyi dan siap diputar, pemutar akan menyiarkan acara video cued (5).

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

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

      • Jika nilai properti listType adalah playlist, properti list menentukan ID playlist atau array ID video. Dalam 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 hasil upload-nya 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 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 diputarnya video pertama dalam daftar saat fungsi playVideo() dipanggil. Jika Anda menentukan nilai startSeconds, lalu memanggil seekTo(), pemutar akan memutar dari waktu yang ditentukan dalam panggilan seekTo(). Jika Anda memberi isyarat ke 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 oleh YouTube.

      • Jika nilai properti listType adalah playlist, properti list 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 hasil upload-nya 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 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 diputarnya video pertama dalam daftar.

Kontrol pemutaran dan setelan pemutar

Memutar video

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

Catatan: Pemutaran hanya akan diperhitungkan 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 akan menjadi paused (2) kecuali jika pemutar berada dalam status ended (0) saat fungsi dipanggil, dalam hal ini status pemutar tidak akan berubah.
player.stopVideo():Void
Menghentikan dan membatalkan pemuatan video saat ini. Fungsi ini seharusnya dicadangkan untuk situasi yang jarang terjadi ketika Anda mengetahui bahwa pengguna tidak akan menonton video tambahan di pemutar. Jika Anda ingin menjeda video, cukup panggil fungsi pauseVideo. Jika ingin mengubah video yang diputar pemutar, Anda dapat memanggil salah satu fungsi antrean tanpa memanggil stopVideo terlebih dahulu.

Penting: Berbeda dengan fungsi pauseVideo, yang membuat pemain berada dalam status paused (2), fungsi stopVideo dapat menempatkan pemutar ke dalam status tidak memutar, 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 saat pemutar harus maju.

    Pemutar akan maju ke keyframe 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 tetapkan parameter ini ke false saat pengguna menarik mouse di sepanjang status progres video, lalu menetapkannya ke true saat pengguna melepaskan mouse. Dengan pendekatan ini, pengguna dapat men-scroll ke bagian lain 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 perlu.

Mengontrol pemutaran video 360°

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

player.getSphericalProperties():Object
Mengambil properti yang mendeskripsikan perspektif atau tampilan penonton saat ini untuk pemutaran video. Selain itu:
  • Objek ini hanya diisi untuk video 360°, yang juga disebut video sferis.
  • Jika video saat ini bukan video 360° atau jika fungsi dipanggil dari perangkat yang tidak didukung, fungsi akan menampilkan objek kosong.
  • Di perangkat seluler yang didukung, jika properti enableOrientationSensor ditetapkan ke true, fungsi ini akan menampilkan objek yang memiliki properti fov berisi nilai yang benar dan properti lainnya ditetapkan 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 ke kiri atau kanan. Posisi netral, menghadap ke bagian tengah video dalam proyeksi equirectangular, menggambarkan 0°, dan nilai ini akan bertambah saat penonton menoleh 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, menghadap ke bagian tengah video dalam proyeksi equirectangular, menggambarkan 0°, dan nilai ini akan bertambah saat penonton melihat ke atas.
roll Angka dalam rentang [-180, 180] yang mewakili sudut rotasi searah jarum jam atau berlawanan arah jarum jam dalam derajat. Posisi netral, dengan sumbu horizontal dalam proyeksi equirectangular yang sejajar dengan sumbu horizontal tampilan, mewakili 0°. Nilainya akan bertambah jika tampilan berputar searah jarum jam dan berkurang jika tampilan diputar berlawanan arah jarum jam.

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

Nilai default-nya adalah 100 derajat. Menurunkan nilai sama seperti memperbesar tampilan konten video, dan meningkatkan nilainya sama halnya dengan memperkecil tampilan. Nilai ini dapat disesuaikan dengan menggunakan API atau dengan menggunakan roda mouse saat video dalam mode layar penuh.
player.setSphericalProperties(properties:Object):Void
Menyetel orientasi video untuk pemutaran video 360°. (Jika video saat ini tidak berbentuk bulat, metode ini akan menjadi tanpa pengoperasian, apa pun inputnya.)

Tampilan pemutar akan merespons panggilan ke metode ini dengan melakukan update untuk mencerminkan nilai properti yang diketahui dalam objek properties. Tampilan ini 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, 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 menetapkan 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 hanya memengaruhi pengalaman tampilan 360° di perangkat yang didukung.Nilai boolean yang menunjukkan apakah sematan IFrame harus merespons peristiwa yang menandakan perubahan dalam orientasi perangkat yang didukung, seperti DeviceOrientationEvent browser seluler. Nilai parameter default adalah true.

Perangkat seluler yang didukung
  • Saat 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 tersebut sebenarnya adalah satu-satunya cara untuk mengubah properti fov di perangkat seluler. Ini merupakan perilaku default.
  • Jika nilainya false, berarti pergerakan perangkat tidak akan memengaruhi pengalaman tampilan 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 dalam playlist.

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

  • Jika player.nextVideo() dipanggil saat video terakhir dalam playlist sedang ditonton dan playlist tidak disetel untuk diputar terus-menerus, maka 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 diputar dalam 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 di posisi yang ditentukan dalam playlist yang diacak.

Mengubah volume pemutar

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

Menyetel ukuran pemutar

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

Menetapkan kecepatan pemutaran

player.getPlaybackRate():Number
Fungsi ini mengambil laju 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, kecepatan hanya akan berubah untuk video yang sudah diberi isyarat atau diputar. Jika Anda menyetel kecepatan pemutaran untuk video isyarat, laju 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.

Pemanggilan 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 memanggil fungsi setPlaybackRate.

Metode getAvailablePlaybackRates akan menampilkan kemungkinan kecepatan pemutaran untuk video yang sedang diputar. Namun, jika Anda menetapkan parameter suggestedRate ke nilai float atau bilangan bulat yang tidak didukung, pemutar akan membulatkan nilai tersebut ke bawah ke nilai terdekat yang didukung di arah 1.
player.getAvailablePlaybackRates():Array
Fungsi ini menampilkan serangkaian laju pemutaran yang tersedia untuk 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 tercepat. Meskipun pemutar tidak mendukung kecepatan pemutaran variabel, array harus selalu berisi setidaknya satu nilai (1).

Menetapkan perilaku pemutaran untuk playlist

player.setLoop(loopPlaylists:Boolean):Void

Fungsi ini menunjukkan apakah pemutar video akan terus memutar playlist atau berhenti diputar setelah video terakhir dalam playlist berakhir. Perilaku defaultnya adalah playlist tidak berulang.

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

Parameter loopPlaylists yang diperlukan mengidentifikasi perilaku looping.

  • Jika nilai parameter 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 parameter 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 atau tidak dalam urutan yang berbeda dengan urutan yang ditentukan oleh kreator playlist. Jika Anda mengacak playlist setelah mulai diputar, daftar tersebut akan diurutkan ulang selagi video yang sedang diputar terus diputar. Video yang diputar berikutnya akan dipilih berdasarkan daftar yang telah diurutkan ulang.

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

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

  • Jika nilai parameter adalah true, YouTube akan mengacak urutan playlist. Jika Anda menginstruksikan fungsi untuk mengacak playlist yang telah diacak, YouTube akan mengacak kembali urutan tersebut.

  • Jika nilai parameter 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 kini 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 – isyarat video
player.getCurrentTime():Number
Menampilkan waktu berlalu dalam detik sejak video mulai diputar.
player.getVideoStartBytes():Number
Dihentikan 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 mengalami buffering.

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 mengalami buffering.

Menampilkan ukuran dalam byte video yang sedang dimuat/diputar, atau merupakan 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 dari 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 yang telah berlalu sejak streaming video live dimulai. Khususnya, ini adalah durasi waktu video di-streaming tanpa direset atau terganggu. Selain itu, durasi ini biasanya lebih lama daripada waktu acara yang sebenarnya karena streaming kemungkinan 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 sesuai urutan yang ditentukan oleh pemilik playlist. Namun, jika Anda telah memanggil fungsi setShuffle untuk mengacak urutan playlist, nilai yang ditampilkan dari fungsi getPlaylist() akan mencerminkan urutan yang diacak.
player.getPlaylistIndex():Number
Fungsi ini menampilkan indeks video playlist yang sedang diputar.

  • Jika Anda belum mengacak playlist, nilai return akan mengidentifikasi posisi penempatan video oleh kreator playlist. Nilai hasil menggunakan indeks berbasis nol, sehingga nilai 0 mengidentifikasi video pertama dalam playlist.

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

Menambahkan atau menghapus pemroses peristiwa

player.addEventListener(event:String, listener:String):Void
Menambahkan fungsi pemroses untuk event yang ditentukan. Bagian Peristiwa di bawah mengidentifikasi berbagai peristiwa yang mungkin 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 memodifikasi node DOM

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

Acara

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 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 diaktifkan API:

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

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

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

Saat pemutar pertama kali memuat video, pemutar akan menyiarkan peristiwa unstarted (-1). Saat video dibaca 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 adanya perubahan pada lingkungan pemutaran penonton. Buka Pusat Bantuan YouTube untuk mengetahui informasi selengkapnya tentang faktor yang memengaruhi kondisi pemutaran atau yang dapat menyebabkan peristiwa diaktifkan.

Nilai properti data objek peristiwa yang diteruskan API ke fungsi pemroses peristiwa akan berupa string yang mengidentifikasi kualitas pemutaran yang 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 berasumsi bahwa kecepatan pemutaran akan otomatis berubah saat fungsi setPlaybackRate(suggestedRate) dipanggil. Demikian pula, kode Anda tidak boleh berasumsi bahwa kecepatan pemutaran video hanya akan berubah sebagai hasil dari panggilan eksplisit ke setPlaybackRate.

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

  • 2 – Permintaan berisi nilai parameter yang tidak valid. Misalnya, error ini terjadi jika Anda 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 yang terkait dengan 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 mengizinkannya diputar di pemutar tersemat.
  • 150 – Error ini sama dengan 101. Ini hanya error 101 yang tersembunyi!
onApiChange
Peristiwa ini diaktifkan untuk menunjukkan bahwa pemain telah memuat (atau menghapus muatan) modul dengan metode API yang terekspos. Aplikasi Anda dapat memproses peristiwa ini, lalu melakukan polling pada pemutar untuk menentukan opsi mana yang diekspos untuk modul yang baru dimuat. Selanjutnya, aplikasi Anda dapat mengambil atau memperbarui setelan yang ada untuk opsi tersebut.

Perintah berikut mengambil array nama modul yang opsi pemutarnya dapat Anda setel:
player.getOptions();
Saat ini, satu-satunya modul yang opsinya dapat Anda setel adalah modul captions, yang menangani pemberian teks tertutup pada 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 menggunakan perintah ini, Anda dapat mengonfirmasi bahwa opsi yang ingin Anda akses memang dapat diakses. Perintah berikut mengambil dan memperbarui opsi modul:
Retrieving an option:
player.getOption(module, option);

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

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

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

Sebagian besar browser memiliki kebijakan yang dapat memblokir putar otomatis di lingkungan desktop, seluler, dan lingkungan lainnya jika kondisi tertentu terpenuhi. Kasus yang memicu kebijakan ini mencakup pemutaran dibunyikan tanpa interaksi pengguna, atau saat Kebijakan Izin untuk mengizinkan putar otomatis pada iframe lintas origin belum disetel.

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

Contoh

Membuat objek YT.Player

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

    Dalam contoh ini, elemen <iframe> di halaman sudah menentukan pemutar yang akan menggunakan 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 sudah siap. Fungsi onPlayerStateChange kemudian mengubah warna batas di sekitar pemutar berdasarkan status pemain 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 1280px x 720px. Pemroses peristiwa untuk peristiwa onReady kemudian memanggil fungsi setVolume untuk menyesuaikan volume ke setelan tertinggi.

    function onYouTubeIframeAPIReady() {
  var player;
  player = new YT.Player('player', {
    width: 1280,
    height: 720,
    videoId: 'M7lc1UVf-VE',
    events: {
      'onReady': onPlayerReady,
      'onStateChange': onPlayerStateChange,
      'onError': onPlayerError
    }
  });
}

function onPlayerReady(event) {
  event.target.setVolume(100);
  event.target.playVideo();
}

  • Contoh 3: Contoh ini menetapkan parameter pemutar untuk otomatis memutar video saat dimuat dan menyembunyikan kontrol pemutar video. Ia 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 sematan pemutar YouTube di aplikasi Android, untuk memverifikasi keaslian aplikasi penyematan. Dengan perubahan ini, aplikasi yang menyematkan akan otomatis mengirimkan ID aplikasi yang telah disahkan ke YouTube. Data yang dikumpulkan melalui penggunaan API ini adalah metadata aplikasi (nama paket, nomor versi, dan sertifikat penandatanganan) serta token pengesahan perangkat yang dibuat oleh layanan Google Play.

Data tersebut digunakan untuk memverifikasi integritas aplikasi dan perangkat. Data tersebut 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 pilihan tidak ikut.

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.