Ringkasan YouTube Live Streaming API

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

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

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

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

    1. Buka API Console, lalu pilih project yang baru saja Anda daftarkan.
    2. 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.

  4. 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, atau unlisted. (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:

  1. Class ini memiliki durasi waktu yang telah ditentukan, yang Anda tetapkan menggunakan properti durationSecs resource cuepoint. Setelah jeda iklan berakhir, penonton kembali ke live streaming.

  2. 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 properti insertionOffsetTimeMs ke 0 atau jangan tentukan nilai untuk properti tersebut dan jangan tentukan nilai untuk properti walltimeMs.

      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 properti walltimeMs untuk menentukan waktu yang diinginkan. Nilai properti adalah bilangan bulat yang merepresentasikan stempel waktu epoch.

  • 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 status live.

    Saat menyisipkan titik tanda, tetapkan properti insertionOffsetTimeMs resource cuepoint 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 metode liveBroadcasts.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 dari ready menjadi testing, YouTube akan menyetel 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, yang menunjukkan bahwa transisi telah selesai.

    Jika siaran terhenti dengan status testStarting atau liveStarting, Anda harus memanggil metode liveBroadcasts.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 properti status.streamStatus untuk streaming yang terikat dengan siaran Anda adalah active sebelum memanggil metode tersebut.