YouTube Live Streaming API'ya Genel Bakış

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

Canlı Yayın API'si aslında YouTube Data API ve YouTube Content ID API'nin bileşenlerinden oluşur. Data API, YouTube kullanıcılarının YouTube hesaplarını yönetmesine olanak tanırken YouTube Content ID API, YouTube'un hak yönetimi sistemiyle etkileşim kurulmasını sağlar. Ancak Live Streaming API'yi oluşturan tüm kaynaklar yalnızca canlı etkinlikler oluşturmak ve yönetmek için kullanılır.

Bu belge, YouTube'da canlı yayın yapmayı kolaylaştıran uygulamalar yazmak isteyen geliştiriciler içindir. YouTube ve API ile ilgili temel kavramları açıklar. Ayrıca API'nin desteklediği farklı işlevlere genel bir bakış sunar.

Temel kavramlar

yayınlar

Yayın, YouTube'da canlı olarak izlenebilen bir etkinliği ifade eder. Yayınlar kaydedilip YouTube videosu olarak da saklanabilir. Böylece kullanıcılar yayınları daha sonra izleyebilir.

dinlenme

Yayın, YouTube'a iletilen ses ve video içeriğini tanımlar. Her yayın bir video akışıyla ilişkilendirilir.

işaret noktaları

cuepoint, canlı yayına eklenebilen bir reklam arasını temsil eder.

API kullanım alanları

Aşağıdaki listede, API'yi uygulamanızda kullanmanın birkaç yolu önerilmektedir:

• Yayınları planlayabilir ve yayın ayarlarını tanımlayabilirsiniz. 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şkilendirme

• Yayıncıların, bir yayın ve videosuyla ilgili bilgileri (YouTube Data API'yi kullanarak) aynı anda tanımlamasına olanak tanır.

• Yayın durumları (ör. testing veya live) arasındaki geçişleri basitleştirin ve kullanıcıların işaret noktaları eklemesine olanak tanıyın.

Başlamadan önce

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

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

3. Uygulamanızı kaydettikten sonra, uygulamanızın kullandığı hizmetlerden biri olarak YouTube Data API simgesini seçin:

   1. Cloud console sayfasına gidip yeni kaydettiğiniz projeyi seçin.
   2. Etkin API'ler sayfasını ziyaret edin. API listesinde, YouTube Data API v3'ün ve YouTube içerik ortağıysanız YouTube Content ID API'nin durumunun AÇIK olduğundan emin olun.

4. JavaScript Object Notation (JSON) veri biçiminin temel kavramlarını öğrenme JSON, rastgele veri yapılarını basit metin biçiminde sunan, yaygın şekilde kullanılan ve 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 Stream API, teknik olarak YouTube Data API veya YouTube Content ID API'nin bir parçası olan işlevleri kullanır. Öğelerinizle ilgili meta verileri, sahiplik bilgilerini ve politika bilgilerini YouTube'a sağlamak için Content ID API'yi kullanabilirsiniz. (Canlı video yayını, bir öğe örneğidir.) API, videolar için hak talebinde bulunmanıza ve videolarınız için reklam politikaları belirlemenize de olanak tanır.

Bu bölümde, Content ID API için gönderilen isteklerin yetkilendirme koşulları açıklanmaktadır. Bu koşullar, diğer Live Streaming API isteklerini yetkilendirme koşullarından farklıdı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 YouTube kanalının sahibi olan içerik sahibine bağlı bir Google Hesabı tarafından yetkilendirilmelidir.

Kaynaklar ve kaynak türleri

Kaynak, benzersiz tanımlayıcısı olan bağımsız bir veri varlığıdır. Aşağıdaki tabloda, Live Streaming API kullanarak etkileşimde bulunacağınız farklı kaynak türleri açıklanmaktadır. Teknik olarak, bu kaynakların tümü aslında YouTube Data API veya YouTube Content ID API'nin bir parçası olarak tanımlanır. Ancak liveBroadcast, liveStream ve cuepoint kaynakları yalnızca canlı etkinlik oluşturmak ve yönetmek için kullanılır.

Desteklenen işlemler

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

Aşağıdaki tabloda, farklı kaynak türleri için desteklenen işlemler belirtilmiştir. Kaynak ekleyen, güncelleyen veya silen işlemler için her zaman kullanıcı yetkilendirmesi gerekir. Bazı durumlarda, list yöntemleri hem yetkili hem de yetkisiz istekleri destekler. Yetkisiz istekler yalnızca herkese açık verileri alırken yetkili istekler, kimliği doğrulanmış kullanıcıyla sınırlı bilgileri de alabilir.

Kısmi kaynaklar

API, uygulamaların gereksiz verileri aktarmasını, ayrıştırmasını ve depolamasını önlemek için kısmi kaynakların alınmasına izin verir ve aslında bunu zorunlu kılar. Bu yaklaşım, API'nin ağ, CPU ve bellek kaynaklarını daha verimli kullanmasını da sağlar.

part parametresi, bir YouTube Data API kaynağını alan veya döndüren tüm API istekleri için zorunlu bir parametredir. Parametre, bir 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ğında aşağıdaki bölümler bulunur:

• snippet
• cdn
• status

Bu bölümlerin tümü, iç içe yerleştirilmiş özellikler içeren nesnelerdir. Bu nesneleri, API sunucusunun alabileceği (veya alamayacağı) meta veri alanları 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ı almak için 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.

Zaman içinde kaynaklar daha fazla bölüm ekledikçe uygulamanız desteklemediği yeni özellikleri istemeyeceği için bu avantajlar daha da artacaktır.

İpuçları ve en iyi uygulamalar

İçeriğiniz için hak talebinde bulunma

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

Canlı yayın videonuzu talep etme süreci, normal video talep etme sürecinden farklıdır. Canlı video üzerinde hak talebinde bulunurken, video gerçekten yayınlanmadan önce hak talebinizi oluşturmanız gerekir. API bunu destekler ve Yayın ömrü dokümanında, hak talebinizi oluşturmanızı sağlayan YouTube Content ID API çağrıları açıklanır.

İçeriğinizi önizleme ve test etme

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

• İzleme yayını, video yayınınızı önizlemenize (ve test etmenize) olanak tanır. Bu, yalnızca sizin erişebileceğiniz özel bir akıştır. Bir yayını testing aşamasına geçirebilmek için yayının izleme yayınının etkinleştirilmiş olması gerekir. Monitör akışında reklam araları gösterilmez.

• Yayın akışı, kitlenizin görebildiği akıştır. Yayın gizlilik durumunu public, private veya unlisted olarak ayarlayabilirsiniz. (Gizli yayınlar yalnızca izlemeye açıkça davet edilen kullanıcılara görünürken liste dışı yayınlar, görüntüleme bağlantısına sahip olan herkese görünür.)

  Yayın akışını, monitör akışıyla aynı anda çalışmayacak şekilde geciktirmeyi seçebilirsiniz. Yayın akışını geciktirerek, yayına işaret noktaları eklediğiniz zaman üzerinde daha ayrıntılı kontrole sahip olabilirsiniz.

  Ancak yayın akışını geciktirmek, canlı sunucularınızın izleyici kitlenizle etkileşim kurmasını zorlaştırır. Ayrıca, yayını geciktirmek izleyicilerin etkinlik hakkındaki önemli ayrıntıları yayınınız dışındaki kaynaklardan öğrenme olasılığını artırır. Örneğin, bir spor etkinliğini 60 saniyelik gecikmeyle yayınlıyorsanız izleyiciler, etkinlikteki önemli anları yayında görmeden önce diğer anlık haber kaynaklarından öğrenebilir.

YouTube, içeriğinizi test edebilmeniz için yayınınızda izleme akışını etkinleştirmenizi önerir. Yayınınıza gecikme ekleyip eklemeyeceğinizi, kitlenizle etkileşim kurma veya bir etkinliği anlık olarak aktarma isteğinize değil, işaret noktalarının zamanlamasını kontrol etme isteğinize göre belirlemelisiniz.

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

Yayın sırasında, yayında en kısa sürede veya belirtilen bir zamanda reklam arası başlatılması gerektiğini belirtmek için cuepoint ekleyebilirsiniz. Reklam arası, YouTube'un yayın sırasında ara reklamlar yayınlamasına olanak tanır.

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

1. cuepoint kaynağının durationSecs özelliğini kullanarak ayarladığınız önceden tanımlanmış bir süresi vardır. Reklam arası sona erdikten sonra izleyiciler canlı yayına geri döner.

2. Reklam arası gerçekleştiğinde, yalnızca ipucu noktası yerleştirilirken yayını izleyen kullanıcılara video oynatıcıda reklam gösterilir. İzleyiciler, yayının oynatıldığı sayfayı yenilediğinde veya ziyaretçiler, işaret noktası eklendikten sonra yayını izlemeye başladığında reklam yayınlanmaz.

Aşağıdaki adımların sırası, yayınınız sırasında reklam arası eklemeyle ilgili en iyi uygulamayı yansıtmaktadır:

Zaman farklarını ayarlama

İşaret noktası eklerken, hemen mi yoksa yayının belirli bir noktasında mı eklenmesi gerektiğini belirtebilirsiniz. Seçenekleriniz, videonuzun yayın akışının gecikmeli olup olmamasına bağlıdır.

• Yayın akışınız gecikmeli değilse işaret noktasını hemen ekleyebilir veya reklam arasının belirli bir zamanda başlaması için walltimeMs özelliğini kullanabilirsiniz.

  • Reklam arasını hemen başlatmak için liveBroadcasts.cuepoint yöntemini çağırın. İstek gövdesindeki kaynakta, insertionOffsetTimeMs özelliğinin değerini 0 olarak ayarlayın veya bu özellik için bir değer belirtmeyin ve walltimeMs özelliği için bir değer belirtmeyin.

    Önemli: İzleyicilerin, oluşturulan reklam içeriğini hemen görmeyeceğini unutmayın. Reklam içeriğinin kullanıcılara gösterilmesi yaklaşık 30 saniye sürebilir. Bu gecikme sırasında yayın akışınız izleyicileriniz tarafından görünmeye devam eder. Reklam içeriğinin, monitör akışınız yerine ne zaman gösterildiğini belirlemek için yayın akışını izlemeniz gerekir.

  • Reklam arasını belirli bir zamanda başlatmak için liveBroadcasts.cuepoint yöntemini çağırın ve istenen zamanı belirtmek için walltimeMs özelliğini kullanın. Özellik değeri, bir epoch zaman damgasını temsil eden tam sayıdır.

• Yayın akışınız gecikirse işaret noktasını yukarıda açıklandığı gibi hemen ekleyebilir, yukarıda açıklandığı gibi bir saat belirtebilir veya reklam arasının ne zaman başlayacağını belirlemek için bir zaman farkı belirtebilirsiniz. Zaman farkı, yayınınızda izleyicilerin reklam görmesi gereken bir noktayı belirtir.

  Ofset değeri, yayınınız için monitör akışının başlangıcından itibaren milisaniye cinsinden ölçülür. Yayınınızda test aşaması varsa izleme yayınının, yayınınız testing durumuna geçtiğinde başladığını unutmayın. Aksi takdirde, izleme yayınınız, yayınınız live durumuna geçtiğinde başlar.

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

Zaman farkı değerini hesaplama

Ofset değerini almak için, izleme yayınını oynatan oynatıcıya yönelik YouTube Player API'nin getCurrentTime işlevini çağırın. Alınan değeri kullanarak işaret noktasını o anda yayın akışına ekleyin.

Ofset süresi için olası değerler aşağıdaki aralık olarak hesaplanabilir:

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

Δ, YouTube'un bir işaret noktasını tam olarak ekleyemediği durumlarda, olası zaman farklarının başında ve sonunda beş saniyelik bir aralıktır. Örneğin:

• Yayınlarda beş dakikalık bir test aşaması vardır.
• Yayın akışı, izleme akışından 60 saniye sonra başlar.
• Yayıncı, yayın live durumuna geçtikten dört dakika sonra işaret noktasını ekliyor. (Bu, yayın akışının görünür hâle gelmesinden üç dakika sonrasıdır.)

Bu durumda, olası ofset süresi aralığı [(485,000), (535,000)] olur.

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

• elapsed_time=540000: liveBroadcasts.cuepoint yöntemi çağrıldığında izleme akışı dokuz dakika (540 saniye, 540.000 milisaniye) boyunca çalışmıştır.
• broadcast_delay=60000: Yayın akışı 60 saniye veya 60.000 milisaniye geciktirilir.
• Δ=5000: İşaret noktası güvenilir bir şekilde eklenemediğinde kullanılan beş saniyelik arabellek.

Sorun giderme ve hata işleme

Aşağıdaki yönergelerde, ortaya çıkabilecek belirli sorunların nasıl çözüleceği açıklanmaktadır. Her bir API yönteminin döndürebileceği hataların listesi için YouTube Live Streaming API - Hatalar bölümüne bakın.

• Bir yayın bir durumdan diğerine geçerken YouTube, geçişle ilişkili işlemleri tamamlarken geçici olarak başka bir durum atanabilir. Örneğin, bir yayının durumunu ready'den testing'ye 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 geçişin tamamlandığını belirtir.

  Bir yayın testStarting veya liveStarting durumuyla 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 dokümanlarında belirtildiği gibi, bu yöntemi çağırmadan önce yayınınızla ilişkili akışın status.streamStatus özelliğinin değerinin active olduğunu doğrulamanız gerekir.