Halaman ini diterjemahkan oleh Cloud Translation API.

Ringkasan YouTube Live Streaming API

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

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 menyusun Live Streaming API hanya digunakan untuk membuat dan mengelola live streaming.

Dokumen ini ditujukan untuk developer yang ingin menulis aplikasi untuk memfasilitasi live streaming di YouTube. Dokumen 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 selesai.
stream: Streaming mengidentifikasi konten audio-video yang dikomunikasikan 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 tersebut untuk diterapkan ke siaran tertentu.
Kaitkan streaming dan siaran video.
Memungkinkan penyiar menentukan informasi tentang siaran dan videonya (menggunakan YouTube Data API) secara bersamaan.
Menyederhanakan transisi antara status siaran (testing, live, dll.) dan memungkinkan pengguna menyisipkan titik tanda.

Sebelum memulai

Anda membutuhkan Akun Google untuk mengakses Google API Console, meminta kunci API, dan mendaftarkan aplikasi.
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:
1. Buka API Console, lalu pilih project yang baru saja Anda daftarkan.
2. Buka halaman APIs 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). JSON adalah format data umum independen bahasa yang memberikan representasi teks sederhana untuk struktur data arbitrer. Untuk informasi selengkapnya, buka json.org.

Mengizinkan 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 YouTube untuk aset Anda. (Siaran video langsung adalah contoh aset.) Dengan API, Anda juga dapat mengklaim video dan menetapkan kebijakan iklan untuk video Anda.

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

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

Resource dan jenis resource

Resource adalah setiap entitas data 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 didefinisikan sebagai bagian dari YouTube Data API atau YouTube Content ID API. Namun, resource liveBroadcast, liveStream, dan cuepoint hanya digunakan untuk membuat dan mengelola live streaming.

Resource
`liveBroadcast`	Berisi informasi tentang acara yang Anda siarkan di YouTube. Resource `liveBroadcast` adalah perluasan dari resource video YouTube dan menyetel metadata video yang akan relevan dengan siaran langsung tetapi tidak relevan dengan video YouTube lainnya. Dengan demikian, resource `liveBroadcast` berkaitan dengan tepat satu resource video YouTube. Bahkan, resource `liveBroadcast` dan resource `video` menggunakan ID yang sama. Dan 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 ini menyediakan konten yang akan disiarkan kepada pengguna YouTube. Setelah dibuat, resource `liveStream` dapat diikat ke tepat satu resource `liveBroadcast`. (Demikian pula, resource `liveBroadcast` hanya dapat terikat ke 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` adalah perluasan 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 dapat menggunakan YouTube Content ID API untuk menetapkan opsi iklan.
`asset`	Merepresentasikan kekayaan intelektual, seperti film atau episode dari 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 tersebut. Anda membuat klaim menggunakan YouTube Content ID API untuk mengidentifikasi diri Anda sebagai pemilik video siaran.
`policy`	Menentukan aturan yang menentukan situasi konten Anda terlihat 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:

Operasional
`list`	Mengambil (`GET`) daftar nol atau beberapa resource.
`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 mengirimkan 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 sah dan tidak sah, dengan permintaan yang tidak sah hanya mengambil data publik sementara 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
siaran langsung
live stream

Resource parsial

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 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 level teratas (non-nested) yang harus disertakan dalam respons API. Misalnya, resource liveStream memiliki bagian-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 dapat (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 ini mengurangi latensi dengan mencegah server API menghabiskan waktu untuk mengambil kolom metadata yang tidak digunakan oleh 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

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 untuk mengklaim video live streaming Anda berbeda dari 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 aktif 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 pada dua streaming keluar yang berbeda:

Streaming monitor memungkinkan Anda melihat pratinjau (dan menguji) siaran video. Ini adalah streaming pribadi yang hanya dapat Anda akses. Anda hanya dapat mentransisikan siaran ke fase testing jika streaming monitor siaran diaktifkan. Aliran monitor tidak menampilkan jeda iklan.
Streaming siaran adalah streaming yang terlihat oleh audiens. 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 tidak publik dapat dilihat oleh siapa saja yang memiliki link untuk melihatnya.)

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 selama waktu Anda memasukkan titik tanda ke dalam siaran.

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

YouTube menyarankan agar Anda mengaktifkan streaming monitor untuk siaran sehingga Anda dapat menguji konten Anda. Anda harus memilih apakah akan menunda siaran berdasarkan keinginan untuk mengontrol waktu tanda titik, dan bukan keinginan Anda untuk berinteraksi dengan penonton atau memberikan liputan real-time acara.

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 tertentu. Dengan jeda iklan, YouTube dapat menjalankan iklan mid-roll selama siaran.

Jeda iklan memiliki karakteristik berikut:

Hal ini memiliki durasi waktu yang telah ditetapkan, yang Anda tetapkan menggunakan properti durationSecs resource cuepoint. Setelah jeda iklan berakhir, penonton akan 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 saat penonton memuat ulang halaman tempat siaran diputar atau saat pengunjung mulai menonton siaran setelah titik tanda disisipkan.

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

Menyetel selisih waktu

Saat menyisipkan titik tanda, Anda dapat menentukan bahwa titik tanda harus langsung disisipkan atau titik titik tersebut harus disisipkan pada titik tertentu dalam siaran. Opsi Anda bergantung pada apakah streaming siaran untuk video Anda tertunda.

Jika streaming siaran tidak tertunda, Anda dapat langsung menyisipkan titik tanda atau menggunakan properti walltimeMs untuk memulai jeda iklan pada waktu tertentu.
- Untuk segera memulai jeda iklan, panggil metode liveBroadcasts.cuepoint. Dalam 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 akan tetap terlihat oleh penonton, dan Anda perlu menonton streaming siaran untuk menentukan kapan konten iklan benar-benar ditampilkan, bukan streaming monitor.
- 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 mewakili stempel waktu epoch.
Jika streaming siaran tertunda, Anda dapat menyisipkan titik tanda segera 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. Perlu diperhatikan bahwa jika siaran Anda memiliki fase pengujian, maka streaming monitor akan dimulai saat siaran ditransisikan ke status testing. Jika tidak, aliran data monitor akan dimulai saat siaran bertransisi ke status live.

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

Hitung 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 titik tanda dalam streaming siaran pada saat itu.

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

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

Δ adalah buffering lima detik di awal dan di akhir kemungkinan selisih waktu jika YouTube tidak dapat menyisipkan titik tanda secara tepat. Contoh:

Siaran memiliki fase pengujian berdurasi lima menit.
Streaming siaran tertunda 60 detik setelah streaming monitor.
Penyiar memasukkan titik tanda empat menit setelah transisi siaran ke status live. (Ini tiga menit setelah streaming siaran terlihat.)

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

Waktu tersebut 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 tertunda selama 60 detik, atau 60.000 milidetik.
Δ=5000 – Buffering lima detik ketika titik tanda tidak dapat disisipkan dengan andal.

Pemecahan masalah dan penanganan error

Panduan berikut menjelaskan cara menyelesaikan masalah tertentu yang mungkin muncul. Lihat juga dokumentasi error untuk mengetahui daftar error yang mungkin ditampilkan oleh setiap metode API.

Saat transisi dari satu status ke status lainnya, siaran dapat diberi status sementara ketika 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 ke 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 macet dengan status testStarting atau liveStarting, Anda harus memanggil metode liveBroadcasts.delete dan menghapus siaran. Kemudian buat siaran baru, ikatkan ke aliran langsung, dan lanjutkan dengan proses pengujian.

Seperti yang dinyatakan dalam dokumentasi metode liveBroadcasts.transition, Anda harus mengonfirmasi bahwa nilai properti status.streamStatus untuk aliran data yang terikat dengan siaran Anda adalah active sebelum memanggil metode tersebut.