Życie transmisji

Wprowadzenie

W tym dokumencie opisujemy cykl życia transmisji na żywo w YouTube, która jest tworzona i zarządzana za pomocą interfejsu YouTube Live Streaming API oraz interfejsu YouTube Content ID API.

Zasoby i typy zasobów

Jak wyjaśniono w przewodniku pierwsze kroki, zasób to pojedynczy element danych z unikalnym identyfikatorem. Aby tworzyć wydarzenia na żywo w YouTube i nimi zarządzać, będziesz używać różnych typów zasobów zdefiniowanych w interfejsie YouTube Data API lub YouTube Content ID API. Zasoby wymienione w sekcji YouTube Live Streaming API są technicznie zdefiniowane w innych interfejsach API, ale są wymienione oddzielnie, ponieważ są używane tylko w transmisjach na żywo.

Materiały dotyczące interfejsu YouTube Live Streaming API

Materiały dotyczące interfejsu YouTube Data API

Zasoby interfejsu Content ID API w YouTube

Tworzenie transmisji na żywo i zarządzanie nią

Poniżej znajdziesz instrukcje tworzenia wydarzeń na żywo w YouTube i zarządzania nimi. Czynności są podzielone na te etapy:

  1. Konfigurowanie transmisji
  2. Przejmowanie treści
  3. Test
  4. Broadcast
  5. Zakończ transmisję
  6. Tworzenie pliku referencyjnego

Etap 1. Skonfiguruj transmisję

Krok 1.1. Utwórz transmisję

Wywołaj metodę liveBroadcasts.insert, aby dodać transmisję do harmonogramu wydarzeń na żywo w YouTube. Wstawiany zasób liveBroadcast musi zawierać wartości tych właściwości:

Podczas konfigurowania transmisji weź pod uwagę te wskazówki:

  • Jeśli chcesz przeprowadzić fazę testową transmisji, w której możesz oglądać transmisję wideo bez możliwości oglądania jej przez innych widzów, musisz ustawić właściwość contentDetails.monitorStream.enableMonitorStream na true, a właściwość contentDetails.enableAutoStart na false. Są to wartości domyślne obu właściwości.

  • Jeśli chcesz utworzyć odniesienie z nagrania transmisji, musisz ustawić właściwość contentDetails.recordFromStart transmisji na true. Jeśli chcesz, aby nagrany film był dostępny do odtwarzania natychmiast po zakończeniu transmisji, musisz też ustawić właściwość contentDetails.enableDvr na true. (Obie te właściwości mają domyślną wartość true).

  • Możesz zmienić dowolną z właściwości contentDetails, dopóki stan transmisji jest created lub ready.

  • Możesz zaktualizować zaplanowany czas rozpoczęcia i zakończenia transmisji, o ile jej stan to created, ready lub testing.

  • Tytuł, opis, stan prywatności i inne metadane transmisji pola, które są częścią zasobu video transmisji, można w każdej chwili zaktualizować.

    Uwaga: jeśli chcesz, aby Twój film był dostępny tylko dla określonych użytkowników YouTube, ustaw wartość właściwości status.privacyStatus na unlisted lub private, w zależności od potrzeb.

Przetwarzanie odpowiedzi interfejsu API

Gdy wywołasz metodę liveBroadcasts.insert, odpowiedź interfejsu API będzie zawierać utworzony zasób liveBroadcast. Kod powinien wyodrębnić i zapisać id z tego zasobu. Ta wartość będzie potrzebna do identyfikowania transmisji w przyszłych żądaniach interfejsu API. (Możesz też zidentyfikować zasób video, który odpowiada zasobowi liveBroadcast, używając tego samego identyfikatora).

Krok 1.2. Utwórz strumień

Zasób liveStream umożliwia przesyłanie filmu do YouTube i opisuje przesyłane treści. Każda transmisja musi być powiązana z dokładnie 1 strumieniem.

Aby utworzyć strumień wideo dla wydarzenia, wywołaj metodę liveStreams.insert. Podczas tworzenia strumienia musisz ustawić wartości tych właściwości:

Z wyjątkiem tytułu transmisji tych wartości nie można aktualizować po utworzeniu transmisji. Jeśli chcesz je zmienić, musisz utworzyć inny strumień, powtarzając ten krok. Ten proces został szczegółowo omówiony w kroku 3.5 w dalszej części tego dokumentu.

Możesz też ustawić wartości tych właściwości:

  • snippet.description – podobnie jak tytuł transmisji, opis transmisji można zaktualizować po utworzeniu transmisji. Ani tytuł, ani opis nie są widoczne dla użytkowników YouTube.

  • contentDetails.isReusable – wskazuje, czy strumień można ponownie wykorzystać, co oznacza, że można go powiązać z wieloma transmisjami. Wartość tej właściwości określa, czy kanał ma relację wiele do jednego czy jeden do jednego między zasobami liveBroadcast i liveStream:

    • Jeśli używasz domyślnej wartości właściwości true, możesz używać tego samego zasobu liveStream w przypadku wszystkich transmisji na kanale. Oznacza to, że nie musisz powtarzać tego kroku (1.2) w przypadku każdej transmisji. Zamiast tego możesz użyć tego samego identyfikatora strumienia w kolejnych transmisjach.
    • Jeśli ustawisz wartość właściwości na false, musisz utworzyć nowy strumień dla każdej transmisji.

Po wysłaniu żądania do interfejsu API odpowiedź interfejsu API zawiera utworzony zasób liveStream. Kod powinien wyodrębnić i zapisać wartość id z tego zasobu. Ta wartość będzie potrzebna do identyfikowania strumienia w przyszłych żądaniach interfejsu API.

Krok 1.3. Powiąż transmisję ze strumieniem

Po utworzeniu zasobów liveBroadcast i liveStream musisz je ze sobą powiązać za pomocą metody liveBroadcasts.bind. Ta czynność łączy fragmenty filmu, które będziesz przesyłać do YouTube, z transmisją wydarzenia związanego z tym filmem.

Podczas wywoływania metody liveBroadcasts.bind ustaw parametr id na identyfikator transmisji uzyskany w kroku 1.1, a parametr streamId na identyfikator strumienia uzyskany w kroku 1.2.

Etap 2. Przejmij prawa do treści

Jeśli chcesz wyświetlać reklamy podczas transmisji, musisz zgłosić prawa do filmu z transmisją przed rozpoczęciem wydarzenia. Poniższe kroki opisują ten proces. Pamiętaj, że wszystkie wywołania interfejsu API omówione na tym etapie są zdefiniowane w interfejsie API YouTube Content ID.

Krok 2.1. Tworzenie komponentu

Zasób asset reprezentuje element własności intelektualnej. W tym przypadku zasobem jest Twoja transmisja. Aby utworzyć komponent, wywołaj metodę assets.insert.

Odpowiedź interfejsu API będzie zawierać utworzony przez Ciebie zasób asset. Kod powinien wyodrębnić i zapisać id z tego zasobu, ponieważ ta wartość będzie potrzebna do identyfikowania komponentu w przyszłych żądaniach interfejsu API.

Krok 2.2. Określ, czy jesteś właścicielem komponentu

Dane dotyczące własności zasobu określają właścicieli zasobu oraz regiony, w których mają oni prawa do tego zasobu. YouTube wykorzystuje te dane, aby określić, gdzie właściciel może ustawić zasady dotyczące filmu objętego roszczeniem.

Jeśli na przykład masz prawo do transmitowania wydarzenia w Stanach Zjednoczonych, a inny nadawca ma takie samo prawo w Kanadzie, możecie zdefiniować różne zasady dotyczące transmitowanego filmu i filmów przesłanych przez użytkowników, które są z nim zgodne. Twoje zasady dopasowania będą stosowane w przypadku pasujących filmów przesłanych przez użytkowników w Stanach Zjednoczonych, a zasady innego właściciela będą stosowane w przypadku pasujących filmów w Kanadzie.

Aby określić regiony, w których masz prawa własności do zasobu, wywołaj metodę ownership.update. W tym żądaniu ustaw parametr assetId na wartość id, którą zapisano w kroku 2.1.

Krok 2.3. Skonfiguruj zasadę dopasowania zasobu

Zasady dopasowania zasobu określają, co YouTube powinien zrobić, gdy użytkownik prześle film, który pasuje do pliku referencyjnego powiązanego z zasobem. W takim przypadku zasada dopasowania określi, jak YouTube ma postępować z przesłanym filmem, który pasuje do Twojej transmisji na żywo.

Uwaga: zasadę dopasowania należy ustawić, jeśli planujesz utworzyć plik referencyjny na podstawie swojego filmu z transmisji i używać go do identyfikowania filmów przesłanych przez użytkowników, które pasują do Twojej transmisji. W przeciwnym razie możesz pominąć ten krok.

Aby ustawić zasadę dopasowania, musisz najpierw określić zasadę, którą chcesz zastosować. Listę istniejących zasad możesz pobrać, wywołując metodę policies.list, a nowe zasady możesz zdefiniować, wywołując metodę policies.insert. W obu przypadkach musisz zarejestrować id zasady, które chcesz zastosować.

Po zidentyfikowaniu zasady wywołaj metodę assetMatchPolicy.update. W tym żądaniu ustaw parametr assetId na wartość id zapisaną w kroku 2.1.

Krok 2.4. Zgłoś roszczenie do filmu

W tym kroku utworzysz roszczenie, które połączy film, który będziesz transmitować, z zasobem utworzonym w kroku 2.1. Roszczenie określa zasady, które dotyczą tylko Twojego filmu transmitowanego na żywo. (Filmy przesłane przez użytkowników, które pasują do Twojego filmu, są objęte zasadami dopasowania ustawionymi w poprzednim kroku).

Aby utworzyć roszczenie, wywołaj metodę claims.insert. W zasobie claim, który wstawiasz, musisz ustawić wartości tych właściwości:

  • assetId – tę wartość uzyskaliśmy w kroku 2.1.
  • videoId – to identyfikator transmisji uzyskany w kroku 1.1.
  • policy – to zasób policy. Aby zastosować istniejącą zasadę, ustaw właściwość id tego zasobu na identyfikator istniejącej zasady. W poprzednim kroku wyjaśniliśmy, jak pobrać identyfikator istniejących zasad.
  • contentType – ustaw tę wartość na audiovisual.

Przetwarzanie odpowiedzi interfejsu API

Gdy wstawisz roszczenie, odpowiedź interfejsu API będzie zawierać utworzony zasób claim. Kod powinien wyodrębnić i zapisać wartość id z tego zasobu. Użyjesz tej wartości później, aby utworzyć plik referencyjny z przetworzonego filmu.

Krok 2.5. Zaktualizuj ustawienia reklam w transmisji

Jeśli chcesz wyświetlać reklamy przed rozpoczęciem transmisji lub w jej trakcie, musisz skonfigurować opcje reklamowania filmu.

  • Jeśli włączysz reklamy przed transmisją, wszyscy widzowie zobaczą reklamę, gdy zaczną oglądać transmisję, nawet jeśli zaczną oglądać ją w połowie.
  • Jeśli włączysz reklamy w trakcie transmisji, będziesz mieć możliwość wstawiania punktów wstawienia reklam podczas transmisji.

Aby włączyć reklamy, wywołaj metodę videoAdvertisingOptions.update. W żądaniu ustaw parametr videoId na identyfikator transmisji id uzyskany w kroku 1.1. Użyj właściwości videoAdvertisingOption zasobuadFormats[], aby określić formaty reklam (preroll, midroll lub postroll), które chcesz włączyć.

Etap 3. Testowanie

Na tym etapie umieszczasz odtwarzacz, który wyświetla strumień monitora transmisji, aby przetestować wrażenia widzów. Strumień monitora to strumień prywatny, który umożliwia wyświetlenie podglądu transmisji wideo w takiej postaci, w jakiej będzie ona widoczna dla widzów YouTube.

Pamiętaj, że możesz przetestować transmisję wideo tylko wtedy, gdy jest włączony strumień monitora. Domyślnie strumienie monitorujące transmisji są włączone. Możesz wyłączyć strumień monitorowania transmisji, ustawiając właściwość contentDetails.monitorStream.enableMonitorStream na false podczas tworzenia lub aktualizowania tej transmisji.

Krok 3.1. Osadź odtwarzacz strumienia monitora

Pobierz transmisję za pomocą metody liveBroadcasts.list i wyodrębnij wartość właściwości contentDetails.streamDetails.monitorStreamEmbedHtml. Ta wartość zawiera kod HTML, który jest potrzebny do umieszczenia odtwarzacza YouTube wyświetlającego strumień z monitora.

Krok 3.2. Rozpocznij film

Rozpocznij przesyłanie wideo w strumieniu wideo.

Krok 3.3. Sprawdź, czy strumień wideo jest aktywny

Wywołaj metodę liveStreams.list, aby pobrać zasób liveStream powiązany z transmisją. Sprawdź, czy wartość właściwości status.streamStatus to active. Oznacza to, że serwery YouTube prawidłowo odbierają dane z enkodera.

Krok 3.4. Zmień stan transmisji na testowanie

Aby zaktualizować stan transmisji, wywołaj metodę liveBroadcasts.transition. Ustaw wartość parametru id na identyfikator transmisji uzyskany w kroku 1.1, a wartość parametru broadcastStatus na testing.

Po wywołaniu metody liveBroadcasts.transition przejście może potrwać kilka sekund, a nawet minutę. W tym czasie należy odpytywać interfejs API, aby sprawdzić stan transmisji. Do czasu zakończenia przejścia stan transmisji będzie testStarting. Po zakończeniu przenoszenia stan zmieni się na testing.

Krok 3.5. Zakończenie testowania

Jeśli test przebiegł bez problemów, możesz przejść do etapu 4. W niektórych przypadkach może być jednak konieczne przeprowadzenie dodatkowych testów. Jeśli na przykład testy wykażą, że strumień wideo nie jest prawidłowo skonfigurowany, musisz to naprawić, zanim rozpoczniesz transmisję.

Jeśli strumień wideo nie jest prawidłowo skonfigurowany, musisz odłączyć (i usunąć) istniejący strumień i utworzyć nowy. Na przykład strumień może być nieprawidłowo skonfigurowany, jeśli określa nieprawidłowy format wideo.

  1. Aby odłączyć strumień wideo, wywołaj metodę liveBroadcasts.bind z kroku 1.3. W żądaniu interfejsu API ustaw parametr id na wartość id uzyskaną w kroku 1.1. Nie uwzględniaj w żądaniu parametru streamId.

  2. Aby usunąć strumień wideo, wywołaj metodę liveStreams.delete. W żądaniu ustaw parametr id na wartość id uzyskaną w kroku 1.2.

  3. Powtórz krok 1.2, aby utworzyć nowy, prawidłowo skonfigurowanyliveStream zasób. Następnie powtórz krok 1.3, aby powiązać nowy strumień z transmisją, oraz kroki 3.1–3.3, aby przetestować nowy strumień.

Krok 3.6. Włącz właściwości autoStart i autoStop

Po zakończeniu etapu testowania możesz ustawić właściwości transmisji contentDetails.enableAutoStart i contentDetails.enableAutoStop na true przed rozpoczęciem transmisji. Przed etapem testowania nie można ustawić tych właściwości na true, ponieważ test spowodowałby rozpoczęcie transmisji.

Etap 4. Nadawanie

Na tym etapie film z transmisji jest widoczny dla odbiorców.

Krok 4.1. Rozpocznij film

Rozpocznij przesyłanie wideo w strumieniu wideo.

Krok 4.2. Sprawdź, czy strumień wideo jest aktywny

Wywołaj metodę liveStreams.list, aby pobrać zasób liveStream powiązany z transmisją. Sprawdź, czy wartość właściwości status.streamStatus to active. Oznacza to, że serwery YouTube prawidłowo odbierają dane z enkodera.

Krok 4.3. Zmień stan transmisji na żywo

Ważne: dzięki temu Twój film będzie widoczny dla odbiorców.

Aby zaktualizować stan transmisji, wywołaj metodę liveBroadcasts.transition. Ustaw wartość parametru id na identyfikator transmisji uzyskany w kroku 1.1, a wartość parametru broadcastStatus na live.

Jeśli ustawisz właściwość contentDetails.enableAutoStart zasobu liveBroadcast na true, nie musisz wywoływać metody liveBroadcasts.transition.

Po wywołaniu tego interfejsu API lub, jeśli właściwość contentDetails.enableAutoStart ma wartość true, po rozpoczęciu przesyłania strumieniowego zwykle musisz poczekać 5–10 sekund, aż przejście się zakończy. Może to potrwać do minuty. W tym czasie należy odpytywać interfejs API, aby sprawdzić stan transmisji. Do czasu zakończenia przejścia stan transmisji będzie liveStarting. Gdy przejście zostanie zakończone i widzowie będą mogli oglądać transmisję od tego momentu w strumieniu monitora, stan zmieni się na live.

Pamiętaj o tych skutkach tego polecenia:

  • Jeśli włączysz strumień monitora dla transmisji – patrz krok 3.1 – zobaczysz go w odtwarzaczu osadzonym.
  • Jeśli ustawisz wartość właściwości transmisjicontentDetails.streamDetails.broadcastStreamDelayMs, strumień transmisji widoczny dla innych widzów będzie opóźniony o ten czas.

Krok 4.4. Wstawianie przerw na reklamy do transmisji

Aby wstawić punkt wskazujący, wywołaj metodę liveBroadcasts.cuepoint. Punkt sygnałowy może wywołać przerwę na reklamę. W zasobie cuepoint podanym w treści żądania ustaw właściwość durationSecs na żądaną długość przerwy (w sekundach), która ma się wyświetlać. (Wartością domyślną jest 30).

W tym momencie YouTube próbuje wyświetlić reklamę w odtwarzaczu wideo wszystkim widzom, którzy oglądali transmisję w momencie wstawienia punktu wstawienia reklamy. To, czy reklama się wyświetli, zależy od wielu czynników, takich jak dostępność reklam i historia wyświetlania reklam przez widza. Widzowie, którym wyświetli się przerwa na reklamy, wrócą do transmisji po jej zakończeniu, a widzowie, którym nie wyświetli się reklama, będą nadal oglądać transmisję podczas przerwy.

Więcej informacji o oglądaniu reklam podczas transmisji na żywo znajdziesz w przewodniku Pierwsze kroki.

Etap 5. Zakończ transmisję

Krok 5.1. Zatrzymywanie transmisji

To koniec testu systemu transmisji na żywo w YouTube.

Krok 5.2. Zmień stan transmisji na „Zakończono”

Gdy chcesz zakończyć transmisję, wywołaj metodę liveBroadcasts.transition interfejsu API, aby zaktualizować stan transmisji. Ustaw wartość parametru id na identyfikator transmisji uzyskany w kroku 1.1, a wartość parametru broadcastStatus na complete.

Jeśli właściwości transmisji contentDetails.recordFromStart i contentDetails.enableDvr zostały ustawione na true, po zakończeniu wydarzenia na żywo widzowie będą mogli od razu obejrzeć jego nagranie.

Etap 6. Tworzenie pliku referencyjnego

Po zakończeniu nagrywania na żywo możesz utworzyć plik referencyjny na podstawie nagranego filmu. To działanie powoduje, że YouTube wyszukuje przesłane przez użytkowników filmy, które pasują do transmisji, i postępuje z nimi zgodnie z zasadami dopasowania ustawionymi w kroku 2.3.

Ważne: aby utworzyć odniesienie, musisz ustawić właściwość contentDetails.recordFromStart transmisji na true.

Krok 6.1. Sprawdź stan filmu w interfejsie Data API

Zanim utworzysz materiał referencyjny na podstawie transmisji lub przesłanego filmu, YouTube musi zakończyć jego przetwarzanie. Aby sprawdzić, czy film został przetworzony, wywołaj metodę videos.list interfejsu YouTube Data API, ustawiając parametr part na status, a parametr id na identyfikator transmisji, który został zapisany w kroku 1.1.

Odpowiedź interfejsu API na Twoje żądanie dotyczące sondowania będzie zawierać zasób video. Gdy wartość właściwości status.uploadStatus tego zasobu to processed, przejdź do kroku 6.2.

Krok 6.2. Utwórz plik referencyjny z przetworzonego filmu

Aby utworzyć odniesienie, wywołaj metodę references.insert interfejsu Content ID API i ustaw parametr claimId na identyfikator roszczenia zapisany w kroku 2.4.

Przesyłanie treści na żywo w Content ID

Niektórzy partnerzy YouTube mogą utworzyć plik referencyjny przed przejściem transmisji w stan testing, ale ta funkcja nie jest dostępna dla wszystkich partnerów. W tym procesie YouTube generuje i stale aktualizuje referencję z transmisji na żywo, gdy jest ona w toku. Dodatkowo YouTube szuka pasujących filmów przesłanych przez użytkowników, gdy transmisja jest jeszcze w toku. Pamiętaj, że utworzenie odniesienia przed rozpoczęciem transmisji automatycznie włącza nagrywanie transmisji. Po utworzeniu odniesienia nie można wyłączyć nagrywania.

Aby włączyć transmisję na żywo w celu dostarczania Content ID, po zgłoszeniu roszczenia do filmu w kroku 2.4 wykonaj czynności opisane w kroku 6.2. Jeśli Twoje konto partnera nie zostało zatwierdzone do tworzenia odniesienia do transmisji na żywo przed rozpoczęciem tej transmisji, interfejs API zwróci błąd fingerprintingNotAllowed. W takim przypadku musisz poczekać na zakończenie transmisji, jak opisano w krokach 6.1 i 6.2 powyżej, zanim utworzysz odniesienie.