Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Ż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 dla początkujących, zasób to pojedyncza encja danych z unikalnym identyfikatorem. Aby tworzyć wydarzenia na żywo na YouTube i nimi zarządzać, będziesz używać różnych typów zasobów, które są zdefiniowane 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 przypadku transmisji na żywo.

Zasoby interfejsu API YouTube do transmitowania na żywo

Zasoby YouTube Data API

video

Zasoby interfejsu YouTube Content ID API

Tworzenie transmisji na żywo i zarządzanie nią

Poniżej opisujemy, jak utworzyć wydarzenie na żywo w YouTube i nim zarządzać. Czynności są podzielone na te etapy:

Konfigurowanie transmisji
Zgłaszanie roszczeń do treści
Testowanie
Broadcast
Zakończ transmisję
Tworzenie odwołania

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. Zasób liveBroadcast, który wstawiasz, musi definiować wartości właściwości wymienionych poniżej.

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

Jeśli chcesz przeprowadzić fazę testową transmisji, w której możesz wyświetlać 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ć plik referencyjny na podstawie nagranej transmisji, musisz ustawić właściwość contentDetails.recordFromStart transmisji na true. Jeśli chcesz, aby nagrany film był dostępny do odtworzenia 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).
Jeśli chcesz ograniczyć regiony, w których można oglądać transmisję, możesz ustawić właściwość contentDetails.availabilityConfig. Ta właściwość pozwala zablokować określone regiony lub ograniczyć dostępność do zdefiniowanej listy regionów. Możesz też określić przedziały czasowe dostępności regionalnej.
Możesz opcjonalnie określić kategorię filmu w przypadku transmisji za pomocą właściwości snippet.categoryId. Jeśli nie podasz tu żadnej wartości, domyślnie zostanie użyta kategoria Entertainment.
Możesz zaktualizować dowolną właściwość contentDetails, o ile stan transmisji to 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, kategorię i stan prywatności transmisji oraz inne pola metadanych, które są częścią zasobu video transmisji, można aktualizować w dowolnym momencie.

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. Będzie ona potrzebna do identyfikowania transmisji w przyszłych żądaniach do 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 jedną transmisją na żywo.

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

Po utworzeniu strumienia nie można zmienić tych wartości (z wyjątkiem tytułu strumienia). Jeśli chcesz je zmienić, musisz utworzyć inny strumień, powtarzając ten krok. Ten proces został omówiony bardziej szczegółowo 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](

/youtube/data/live/reference/rest/v3/liveStreams#contentDetails.isReusable)

Wskazuje, czy strumień może być używany wielokrotnie, 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, czyli true, możesz używać tego samego zasobu liveStream we wszystkich transmisjach na kanale. Oznacza to, że nie musisz powtarzać tego kroku (1.2) w przypadku każdej transmisji. Zamiast tego możesz użyć identyfikatora strumienia w kolejnych transmisjach.
- Jeśli ustawisz wartość właściwości na false, musisz utworzyć nowy strumień dla każdej transmisji.

Gdy wyślesz żądanie do interfejsu API, odpowiedź interfejsu API będzie zawierać utworzony zasób liveStream. Kod powinien wyodrębnić i zapisać id z tego zasobu. Ta wartość będzie potrzebna do identyfikacji strumienia w przyszłych żądaniach do interfejsu API.

Krok 1.3. Powiąż transmisję ze strumieniem

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

Wywołując metodę 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. Zgłoś roszczenie do treści

Jeśli chcesz wyświetlać reklamy podczas transmisji, musisz zgłosić film z transmisją przed rozpoczęciem wydarzenia. Aby skonfigurować transmisję, film i reklamy, wykonaj te czynności: Pamiętaj, że kanał właściciela transmisji musi kwalifikować się do wyświetlania reklam.

Pamiętaj, że wszystkie wywołania interfejsu API omówione na tym etapie są zdefiniowane w interfejsie YouTube Content ID API.

Krok 2.1. Utwórz zasób

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 zasób asset. Kod powinien wyodrębnić i zapisać id z tego zasobu, ponieważ ta wartość będzie potrzebna do identyfikacji zasobu w przyszłych żądaniach do interfejsu API.

Krok 2.2. Określ własność zasobu

Dane o własności zasobu identyfikują właścicieli zasobu oraz terytoria, na których mają oni do niego prawa. YouTube wykorzystuje te dane, aby określić, gdzie właściciel może ustawić zasadę dotyczącą filmu objętego roszczeniem.

Jeśli na przykład masz prawo do transmisji wydarzenia w Stanach Zjednoczonych, a inny nadawca ma takie samo prawo w Kanadzie, możecie określić różne zasady dotyczące filmu z transmisji i filmów przesłanych przez użytkowników, które pasują do filmu z transmisji. Twoja zasada dopasowania będzie stosowana do pasujących filmów przesłanych przez użytkowników w Stanach Zjednoczonych, a zasada drugiego właściciela będzie stosowana do pasujących filmów w Kanadzie.

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

Krok 2.3. Skonfiguruj zasadę dopasowania zasobu

Zasada dopasowania zasobu określa, co YouTube powinien zrobić, gdy użytkownik prześle film, który pasuje do pliku referencyjnego powiązanego z zasobem. W tym przypadku zasada dopasowania określi, jak YouTube powinien 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 z filmu z transmisji i użyć go do identyfikacji 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. Możesz też zdefiniować nowe zasady, wywołując metodę policies.insert. W obu przypadkach musisz zarejestrować id zasady, które chcesz zastosować.

Gdy znajdziesz zasadę, wywołaj metodę assetMatchPolicy.update. W tym żądaniu ustaw parametr assetId na wartość id zapisaną w kroku 2.1.

Krok 2.4. Zgłoś prawa 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 zasadę, która dotyczy tylko Twojej transmisji. (Filmy przesłane przez użytkowników, które pasują do Twojej transmisji, są objęte zasadą dopasowania ustawioną w poprzednim kroku).

Aby utworzyć roszczenie, wywołaj metodę claims.insert. We wstawianym zasobie claim musisz ustawić wartości tych właściwości:

assetId – tę wartość uzyskasz w kroku 2.1.
videoId – jest 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 przez Ciebie zasób claim. Kod powinien wyodrębnić i zapisać 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 przypadku transmisji

Jeśli chcesz wyświetlać reklamę przed filmem, gdy widzowie zaczną oglądać transmisję, lub reklamy podczas przerw w transmisji, musisz ustawić opcje reklamowe dla filmu.

Jeśli włączysz reklamy przed filmem w swojej transmisji, wszyscy widzowie zobaczą reklamę, gdy zaczną oglądać transmisję, nawet jeśli zaczną oglądać w jej trakcie.
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 wartość id uzyskaną w kroku 1.1. Użyj właściwości videoAdvertisingOption zasobu adFormats[] do określenia formatów 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ń monitorujący to prywatny strumień, który umożliwia podgląd transmisji wideo w takiej postaci, w jakiej będzie ona widoczna dla widzów na YouTube.

Pamiętaj, że transmisję wideo możesz przetestować tylko wtedy, gdy włączony jest strumień monitora. Domyślnie strumienie monitora 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. Umieszczanie odtwarzacza strumienia monitorującego

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 transmisję 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 Twoją transmisją. Sprawdź, czy wartość właściwości status.streamStatus wynosi active, co oznacza, że serwery YouTube prawidłowo odbierają dane z kodera.

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 testów

Jeśli test przebiegł pomyślnie, możesz przejść do etapu 4. W niektórych przypadkach może być jednak konieczne przeprowadzenie dalszych 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.

Aby odłączyć strumień wideo, wywołaj metodę liveBroadcasts.bind z kroku 1.3. W żądaniu do interfejsu API ustaw parametr id na wartość id uzyskaną w kroku 1.1. Nie uwzględniaj w żądaniu parametru streamId.
Aby usunąć strumień wideo, wywołaj metodę liveStreams.delete. W żądaniu ustaw parametr id na wartość id uzyskaną w kroku 1.2.
Powtórz krok 1.2, aby utworzyć nowy, prawidłowo skonfigurowanyliveStream zasób. Następnie powtórz krok 1.3, aby powiązać nową transmisję z transmisją na żywo, oraz kroki 3.1–3.3, aby przetestować nową transmisję.

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

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

Etap 4. Transmisja

Na tym etapie Twoja transmisja jest widoczna dla widzów.

Krok 4.1. Rozpocznij nagrywanie filmu

Rozpocznij przesyłanie obrazu w strumieniu wideo.

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

Krok 4.3. Zmień stan transmisji na „na żywo”

Ważne: ten krok sprawi, że Twój film będzie widoczny dla odbiorców.

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

Po wywołaniu interfejsu API lub po rozpoczęciu transmisji (jeśli właściwość contentDetails.enableAutoStart ma wartość true) zwykle musisz poczekać 5–10 sekund na zakończenie przejścia. Przejście może potrwać do minuty. W tym czasie należy odpytywać interfejs API, aby sprawdzić stan transmisji. Dopóki nie zostanie zakończone, stan transmisji będzie wynosił liveStarting. Po zakończeniu przejścia stan zmieni się na live, a widzowie będą mogli oglądać transmisję od tego momentu w strumieniu podglądu.

Pamiętaj o tych skutkach tego polecenia:

Jeśli włączysz strumień monitora dla transmisji – patrz krok 3.1 – strumień monitora będzie widoczny w odtwarzaczu osadzonym.
Jeśli ustawisz wartość właściwości contentDetails.streamDetails.broadcastStreamDelayMs transmisji, strumień transmisji, który jest widoczny dla innych widzów, będzie opóźniony o tę wartość.

Krok 4.4. Wstawianie przerw na reklamy do transmisji

Aby wstawić punkt wskazujący, wywołaj metodę liveBroadcasts.cuepoint. Punkt wstawienia 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órą chcesz wyświetlić. (Wartością domyślną jest 30).

W tym momencie YouTube próbuje odtworzyć reklamę w odtwarzaczu u wszystkich widzów, którzy oglądali transmisję, gdy wstawiono punkt wstawienia reklamy. To, czy reklama się wyświetli, zależy od wielu czynników, takich jak dostępność reklamy i historia wyświetlania reklam przez widza. Widzowie, którym wyświetli się przerwa na reklamę, 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 podczas przerwy na reklamę w trakcie transmisji na żywo znajdziesz w przewodniku Wprowadzenie.

Etap 5. Zakończenie transmisji

Krok 5.1. Zatrzymaj transmisję

To już koniec testu systemu transmisji na żywo w YouTube.

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

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 contentDetails.recordFromStart i contentDetails.enableDvr transmisji zostały ustawione na true, po zakończeniu wydarzenia na żywo widzowie mogą od razu obejrzeć jego powtórkę.

Etap 6. Tworzenie odniesienia

Po zakończeniu nagrywania na żywo możesz utworzyć plik referencyjny z nagranego filmu. Ta czynność 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ć plik referencyjny, musisz ustawić właściwość contentDetails.recordFromStart transmisji na true.

Krok 6.1. Odpytaj interfejs Data API o stan filmu

Zanim utworzysz plik referencyjny z filmu, YouTube musi zakończyć przetwarzanie transmisji lub przesłanego filmu. Aby sprawdzić, czy przetwarzanie filmu zostało zakończone, wywołaj metodę videos.list interfejsu YouTube Data API, ustawiając parametr part na status, a parametr id na identyfikator transmisji zapisany w kroku 1.1.

Odpowiedź interfejsu API na żądanie 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ć plik referencyjny, 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 do systemu Content ID

Niektórzy partnerzy YouTube mogą utworzyć plik referencyjny, zanim transmisja przejdzie w stan testing, ale ta funkcja nie jest dostępna dla wszystkich partnerów. W tym procesie YouTube generuje i stale aktualizuje plik referencyjny z transmisji wydarzenia na żywo, gdy transmisja jest 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 i nie można go wyłączyć po utworzeniu odniesienia.

Aby włączyć dostarczanie Content ID na żywo w transmisji, wykonaj czynności opisane w kroku 6.2 po zgłoszeniu roszczenia do filmu w kroku 2.4. Jeśli Twoje konto partnera nie zostało zatwierdzone do tworzenia pliku referencyjnego dla transmisji na żywo przed jej rozpoczęciem, 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.