Ringkasan YouTube Live Streaming API

YouTube Live Streaming API memungkinkan Anda membuat, memperbarui, dan mengelola acara live di YouTube. Dengan menggunakan API, Anda dapat menjadwalkan acara (siaran) dan mengaitkannya dengan streaming video, yang mewakili konten siaran sebenarnya.

Live Streaming API sebenarnya terdiri dari komponen YouTube Data API dan YouTube Content ID API. Data API memungkinkan pengguna YouTube mengelola akun YouTube mereka, sedangkan YouTube Content ID API memungkinkan interaksi dengan sistem pengelolaan hak YouTube. Namun, semua resource yang membentuk Live Streaming API hanya digunakan untuk membuat dan mengelola acara live.

Dokumen ini ditujukan bagi developer yang ingin menulis aplikasi untuk memfasilitasi live streaming di YouTube. Dokumen ini menjelaskan konsep dasar YouTube dan API itu sendiri. Dokumen ini juga memberikan ringkasan berbagai fungsi yang didukung API.

Konsep inti

siaran
Siaran mewakili acara yang dapat ditonton di YouTube saat berlangsung. Siaran juga dapat direkam dan disimpan sebagai video YouTube sehingga pengguna dapat menontonnya setelah siaran selesai.
streaming
Streaming mengidentifikasi konten audio-video yang dikirimkan ke YouTube. Setiap siaran dikaitkan dengan satu streaming video.
cuepoint
cuepoint mewakili jeda iklan yang dapat disisipkan ke live streaming.

Kasus penggunaan API

Daftar di bawah menyarankan beberapa cara untuk menggunakan API di aplikasi Anda:

  • Menjadwalkan siaran dan menentukan setelan siaran. Aplikasi Anda dapat memungkinkan pengguna menentukan setelan siaran terlebih dahulu, lalu memilih setelan yang akan diterapkan ke siaran tertentu.

  • Mengaitkan streaming video dan siaran.

  • Memungkinkan penyiar menentukan informasi tentang siaran dan videonya (menggunakan YouTube Data API) secara bersamaan.

  • Menyederhanakan transisi antara status siaran (misalnya, testing atau live) dan memungkinkan pengguna menyisipkan cuepoint.

Sebelum memulai

  1. Anda memerlukan Akun Google untuk mengakses Google Cloud console, meminta kunci API, dan mendaftarkan aplikasi Anda.

  2. Daftarkan aplikasi Anda dengan Google sehingga dapat mengirimkan permintaan API.

  3. Setelah mendaftarkan aplikasi Anda, pilih YouTube Data API sebagai salah satu layanan yang digunakan aplikasi Anda:

    1. Buka Cloud console dan pilih project yang baru saja Anda daftarkan.
    2. Buka halaman API yang Diaktifkan. Dalam daftar API, pastikan statusnya AKTIF untuk YouTube Data API v3 dan, jika Anda adalah Partner Konten YouTube, YouTube Content ID API.

  4. Pelajari konsep inti format data JavaScript Object Notation (JSON). JSON adalah format data umum yang tidak terikat bahasa yang memberikan representasi teks sederhana untuk struktur data arbitrer. Untuk informasi selengkapnya, lihat json.org.

Melakukan otorisasi permintaan API

Seperti yang disebutkan di atas, Live Streaming API menggunakan fungsi yang secara teknis merupakan bagian dari YouTube Data API atau YouTube Content ID API. Anda dapat menggunakan Content ID API untuk memberikan metadata, informasi kepemilikan, dan informasi kebijakan untuk aset Anda kepada YouTube. (Siaran video live adalah contoh aset.) API ini juga memungkinkan Anda mengklaim video dan menetapkan kebijakan iklan untuk video Anda.

Bagian ini menjelaskan persyaratan otorisasi untuk permintaan ke Content ID API, yang berbeda dengan persyaratan untuk mengotorisasi permintaan Live Streaming API lainnya.

Memanggil Data API
Permintaan API harus diotorisasi oleh Akun Google yang memiliki channel YouTube siaran.
Memanggil Content ID API
Permintaan API harus diotorisasi oleh Akun Google yang ditautkan ke pemilik konten yang memiliki channel YouTube siaran.

Resource dan jenis resource

Resource adalah entity data individual dengan ID unik. Tabel di bawah menjelaskan berbagai jenis resource yang akan Anda gunakan saat berinteraksi menggunakan Live Streaming API. Secara teknis, semua resource ini sebenarnya ditentukan sebagai bagian dari YouTube Data API atau YouTube Content ID API. Namun, resource liveBroadcast, liveStream, dan cuepoint hanya digunakan untuk membuat dan mengelola acara live.

Resource
liveBroadcast Berisi informasi tentang acara yang Anda siarkan di YouTube. Resource liveBroadcast adalah ekstensi dari resource video YouTube dan menetapkan metadata video yang akan relevan dengan siaran live, tetapi tidak untuk video YouTube lainnya.

Dengan demikian, resource liveBroadcast sesuai dengan tepat satu resource video YouTube. Faktanya, resource liveBroadcast dan resource video memiliki ID yang sama. Setelah membuat siaran menggunakan Live Streaming API, Anda dapat menggunakan YouTube Data API untuk memberikan metadata tambahan tentang video.
liveStream Berisi informasi tentang streaming video yang Anda kirimkan ke YouTube. Streaming ini menyediakan konten yang akan disiarkan kepada pengguna YouTube. Setelah dibuat, resource liveStream dapat terikat ke tepat satu resource liveBroadcast. Demikian pula, resource liveBroadcast hanya dapat terikat ke satu liveStream resource.
cuepoint Menyisipkan cuepoint dalam streaming video siaran, yang mungkin memicu jeda iklan. Gunakan metode liveBroadcasts.cuepoint untuk menyisipkan cuepoint selama siaran.
video Mewakili satu video YouTube. Seperti yang disebutkan di atas, resource liveBroadcast adalah ekstensi dari resource video. Anda dapat menggunakan YouTube Data API untuk memperbarui metadata tentang video, seperti lokasi rekaman atau wilayah tempat siaran akan dapat dilihat.
videoAdvertisingOptions Menentukan setelan iklan untuk video (atau siaran). Anda menggunakan YouTube Content ID API untuk menetapkan opsi iklan.
asset Mewakili bagian dari kekayaan intelektual, seperti film atau episode acara. Dalam hal ini, video siaran adalah aset. Anda akan menggunakan YouTube Content ID API untuk membuat dan mengelola resource asset.
claim Menautkan video ke aset yang cocok dengan video tersebut. Anda membuat klaim, menggunakan YouTube Content ID API, untuk mengidentifikasi diri Anda sebagai pemilik video siaran.
policy Menentukan aturan yang menentukan kondisi saat Anda ingin konten Anda dapat dilihat di YouTube atau diblokir agar tidak muncul di YouTube. Anda harus menerapkan kebijakan ke video siaran Anda dan juga dapat menentukan kebijakan yang akan diterapkan YouTube ke video yang diupload pengguna yang cocok dengan video siaran Anda.

Operasi yang didukung

Tabel berikut menunjukkan berbagai metode yang didukung API:

Operasi
list Mengambil (GET) daftar nol atau beberapa resource.
insert Membuat (POST) resource baru.
update Mengubah (PUT) resource yang ada untuk mencerminkan data dalam permintaan Anda.
bind Menautkan resource liveBroadcast dengan resource liveStream atau menghapus tautan tersebut.
transition Mengubah status resource liveBroadcast dan memulai proses apa pun yang terkait dengan status baru. Misalnya, saat Anda mengubah status siaran menjadi testing, YouTube akan mulai mengirimkan video ke streaming monitor siaran tersebut.
delete Menghapus (DELETE) resource tertentu.

Tabel berikut mengidentifikasi operasi yang didukung untuk berbagai jenis resource. Operasi yang menyisipkan, memperbarui, atau menghapus resource selalu memerlukan otorisasi pengguna. Dalam beberapa kasus, metode list mendukung permintaan yang diotorisasi dan tidak diotorisasi. Permintaan yang tidak diotorisasi hanya mengambil data publik, sedangkan permintaan yang diotorisasi juga dapat mengambil informasi yang dibatasi untuk pengguna yang diautentikasi.

Operasi yang Didukung
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

Resource parsial

API memungkinkan, dan sebenarnya mewajibkan, pengambilan resource parsial sehingga aplikasi menghindari transfer, penguraian, dan penyimpanan data yang tidak diperlukan. Pendekatan ini juga memastikan bahwa API menggunakan resource jaringan, CPU, dan memori secara lebih efisien.

Parameter part adalah parameter yang diperlukan untuk permintaan API apa pun yang mengambil atau menampilkan resource YouTube Data API. Parameter ini mengidentifikasi satu atau beberapa properti resource tingkat atas (tidak bertingkat) yang harus disertakan dalam respons API. Misalnya, resource liveStream memiliki bagian berikut:

  • snippet
  • cdn
  • status

Semua bagian ini adalah objek yang berisi properti bertingkat, dan Anda dapat menganggap objek ini sebagai grup kolom metadata yang mungkin (atau mungkin tidak) diambil oleh server API. Dengan demikian, parameter part mengharuskan Anda memilih komponen resource yang benar-benar digunakan aplikasi Anda. Persyaratan ini memiliki dua tujuan penting:

  • Mengurangi latensi dengan mencegah server API menghabiskan waktu untuk mengambil kolom metadata yang tidak digunakan aplikasi Anda.
  • Mengurangi penggunaan bandwidth dengan mengurangi (atau menghilangkan) jumlah data yang tidak diperlukan yang mungkin diambil oleh aplikasi Anda.

Seiring waktu, saat resource menambahkan lebih banyak bagian, manfaat ini hanya akan meningkat karena aplikasi Anda tidak akan meminta properti yang baru diperkenalkan yang tidak didukungnya.

Tips dan praktik terbaik

Mengklaim konten Anda

Jika ingin menampilkan iklan selama siaran, Anda harus mengklaim video siaran sebelum acara dimulai. Untuk mengklaim konten, Anda harus menjadi Partner Konten YouTube yang berpartisipasi dalam program Content ID.

Proses untuk mengklaim video siaran live Anda berbeda dengan proses normal untuk mengklaim video. Saat mengklaim video live, Anda harus membuat klaim sebelum video benar-benar ada. API mendukung hal ini, dan dokumen masa berlaku siaran menjelaskan panggilan YouTube Content ID API yang memungkinkan Anda membuat klaim.

Melihat pratinjau dan menguji konten Anda

Setelah menerima streaming video masuk Anda, YouTube dapat menyiarkan video tersebut di dua streaming keluar yang berbeda:

  • Streaming monitor memungkinkan Anda melihat pratinjau (dan menguji) siaran video Anda. Streaming ini adalah streaming pribadi yang hanya dapat diakses oleh Anda. Anda hanya dapat mengubah siaran ke fase testing jika streaming monitor siaran diaktifkan. Streaming monitor tidak menampilkan jeda iklan.

  • Streaming siaran adalah streaming yang terlihat oleh audiens Anda. Anda dapat menetapkan status privasi siaran ke public, private, atau unlisted. (Siaran pribadi hanya dapat dilihat oleh pengguna yang telah diundang secara eksplisit untuk menontonnya, sedangkan siaran yang tidak publik dapat dilihat oleh siapa saja yang memiliki link untuk melihatnya.)

    Anda dapat memilih untuk menunda streaming siaran sehingga tidak berjalan secara bersamaan dengan streaming monitor. Dengan menunda streaming siaran, Anda dapat memiliki kontrol yang lebih baik atas waktu penyisipan cuepoint ke siaran.

    Namun, menunda streaming siaran akan menyulitkan presenter live Anda untuk berinteraksi dengan audiens yang menonton. Selain itu, menunda siaran akan meningkatkan kemungkinan penonton menemukan detail penting tentang acara dari sumber selain siaran Anda. Misalnya, jika Anda menyiarkan acara olahraga dengan penundaan 60 detik, penonton mungkin akan mengetahui momen penting dalam acara tersebut dari sumber berita real-time lainnya sebelum benar-benar melihatnya dalam siaran.

YouTube merekomendasikan agar Anda mengaktifkan streaming monitor untuk siaran Anda sehingga Anda dapat menguji konten Anda. Anda harus memilih apakah akan menunda siaran Anda berdasarkan keinginan Anda untuk mengontrol waktu cuepoint, bukan keinginan Anda untuk berinteraksi dengan audiens atau memberikan liputan real-time tentang acara.

Menjalankan iklan mid-roll selama streaming siaran

Selama siaran, Anda dapat menyisipkan cuepoint untuk menunjukkan bahwa jeda iklan harus dimulai dalam siaran sesegera mungkin atau pada waktu yang ditentukan. Jeda iklan memungkinkan YouTube menjalankan iklan mid-roll selama siaran.

Jeda iklan memiliki karakteristik berikut:

  1. Jeda iklan memiliki durasi waktu yang telah ditentukan, yang Anda tetapkan menggunakan properti cuepoint resource's durationSecs. Setelah jeda iklan selesai, penonton akan kembali ke siaran live.

  2. Saat jeda iklan terjadi, iklan hanya diputar di pemutar video untuk penonton yang menonton siaran saat cuepoint disisipkan. Iklan tidak berjalan saat penonton memuat ulang halaman tempat siaran diputar atau saat pengunjung mulai menonton siaran setelah cuepoint disisipkan.

Urutan langkah-langkah di bawah mencerminkan praktik terbaik untuk menyisipkan jeda iklan selama siaran Anda:

Menetapkan selisih waktu

Saat menyisipkan cuepoint, Anda dapat menentukan bahwa cuepoint harus segera disisipkan atau bahwa cuepoint harus disisipkan pada titik tertentu dalam siaran. Opsi Anda bergantung pada apakah streaming siaran untuk video Anda ditunda.

  • Jika streaming siaran Anda tidak ditunda, Anda dapat segera menyisipkan cuepoint atau menggunakan properti walltimeMs agar jeda iklan dimulai pada waktu tertentu.

    • Untuk segera memulai jeda iklan, panggil metode liveBroadcasts.cuepoint. Di resource dalam isi permintaan, tetapkan nilai properti insertionOffsetTimeMs ke 0 atau jangan tentukan nilai untuk properti tersebut dan jangan tentukan nilai untuk propertiwalltimeMs.

      Penting: Perhatikan bahwa penonton tidak langsung melihat konten iklan yang dihasilkan. Mungkin ada penundaan sekitar 30 detik sebelum konten iklan terlihat oleh pengguna. Selama penundaan tersebut, streaming siaran Anda akan tetap terlihat oleh penonton , dan Anda harus menonton streaming siaran untuk menentukan kapan konten iklan benar-benar ditampilkan, bukan streaming monitor Anda.

    • Untuk memulai jeda iklan pada waktu tertentu, panggil metode liveBroadcasts.cuepoint dan gunakan walltimeMs properti untuk menentukan waktu yang diinginkan. Nilai properti adalah bilangan bulat yang mewakili stempel waktu epoch.

  • Jika streaming siaran Anda ditunda, Anda dapat segera menyisipkan cuepoint seperti yang dijelaskan di atas, menentukan waktu jam seperti yang dijelaskan di atas, atau Anda dapat menentukan selisih waktu untuk menentukan kapan jeda iklan akan dimulai. Offset waktu menentukan titik dalam siaran Anda saat penonton akan melihat iklan.

    Nilai offset diukur dalam milidetik dari awal streaming monitor untuk siaran Anda. Perhatikan bahwa jika siaran Anda memiliki fase pengujian, streaming monitor dimulai saat siaran Anda bertransisi ke status testing. Jika tidak, streaming monitor Anda akan dimulai saat siaran Anda bertransisi ke status live.

    Saat menyisipkan cuepoint, tetapkan properti resource cuepoint insertionOffsetTimeMs ke offset yang diinginkan.

Menghitung nilai selisih waktu

Untuk mengambil nilai offset, panggil fungsi getCurrentTime YouTube Player API untuk pemutar yang memutar streaming monitor. Gunakan nilai yang diambil untuk menyisipkan cuepoint dalam streaming siaran pada waktu tersebut.

Nilai yang mungkin untuk waktu offset dapat dihitung sebagai rentang berikut:

[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]

Δ adalah buffer lima detik di awal dan akhir kemungkinan selisih waktu saat YouTube tidak dapat menyisipkan cuepoint secara tepat. Contoh:

  • Siaran memiliki fase pengujian selama lima menit.
  • Streaming siaran ditunda 60 detik setelah streaming monitor.
  • Penyiar menyisipkan cuepoint empat menit setelah siaran bertransisi ke live status. (Ini adalah tiga menit setelah streaming siaran terlihat.)

Dalam hal ini, rentang waktu offset yang mungkin adalah [(485,000), (535,000)].

Waktu ini ditentukan dalam milidetik, dan dihitung menggunakan nilai berikut:

  • elapsed_time=540000 – Streaming monitor telah berjalan selama sembilan menit (540 detik, 540.000 milidetik) saat metode liveBroadcasts.cuepoint dipanggil.
  • broadcast_delay=60000 – Streaming siaran ditunda selama 60 detik, atau 60.000 milidetik.
  • Δ=5000 – Buffer lima detik saat cuepoint tidak dapat disisipkan dengan andal.

Pemecahan masalah dan penanganan error

Panduan berikut menjelaskan cara menyelesaikan masalah tertentu yang mungkin muncul. Untuk daftar error yang mungkin ditampilkan oleh setiap metode API, lihat YouTube Live Streaming API - Error.

  • Saat siaran bertransisi dari satu status ke status lainnya, siaran tersebut mungkin akan ditetapkan sementara dengan status lain saat YouTube menyelesaikan tindakan yang terkait dengan transisi tersebut. Misalnya, jika Anda mengirim permintaan liveBroadcasts.transition untuk mengubah status siaran dari ready menjadi testing, YouTube akan menetapkan status siaran menjadi testStarting, lalu menyelesaikan tindakan yang terkait dengan perubahan status tersebut. Setelah semua tindakan tersebut selesai, YouTube akan memperbarui status siaran menjadi testing, sehingga menunjukkan bahwa transisi telah selesai.

    Jika siaran mengalami masalah dengan status testStarting atau liveStarting, Anda harus memanggil metode liveBroadcasts.delete dan menghapus siaran tersebut. Kemudian, buat siaran baru, kaitkan dengan livestream Anda, dan lanjutkan dengan proses pengujian.

    Seperti yang disebutkan dalam dokumentasi metode liveBroadcasts.transition, Anda harus mengonfirmasi bahwa nilai properti status.streamStatus untuk streaming yang terikat ke siaran Anda adalah active sebelum memanggil metode tersebut.