YouTube Live Streaming API'ya Genel Bakış

YouTube Live Streaming API, YouTube'da canlı etkinlikler oluşturmanıza, bunları güncellemenize ve yönetmenize olanak tanır. API'yi kullanarak etkinlikler (yayınlar) planlayabilir ve bunları, gerçek yayın içeriğini temsil eden video akışlarıyla ilişkilendirebilirsiniz.

Live Streaming API, YouTube Data API ve YouTube Content ID API bileşenlerinden oluşur. Data API, YouTube kullanıcılarının YouTube hesaplarını yönetmelerine olanak tanırken YouTube Content ID API, YouTube'un hak yönetimi sistemiyle etkileşimleri etkinleştirir. Bununla birlikte, Live Streaming API'yi oluşturan tüm kaynaklar, yalnızca canlı etkinlik oluşturmak ve yönetmek için kullanılır.

Bu doküman, YouTube'da canlı yayın yapmayı kolaylaştırmak amacıyla uygulama yazmak isteyen geliştiricilere yöneliktir. YouTube ve API'nin temel kavramlarını açıklar. Ayrıca, API'nin desteklediği farklı işlevlere dair genel bir bakış da sunar.

Temel kavramlar

yayınlar
Yayın, YouTube'da gerçekleştiği anda izlenebilen bir etkinliği temsil eder. Yayınlar ayrıca kaydedilip YouTube videoları olarak kaydedilerek kullanıcıların gerçekleştikten sonra izleyebilmesini sağlar.
akış
Akış, YouTube'a iletilen ses-video içeriğini tanımlar. Her yayın bir video akışıyla ilişkilendirilir.
işaret noktaları
İşaret noktası, canlı yayına eklenebilecek reklam arasını temsil eder.

API kullanım alanları

Aşağıdaki liste, API'yı uygulamanızda kullanmanın çeşitli yollarını önerir:

  • Yayınları planlayın ve yayın ayarlarını tanımlayın. Uygulamanız, kullanıcıların yayın ayarlarını önceden tanımlamasına ve ardından belirli bir yayına uygulanacak ayarları seçmesine olanak tanıyabilir.

  • Video akışlarını ve yayınları ilişkilendirin.

  • Yayıncıların bir yayın ve yayın videosuyla ilgili bilgileri aynı anda tanımlamasını (YouTube Data API'yi kullanarak) etkinleştirin.

  • Yayın durumları arasındaki geçişleri basitleştirin (örneğin, testing veya live) ve kullanıcıların işaret noktaları eklemesine izin verin.

Başlamadan önce

  1. Google API Console hizmetine erişmek, API anahtarı istemek ve uygulamanızı kaydetmek için bir Google Hesabınız olmalıdır.

  2. API isteklerini gönderebilmesi için Google ile uygulamanızı kaydedin.

  3. Başvurunuzu kaydettikten sonra, uygulamanızın kullandığı hizmetlerden biri olarak YouTube Data API hizmetini seçin:

    1. API Console'e gidin ve az önce kaydettiğiniz projeyi seçin.
    2. Etkin API'ler sayfasını ziyaret edin. API'ler listesinde, YouTube Data API v3 ve YouTube İçerik İş Ortağıysanız YouTube Content ID API için durumun AÇIK olduğundan emin olun.

  4. JavaScript Object Notation (JSON) veri biçimiyle ilgili temel kavramlar hakkında bilgi edinin. JSON, rastgele veri yapılarının basit metin temsilini sağlayan, dilden bağımsız bir veri biçimidir. Daha fazla bilgi için json.org adresine bakın.

API isteklerini yetkilendirme

Yukarıda belirtildiği gibi Live Streaming API, teknik olarak YouTube Data API veya YouTube Content ID API'nin bir parçası olan işlevleri kullanır. Öğelerinizin meta verilerini, sahiplik bilgilerini ve politika bilgilerini YouTube'a sağlamak için Content ID API'sini kullanabilirsiniz. (Canlı video yayını, öğelere örnek olarak gösterilebilir.) API, videolarla ilgili hak talebinde bulunmanıza ve videolarınız için reklam politikaları belirlemenize de olanak tanır.

Bu bölümde, diğer Live Streaming API isteklerinin yetkilendirilmesine ilişkin şartlardan farklı olan, Content ID API için yapılan isteklere ilişkin yetkilendirme gereksinimleri açıklanmaktadır.

Data API aranıyor
API isteği, yayını yapan YouTube kanalının sahibi olan Google Hesabı tarafından yetkilendirilmelidir.
Content ID API aranıyor
API isteği, yayını yapan YouTube kanalının sahibi olan içerik sahibine bağlı bir Google Hesabı tarafından yetkilendirilmelidir.

Kaynaklar ve kaynak türleri

Kaynak, benzersiz bir tanımlayıcıya sahip bağımsız bir veri varlığıdır. Aşağıdaki tabloda her tür kaynağı kullanabilirsiniz. Live Streaming API Teknik olarak bu kaynakların hepsi YouTube Data API kapsamında tanımlandığından veya YouTube Content ID API. Ancak liveBroadcast liveStream ve cuepoint kaynak Yalnızca canlı etkinlikler oluşturmak ve yönetmek için kullanılır.

Kaynaklar
liveBroadcast YouTube'da yayınladığınız bir etkinlikle ilgili bilgileri içerir. CEVAP liveBroadcast kaynağı, bir YouTube video kaynağının uzantısıdır ve diğer YouTube videolarıyla ilgili olmayan ancak canlı yayınla ilgili video meta verileri.

Bu nedenle, liveBroadcast kaynağı tam olarak bir YouTube video kaynağına karşılık gelir. Hatta liveBroadcast kaynağı ve video kaynağı, aynı kimlik. Canlı Akış API'sını kullanarak yayını oluşturduktan sonra, Video hakkında ek meta veri sağlamak için YouTube Data API.
liveStream YouTube'a ilettiğiniz video akışıyla ilgili bilgileri içerir. Akış YouTube kullanıcılarına yayınlanacak içeriği sağlar. Oluşturulduktan sonra liveStream kaynak, tam olarak bir liveBroadcast kaynağa bağlı olabilir. Aynı şekilde, liveBroadcast kaynağı yalnızca bir liveStream kaynağına bağlanabilir.
cuepoint Yayın video akışına, reklam arası tetikleyebilecek bir işaret noktası ekler. Şunu kullanın: liveBroadcasts.cuepoint işaret noktası ekleme yöntemini kullanır.
video Tek bir YouTube videosunu temsil eder. Yukarıda belirtildiği gibi, liveBroadcast kaynağı, video kaynağının uzantısıdır. Videoyla ilgili meta verileri (ör. kayıt konumu veya yayının izlenebileceği bölgeler) güncellemek için YouTube Data API'yi kullanabilirsiniz.
videoAdvertisingOptions Bir video (veya yayın) için reklamcılık ayarlarını tanımlar. Reklam seçeneklerini belirlemek için YouTube Content ID API kullanırsınız.
asset Film veya programın bir bölümü gibi bir fikri mülkiyet parçasını temsil eder. Bu durumda, yayınlanan video öğedir. asset kaynaklarını oluşturmak ve yönetmek için YouTube Content ID API bölümünü kullanacaksınız.
claim Bir videoyu, eşleştiği bir öğeye bağlar. Yayın videosunun sahibi olduğunuzu doğrulamak için YouTube Content ID API kullanarak bir hak talebi oluşturursunuz.
policy İçeriğinizin YouTube'da görüntülenmesini veya YouTube'da görünmesinin engellenmesini istediğiniz koşulları belirleyen kuralları tanımlar. Yayın videonuza bir politika uygulamanız gerekir. Ayrıca YouTube'un, yayınlanan videonuzla eşleşen kullanıcı tarafından yüklenen videolara uygulayacağı bir politika da belirleyebilirsiniz.

Desteklenen işlemler

Aşağıdaki tabloda, API'nin desteklediği farklı yöntemler gösterilmektedir:

İşlemler
list Sıfır veya daha fazla kaynağın listesini alır (GET).
insert Yeni bir kaynak oluşturur (POST).
update Mevcut bir kaynağı isteğinizdeki verileri yansıtacak şekilde değiştirir (PUT).
bind Bir liveBroadcast kaynağını liveStream kaynağına bağlar veya böyle bir bağlantıyı kaldırır.
transition Bir liveBroadcast kaynağının durumunu değiştirir ve yeni durumla ilişkili tüm işlemleri başlatır. Örneğin, bir yayının durumunu testing olarak değiştirdiğinizde YouTube, söz konusu yayının monitör akışına video aktarmaya başlar.
delete Belirli bir kaynağı kaldırır (DELETE).

Aşağıdaki tabloda, farklı kaynak türleri için desteklenen işlemler tanımlanmıştır. Kaynakları ekleyen, güncelleyen veya silen işlemler için her zaman kullanıcı yetkilendirmesi gerekir. Bazı durumlarda, list yöntemleri hem yetkilendirilmiş hem de yetkisiz istekleri destekler. Bu durumda yetkisiz istekler yalnızca herkese açık verileri alırken, yetkilendirilmiş istekler de o anda kimliği doğrulanmış kullanıcıyla sınırlı olan bilgileri alabilir.

Desteklenen İşlemler
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

Kısmi kaynaklar

API, uygulamaların gereksiz verilerin aktarılmasından, ayrıştırılmasını ve depolanmasını önlemek için kısmi kaynakların alınmasını sağlar ve aslında bunu gerektirir. Bu yaklaşım ayrıca API'nin ağ, CPU ve bellek kaynaklarını daha verimli kullanmasını da sağlar.

part parametresi, YouTube Data API kaynağını alan veya döndüren tüm API istekleri için gerekli bir parametredir. Parametre, API yanıtına dahil edilmesi gereken bir veya daha fazla üst düzey (iç içe yerleştirilmemiş) kaynak özelliğini tanımlar. Örneğin, bir liveStream kaynağı aşağıdaki bölümlere sahiptir:

  • snippet
  • cdn
  • status

Bu parçaların hepsi, iç içe yerleştirilmiş özellikler içeren nesnelerdir. Bu nesneleri, API sunucusunun alabileceği (veya almayabileceği) meta veri alanı grupları olarak düşünebilirsiniz. Bu nedenle, part parametresi, uygulamanızın gerçekten kullandığı kaynak bileşenlerini seçmenizi gerektirir. Bu şartın iki önemli amacı vardır:

  • API sunucusunun uygulamanızın kullanmadığı meta veri alanlarını almaya zaman harcamasını önleyerek gecikmeyi azaltır.
  • Uygulamanızın alabileceği gereksiz veri miktarını azaltarak (veya ortadan kaldırarak) bant genişliği kullanımını azaltır.

Zamanla kaynaklar daha fazla parça ekledikçe bu avantajların artmasının nedeni, uygulamanız yeni kullanıma sunulan mülkleri istemeyecektir.

İpuçları ve en iyi uygulamalar

İçeriğinizle ilgili hak talebinde bulunma

Yayınınız sırasında reklam göstermek istiyorsanız etkinlik başlamadan önce yayın videosuyla ilgili hak talebinde bulunmanız gerekir. İçeriklerle ilgili hak talebinde bulunmak için Content ID programına katılan bir YouTube İçerik İş Ortağı olmanız gerekir.

Canlı yayınlanan videonuzla ilgili hak talebinde bulunma süreci, bir videoyla ilgili hak talebinde bulunmak için uygulanan normal süreçten farklıdır. Canlı bir videoyla ilgili hak talebinde bulunurken, hak talebinizi video var olmadan önce oluşturmanız gerekir. API bu durumu destekler. Hak talebinizi oluşturmanızı sağlayan YouTube Content ID API çağrıları, yayının ömrü dokümanında açıklanmaktadır.

İçeriğinizi önizleme ve test etme

Gelen video akışınızı aldıktan sonra, YouTube bu videoyu iki farklı giden akışta yayınlayabilir:

  • Akışı izleme özelliği, video yayınınızı önizlemenize (ve test etmenize) olanak tanır. Bu, yalnızca sizin erişebildiğiniz gizli bir akıştır. Bir yayını testing aşamasına yalnızca yayının monitör akışı etkinse geçirebilirsiniz. İzleme akışı reklam araları göstermez.

  • Yayın akışı, kitlenize görünür olan akıştır. Yayının gizlilik durumunu public, private veya unlisted olarak ayarlayabilirsiniz. (Özel bir yayını yalnızca izlemeye davet edilen kullanıcılar görebilir. Liste dışı bir yayını ise görüntüleme bağlantısına sahip olan herkes görebilir.)

    Yayın akışını, monitör akışıyla eş zamanlı olarak çalışmayacak şekilde ertelemeyi seçebilirsiniz. Yayın akışını geciktirerek, yayına işaret noktaları eklediğiniz süre üzerinde daha ayrıntılı bir denetime sahip olabilirsiniz.

    Ancak yayın akışının gecikmesi, canlı sunucularınızın görüntüleyen kitlenizle etkileşim kurmasını zorlaştırır. Ayrıca, yayını geciktirmek, izleyicilerin etkinlikle ilgili önemli ayrıntıları yayınınız dışındaki kaynaklardan keşfetme olasılığını artırır. Örneğin, bir spor etkinliğini 60 saniyelik gecikmeyle yayınlıyorsanız izleyiciler yayında görmeden önce diğer gerçek zamanlı haber kaynaklarından önemli anlar hakkında bilgi edinebilir.

YouTube, içeriğinizi test edebilmeniz için yayınınızda izleme akışını etkinleştirmenizi önerir. Yayınınızı ertelemek için tercih ettiğiniz noktalara göre, kitlenizle etkileşim kurmak veya bir olayı gerçek zamanlı olarak aktarmak istediğinizin aksine işaret noktalarının zamanlamasını kontrol etmeniz gerekir.

Yayın sırasında videonun ortasında gösterilen reklamlar yayınlama

Yayın sırasında reklam arasının başlaması için bir işaret noktası ekleyebilirsiniz. bir an önce yapılması gerekir. Reklam arası, YouTube'un yayın sırasında videonun ortasında gösterilen reklamları kullanabilirsiniz.

Reklam araları aşağıdaki özelliklere sahiptir:

  1. Önceden tanımlanmış bir süreye sahip. Bu süreyi cuepoint kaynağının durationSecs Reklam arası sona erdikten sonra izleyiciler canlı yayına geri döner.

  2. Reklam arası gerçekleştiğinde, video oynatıcıda yalnızca videoyu izleyen kullanıcılar için reklam oynatılır işaret noktası eklendiğinde yayın başlar. İzleyiciler sayfayı yenilediğinde reklam yayınlanmıyor yayının oynatıldığı veya ziyaretçiler yayını izlemeye başladıktan sonra işaret noktası eklendi.

Aşağıdaki adımların sırası, yayınınız sırasında reklam arası eklemek için en iyi uygulamayı yansıtır:

Zaman farkını ayarlama

Bir işaret noktası eklerken, işaret noktasının hemen eklenmesini veya işaret noktasının hemen eklenmesini Yayında belirli bir noktaya eklenmelidir. Seçenekleriniz, videonuzun yayın akışı gecikti.

  • Yayın akışınız gecikmeli değilse işaret noktasını hemen ekleyebilir veya walltimeMs özelliğini etkinleştirin.

    • Reklam arasını hemen başlatmak için liveBroadcasts.cuepoint yöntemini çağırın. kaynak görmek için istek gövdesinde insertionOffsetTimeMs mülkünün 0 değerine ayarlayın veya o özellik için bir değer belirtmeyin ve walltimeMs için bir değer

      Önemli: İzleyicilerin gösterilen reklamı görmediğini unutmayın geri dönelim. Reklam içeriği oynatılmadan önce yaklaşık 30 saniyelik bir gecikme olabilir. kullanıcılara görünür. Bu gecikme sırasında yayın akışınız, yayın akışını izlemeniz gerekir. Yayın akışını izleyerek reklam içeriğinin otomatik olarak görüntülenecektir.

    • Reklam arasını belirli bir zamanda başlatmak için liveBroadcasts.cuepoint işlevini çağırın. yöntemini kullanın ve walltimeMs özelliğini kullanabilirsiniz. Özellik değeri, dönem zaman damgasıdır.

  • Yayın akışınız gecikiyorsa işaret noktasını yukarıda açıklandığı gibi bir saat saati belirtin veya saat farkını reklam arasının ne zaman başlayacağını belirler. Zaman farkı, yayınınızdaki bir noktayı belirtir tam olarak ne zaman gösterileceğini belirler.

    Ofset değeri, şunun için monitör akışının başlangıcından itibaren milisaniye cinsinden ölçülür: yayınınıza ekleyin. Yayınınızda test aşaması varsa canlı yayının yayınınız testing durumuna geçtiğinde başlar. Aksi halde Yayınınız live durumuna geçtiğinde akışı izlemeye başlayın.

    İşaret noktası eklerken cuepoint kaynağının insertionOffsetTimeMs özelliğini istediğiniz ofsete ekleyebilirsiniz.

Zaman farkı değerini hesaplama

Ofset değerini almak amacıyla, izleme akışını oynatan oynatıcı için YouTube Oynatıcı API'sının getCurrentTime işlevini çağırın. İşaret noktasını o anki yayın akışına eklemek için alınan değeri kullanın.

Uzaklık süresine ilişkin olası değerler aşağıdaki aralıkla hesaplanabilir:

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

YouTube tam olarak bir işaret noktası ekleyemediğinde Δ, olası zaman ofsetlerinin başında ve sonunda bulunan beş saniyelik bir arabellektir. Örneğin:

  • Bir yayında beş dakikalık bir test aşaması vardır.
  • Yayın akışı, monitör akışından sonra 60 saniye gecikmelidir.
  • Yayıncı, yayın geçişinden dört dakika sonra işaret noktasını yerleştiriyor. live durumu. (Bu, yayın akışının görünür hale gelmesinden üç dakika sonradır.)

Bu durumda, ofset sürelerinin aralığı [(485,000), (535,000)] şeklindedir.

Bu süreler milisaniye cinsinden belirtilir ve aşağıdaki değerler kullanılarak hesaplanır:

  • elapsed_time=540000 – Denetleyici akışı dokuz gündür devam etti dakika (540 saniye, 540.000 milisaniye).liveBroadcasts.cuepoint
  • broadcast_delay=60000 – Yayın akışı 60 saniye veya 60.000 milisaniye gecikmelidir.
  • Δ=5000 – İşaret noktası güvenilir bir şekilde eklenemediğinde beş saniyelik arabellek.

Sorun giderme ve hata giderme

Aşağıdaki yönergelerde, ortaya çıkabilecek belirli sorunların nasıl çözüleceği açıklanmaktadır. Bu listeler için YouTube Live Streaming API - Hatalar bölümünü inceleyin.

  • YouTube geçişle ilişkili işlemleri tamamlarken, bir yayın bir durumdan diğerine geçtiğinde, geçici olarak başka bir duruma atanabilir. Örneğin, bir yayının ready olan durumunu testing olarak değiştirmek için liveBroadcasts.transition isteği gönderirseniz YouTube, yayının durumunu testStarting olarak ayarlar ve ardından durum değişikliğiyle ilişkili işlemleri tamamlar. Bu işlemlerin tümü tamamlandığında YouTube, yayının durumunu testing olarak günceller ve böylece geçişin tamamlandığını belirtir.

    Bir yayın testStarting veya liveStarting durumunda takılı kalırsa liveBroadcasts.delete yöntemini çağırmanız ve yayını silmeniz gerekir. Ardından yeni bir yayın oluşturun, bunu canlı yayınınıza bağlayın ve test sürecine devam edin.

    liveBroadcasts.transition yönteminin belgelerinde belirtildiği gibi, bu yöntemi çağırmadan önce yayınınıza bağlı akışın status.streamStatus özelliğinin değerinin active olduğunu onaylamanız gerekir.