YouTube Live Streaming API'ya Genel Bakış

YouTube Live Streaming API, YouTube'da canlı etkinlikler oluşturmanızı, mevcut etkinlikleri güncellemenizi ve yönetmenizi sağlar. API'yı kullanarak etkinlikleri (yayınlar) planlayabilir ve bunları gerçek yayın içeriğini temsil eden video akışlarıyla ilişkilendirebilirsiniz.

Live Streaming API aslında 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şimlere olanak tanır. 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ı kolaylaştırmak için uygulama yazmak isteyen geliştiricilere yöneliktir. YouTube ve API'nin temel kavramlarını açıklar. API'nın desteklediği farklı işlevlere genel bir bakış da sunulur.

Temel kavramlar

anonslar
Yayın, YouTube'da gerçekleştiği anda izlenebilen bir etkinliği temsil eder. Ayrıca yayınlar YouTube videoları olarak kaydedilip kaydedilebilir. Böylece kullanıcılar, oluştuktan sonra bunları izleyebilirsiniz.
akışlar
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 listede, uygulamanızda API'yı kullanmanın çeşitli yolları önerilmiştir:

  • 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şkilendirme.

  • Yayıncıların bir yayın ve videosuyla ilgili bilgileri aynı anda tanımlamasını (YouTube Data API kullanarak) sağlar.

  • Yayın durumları arasındaki geçişleri basitleştirin (testing, live vb.) ve kullanıcıların işaret noktaları ekleyebilmesini sağlayın.

Başlamadan önce

  1. Google API Console ürününe 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. Uygulamanızı kaydettikten sonra, uygulamanızın kullandığı hizmetlerden biri olarak YouTube Data API hizmetini seçin:

    1. API Console sayfasına gidin ve yeni kaydettiğiniz projeyi seçin.
    2. Etkin API'ler sayfasını ziyaret edin. API 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. JSON (JavaScript Object Notation - JavaScript Object Notation) veri biçiminin temel kavramlarını öğrenin. JSON, rastgele veri yapılarının basit metin temsilini sağlayan yaygın, 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'sının veya YouTube Content ID API'sinin bir parçası olan işlevleri kullanır. YouTube'a öğelerinizle ilgili meta veriler, sahiplik bilgileri ve politika bilgileri sağlamak için Content ID API'yi kullanabilirsiniz. (Canlı video yayını öğelere bir örnektir.) API sayesinde videolarla ilgili hak talebinde bulunabilir ve videolarınız için reklam politikaları belirleyebilirsiniz.

Bu bölümde, Content ID API istekleri için yetkilendirme gereksinimleri açıklanmaktadır. Bunlar, diğer Live Streaming API isteklerinin yetkilendirilmesine ilişkin gereksinimlerden farklıdır.

Data API aranıyor
API isteği, yayınlayan YouTube kanalının sahibi olan Google Hesabı tarafından yetkilendirilmelidir.
Content ID API aranıyor
API isteği, yayınlanan 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, Live Streaming API kullanarak etkileşimde bulunacağınız farklı kaynak türleri açıklanmaktadır. Teknik olarak bu kaynakların tümü YouTube Data API veya YouTube Content ID API kapsamında tanımlanır. Bununla birlikte liveBroadcast, liveStream ve cuepoint kaynakları yalnızca canlı etkinlikler oluşturmak ve yönetmek için kullanılır.

Kaynaklar
liveBroadcast YouTube'da yayınlamakta olduğunuz bir etkinlikle ilgili bilgileri içerir. liveBroadcast kaynağı, bir YouTube video kaynağının uzantısıdır ve canlı yayına uygun olan ancak diğer YouTube videoları için uygun olmayan video meta verilerini ayarlar.

Bu nedenle, liveBroadcast kaynağı tam olarak bir YouTube video kaynağına karşılık gelir. Aslında liveBroadcast kaynağı ve video kaynağı aynı kimliği paylaşır. Ayrıca, Live Streaming API'yi kullanarak yayını oluşturduktan sonra videoyla ilgili ek meta veriler sağlamak için YouTube Data API'yi kullanabilirsiniz.
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. Bir liveStream kaynağı oluşturulduktan sonra tam olarak bir liveBroadcast kaynağına bağlanabilir. (Benzer şekilde, liveBroadcast kaynağı yalnızca bir liveStream kaynağına bağlanabilir.
cuepoint Yayın video akışına bir işaret noktası ekler. Bu nokta, reklam arasını tetikleyebilir. Yayın sırasında işaret noktası eklemek için liveBroadcasts.cuepoint yöntemini kullanın.
video Tek bir YouTube videosunu temsil eder. Yukarıda belirtildiği gibi, liveBroadcast kaynağı, video kaynağının bir uzantısıdır. Kayıt konumu veya yayının görüntülenebileceği bölgeler gibi videoyla ilgili meta verileri güncellemek için YouTube Data API'yi kullanabilirsiniz.
videoAdvertisingOptions Bir video (veya yayın) için reklam ayarlarını tanımlar. Reklamcılık seçeneklerini belirlemek için YouTube Content ID API kullanılır.
asset Bir fikri mülkiyet parçasını (ör. film veya programın bir bölümü) temsil eder. Bu durumda, yayın videosu öğedir. asset kaynaklarını oluşturmak ve yönetmek için YouTube Content ID API öğelerini kullanacaksınız.
claim Bir videoyu videonun eşleştiği bir öğeye bağlar. Kendinizi yayın videosunun sahibi olarak tanıtmak için YouTube Content ID API kullanarak bir hak talebi oluşturursunuz.
policy İçeriğinizin YouTube'da görüntülenebilir olmasını veya YouTube'da görünmesinin engellenmesini istediğiniz koşulları belirten 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 kaynak içeren bir liste alır (GET).
insert Yeni kaynak oluşturur (POST).
update Mevcut bir kaynağı, talebinizdeki 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, videoyu bu yayının monitör akışına 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ımlanmaktadır. Kaynakları ekleyen, güncelleyen veya silen işlemler her zaman kullanıcı yetkilendirme gerektirir. Bazı durumlarda, list yöntemleri hem yetkili hem de yetkisiz istekleri destekler. Yetki verilmiş istekler, kimliği doğrulanmış kullanıcılarla sınırlı olan bilgileri de alabilirken, yetkisiz isteklerin yalnızca herkese açık verileri alması sağlanır.

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

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 bunu gerektirir. Bu yaklaşım aynı zamanda 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 zorunlu bir parametredir. Parametre, bir API yanıtına eklenmesi gereken bir veya daha fazla üst düzey (iç içe yerleştirilmiş) kaynak özelliğini tanımlar. Örneğin, bir liveStream kaynağı aşağıdaki bölümlerden oluşur:

  • snippet
  • cdn
  • status

Bu parçaların tümü, iç içe yerleştirilmiş özellikler içeren nesnelerdir ve bu nesneleri, API sunucusunun alabileceği (veya almayabileceği) meta veri alanı grupları olarak düşünebilirsiniz. Dolayısıyla, part parametresi, uygulamanızın gerçekte 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.

Kaynaklar zamanla daha fazla parça ekledikçe, uygulamanız desteklemediği yeni özellikler için istekte bulunmayacağından, bu avantajlar da zamanla artacaktır.

İpuçları ve en iyi uygulamalar

İçeriğinizle ilgili hak talebinde bulunun

Yayınınız sırasında reklam göstermek isterseniz etkinlik başlamadan önce yayınlanan videoyla ilgili hak talebinde bulunmanız gerekir. İçerik üzerinde 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, videoyla ilgili normal hak talebinde bulunma sürecinden farklıdır. Canlı videoyla ilgili hak talebinde bulunurken videonun gerçekten mevcut olmaması için hak talebinizi oluşturmanız gerekir. API bunu destekler. Yayın ömrü belgesinde, hak talebinizi oluşturmanıza olanak tanıyan YouTube Content ID API çağrıları 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:

  • İzleme akışı, 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 geçirebilmek için yayının izleme akışı etkinleştirilmiş olmalıdır. İzleme akışı, reklam aralarını göstermez.

  • Yayın akışı, kitleniz tarafından görülebilen akıştır. Yayının gizlilik durumunu public, private veya unlisted olarak ayarlayabilirsiniz. (Gizli bir yayın, yalnızca onu izlemeye açıkça davet edilmiş kullanıcılar tarafından görülebilirken, liste dışı bir yayın, onu görüntüleme bağlantısına sahip olan herkes tarafından görülebilir.)

    Yayın akışını, monitör akışıyla eş zamanlı olarak yayınlanmayacak şekilde geciktirebilirsiniz. Yayın akışını geciktirerek yayına işaret noktaları eklediğiniz süre üzerinde daha hassas bir denetime sahip olabilirsiniz.

    Ancak yayın akışını ertelemek canlı sunucularınızın izleyicilerinizle etkileşim kurmasını zorlaştırır. Ayrıca yayını ertelemek, görüntüleyenlerin yayınınız dışındaki kaynaklardan olayla ilgili önemli ayrıntıları keşfetme olasılığını artırır. Örneğin, bir spor karşılaşmasını 60 saniyelik gecikmeyle yayınlıyorsanız izleyiciler, o önemli anları yayında görmeden önce diğer gerçek zamanlı haber kaynaklarından bu olaydaki önemli anları öğrenebilirler.

YouTube, içeriğinizi test edebilmeniz için yayınınızda monitör akışını etkinleştirmenizi önerir. Yayınınızı, kitlenizle etkileşime geçme veya bir etkinliği gerçek zamanlı olarak sunma isteğinizden ziyade işaret noktalarının zamanlamasını kontrol etme isteğinize bağlı olarak da geciktirip yayınlamayacağınızı seçmelisiniz.

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

Yayın sırasında, yayında bir reklam arasının mümkün olan en kısa sürede veya belirli bir zamanda başlaması gerektiğini belirtmek için bir işaret noktası ekleyebilirsiniz. Reklam arası, YouTube'un yayın sırasında videonun ortasında gösterilen reklamları yayınlamasını sağlar.

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

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

  2. Reklam arası gerçekleştiğinde reklam, yalnızca işaret noktası eklendiğinde yayını izleyen izleyiciler için video oynatıcıda oynatılır. Görüntüleyenler yayının oynatıldığı sayfayı yenilediğinde veya işaret noktası eklendikten sonra ziyaretçiler yayını izlemeye başladığında reklam çalışmaz.

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

Zaman ofsetlerini ayarla

İşaret noktası eklerken o noktanın hemen veya yayındaki belirli bir noktaya 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 gecikmezse işaret noktasını hemen ekleyebilir veya reklam arasının belirli bir zamanda başlatılması 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 değer belirtmeyin ve walltimeMs özelliği için değer belirtmeyin.

      Önemli: İzleyicilerin, gösterilen reklam içeriğini hemen görmediğini unutmayın. Reklam içeriğinin kullanıcılar tarafından görülebilmesi için yaklaşık 30 saniyelik bir gecikme olabilir. Bu gecikme sırasında yayın akışınız izleyicilerinize görünmeye devam eder ve reklam içeriğinin monitör akışınız yerine gerçekten ne zaman gösterileceğ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, sıfır zaman damgasını temsil eden bir 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 zamanı belirtebilir veya reklam arasının ne zaman başlayacağını belirlemek için zaman farkı belirleyebilirsiniz. Zaman farkı, yayınınızda izleyicilerin bir reklamı görmesi gereken noktayı belirtir.

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

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

Zaman farkı değerini hesaplama

Ofset değerini almak amacıyla, monitör akışını oynatan oynatıcı için YouTube Oynatıcı API'sının getCurrentTime işlevini çağırın. Alınan değeri kullanarak işaret noktasını o anda yayın akışına ekleyin.

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

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

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

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

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

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

  • elapsed_time=540000liveBroadcasts.cuepoint yöntemi çağrıldığında izleme akışı, dokuz dakika (540 saniye, 540.000 milisaniye) boyunca çalışır.
  • broadcast_delay=60000 – Yayın akışı 60 saniye, yani 60.000 milisaniye gecikir.
  • Δ=5000: İşaret noktasının güvenilir bir şekilde yerleştirilemediği 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. Her bir API yönteminin döndürebileceği hataların listesi için hata dokümanlarına da bakın.

  • Bir yayın bir durumdan diğerine geçirildiğinde, YouTube geçişle ilişkili işlemleri tamamlarken yayına geçici olarak başka bir durum atanabilir. Örneğin, bir yayının durumunu ready iken 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. Tüm bu işlemler tamamlandığında YouTube, yayının durumunu testing olarak güncelleyerek 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 dokümanlarında 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.