YouTube Live Streaming API memungkinkan Anda membuat, memperbarui, dan mengelola live streaming di YouTube. Dengan API, Anda dapat menjadwalkan acara (siaran) dan mengaitkannya dengan streaming video, yang mewakili konten siaran yang 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 live streaming.
Dokumen ini ditujukan bagi developer yang ingin menulis aplikasi untuk memfasilitasi siaran langsung di YouTube. Panduan ini menjelaskan konsep dasar YouTube dan API itu sendiri. Panduan ini juga memberikan ringkasan tentang berbagai fungsi yang didukung API.
Konsep inti
- siaran
- Siaran mewakili peristiwa yang dapat ditonton di YouTube saat terjadi. Siaran juga dapat direkam dan disimpan sebagai video YouTube sehingga pengguna dapat menontonnya setelah terjadi.
- streaming
- Stream mengidentifikasi konten audio-video yang disampaikan ke YouTube. Setiap siaran dikaitkan dengan satu streaming video.
- titik tanda
- Titik tanda mewakili jeda iklan yang dapat disisipkan ke dalam live streaming.
Kasus penggunaan API
Daftar di bawah ini menyarankan beberapa cara untuk menggunakan API di aplikasi Anda:
-
Jadwalkan siaran dan tentukan setelan siaran. Aplikasi Anda dapat memungkinkan pengguna menentukan setelan siaran terlebih dahulu, lalu memilih setelan yang akan diterapkan ke siaran tertentu.
-
Mengaitkan streaming dan siaran video.
-
Izinkan penyiar untuk menentukan informasi tentang siaran dan videonya (menggunakan YouTube Data API) secara bersamaan.
-
Sederhanakan transisi antara status siaran (
testing
,live
, dll.) dan mungkinkan pengguna menyisipkan titik tanda.
Sebelum memulai
-
Anda memerlukan Akun Google untuk mengakses Google API Console, meminta kunci API, dan mendaftarkan aplikasi Anda.
-
Daftarkan aplikasi Anda dengan Google sehingga dapat mengirimkan permintaan API.
-
Setelah mendaftarkan aplikasi, pilih YouTube Data API sebagai salah satu layanan yang digunakan aplikasi Anda:
- Buka API Console, lalu pilih project yang baru saja Anda daftarkan.
- Kunjungi 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.
-
Pelajari konsep inti format data JSON (JavaScript Object Notation) dengan baik. JSON adalah format data umum independen bahasa yang memberikan representasi teks sederhana dari struktur data arbitrer. Untuk informasi selengkapnya, buka json.org.
Melakukan otorisasi permintaan API
Seperti 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 memberi YouTube metadata, informasi kepemilikan, dan informasi kebijakan untuk aset Anda. (Siaran video live adalah contoh aset.) API ini juga memungkinkan Anda mengklaim video dan menetapkan kebijakan iklan untuk video.
Bagian ini menjelaskan persyaratan otorisasi untuk permintaan ke Content ID API, yang berbeda dengan persyaratan untuk memberi otorisasi permintaan Live Streaming API lainnya.
- Memanggil Data API
- Permintaan API harus diizinkan oleh Akun Google yang memiliki channel YouTube penyiaran.
- Memanggil Content ID API
- Permintaan API harus diizinkan oleh Akun Google yang ditautkan ke pemilik konten yang memiliki channel YouTube penyiaran.
Resource dan jenis resource
Resource adalah entity data individual dengan ID unik. Tabel di bawah ini menjelaskan berbagai jenis resource yang akan berinteraksi dengan Anda 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.
Referensi | |
---|---|
liveBroadcast |
Berisi informasi tentang acara yang Anda siarkan di YouTube. Resource
liveBroadcast adalah perpanjangan resource video YouTube dan menetapkan metadata
video yang terkait dengan live streaming, tetapi tidak terkait dengan video YouTube lainnya.Dengan demikian, referensi liveBroadcast sesuai dengan satu referensi video YouTube.
Bahkan, 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 transmisikan ke YouTube. Streaming menyediakan konten yang akan disiarkan kepada pengguna YouTube. Setelah dibuat, resource liveStream dapat diikat dengan tepat satu resource liveBroadcast . (Demikian pula, resource liveBroadcast hanya dapat diikat dengan satu resource liveStream . |
cuepoint |
Menyisipkan titik tanda dalam streaming video siaran, yang dapat memicu jeda iklan. Gunakan metode liveBroadcasts.cuepoint untuk menyisipkan titik tanda selama siaran.
|
video |
Mewakili satu video YouTube. Seperti disebutkan di atas, resource liveBroadcast merupakan ekstensi dari resource video . Anda dapat menggunakan YouTube Data API untuk memperbarui metadata tentang video, seperti lokasi rekaman atau wilayah tempat siaran dapat dilihat. |
videoAdvertisingOptions |
Menentukan setelan iklan untuk video (atau siaran). Anda menggunakan YouTube Content ID API untuk menetapkan opsi iklan. |
asset |
Mewakili bagian kekayaan intelektual, seperti film atau episode suatu acara. Dalam hal ini, video siaran adalah asetnya. Anda akan menggunakan YouTube Content ID API untuk membuat dan mengelola resource asset . |
claim |
Menautkan video ke aset yang cocok dengan video. Anda membuat klaim, menggunakan YouTube Content ID API, untuk mengidentifikasi diri Anda sebagai pemilik video siaran. |
policy |
Menentukan aturan yang menentukan keadaan saat Anda ingin konten dapat ditonton di YouTube atau diblokir agar tidak muncul di YouTube. Anda harus menerapkan kebijakan pada video siaran Anda dan juga dapat menentukan kebijakan yang akan diterapkan YouTube pada 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 resource atau lebih. |
insert |
Membuat (POST ) resource baru. |
update |
Memodifikasi (PUT ) resource yang ada untuk mencerminkan data dalam permintaan Anda. |
bind |
Menautkan resource liveBroadcast dengan resource liveStream atau menghapus link tersebut. |
transition |
Mengubah status resource liveBroadcast dan memulai proses apa pun yang berkaitan dengan status baru. Misalnya, saat Anda mentransisikan status siaran ke testing , YouTube akan mulai mengirimkan video ke streaming monitor siaran tersebut. |
delete |
Menghapus (DELETE ) resource tertentu. |
Tabel di bawah ini mengidentifikasi operasi yang didukung untuk berbagai tipe resource. Operasi yang menyisipkan, memperbarui, atau menghapus resource selalu memerlukan otorisasi pengguna. Dalam beberapa kasus, metode list
mendukung permintaan yang sah dan tidak sah. Permintaan yang tidak sah hanya mengambil data publik, sedangkan permintaan yang sah juga dapat mengambil informasi yang dibatasi untuk pengguna yang saat ini diautentikasi.
Operasi yang Didukung | |||||||
---|---|---|---|---|---|---|---|
list | insert | update | bind | transition | cuepoint | delete | |
liveBroadcast | |||||||
liveStream |
Resource sebagian
API memungkinkan, dan benar-benar memerlukan, pengambilan resource sebagian 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 wajib untuk permintaan API apa pun yang mengambil atau menampilkan resource YouTube Data API. Parameter ini mengidentifikasi satu atau beberapa properti resource tingkat teratas (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 kelompok kolom metadata yang mungkin diambil (atau tidak diambil) oleh server API. Dengan demikian, parameter part
mengharuskan Anda memilih komponen resource yang benar-benar digunakan oleh aplikasi Anda. Persyaratan ini memiliki dua tujuan penting:
- Hal ini 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 tidak perlu 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
Klaim 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 mengklaim video live streaming berbeda dengan proses biasanya untuk mengklaim video. Saat mengklaim video live, Anda harus membuat klaim sebelum video tersebut benar-benar ada. API mendukung hal ini, dan dokumen masa aktif siaran menjelaskan panggilan YouTube Content ID API yang memungkinkan Anda membuat klaim.
Melihat pratinjau dan menguji konten
Setelah menerima streaming video masuk Anda, YouTube kemudian dapat menyiarkan video tersebut pada dua streaming keluar yang berbeda:
-
Pantau streaming memungkinkan Anda melihat pratinjau (dan menguji) siaran video Anda. Ini adalah streaming pribadi yang hanya dapat diakses oleh Anda. Anda hanya dapat mentransisikan siaran ke fase
testing
jika streaming monitor siaran diaktifkan. Streaming pemantauan tidak menampilkan jeda iklan. -
Streaming siaran adalah streaming yang terlihat oleh audiens Anda. Anda dapat menyetel status privasi siaran ke
public
,private
, atauunlisted
. (Siaran pribadi hanya dapat dilihat oleh pengguna yang telah diundang secara eksplisit untuk menontonnya, sedangkan siaran yang tidak tercantum dapat dilihat oleh siapa saja yang memiliki link untuk menontonnya.)Anda dapat memilih untuk menunda streaming siaran agar tidak berjalan bersamaan dengan streaming monitor. Dengan menunda streaming siaran, Anda dapat memiliki kontrol yang lebih terperinci terhadap waktu saat Anda menyisipkan titik tanda ke dalam siaran.
Namun, menunda streaming siaran akan menyulitkan presenter langsung untuk berinteraksi dengan audiens yang menonton. Selain itu, menunda siaran juga meningkatkan kemungkinan bahwa penonton akan menemukan detail penting tentang acara tersebut dari sumber selain siaran Anda. Misalnya, jika Anda menyiarkan acara olahraga pada penundaan 60 detik, penonton mungkin mempelajari momen penting dalam acara tersebut dari sumber berita real-time lainnya sebelum benar-benar melihatnya dalam siaran.
YouTube menyarankan agar Anda mengaktifkan streaming pemantauan untuk siaran sehingga Anda dapat menguji konten. Anda harus memilih apakah akan menunda siaran juga berdasarkan keinginan Anda untuk mengontrol waktu titik tanda, bukan keinginan untuk berinteraksi dengan audiens atau memberikan liputan peristiwa secara real-time.
Menjalankan iklan mid-roll selama streaming siaran
Selama siaran, Anda dapat menyisipkan titik tanda 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:
-
Class ini memiliki durasi waktu yang telah ditentukan, yang Anda tetapkan menggunakan properti
durationSecs
resourcecuepoint
. Setelah jeda iklan berakhir, penonton kembali ke live streaming. -
Saat jeda iklan terjadi, iklan hanya diputar di pemutar video untuk penonton yang menonton siaran saat titik tanda disisipkan. Iklan tidak berjalan jika penonton memuat ulang halaman tempat siaran sedang diputar atau saat pengunjung mulai menonton siaran setelah titik tanda disisipkan.
Urutan langkah-langkah di bawah ini mencerminkan praktik terbaik untuk menyisipkan jeda iklan selama siaran Anda:
Menyetel offset waktu
Saat menyisipkan titik tanda, Anda dapat menentukan bahwa titik tersebut harus langsung dimasukkan atau harus disisipkan pada titik tertentu dalam siaran. Opsi yang tersedia bergantung pada apakah streaming siaran untuk video Anda tertunda atau tidak.
-
Jika streaming siaran tidak tertunda, Anda dapat segera memasukkan titik tanda atau menggunakan properti
walltimeMs
agar jeda iklan dimulai pada waktu tertentu.-
Untuk segera memulai jeda iklan, panggil metode
liveBroadcasts.cuepoint
. Pada resource di isi permintaan, tetapkan nilai propertiinsertionOffsetTimeMs
ke0
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 masih akan terlihat oleh penonton, dan Anda harus menonton streaming siaran untuk menentukan kapan konten iklan benar-benar ditampilkan, bukan streaming yang dipantau.
-
Untuk memulai jeda iklan pada waktu tertentu, panggil metode
liveBroadcasts.cuepoint
dan gunakan propertiwalltimeMs
untuk menentukan waktu yang diinginkan. Nilai properti adalah bilangan bulat yang merepresentasikan stempel waktu epoch.
-
Untuk segera memulai jeda iklan, panggil metode
-
Jika streaming siaran tertunda, Anda dapat segera memasukkan titik tanda seperti yang dijelaskan di atas, menentukan waktu jam seperti yang dijelaskan di atas, atau 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 akan dimulai saat siaran bertransisi ke status
testing
. Jika tidak, streaming monitor Anda akan dimulai saat siaran bertransisi ke statuslive
.Saat menyisipkan titik tanda, tetapkan properti
insertionOffsetTimeMs
resourcecuepoint
ke offset yang diinginkan.
Menghitung nilai kompensasi waktu
Untuk mengambil nilai offset, panggil fungsi getCurrentTime
YouTube Player API untuk pemutar yang memutar streaming monitor. Gunakan nilai yang diambil untuk memasukkan titik tanda di streaming siaran pada saat itu.
Nilai yang mungkin untuk waktu offset dapat dihitung sebagai rentang berikut:
[(elapsed_time - broadcast_delay + Δ), (elapsed_time - Δ)]
Δ
adalah buffering lima detik di awal dan akhir offset waktu yang memungkinkan saat YouTube tidak dapat menyisipkan titik tanda dengan tepat. Contoh:
- Sebuah siaran memiliki fase pengujian lima menit.
- Streaming siaran tertunda 60 detik setelah streaming monitor.
- Penyiar memasukkan titik tanda empat menit setelah transisi siaran ke
status
live
. (Waktunya tiga menit setelah streaming siaran terlihat.)
Dalam hal ini, kemungkinan rentang waktu offset 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, 540000 milidetik) saat metodeliveBroadcasts.cuepoint
dipanggil.broadcast_delay=60000
– Streaming siaran tertunda selama 60 detik, atau 60.000 milidetik.Δ=5000
– Buffering lima detik saat titik tanda tidak dapat disisipkan dengan andal.
Pemecahan masalah dan penanganan error
Panduan berikut menjelaskan cara menyelesaikan masalah khusus yang mungkin timbul. Lihat juga dokumentasi error untuk mengetahui daftar error yang mungkin ditampilkan oleh setiap metode API.
-
Jika siaran bertransisi dari satu status ke status lainnya, siaran mungkin ditetapkan dengan status lain untuk sementara sementara YouTube menyelesaikan tindakan yang terkait dengan transisi tersebut. Misalnya, jika Anda mengirim permintaan
liveBroadcasts.transition
untuk mengubah status siaran dariready
menjaditesting
, YouTube akan menyetel status siaran menjaditestStarting
, lalu menyelesaikan tindakan yang terkait dengan perubahan status tersebut. Setelah semua tindakan tersebut selesai, YouTube akan memperbarui status siaran menjaditesting
, yang menunjukkan bahwa transisi telah selesai.Jika siaran terhenti dengan status
testStarting
atauliveStarting
, Anda harus memanggil metodeliveBroadcasts.delete
dan menghapus siaran. Kemudian buat siaran baru, ikat ke live stream Anda, dan lanjutkan dengan proses pengujian.Seperti yang tercantum dalam dokumentasi metode
liveBroadcasts.transition
, Anda harus mengonfirmasi bahwa nilai propertistatus.streamStatus
untuk streaming yang terikat dengan siaran Anda adalahactive
sebelum memanggil metode tersebut.