Omówienie interfejsu YouTube Live Streaming API

Interfejs YouTube Live Streaming API umożliwia tworzenie i aktualizowanie wydarzeń na żywo w YouTube oraz zarządzanie nimi. Za jego pomocą można układać harmonogram wydarzeń (transmisji) i łączyć je ze strumieniami wideo, które stanowią właściwą treść przekazu.

Interfejs Live Streaming API w rzeczywistości składa się z interfejsów YouTube Data API i YouTube Content ID API. Interfejs Data API umożliwia użytkownikom YouTube zarządzanie kontami, a interfejs YouTube Content ID API umożliwia interakcję z systemem zarządzania prawami w YouTube. Jednak wszystkie zasoby, które składają się na interfejs Live Streaming API, są używane tylko do tworzenia wydarzeń na żywo i zarządzania nimi.

Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje ułatwiające transmitowanie na żywo w YouTube. Opisuje podstawowe zagadnienia dotyczące YouTube i samego interfejsu API. Znajdziesz tam też omówienie różnych funkcji obsługiwanych przez ten interfejs API.

Podstawowe pojęcia

Komunikaty
Transmisja przedstawia wydarzenie, które można oglądać w YouTube na bieżąco. Transmisja może być też nagrywana i zapisywana jako filmy w YouTube, aby użytkownicy mogli je oglądać po zakończeniu transmisji.
strumienie
Strumień wskazuje treści audio i wideo, które są przekazywane do YouTube. Każda transmisja jest powiązana z jednym strumieniem wideo.
punkty wstawienia reklamy
Punkt wstawienia reklamy to przerwa na reklamę, którą można wstawić do transmisji na żywo.

Przypadki użycia interfejsu API

Poniższa lista sugeruje kilka sposobów korzystania z interfejsu API w aplikacjach:

  • Planowanie transmisji i określanie ustawień. Aplikacja może umożliwiać wstępnie zdefiniowane ustawienia transmisji, a następnie wybieranie ustawień, które mają być stosowane do konkretnej transmisji.

  • Powiązanie strumieni wideo i transmisji.

  • Zapewnij widzom możliwość jednoczesnego definiowania informacji o transmisji i jej filmie (przy użyciu interfejsu YouTube Data API).

  • Uprość przejścia między stanami transmisji (testing, live itd.) i umożliw użytkownikom wstawianie punktów wstawienia.

Zanim rozpoczniesz

  1. Musisz mieć konto Google, aby uzyskać dostęp do usługi Google API Console, zażądać klucza API i zarejestrować aplikację.

  2. Zarejestruj swoją aplikację w Google, aby móc przesyłać żądania interfejsu API.

  3. Po zarejestrowaniu aplikacji wybierz YouTube Data API jako jedną z usług, z których korzysta Twoja aplikacja:

    1. Otwórz API Console i wybierz zarejestrowany właśnie projekt.
    2. Wejdź na stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy interfejs YouTube Data API w wersji 3 jest włączony, a jeśli jesteś partnerem treści – YouTube API.

  4. Zapoznaj się z podstawowymi pojęciami dotyczącymi formatu danych JSON (JavaScript Object Notation). JSON to powszechny, niezależny od języka format danych, który w prosty sposób prezentuje dowolne struktury danych. Więcej informacji znajdziesz na stronie json.org.

Autoryzowanie żądań do interfejsu API

Jak już wspomnieliśmy, interfejs Live Streaming API wykorzystuje funkcje, które są częścią YouTube Data API lub YouTube Content ID API. Możesz przesłać do YouTube metadane, informacje o własności oraz informacje o zasadach dotyczących zasobów za pomocą interfejsu Content ID API. (Przykładowa transmisja wideo na żywo to przykład zasobu). Umożliwia on też zgłaszanie roszczeń do filmów i ustalanie zasad dotyczących reklam.

W tej sekcji opisano wymagania dotyczące żądań wysyłane do Content ID API, które różnią się od wymagań dotyczących autoryzacji pozostałych żądań Live Streaming API.

Dzwonię pod numer Data API
Żądanie do interfejsu API musi zostać autoryzowane przez konto Google, do którego należy kanał YouTube.
Dzwonię pod numer Content ID API
Żądanie interfejsu API musi być autoryzowane przez konto Google, które jest połączone z właścicielem treści, do którego należy kanał YouTube.

Zasoby i typy zasobów

Zasób to konkretna jednostka danych z unikalnym identyfikatorem. W tabeli poniżej opisujemy różne typy zasobów, z których będziesz korzystać za pomocą Live Streaming API. Ogólnie rzecz biorąc, wszystkie te zasoby są zdefiniowane w zasadzie YouTube Data API albo jako YouTube Content ID API. Zasoby liveBroadcast, liveStream i cuepoint są jednak używane tylko do tworzenia wydarzeń na żywo i zarządzania nimi.

Zasoby
liveBroadcast Zawiera informacje o wydarzeniu, które transmitujesz w YouTube. Zasób liveBroadcast jest rozszerzeniem zasobu wideo w YouTube i zawiera metadane filmu na temat transmisji na żywo, ale nie dotyczy innych filmów w YouTube.

Zasób liveBroadcast odpowiada dokładnie jednemu zasobowi wideo YouTube. Zasoby liveBroadcast i video mają ten sam identyfikator. Natomiast po utworzeniu transmisji za pomocą interfejsu Live Streaming API możesz użyć YouTube Data API do podania dodatkowych metadanych filmu.
liveStream Zawiera informacje o strumieniu wideo, które przesyłasz do YouTube. Strumień zawiera treści, które będą udostępniane użytkownikom YouTube. Po utworzeniu zasób liveStream może być powiązany tylko z jednym zasobem liveBroadcast. Podobnie zasób liveBroadcast może być powiązany tylko z jednym zasobem liveStream.
cuepoint Wstawia punkt wstawienia w transmisji wideo, który może spowodować przerwę na reklamę. Za pomocą metody liveBroadcasts.cuepoint możesz wstawić punkt wstawienia podczas transmisji.
video Reprezentuje jeden film w YouTube. Jak wspomnieliśmy wcześniej, zasób liveBroadcast jest rozszerzeniem zasobu video. Za pomocą interfejsu YouTube Data API możesz zaktualizować metadane filmu, np. lokalizację nagrania lub regiony, w których transmisja będzie widoczna.
videoAdvertisingOptions Określa ustawienia reklamy wideo (lub transmisji). Opcje YouTube Content ID API umożliwiają ustawianie opcji reklamowych.
asset Reprezentuje fragment własności intelektualnej, np. film lub odcinek programu. W takim przypadku odpowiedni zasób jest filmem. Za pomocą YouTube Content ID API będziesz tworzyć asset zasoby i nimi zarządzać.
claim Łączy film z dopasowanym zasobem. Tworzysz roszczenie, korzystając z YouTube Content ID API, aby potwierdzić, że jesteś właścicielem transmitowanego filmu.
policy Definiuje reguły, które określają okoliczności, w jakich Twoje treści mają być widoczne lub zablokowane w YouTube. Musisz zastosować zasadę do transmitowanego filmu, a także określić zasadę, którą YouTube będzie stosować do filmów przesłanych przez użytkowników, które pasują do filmu.

Obsługiwane operacje

W tabeli poniżej znajdziesz różne metody obsługiwane przez interfejs API:

Zarządzanie
list Pobiera (GET) listę z 0 lub większą liczbą zasobów.
insert Tworzy (POST) nowy zasób.
update Modyfikuje (PUT) istniejący zasób, aby odzwierciedlał on dane w żądaniu.
bind Łączy zasób liveBroadcast z zasobem liveStream lub usuwa taki link.
transition Zmienia stan zasobu liveBroadcast i inicjuje wszystkie procesy powiązane z nowym stanem. Gdy na przykład zmienisz stan transmisji na testing, YouTube zacznie przesyłać wideo do strumienia monitorowania tej transmisji.
delete Usuwa (DELETE) konkretny zasób.

Poniższa tabela przedstawia operacje, które są obsługiwane w przypadku różnych typów zasobów. Operacje wstawiania, aktualizowania lub usuwania zasobów zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach metody list obsługują zarówno autoryzowane, jak i nieautoryzowane żądania. Nieautoryzowane żądania pobierają tylko dane publiczne. Natomiast autoryzowane żądania mogą pobierać informacje ograniczone tylko do aktualnie uwierzytelnionego użytkownika.

Obsługiwane operacje
list insert update bind transition cuepoint delete
transmisja na żywo
transmisja na żywo

Częściowe zasoby

Interfejs API umożliwia pobieranie informacji o częściach zasobów, a właściwie wymaga, aby aplikacje mogły przenosić, analizować i przechowywać niepotrzebne dane. Takie podejście zapewnia też wydajniejsze wykorzystanie zasobów sieciowych, CPU i pamięci.

Parametr part jest wymagany w przypadku każdego żądania interfejsu API, które pobiera lub zwraca zasób YouTube Data API. Ten parametr określa jedną lub więcej właściwości zasobów najwyższego poziomu (niezagnieżdżonych), które powinny być uwzględnione w odpowiedzi interfejsu API. Na przykład zasób liveStream składa się z następujących elementów:

  • snippet
  • cdn
  • status

Wszystkie te części to obiekty zawierające właściwości zagnieżdżone. Możesz traktować je jako grupy pól metadanych, które serwer interfejsu API może pobrać (lub nie). W związku z tym parametr part wymaga wybrania komponentów zasobów, których aplikacja faktycznie używa. Ten wymóg ma 2 ważne cele:

  • Zmniejsza to opóźnienie, ponieważ nie pozwala czasowi serwera API na pobieranie pól metadanych, których nie używa Twoja aplikacja.
  • Zmniejsza użycie przepustowości, zmniejszając (lub eliminując) niepotrzebne dane, które aplikacja może pobrać.

W miarę dodawania kolejnych zasobów liczba korzyści będzie rosnąć, ponieważ aplikacja nie będzie prosić o wprowadzenie nowych właściwości, których nie obsługuje.

Porady i sprawdzone metody

Zgłaszanie roszczeń do swoich treści

Jeśli chcesz wyświetlać reklamy podczas transmisji, musisz zgłosić do niej prawa przed rozpoczęciem wydarzenia. Aby zgłosić prawa do treści, musisz być partnerem w sieci reklamowej YouTube uczestniczącym w programie Content ID.

Zgłaszanie roszczeń do transmisji na żywo różni się od zwykłego procesu zgłaszania roszczeń do filmów. Zgłaszając roszczenie do filmu na żywo, musisz utworzyć roszczenie, zanim faktycznie ono pojawi się. Interfejs API obsługuje tę funkcję, a dokument życia transmisji zawiera wywołania YouTube Content ID API, które umożliwiają utworzenie roszczenia.

Wyświetlanie podglądu i testowanie treści

Po otrzymaniu przychodzącego strumienia wideo YouTube może go transmitować na 2 różnych strumieniach:

  • Strumień monitorowania umożliwia podgląd (i testowanie) transmisji wideo. To jest strumień prywatny, który jest dostępny tylko dla Ciebie. Transmisję można przenieść do etapu testing tylko wtedy, gdy włączony jest strumień monitorowania transmisji. Strumień monitorowania nie pokazuje przerw na reklamy.

  • Strumień transmisji jest widoczny dla Twoich odbiorców. Ustawienie prywatności transmisji możesz ustawić na public, private lub unlisted. (Transmisja prywatna jest widoczna tylko dla tych użytkowników, którzy zostali bezpośrednio zaproszeni do oglądania, a wiadomości niepubliczne są widoczne dla każdego, kto ma do niej link).

    Możesz opóźnić transmisję, aby nie uruchamiała się jednocześnie ze strumieniem monitorowania. Opóźnienie transmisji sprawia, że masz większą kontrolę nad czasem wstawiania punktów wstawienia.

    Opóźnienie transmisji na żywo utrudnia jednak osobom prowadzącym transmisję na żywo nawiązanie kontaktu z widzami. Poza tym opóźnienie transmisji zwiększa szansę na to, że widzowie zauważą kluczowe szczegóły wydarzenia ze źródeł innych niż Twoja transmisja. Jeśli np. transmitujesz wydarzenie sportowe z 60-sekundowym opóźnieniem, widzowie mogą dowiedzieć się o ważnych momentach z innych źródeł wiadomości w czasie rzeczywistym, zanim faktycznie je zobaczą.

YouTube zaleca włączenie transmisji monitorowania, aby można było przetestować treści. Musisz zdecydować, czy opóźnić transmisję, zależnie od chęci kontrolowania czasu wstawienia reklamy, a nie od nawiązywania kontaktu z odbiorcami czy udostępniania wydarzenia w czasie rzeczywistym.

Wyświetlanie reklam w trakcie transmisji

Podczas transmisji możesz wstawić punkt wstawienia reklamy, który wskazuje, że przerwa na reklamę ma się rozpocząć w jak najkrótszym czasie lub o określonej godzinie. Przerwa na reklamę umożliwia YouTube wyświetlanie reklam w trakcie transmisji.

Przerwy na reklamy mają następujące cechy:

  1. Ma wstępnie zdefiniowany czas ustawiony za pomocą właściwości durationSecs zasobu cuepoint. Po zakończeniu przerwy na reklamę widzowie wracają do transmisji na żywo.

  2. Po przerwie na reklamę reklama w odtwarzaczu jest odtwarzana tylko u widzów, którzy oglądają transmisję po wstawieniu punktu wstawienia. Reklama nie wyświetla się, gdy widzowie odświeżają stronę, na której odtwarza się transmisja, lub gdy użytkownicy zaczynają ją oglądać po wstawieniu punktu wstawienia.

Poniżej przedstawiamy sprawdzone metody wstawiania przerwy na reklamę podczas transmisji:

Ustaw przesunięcie czasu

Wstawiając punkt wstawienia, możesz określić, czy ma być on wstawiony od razu, czy też w określonym miejscu w transmisji. Dostępne opcje zależą od tego, czy strumień transmisji Twojego filmu jest opóźniony.

  • Jeśli Twoja transmisja nie jest opóźniona, możesz wstawić punkt wstawienia reklamy od razu lub użyć właściwości walltimeMs, aby rozpocząć przerwę na reklamę w określonym czasie.

    • Aby natychmiast rozpocząć przerwę na reklamę, wywołaj metodę liveBroadcasts.cuepoint. W zasobie w treści, ustaw wartość właściwości insertionOffsetTimeMs na 0 lub nie określaj wartości tej właściwości ani nie określaj wartości właściwości walltimeMs.

      Ważne: widzowie nie widzą natychmiast reklamy. Może minąć około 30 sekund, zanim treść reklamy stanie się widoczna dla użytkowników. W tym czasie transmisja będzie nadal widoczna dla Twoich widzów i musisz oglądać transmisję, aby określić, kiedy treść reklamy będzie wyświetlana zamiast strumienia monitorowania.

    • Aby rozpocząć przerwę na reklamę o określonej godzinie, wywołaj metodę liveBroadcasts.cuepoint i użyj właściwości walltimeMs, aby określić odpowiedni czas. Wartość właściwości to liczba całkowita reprezentująca sygnaturę czasową epoki.

  • Jeśli Twoja transmisja jest opóźniona, możesz wstawić punkt wstawienia reklamy od razu w sposób opisany powyżej, określić czas zgodnie z powyższym opisem lub określić czas rozpoczęcia przerwy na reklamę. Opóźnienie określa moment, w którym widzowie powinni zobaczyć reklamę.

    Wartość przesunięcia jest mierzona w milisekundach od początku strumienia monitorowania dla Twojej transmisji. Pamiętaj, że jeśli w fazie transmisji znajduje się faza testowania, po jej przejściu do stanu testing rozpocznie się strumień monitorowania. W przeciwnym razie strumień monitora rozpocznie się, gdy Twoja transmisja zmieni stan na live.

    Podczas wstawiania punktu wstawienia ustaw we właściwości insertionOffsetTimeMs zasobu cuepoint odpowiednią wartość przesunięcia.

Obliczanie wartości przesunięcia czasu

Aby pobrać wartość przesunięcia, wywołaj funkcję getCurrentTime interfejsu API odtwarzacza YouTube dla odtwarzacza odtwarzającego strumień monitora. Użyj wartości pobranej, aby wstawić punkt wstawienia w strumieniu do transmisji.

Możliwe wartości czasu przesunięcia są obliczane w następujący sposób:

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

Δ to 5-sekundowy bufor na początku i na końcu możliwych różnic czasowych, gdy YouTube nie może dokładnie wstawić punktu wstawienia. Przykład:

  • Transmisja ma 5-minutowy etap testowania.
  • Transmisja jest opóźniona o 60 sekund po transmisji.
  • Nadawca wstawia punkt wstawienia w ciągu 4 minut od momentu, w którym transmisja przechodzi do stanu live. (po 3 minutach od pojawienia się transmisji).

W tym przypadku możliwy zakres przesunięcia to [(485,000), (535,000)].

Czas jest określany w milisekundach i obliczany za pomocą tych wartości:

  • elapsed_time=540000 – strumień wywołany przez 9 minut (540 sekund, 540 000 milisekund) zostanie wywołany przez metodę liveBroadcasts.cuepoint.
  • broadcast_delay=60000 – strumień transmisji jest opóźniony o 60 sekund lub 60 000 milisekund.
  • Δ=5000 – 5-sekundowy bufor, gdy nie można prawidłowo wstawić punktu wstawienia.

Rozwiązywanie problemów i obsługa błędów

Poniższe wskazówki wyjaśniają, jak rozwiązywać konkretne problemy, które mogą się pojawić. Listę błędów, które mogą zostać zwrócone przez poszczególne metody API, znajdziesz w dokumentacji.

  • Gdy transmisja przechodzi z jednego stanu na inny, może zostać tymczasowo przypisana do innego stanu, podczas gdy YouTube ukończy działania związane z przenoszeniem. Jeśli na przykład wyślesz żądanie liveBroadcasts.transition dotyczące zmiany stanu transmisji z ready na testing, YouTube ustawi jej stan na testStarting, a następnie zakończy działania związane ze zmianą stanu. Po wykonaniu wszystkich tych działań YouTube zaktualizuje stan transmisji na: testing, wskazując, że przenoszenie zostało zakończone.

    Jeśli transmisja utknie w stanie testStarting lub liveStarting, musisz wywołać metodę liveBroadcasts.delete i usunąć transmisję. Następnie utwórz nową transmisję, powiąż ją z transmisją na żywo i kontynuuj testowanie.

    Jak podano w dokumentacji metody liveBroadcasts.transition, przed wywołaniem tej metody musisz sprawdzić, czy wartość właściwości status.streamStatus dla strumienia powiązanego z Twoją transmisją wynosi active.