Omówienie interfejsu YouTube Live Streaming API

Interfejs API YouTube do transmitowania na żywo umożliwia tworzenie i aktualizowanie wydarzeń na żywo na 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 składa się z komponentów interfejsu YouTube Data API i interfejsu YouTube Content ID API. Interfejs Data API umożliwia użytkownikom YouTube zarządzanie kontami YouTube, a YouTube Content ID API – interakcje z systemem zarządzania prawami YouTube. Wszystkie zasoby, które składają się na interfejs Live Streaming API, służą jednak 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 transmisje na żywo w YouTube. Wyjaśnia podstawowe pojęcia związane z YouTube i samym interfejsem API. Zawiera też omówienie różnych funkcji obsługiwanych przez interfejs API.

Podstawowe pojęcia

transmisje

Transmisja to wydarzenie, które można oglądać na YouTube na żywo. Transmisje można też nagrywać i zapisywać jako filmy na YouTube, aby użytkownicy mogli je obejrzeć po zakończeniu.

strumienie

Strumień identyfikuje treści audio-wideo przesyłane do YouTube. Każda transmisja jest powiązana z 1 strumieniem wideo.

punkty wstawienia

cuepoint to przerwa na reklamę, którą można wstawić do transmisji na żywo.

Przypadki użycia interfejsu API

Poniższa lista zawiera kilka sposobów użycia interfejsu API w aplikacji:

• Planowanie transmisji i definiowanie ustawień transmisji. Aplikacja może umożliwiać użytkownikom wstępne definiowanie ustawień transmisji, a następnie wybieranie ustawień, które mają być stosowane do konkretnej transmisji.

• Łączenie strumieni wideo i transmisji.

• Umożliwianie nadawcom jednoczesnego definiowania informacji o transmisji i jej filmie (za pomocą interfejsu YouTube Data API).

• Upraszczanie przejść między stanami transmisji (np. testing lub live) i umożliwianie użytkownikom wstawiania punktów wstawienia.

Zanim rozpoczniesz

1. Aby uzyskać dostęp do Google Cloud console, poprosić o klucz interfejsu API i zarejestrować aplikację, musisz mieć konto Google.

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

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

   1. Otwórz Cloud console i wybierz projekt, który właśnie zarejestrowałeś.
   2. Otwórz stronę Włączone interfejsy API. Na liście interfejsów API sprawdź, czy interfejs YouTube Data API w wersji 3 jest WŁĄCZONY oraz, jeśli jesteś partnerem YouTube, czy interfejs YouTube Content ID API jest WŁĄCZONY.

4. Zapoznaj się z podstawowymi pojęciami dotyczącymi formatu danych JavaScript Object Notation (JSON). JSON to popularny, niezależny od języka format danych, który zapewnia prostą tekstową reprezentację dowolnych struktur danych. Więcej informacji znajdziesz na stronie json.org.

Autoryzowanie żądań do interfejsu API

Jak wspomnieliśmy powyżej, interfejs Live Streaming API korzysta z funkcji, które technicznie są częścią interfejsu YouTube Data API lub interfejsu YouTube Content ID API. Za pomocą interfejsu Content ID API możesz przekazywać do YouTube metadane, informacje o własności i informacje o zasadach dotyczące Twoich zasobów. (Przykładem zasobu jest transmisja wideo na żywo). Interfejs API umożliwia też zgłaszanie roszczeń do filmów i ustawianie zasad dotyczących reklam dotyczących Twoich filmów.

W tej sekcji opisujemy wymagania dotyczące autoryzacji żądań do interfejsu Content ID API, które różnią się od wymagań dotyczących autoryzacji innych żądań do interfejsu Live Streaming API.

Wywoływanie interfejsu Data API

Żądanie do interfejsu API musi być autoryzowane przez konto Google, które jest właścicielem kanału YouTube nadającego transmisję.

Wywoływanie interfejsu Content ID API

Żądanie do interfejsu API musi być autoryzowane przez konto Google powiązane z właścicielem treści, który jest właścicielem kanału YouTube nadającego transmisję.

Zasoby i typy zasobów

Zasób to pojedyncza encja danych z unikalnym identyfikatorem. W tabeli poniżej opisujemy różne typy zasobów, z którymi będziesz wchodzić w interakcje za pomocą Live Streaming API. Technicznie wszystkie te zasoby są zdefiniowane jako część interfejsu YouTube Data API lub interfejsu YouTube Content ID API. Zasoby liveBroadcast, liveStream i cuepoint służą jednak tylko do tworzenia wydarzeń na żywo i zarządzania nimi.

Obsługiwane operacje

W tabeli poniżej znajdziesz informacje o różnych metodach obsługiwanych przez interfejs API:

W tabeli poniżej znajdziesz informacje o operacjach obsługiwanych w przypadku różnych typów zasobów. Operacje, które wstawiają, aktualizują lub usuwają zasoby, zawsze wymagają autoryzacji użytkownika. W niektórych przypadkach metody list obsługują zarówno autoryzowane, jak i nieautoryzowane żądania. W przypadku nieautoryzowanych żądań pobierane są tylko dane publiczne, a w przypadku autoryzowanych żądań można też pobierać informacje, które są ograniczone do uwierzytelnionego użytkownika.

Częściowe zasoby

Interfejs API umożliwia, a nawet wymaga, pobieranie częściowych zasobów, aby aplikacje nie musiały przesyłać, analizować i zapisywać niepotrzebnych danych. Dzięki temu interfejs API wydajniej wykorzystuje zasoby sieciowe, procesor i pamięć.

Parametr part jest wymagany w przypadku każdego żądania do interfejsu API, które pobiera lub zwraca zasób YouTube Data API. Parametr identyfikuje co najmniej 1 właściwość zasobu najwyższego poziomu (niezagnieżdżoną), która powinna być uwzględniona w odpowiedzi interfejsu API. Na przykład zasób liveStream ma te części:

• snippet
• cdn
• status

Wszystkie te części są obiektami zawierającymi zagnieżdżone właściwości. Możesz je traktować jako grupy pól metadanych, które serwer interfejsu API może (ale nie musi) pobierać. W związku z tym parametr part wymaga wybrania komponentów zasobu, z których faktycznie korzysta Twoja aplikacja. To wymaganie służy 2 ważnym celom:

• Zmniejsza opóźnienie, ponieważ serwer interfejsu API nie traci czasu na pobieranie pól metadanych, których Twoja aplikacja nie używa.
• Zmniejsza wykorzystanie przepustowości, ponieważ ogranicza (lub eliminuje) ilość niepotrzebnych danych, które aplikacja może pobierać.

Z czasem, gdy do zasobów będą dodawane kolejne części, te korzyści będą się zwiększać, ponieważ aplikacja nie będzie prosić o nowo wprowadzone właściwości, których nie obsługuje.

Porady i sprawdzone metody

Zgłaszanie roszczeń do treści

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

Proces zgłaszania roszczeń do filmu z transmisji na żywo różni się od zwykłego procesu zgłaszania roszczeń do filmu. Podczas zgłaszania roszczenia do transmisji na żywo musisz utworzyć roszczenie, zanim film będzie istniał. Interfejs API obsługuje tę funkcję, a dokument dotyczący cyklu życia transmisji wyjaśnia 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 transmitować ten film w 2 różnych strumieniach wychodzących:

• Strumień monitora umożliwia wyświetlanie podglądu (i testowanie) transmisji wideo. Jest to strumień prywatny, do którego masz dostęp tylko Ty. Transmisję można przełączyć w fazę testing tylko wtedy, gdy jest włączony strumień monitora. W strumieniu monitora nie są wyświetlane przerwy na reklamę.

• Strumień transmisji to strumień widoczny dla odbiorców. Możesz ustawić stan prywatności transmisji na public, private lub unlisted. (Transmisja prywatna jest widoczna tylko dla użytkowników, którzy zostali wyraźnie zaproszeni do jej obejrzenia, a transmisja niepubliczna jest widoczna dla każdego, kto ma link do jej obejrzenia).

  Możesz opóźnić strumień transmisji, aby nie był odtwarzany jednocześnie ze strumieniem monitora. Opóźnienie strumienia transmisji pozwala dokładniej kontrolować czas wstawiania punktów wstawienia do transmisji.

  Opóźnienie strumienia transmisji utrudnia jednak prezenterom na żywo interakcję z widzami. Ponadto opóźnienie transmisji zwiększa prawdopodobieństwo, że widzowie dowiedzą się o najważniejszych szczegółach wydarzenia z innych źródeł niż Twoja transmisja. Jeśli na przykład transmitujesz wydarzenie sportowe z 60-sekundowym opóźnieniem, widzowie mogą dowiedzieć się o najważniejszych momentach wydarzenia z innych źródeł informacji w czasie rzeczywistym, zanim zobaczą je w transmisji.

YouTube zaleca włączenie strumienia monitora w transmisji, aby można było przetestować treści. Powinieneś zdecydować, czy opóźnić transmisję, w zależności od tego, czy bardziej zależy Ci na kontrolowaniu czasu punktów wstawienia, czy na interakcji z odbiorcami lub relacjonowaniu wydarzenia w czasie rzeczywistym.

Wyświetlanie reklam w trakcie filmu podczas strumienia transmisji

Podczas transmisji możesz wstawić cuepoint , aby wskazać, że przerwa na reklamę powinna się rozpocząć w transmisji jak najszybciej lub o określonej godzinie. Przerwa na reklamę umożliwia YouTube wyświetlanie reklam w trakcie filmu podczas transmisji.

Przerwy na reklamę mają te cechy:

1. Mają zdefiniowany czas trwania, który ustawiasz za pomocą właściwości cuepoint zasobu durationSecs. Po zakończeniu przerwy na reklamę widzowie wracają do transmisji na żywo.

2. Gdy nastąpi przerwa na reklamę, reklama będzie odtwarzana tylko w odtwarzaczu wideo dla widzów, którzy oglądają transmisję w momencie wstawienia punktu wstawienia. Reklama nie będzie się wyświetlać, gdy widzowie odświeżą stronę na której jest odtwarzana transmisja, lub gdy odwiedzający zaczną oglądać transmisję po wstawieniu punktu wstawienia.

Kolejność czynności opisana poniżej odzwierciedla sprawdzoną metodę wstawiania przerwy na reklamę podczas transmisji:

Ustawianie przesunięć czasowych

Podczas wstawiania punktu wstawienia możesz określić, że ma on zostać wstawiony od razu lub że ma zostać wstawiony w określonym momencie transmisji. Opcje zależą od tego, czy strumień transmisji filmu jest opóźniony.

• Jeśli strumień transmisji nie jest opóźniony, możesz wstawić punkt wstawienia od razu lub użyć właściwości walltimeMs , aby przerwa na reklamę rozpoczęła się o określonej godzinie.

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

    Ważne: pamiętaj, że widzowie nie widzą od razu treści reklamy. Zanim treść reklamy będzie widoczna dla użytkowników, może upłynąć około 30 sekund. W tym czasie strumień transmisji będzie nadal widoczny dla twoich widzów. Musisz oglądać strumień transmisji, aby określić, kiedy treść reklamy będzie się wyświetlać zamiast strumienia monitora.

  • Aby rozpocząć przerwę na reklamę o określonej godzinie, wywołaj metodę liveBroadcasts.cuepoint i użyj walltimeMs właściwości, aby określić żądaną godzinę. Wartość właściwości to liczba całkowita reprezentująca an epoch timestamp.

• Jeśli strumień transmisji jest opóźniony, możesz wstawić punkt wstawienia od razu (jak opisano powyżej) określić godzinę (jak opisano powyżej) lub określić przesunięcie czasowe, aby określić, kiedy rozpocznie się przerwa na reklamę. Przesunięcie czasowe określa moment w transmisji w którym widzowie powinni zobaczyć reklamę.

  Wartość przesunięcia jest mierzona w milisekundach od początku strumienia monitora transmisji dla transmisji. Jeśli transmisja ma fazę testowania, strumień monitora rozpoczyna się, gdy transmisja przechodzi do stanu testing. W przeciwnym razie strumień monitora rozpoczyna się, gdy transmisja przechodzi do stanu live status.

  Podczas wstawiania punktu wstawienia ustaw właściwość zasobu cuepoint insertionOffsetTimeMs na żądane przesunięcie.

Obliczanie wartości przesunięcia czasowego

Aby pobrać wartość przesunięcia, wywołaj funkcję getCurrentTime interfejsu YouTube Player API dla odtwarzacza, który odtwarza strumień monitora. Użyj pobranej wartości, aby wstawić punkt wstawienia do strumienia transmisji w tym czasie.

Możliwe wartości przesunięcia czasowego można obliczyć jako ten zakres:

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

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

• Transmisja ma 5-minutową fazę testowania.
• Strumień transmisji jest opóźniony o 60 sekund po strumieniu monitora.
• Nadawca wstawia punkt wstawienia 4 minuty po przejściu transmisji do live stanu. (To 3 minuty po tym, jak strumień transmisji stanie się widoczny).

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

Te czasy są podawane w milisekundach i obliczane na podstawie tych wartości:

• elapsed_time=540000 – strumień monitora jest odtwarzany przez dziewięć minut (540 sekund, 540 000 milisekund), gdy wywoływana jest metoda liveBroadcasts.cuepoint.
• broadcast_delay=60000 – strumień transmisji jest opóźniony o 60 sekund, czyli 60 000 milisekund.
• Δ=5000 – 5-sekundowy bufor, gdy nie można niezawodnie wstawić punktu wstawienia.

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

Poniższe wytyczne wyjaśniają, jak rozwiązywać konkretne problemy, które mogą się pojawić. Listy błędów, które mogą być zwracane przez poszczególne metody interfejsu API, znajdziesz w artykule Interfejs API YouTube do transmitowania na żywo – błędy.

• Gdy transmisja przechodzi z jednego stanu do drugiego, może tymczasowo zostać przypisany jej inny stan, podczas gdy YouTube wykonuje działania związane z przejściem. Jeśli na przykład wyślesz żądanie liveBroadcasts.transition, aby zmienić stan transmisji z ready na testing, YouTube ustawi stan transmisji na testStarting, a następnie wykona działania związane ze zmianą stanu. Gdy wszystkie te działania zostaną zakończone, YouTube zmieni stan transmisji na testing, co oznacza, że przejście 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ą ze strumieniem na żywo i kontynuuj proces testowania.

  Jak wspomnieliśmy w dokumentacji metody liveBroadcasts.transition, przed wywołaniem tej metody musisz potwierdzić, że wartość właściwości status.streamStatus strumienia powiązanego z transmisją to active.