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 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 acara live.

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

Konsep inti

siaran
Siaran mewakili acara yang dapat ditonton di YouTube saat sedang berlangsung. Siaran juga dapat direkam dan disimpan sebagai video YouTube sehingga pengguna dapat menontonnya setelah selesai.
feed
Streaming mengidentifikasi konten audio-video yang sedang 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:

  • 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 dan siaran video.

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

  • Sederhanakan transisi antar-status siaran (misalnya, testing atau live) dan mungkinkan pengguna untuk 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 Anda, pilih YouTube Data API sebagai salah satu layanan yang digunakan aplikasi Anda:

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

  4. Pelajari konsep inti format data JavaScript Object Notation (JSON). JSON adalah format data umum yang tidak bergantung pada bahasa yang memberikan representasi teks sederhana untuk struktur data arbitrer. Untuk informasi selengkapnya, lihat 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 memberikan metadata, informasi kepemilikan, dan informasi kebijakan 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 mengizinkan 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 menjelaskan berbagai jenis sumber daya yang akan berinteraksi dengan Anda menggunakan Live Streaming API. Secara teknis, semua sumber daya ini sebenarnya didefinisikan sebagai bagian dari YouTube Data API atau YouTube Content ID API. Namun, liveBroadcast, liveStream dan Resource cuepoint hanya digunakan untuk membuat dan mengelola acara live.

Resource
liveBroadcast Berisi informasi tentang acara yang Anda siarkan di YouTube. J Resource liveBroadcast adalah ekstensi dari referensi video YouTube dan menetapkan metadata video yang berhubungan dengan siaran langsung, tetapi tidak terkait dengan video YouTube lainnya.

Dengan demikian, resource liveBroadcast sama persis dengan satu resource video YouTube. Bahkan, liveBroadcast dan resource video berbagi 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. Feed menyediakan konten yang akan disiarkan ke pengguna YouTube. Setelah dibuat, liveStream resource dapat diikat dengan tepat satu resource liveBroadcast. Demikian pula, Resource liveBroadcast hanya dapat diikat ke satu resource liveStream.
cuepoint Menyisipkan titik tanda dalam streaming video siaran, yang dapat memicu jeda iklan. Gunakan liveBroadcasts.cuepoint untuk memasukkan 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 perekaman atau wilayah tempat siaran dapat ditonton.
videoAdvertisingOptions Menentukan setelan iklan untuk video (atau siaran). Anda menggunakan YouTube Content ID API untuk menetapkan opsi iklan.
asset Mewakili kekayaan intelektual, seperti film atau episode acara TV. 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 tersebut.
policy Menentukan aturan yang menentukan dalam situasi apa Anda ingin konten Anda dapat dilihat di YouTube atau diblokir agar tidak muncul di YouTube. Anda harus menerapkan kebijakan pada video siaran 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 ini:

Operasi
list Mengambil (GET) daftar yang berisi 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 terkait dengan status baru. Misalnya, saat Anda mentransisikan status siaran ke testing, YouTube akan mulai mentransmisikan video ke streaming monitor siaran tersebut.
delete Menghapus (DELETE) resource tertentu.

Tabel di bawah ini 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 diizinkan dan tidak sah, dengan permintaan yang tidak sah hanya mengambil data publik, sedangkan permintaan yang diotorisasi 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 sebenarnya memerlukan, pengambilan resource parsial sehingga aplikasi menghindari transfer, penguraian, dan penyimpanan data yang tidak diperlukan. Pendekatan ini juga memastikan bahwa API menggunakan sumber daya jaringan, CPU, dan memori secara lebih efisien.

Parameter part adalah parameter wajib untuk setiap permintaan API yang mengambil atau menampilkan resource YouTube Data API. Parameter ini mengidentifikasi satu atau beberapa properti resource level 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 (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:

  • API tersebut 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 aplikasi Anda.

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

Tips dan praktik terbaik

Klaim konten Anda

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

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

Melihat pratinjau dan menguji konten

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

  • Pemantauan streaming memungkinkan Anda melihat pratinjau (dan menguji) siaran video. Ini adalah streaming pribadi yang hanya dapat diakses oleh Anda. Anda hanya dapat mentransisikan 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 menyetel status privasi siaran ke public, private, atau unlisted. (Siaran pribadi hanya terlihat oleh pengguna yang telah diundang secara eksplisit untuk menontonnya, sementara siaran tidak publik dapat dilihat oleh siapa saja yang memiliki link untuk menontonnya.)

    Anda dapat memilih untuk menunda streaming siaran sehingga tidak berjalan bersamaan dengan streaming monitor. Dengan menunda streaming siaran, Anda dapat memiliki kontrol yang lebih mendetail terkait waktu untuk memasukkan titik tanda ke dalam siaran.

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

YouTube menyarankan agar Anda mengaktifkan streaming pantau untuk siaran sehingga Anda dapat menguji konten. Anda juga harus memilih apakah akan menunda siaran berdasarkan keinginan Anda untuk mengontrol waktu titik tanda, bukan keinginan Anda untuk berinteraksi dengan audiens atau menyediakan liputan real-time dari suatu peristiwa.

Menjalankan iklan mid-roll selama streaming siaran

Selama siaran, Anda dapat memasukkan titik tanda untuk menunjukkan bahwa jeda iklan akan dimulai dalam siaran sesegera mungkin atau pada waktu tertentu. Jeda iklan memungkinkan YouTube berjalan iklan mid-roll selama siaran.

Jeda iklan memiliki karakteristik berikut:

  1. Alat ini memiliki durasi waktu yang telah ditentukan, yang Anda atur menggunakan cuepoint durationSecs saat ini. Setelah jeda iklan berakhir, penonton kembali ke live streaming.

  2. Saat jeda iklan terjadi, iklan hanya diputar di pemutar video untuk penonton yang sedang menonton siaran ketika titik tanda dimasukkan. Iklan tidak akan ditampilkan saat penonton memuat ulang halaman tempat siaran diputar, atau saat pengunjung mulai menonton siaran setelah titik tanda disisipkan.

Urutan langkah di bawah menunjukkan praktik terbaik untuk menyisipkan jeda iklan selama siaran:

Setel offset waktu

Saat memasukkan titik tanda, Anda dapat menentukan bahwa titik tanda harus segera dimasukkan atau titik tanda harus dimasukkan di titik tertentu dalam siaran. Opsi yang tersedia bergantung pada apakah streaming siaran untuk video Anda tertunda.

  • Jika streaming siaran tidak tertunda, Anda dapat langsung memasukkan titik tanda atau menggunakan walltimeMs agar jeda iklan dimulai pada waktu tertentu.

    • Untuk segera memulai jeda iklan, panggil metode liveBroadcasts.cuepoint. Di kolom dalam isi permintaan, setel atribut insertionOffsetTimeMs properti nilai ke 0 atau jangan tentukan nilai untuk properti tersebut dan jangan tentukan nilai untuk walltimeMs saat ini.

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

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

  • Jika streaming siaran tertunda, Anda dapat langsung memasukkan titik tanda sebagai yang dijelaskan di atas, tentukan waktu jam seperti yang dijelaskan di atas, atau Anda dapat menentukan offset waktu menentukan kapan jeda iklan akan dimulai. Offset waktu menentukan titik dalam siaran Anda kapan penonton dapat melihat iklan.

    Nilai offset diukur dalam milidetik dari awal stream monitor untuk siaran Anda. Perlu diperhatikan bahwa jika siaran Anda memiliki fase pengujian, maka pemantauanlah streaming dimulai saat siaran Anda bertransisi ke status testing. Jika tidak, memantau streaming dimulai saat siaran Anda bertransisi ke status live.

    Saat memasukkan titik tanda, setel resource cuepoint insertionOffsetTimeMs properti 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 memasukkan titik tanda dalam 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 dari kemungkinan offset waktu saat YouTube tidak dapat memasukkan titik tanda secara tepat. Contoh:

  • Sebuah siaran memiliki fase pengujian selama lima menit.
  • Streaming siaran ditunda 60 detik setelah streaming monitor.
  • Penyiar memasukkan titik tanda empat menit setelah transisi siaran ke Status live. (Ini adalah 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 – Aliran data monitor telah berjalan selama sembilan menit (540 detik, 540.000 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 spesifik yang mungkin timbul. Untuk daftar error yang mungkin ditampilkan oleh setiap metode API, lihat YouTube Live Streaming API - Error.

  • Ketika sebuah siaran bertransisi dari satu status ke status lainnya, siaran tersebut mungkin akan diberi status lainnya untuk sementara sementara YouTube akan 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 macet dengan status testStarting atau liveStarting, Anda harus memanggil metode liveBroadcasts.delete dan menghapus siaran tersebut. Lalu buat siaran baru, ikatkan ke live stream Anda, dan lanjutkan proses pengujian.

    Seperti yang tercantum 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.