Ta strona została przetłumaczona przez Cloud Translation API.

Życie transmisji

Wprowadzenie

Ten dokument przedstawia cykl transmisji na żywo w YouTube, który jest tworzony i zarządzany przy użyciu interfejsu YouTube Live Streaming API oraz YouTube Content ID API.

Zasoby i typy zasobów

Jak wspomniano w przewodniku Pierwsze kroki, zasób to konkretna jednostka danych z unikalnym identyfikatorem. Do tworzenia wydarzeń na żywo w YouTube i zarządzania nimi będziesz używać różnych typów zasobów, które definiuje się w ramach interfejsu YouTube Data API lub YouTube Content ID API. Zasoby wymienione w nagłówku YouTube Live Streaming API są technicznie zdefiniowane w innych interfejsach API, ale są wymienione oddzielnie, ponieważ są używane tylko do transmisji na żywo.

Zasoby interfejsu YouTube Live Streaming API

Zasoby interfejsu YouTube Data API

video

Zasoby interfejsu YouTube Content ID API

Tworzenie transmisji na żywo i zarządzanie nią

Z podanych niżej instrukcji dowiesz się, jak utworzyć wydarzenie na żywo w YouTube i nim zarządzać. Czynności są podzielone na te etapy:

Konfigurowanie transmisji
Zgłaszanie roszczeń do swoich treści
Testowanie
Transmisja
Zakończ transmisję
Utwórz plik referencyjny

Etap 1. Skonfiguruj transmisję

Krok 1.1: Utwórz transmisję

Wywołaj metodę liveBroadcasts.insert, aby dodać Twoją transmisję do harmonogramu wydarzeń na żywo w YouTube. Wstawiony zasób liveBroadcast musi mieć zdefiniowane wartości właściwości wymienionych poniżej.

Podczas konfigurowania transmisji pamiętaj o tych zasadach:

Jeśli chcesz zakończyć testy swojej transmisji, to gdy jesteś w trakcie jej oglądania, ale inni widzowie nie mają do niej dostępu, 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 usług.
Jeśli chcesz utworzyć plik referencyjny z nagranej transmisji, ustaw właściwość contentDetails.recordFromStart transmisji na true. Jeśli chcesz, aby nagrany film był dostępny do odtwarzania bezpośrednio po zakończeniu transmisji, musisz też ustawić właściwość contentDetails.enableDvr na true. (Obie te usługi mają wartość domyślną true).
Możesz aktualizować dowolną z właściwości contentDetails, pod warunkiem że stan transmisji to nadal created lub ready.
Możesz zmienić zaplanowany czas rozpoczęcia i zakończenie, o ile jej stan to created, ready lub testing.
Tytuł, opis i stan prywatności transmisji oraz inne pola metadanych będące częścią zasobu video można zaktualizować w dowolnym momencie.

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

Przetwarzanie odpowiedzi interfejsu API

Gdy wywołujesz metodę liveBroadcasts.insert, odpowiedź interfejsu API zawiera utworzony przez Ciebie zasób liveBroadcast. Kod powinien wyodrębnić i zapisać id z tego zasobu. Będzie Ci ona potrzebna do identyfikacji transmisji w przyszłych żądaniach do interfejsu API. Możesz też zidentyfikować zasób video, który odpowiada zasóbowi liveBroadcast, używając tego samego identyfikatora.

Krok 1.2. Utwórz transmisję

Zasób liveStream umożliwia przesłanie filmu do YouTube. Opisuje on treść, którą przesyłasz. Każda transmisja musi być powiązana z dokładnie jednym strumieniem.

Wywołaj metodę liveStreams.insert, aby utworzyć strumień wideo dla swojego wydarzenia. Podczas tworzenia strumienia musisz ustawić wartości właściwości wymienionych poniżej:

Z wyjątkiem tytułu transmisji nie można zaktualizować tych wartości po jej utworzeniu. Jeśli zajdzie taka potrzeba, musisz utworzyć inny strumień, powtarzając ten krok. Zostały one szczegółowo opisane w kroku 3.5 w dalszej części tego dokumentu.

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

snippet.description – tak jak tytuł transmisji, jej opis można zaktualizować po utworzeniu strumienia. Użytkownicy nie widzą tytułu ani opisu.
contentDetails.isReusable – wskazuje, czy można ponownie wykorzystywać strumień, co oznacza, że można go powiązać z wieloma transmisjami. Wartość tej właściwości skutecznie określa, czy między kanałem liveBroadcast a liveStream zasobami jest relacja jeden do jednego czy jeden do jednego:
- Jeśli stosujesz wartość domyślną właściwości true, możesz używać tego samego zasobu liveStream we wszystkich transmisjach kanału. Oznacza to, że nie musisz powtarzać tego kroku (1.2) w przypadku każdej transmisji. Możesz za to ponownie użyć identyfikatora transmisji 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 przez Ciebie zasób liveStream. Kod powinien wyodrębnić i zapisać id z tego zasobu. Będzie Ci ona potrzebna do identyfikacji strumienia w przyszłych żądaniach do interfejsu API.

Krok 1.3: powiąż transmisję z transmisją

Po utworzeniu zasobów liveBroadcast i liveStream musisz powiązać je za pomocą metody liveBroadcasts.bind. To działanie spowoduje połączenie bitów filmu, które będziesz przesyłać do YouTube wraz ze zdarzeniem transmisji.

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ś prawa do swoich treści

Jeśli chcesz wyświetlać reklamy podczas transmisji, musisz zgłosić prawa do transmisji na żywo przed rozpoczęciem wydarzenia. Poniżej opisujemy ten proces. Pamiętaj, że wszystkie wywołania interfejsu API omawiane 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ć zasób, wywołaj metodę assets.insert.

Odpowiedź interfejsu API będzie zawierać utworzony przez Ciebie zasób asset. Kod powinien wyodrębniać i przechowywać id z tego zasobu, ponieważ będzie Ci on potrzebny do identyfikacji zasobu w przyszłych żądaniach do interfejsu API.

Krok 2.2: Zdefiniuj własność zasobu

Dane o własności zasobu wskazują właścicieli i regiony, w których jest on właścicielem. Na podstawie tych danych YouTube ustala, gdzie właściciel może ustawić zasadę.

Jeśli na przykład masz prawo do transmitowania wydarzenia w Stanach Zjednoczonych, a inny nadawca ma te same prawa dla Kanady, możesz definiować inne zasady dla każdej transmisji, a dla innych filmów przesyłanych przez użytkowników, które pasują do transmitowanego wydarzenia. Twoja zasada dopasowania będzie stosowana do pasujących filmów przesłanych przez użytkowników w Stanach Zjednoczonych, a zasada dopasowania drugiego właściciela będzie miała zastosowanie do pasujących filmów w Kanadzie.

Aby zdefiniować obszary, na których masz własność zasobu, wywołaj metodę ownership.update. W tym żądaniu ustaw parametr assetId na id zapisany w kroku 2.1.

Krok 2.3. Ustaw zasadę dopasowania zasobu

Zasada dopasowania zasobu określa, co powinien zrobić YouTube, gdy użytkownik prześle film zgodny z plikiem referencyjnym powiązanym z zasobem. W takim przypadku zasada dopasowania wskaże, jak YouTube powinien postępować z przesłanym filmem, który odpowiada transmisji na żywo.

Uwaga: ustaw zasadę dopasowania, jeśli zamierzasz utworzyć plik referencyjny na potrzeby swojego filmu w YouTube i na jego podstawie zidentyfikować filmy przesłane 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ć nową zasadę, wywołując metodę policies.insert. W obu przypadkach musisz przechwycić zasadę id, którą chcesz zastosować.

Po określeniu zasady wywołaj metodę assetMatchPolicy.update. W tym żądaniu ustaw parametr assetId na id zapisany w kroku 2.1.

Krok 2.4. Zgłoś prawa do filmu

W tym kroku utworzysz roszczenie, które połączy film, który chcesz udostępnić, z zasobem utworzonym w kroku 2.1. Roszczenie to określa zasady, które mają zastosowanie tylko do transmisji. (Filmy przesłane przez użytkowników, które pasują do transmitowanego filmu, są objęte zasadami dopasowania określonymi w poprzednim kroku).

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

assetId – wartość została uzyskana w kroku 2,1,
videoId – identyfikator transmisji uzyskany w kroku 1.1.
policy – jest to zasób policy. Możesz zastosować istniejącą zasadę, ustawiając właściwość id tego zasobu na identyfikator istniejącej zasady. Poprzedni krok wyjaśnia, jak pobrać identyfikator istniejącej zasady.
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 dla transmisji

Jeśli chcesz wyświetlać reklamę przed filmem w momencie, gdy widzowie oglądają transmisję, lub w trakcie jej przerw w filmie, musisz ustawić opcje reklamowe.

Jeśli włączysz reklamy przed filmem, zobaczą je wszyscy widzowie, którzy zaczną oglądać Twoją transmisję, nawet jeśli zaczną ją oglądać.
Jeśli włączysz w trakcie transmisji reklamy w trakcie transmisji, będziesz mieć możliwość wstawiania punktów wstawienia reklamy w trakcie jej transmisji.

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

Etap 3. Testowanie

Na tym etapie umieszczasz w odtwarzaczu odtwarzacz, który wyświetla strumień monitorowania transmisji, aby umożliwić Ci przetestowanie odtwarzania. Strumień monitora to prywatny strumień, który umożliwia podgląd transmisji w postaci, w jakiej wygląda w YouTube.

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

Krok 3.1. Umieść odtwarzacz monitora

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

Krok 3.2: Uruchom film

Rozpocznij przesyłanie filmu do swojego strumienia 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ą. Potwierdź, że wartość właściwości status.streamStatus to active, co oznacza, że serwery YouTube prawidłowo odbierają dane z kodera.

Krok 3.4. Przenieś stan transmisji na testowanie

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

Po wywołaniu metody liveBroadcasts.transition może upłynąć kilka sekund, a nawet minuta, zanim zakończy się przenoszenie. W tym czasie musisz sprawdzić interfejs API, aby sprawdzić stan transmisji. Do momentu zakończenia przenoszenia stan transmisji będzie testStarting. Po przeniesieniu stan zmieni się na testing.

Krok 3.5: Testowanie

Jeśli test wykazał bezproblemowy, możesz przejść do etapu 4. W niektórych przypadkach może jednak zaistnieć potrzeba przeprowadzenia dalszych testów. Jeśli na przykład test wykaże, że strumień wideo nie jest prawidłowo skonfigurowany, musisz rozwiązać ten problem, zanim rozpoczniesz transmisję.

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

Aby usunąć przypisanie strumienia wideo, wywołaj metodę liveBroadcasts.bind z kroku 1.3. W żądaniu do interfejsu API ustaw parametr id na id uzyskany w kroku 1.1. Nie umieszczaj w żądaniu parametru streamId.
Aby usunąć strumień wideo, wywołaj metodę liveStreams.delete. W żądaniu ustaw parametr id na id uzyskany w kroku 1.2.
Powtórz krok 1.2, aby utworzyć nowy, poprawnie skonfigurowany zasób liveStream. Następnie powtórz kroki 1.3, aby powiązać nowy strumień z transmisją, oraz kroki od 3.1 do 3.3, aby przetestować nowy strumień.

Krok 3.6. Włącz usługi `autoStart` i `autoStop`

Po ukończeniu etapu testowania możesz zmienić właściwości contentDetails.enableAutoStart i contentDetails.enableAutoStop transmisji na true przed rozpoczęciem transmisji. Tych właściwości nie można ustawić na true przed etapem testowania, ponieważ w rzeczywistości rozpoczęcie transmisji spowodowałoby rozpoczęcie transmisji.

Etap 4. Transmisja

Na tym etapie Twój film jest widoczny dla widzów.

Krok 4.1: Uruchom film

Rozpocznij przesyłanie filmu do swojego strumienia wideo.

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

Krok 4.3. Przenieś stan transmisji na żywo

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

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

Po wykonaniu tego wywołania interfejsu API lub ustawieniu właściwości contentDetails.enableAutoStart na true po rozpoczęciu strumieniowego przesyłania danych zwykle trwa od 5 do 10 sekund. Przenoszenie może potrwać nawet minutę. W tym czasie musisz sprawdzić interfejs API, aby sprawdzić stan transmisji. Do chwili zakończenia przenoszenia transmisja będzie mieć stan liveStarting. Po zakończeniu przenoszenia stan zmieni się na live, a widzowie będą mogli oglądać transmisję od tego momentu w strumieniu monitorowania.

Zwróć uwagę na te efekty tego polecenia:

Jeśli strumień transmisji jest włączony w Twojej transmisji (patrz krok 3.1), możesz go zobaczyć we wbudowanym odtwarzaczu.
Jeśli ustawisz wartość właściwości contentDetails.streamDetails.broadcastStreamDelayMs transmisji, strumień transmisji widoczny dla innych widzów będzie opóźniony o ten czas.

Krok 4.4. Wstaw przerwy na reklamę do transmisji

Wywołaj metodę liveBroadcasts.cuepoint, aby wstawić punkt wstawienia. Punkt wstawienia reklamy może powodować przerwę w reklamie. W zasobie cuepoint podanym w treści żądania ustaw właściwość durationSecs na odpowiednią długość przerwy (w sekundach), którą chcesz wyświetlić. (Wartość domyślna to 30).

Obecnie YouTube próbuje odtworzyć reklamę w odtwarzaczu w przypadku wszystkich widzów, którzy oglądali transmisję po wstawieniu punktu wstawienia reklamy. To, czy reklama zostanie odtworzona, zależy od wielu czynników, takich jak dostępność reklamy i historia oglądania reklamy. Widzowie, którzy przerwą na reklamę, wracają do transmisji w czasie jej trwania.

Przewodnik Pierwsze kroki zawiera więcej informacji o oglądaniu w trakcie przerwy na reklamę.

Etap 5. Zakończ transmisję

Krok 5.1: Zatrzymaj transmisję

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

Krok 5.2. Przenieś stan transmisji, aby zakończyć

Gdy zechcesz 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 widzowie będą mogli je od razu obejrzeć.

Etap 6. Utwórz plik referencyjny

Po zakończeniu nagrywania na żywo możesz utworzyć plik referencyjny z nagranego filmu. To działanie nakazuje YouTube wyszukanie przesłanych przez użytkowników filmów, które pasują do transmisji, i postępowanie z nimi zgodnie z zasadami dopasowania określonymi w kroku 2.3.

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

Krok 6.1: Sprawdź, czy stan interfejsu API danych wskazuje na stan filmu

YouTube musi zakończyć przetwarzanie transmisji lub przesłanego filmu, zanim będzie można utworzyć plik referencyjny z tego filmu. Aby określić, czy przetwarzanie filmu zostało zakończone, odtwórz 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 dotycząca Twojego żądania ankietowego 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ć odwołanie, wywołaj metodę references.insert Content API API i ustaw parametr claimId na identyfikator roszczenia zapisany w kroku 2.4.

Dostarczanie treści na żywo

Niektórzy partnerzy YouTube mogą utworzyć pliki referencyjne przed ich przeniesieniem do stanu testing, ale ta funkcja nie jest dostępna dla wszystkich partnerów. W tym czasie YouTube generuje i stale aktualizuje plik referencyjny z transmisji na żywo w trakcie Twojej transmisji na żywo. Dodatkowo w czasie trwania transmisji YouTube szuka pasujących filmów przesłanych przez użytkowników. Pamiętaj, że utworzenie pliku referencyjnego przed rozpoczęciem transmisji automatycznie włączy w niej nagrywanie, a po utworzeniu pliku referencyjnego nie można go wyłączyć.

Aby włączyć przesyłanie treści na żywo w systemie Content ID, wykonaj czynności opisane w kroku 6.2 po zgłoszeniu roszczenia do filmu w kroku 2.4. Jeśli Twoje konto nie zostało zatwierdzone do tworzenia plików referencyjnych dla transmisji na żywo przed rozpoczęciem transmisji, interfejs API zwróci błąd fingerprintingNotAllowed. W takim przypadku przed utworzeniem pliku referencyjnego musisz poczekać na zakończenie transmisji (zgodnie z krokami 6.1 i 6.2 powyżej).