LiveBroadcasts

Interfejs API umożliwia teraz oznaczanie transmisji na żywo jako „przeznaczonych dla dzieci”, a zasób liveBroadcast zawiera teraz właściwość, która określa stan transmisji „przeznaczona dla dzieci”. 10 stycznia 2020 r. zaktualizowaliśmy również Warunki korzystania z usług YouTube API oraz zasady dla deweloperów. Więcej informacji znajdziesz w historii zmian interfejsu API YouTube do transmisji na żywo i Warunków korzystania z usług interfejsu API YouTube.

Zasób liveBroadcast reprezentuje wydarzenie, które będzie transmitowane w YouTube za pomocą transmisji na żywo.

Metody

Interfejs API obsługuje te metody dotyczące zasobów liveBroadcasts:

list
Zwraca listę transmisji YouTube, które pasują do parametrów żądania interfejsu API. Wypróbuj teraz
wstaw
Tworzy transmisję. Wypróbuj teraz
update
Aktualizuje transmisję. Możesz na przykład zmodyfikować ustawienia transmisji określone w obiekcie contentDetails zasobu liveBroadcast. Wypróbuj
usuń
Usuwa transmisję. Wypróbuj teraz
powiąż
Przywiązuje transmisję w YouTube do strumienia lub usuwa istniejące powiązanie między transmisją a strumieniem. Transmisja może być powiązana tylko z 1 strumieniem wideo, ale strumień wideo może być powiązany z wieloma transmisjami. Wypróbuj teraz
transition
Zmienia stan transmisji na żywo w YouTube i inicjuje procesy związane z nowym stanem. Jeśli na przykład zmienisz stan transmisji na testing, YouTube rozpocznie przesyłanie obrazu do jej strumienia monitorującego. Zanim wywołasz tę metodę, sprawdź, czy wartość właściwości status.streamStatus w strumieniu powiązanym z Twoją transmisją wynosi active. Wypróbuj
punkt wstawienia reklamy
Wstawia punkt wstawienia do transmisji na żywo. Sygnał może wywołać przerwę na reklamę.

Reprezentacja zasobu

Struktura JSON poniżej przedstawia format zasobu liveBroadcasts:

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
      "cuepointSchedule": {
        "enabled": boolean,
        "pauseAdsUntil": datetime,
        "scheduleStrategy": string,
        "repeatIntervalSecs": unsigned integer,
      }
    }
  }
}

Właściwości

Właściwości występujące w tym zasobie są opisane w tabeli poniżej:

Właściwości
kind string
Określa typ zasobu interfejsu API. Wartość wyniesie youtube#liveBroadcast.
etag etag
Etag tego zasobu.
id string
Identyfikator nadawany przez YouTube w celu jednoznacznego identyfikowania transmisji.
snippet object
Obiekt snippet zawiera podstawowe informacje o wydarzeniu, w tym jego tytuł, opis, godzinę rozpoczęcia i zakończenia.
snippet.publishedAt datetime
Data i godzina dodania transmisji do harmonogramu transmisji na żywo w YouTube. Wartość jest podawana w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.channelId string
Identyfikator używany w YouTube do jednoznacznej identyfikacji kanału, który publikuje transmisję.
snippet.title string
Tytuł transmisji. Pamiętaj, że transmisja dotyczy tylko jednego filmu z YouTube. Możesz ustawić to pole, modyfikując zasób transmisji lub ustawiając pole title w odpowiednim zasobie wideo.
snippet.description string
Opis transmisji. Podobnie jak w przypadku pola title, możesz ustawić to pole, modyfikując zasób transmisji lub ustawiając pole description w odpowiednim zasobie wideo.
snippet.thumbnails object
Mapa z miniaturami powiązanymi z transmisją. W przypadku każdego zagnieżdżonego obiektu w tym obiekcie kluczem jest nazwa miniatury, a wartością jest obiekt zawierający inne informacje o miniaturze.
snippet.thumbnails.(key) object
Prawidłowe wartości klucza to:
  • default – domyślna miniatura. Domyślna miniatura filmu lub zasobu odwołującego się do filmu (np. elementu playlisty lub wyniku wyszukiwania) ma szerokość 120 pikseli i wysokość 90 pikseli. Domyślna miniatura kanału ma 88 pikseli szerokości i 88 pikseli wysokości.
  • medium – wersja miniatury w wyższej rozdzielczości. W przypadku filmu (lub zasobu odwołującego się do filmu) obraz ma szerokość 320 pikseli i wysokość 180 pikseli. W przypadku kanału obraz ma 240 pikseli szerokości i 240 pikseli wysokości.
  • high – wersja miniatury w wysokiej rozdzielczości. W przypadku filmu (lub zasobu odniesienia do filmu) obraz ma 480 pikseli szerokości i 360 pikseli wysokości. W przypadku kanału obraz ma 800 pikseli szerokości i 800 pikseli wysokości.
snippet.thumbnails.(key).url string
Adres URL obrazu.
snippet.thumbnails.(key).width unsigned integer
Szerokość obrazu.
snippet.thumbnails.(key).height unsigned integer
Wysokość obrazu.
snippet.scheduledStartTime datetime
Data i godzina rozpoczęcia transmisji. Wartość jest podawana w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Creator Studio umożliwia tworzenie transmisji bez planowania godziny rozpoczęcia. W tym przypadku transmisja rozpoczyna się, gdy właściciel kanału rozpocznie strumieniowanie. W przypadku tych transmisji wartość datetime odpowiada zerowemu czasowi systemu UNIX i nie można jej zmienić za pomocą interfejsu API ani w Studiu twórców.
snippet.scheduledEndTime datetime
Data i godzina zakończenia transmisji. Wartość jest podana w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Jeśli zasób liveBroadcast nie określa wartości tej właściwości, transmisja jest zaplanowana na czas nieokreślony. Podobnie, jeśli nie określisz wartości tej właściwości, YouTube będzie traktować transmisję tak, jakby miała trwać bez końca.
snippet.actualStartTime datetime
Data i godzina rozpoczęcia transmisji. Te informacje są dostępne tylko wtedy, gdy stan transmisji to live. Wartość jest podawana w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.actualEndTime datetime
Data i godzina faktycznego zakończenia transmisji. Ta informacja jest dostępna tylko wtedy, gdy stan transmisji to complete. Wartość jest podawana w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.isDefaultBroadcast boolean
Ta usługa zostanie wycofana 1 września 2020 r. lub później. Wtedy YouTube przestanie tworzyć domyślny strumień i domyślną transmisję, gdy kanał będzie mieć włączoną transmisję na żywo. Więcej informacji znajdziesz w ogłoszeniu o wycofaniu funkcji.
Ta właściwość wskazuje, czy ta transmisja jest transmisją domyślną.

Jak działają transmisje domyślne

Gdy kanał w YouTube jest włączony do transmisji na żywo, YouTube tworzy domyślny strumień i domyślną transmisję. Transmisja określa sposób, w jaki właściciel kanału wysyła transmisję na żywo do YouTube, a transmisja to sposób, w jaki widzowie mogą zobaczyć transmisję domyślną. Właściciel kanału może zidentyfikować te zasoby za pomocą metod liveStreams.list i liveBroadcasts.list.

Gdy kanał rozpocznie strumieniowe przesyłanie filmu do domyślnego strumienia, film będzie widoczny w ramach domyślnej transmisji na kanale. Gdy transmisja dobiegnie końca, YouTube przekształci zakończoną transmisję w film w YouTube i przypisze mu identyfikator filmu w YouTube.

Po zakończeniu konwersji film zostanie dodany do listy przesłanych filmów na kanale. Film nie jest dostępny bezpośrednio po zakończeniu transmisji, a czas opóźnienia jest związany z rzeczywistą długością transmisji.
snippet.liveChatId string
Identyfikator czatu na żywo w YouTube. Dzięki temu identyfikatorowi możesz używać metod zasobu liveChatMessage do pobierania, wstawiania i usuwania wiadomości czatu. Możesz też dodawać i usuwać moderatorów czatu, blokować użytkowników przed uczestnictwem w czatach na żywo oraz usuwać istniejące blokady.
status object
Obiekt status zawiera informacje o stanie zdarzenia.
status.lifeCycleStatus string
Stan transmisji. Stan można zaktualizować za pomocą metody liveBroadcasts.transition interfejsu API.

Dopuszczalne wartości tej właściwości to:
  • complete – transmisja została zakończona.
  • created – transmisja ma niekompletne ustawienia, więc nie jest gotowa do przejścia do stanu live ani testing, ale została utworzona i w innych aspektach jest prawidłowa.
  • live – transmisja jest aktywna.
  • liveStarting – transmisja jest w trakcie przechodzenia do stanu live.
  • ready – ustawienia transmisji zostały skonfigurowane i można zmienić stan transmisji na live lub testing.
  • revoked – ta transmisja została usunięta przez administratora.
  • testStarting – transmisja jest w trakcie przechodzenia do stanu testing.
  • testing – transmisja jest widoczna tylko dla partnera.
status.privacyStatus string
Stan prywatności transmisji. Pamiętaj, że transmisja stanowi dokładnie jeden film w YouTube, więc ustawienia prywatności są identyczne jak w przypadku filmów. Możesz też ustawić to pole, modyfikując zasób transmisji lub ustawiając pole privacyStatus w odpowiednim zasobie wideo.

Dopuszczalne wartości tej właściwości to:
  • private
  • public
  • unlisted
status.recordingStatus string
Stan nagrywania transmisji.

Dozwolone wartości tej właściwości to:
  • notRecording
  • recorded
  • recording
status.madeForKids boolean
Ta wartość wskazuje, czy transmisja jest przeznaczona dla dzieci. Ta wartość właściwości jest tylko do odczytu.
status.selfDeclaredMadeForKids boolean
W żądaniu liveBroadcasts.insert ta właściwość pozwala właścicielowi kanału oznaczyć transmisję jako skierowaną do dzieci. W żądaniu liveBroadcasts.list wartość właściwości jest zwracana tylko wtedy, gdy właściciel kanału autoryzował żądanie interfejsu API.
contentDetails object
Obiekt contentDetails zawiera informacje o treści wideo zdarzenia, np. czy można ją wyświetlić w umieszczonym na stronie odtwarzacza wideo lub czy zostanie zarchiwizowana, dzięki czemu będzie można ją wyświetlić po zakończeniu wydarzenia.
contentDetails.boundStreamId string
Ta wartość jednoznacznie identyfikuje live stream powiązane z transmisją.
contentDetails.boundStreamLastUpdateTimeMs datetime
Data i godzina ostatniej aktualizacji strumienia na żywo, do którego odwołuje się boundStreamId.
contentDetails.monitorStream object
Obiekt monitorStream zawiera informacje o strumieniu monitorowania, których nadawca może używać do sprawdzania treści wydarzenia, zanim strumień transmisji zostanie publicznie wyświetlony.
contentDetails.monitorStream.enableMonitorStream boolean
Ta wartość określa, czy strumień monitorowania jest włączony w przypadku transmisji. Jeśli strumień monitorowania jest włączony, YouTube będzie transmitować zawartość wydarzenia w specjalnym strumieniu przeznaczonym tylko dla nadawcy. Streamer może użyć strumienia, aby sprawdzić treść wydarzenia i określić optymalny czas wstawiania punktów cue.

Jeśli chcesz użyć testing sceny do transmisji lub chcesz opóźnić transmisję wydarzenia, musisz ustawić tę wartość na true. Jeśli wartość tej właściwości to true, musisz przełączyć transmisję do stanu testing, zanim będzie można ją przełączyć do stanu live. (Jeśli wartość właściwości to false, transmisja nie może mieć etapu testing, więc można przenieść transmisję bezpośrednio do stanu live).

Gdy update a broadcast, ta właściwość musi być ustawiona, jeśli żądanie interfejsu API zawiera część contentDetails w wartości parametru part. Jednak w przypadku wartości insert a broadcast ta właściwość jest opcjonalna i ma domyślną wartość true.

Ważne: tej właściwości nie można zaktualizować, gdy transmisja jest w stanie testing lub live.
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
Jeśli właściwość enableMonitorStream jest ustawiona na true, określa ona długość opóźnienia transmisji na żywo.

Gdy update a broadcast, ta właściwość musi być ustawiona, jeśli żądanie interfejsu API zawiera część contentDetails w wartości parametru part. Jednak w przypadku wartości insert a broadcast ta właściwość jest opcjonalna i ma domyślną wartość 0. Ta wartość wskazuje, że transmisja nie ma opóźnienia. Uwaga: tej właściwości nie można zaktualizować, gdy transmisja jest w stanie testing lub live.
contentDetails.monitorStream.embedHtml string
Kod HTML, który umieszcza odtwarzacz, który odtwarza strumień monitora.
contentDetails.enableEmbed boolean
To ustawienie wskazuje, czy transmisja może być odtwarzana w osadzonym odtwarzaczu. Jeśli zdecydujesz się zarchiwizować film (za pomocą właściwości enableArchive), to ustawienie zostanie też zastosowane do zarchiwizowanego filmu.

W polu update a broadcast ta właściwość musi być skonfigurowana, jeśli żądanie do interfejsu API zawiera część contentDetails w wartości parametru part. Jeśli jednak wybierzesz ustawienie insert a broadcast, właściwość będzie opcjonalna i ma wartość domyślną true.

Uwaga: tej właściwości nie można zaktualizować, gdy transmisja jest w stanie testing lub live.
contentDetails.enableDvr boolean
To ustawienie określa, czy widzowie mogą korzystać z elementów sterujących DVR podczas oglądania filmu. Elementy sterujące DVR umożliwiają widzowi sterowanie odtwarzaniem filmu przez wstrzymywanie, przewijanie do tyłu i do przodu. Wartością domyślną tej właściwości jest true.

Gdy update a broadcast, ta właściwość musi być ustawiona, jeśli żądanie interfejsu API zawiera część contentDetails w wartości parametru part. Jeśli jednak wybierzesz ustawienie insert a broadcast, właściwość będzie opcjonalna i ma wartość domyślną true.

Ważne: jeśli chcesz, aby odtwarzanie było dostępne natychmiast po zakończeniu transmisji, musisz ustawić wartość na true i ustawić wartość właściwości enableArchive na true. Ponadto nie można aktualizować tej właściwości, gdy transmisja jest w stanie testing lub live.
contentDetails.recordFromStart boolean
To ustawienie wskazuje, czy YouTube ma automatycznie rozpocząć nagrywanie transmisji po zmianie stanu na „Na żywo”.

Domyślna wartość tej właściwości to true. Można ją ustawić na false tylko wtedy, gdy kanał nadawania może wyłączyć nagrywanie transmisji na żywo.

Jeśli Twój kanał nie ma uprawnień do wyłączania nagrań, a Ty spróbujesz wstawić transmisję z właściwością recordFromStart ustawioną na false, interfejs API zwróci błąd Forbidden. Jeśli Twój kanał nie ma tego uprawnienia i spróbujesz zaktualizować transmisję, aby ustawić wartość właściwości recordFromStart na false, interfejs API zwróci błąd modificationNotAllowed.

W polu update a broadcast ta właściwość musi być skonfigurowana, jeśli żądanie do interfejsu API zawiera część contentDetails w wartości parametru part. Jednak w przypadku wartości insert a broadcast ta właściwość jest opcjonalna i ma domyślną wartość true.

Ważne: jeśli chcesz, aby odtwarzanie było dostępne natychmiast po zakończeniu transmisji, musisz też ustawić wartość właściwości enableDvr na true. Jeśli ustawisz wartość tej właściwości na true, ale nie ustawisz też wartości właściwości enableDvr na true, może minąć około 1 dnia, zanim zarchiwizowany film będzie można odtworzyć.

Uwaga: tej właściwości nie można zaktualizować, gdy transmisja ma stan testing lub live.
contentDetails.enableClosedCaptions boolean
Ta właściwość została wycofana 17 grudnia 2015 r. Zamiast tego użyj właściwości contentDetails.closedCaptionsType.

To ustawienie wskazuje, czy wyświetlanie napisów za pomocą metody HTTP POST jest włączone dla tej transmisji. W przypadku klientów interfejsu API, którzy już korzystają z tej usługi:
  • Ustawienie wartości właściwości na true jest równoznaczne z ustawieniem właściwości contentDetails.closedCaptionsType na closedCaptionsHttpPost.
  • Ustawienie wartości właściwości na false jest równoznaczne z ustawieniem właściwości contentDetails.closedCaptionsType na closedCaptionsDisabled.
contentDetails.closedCaptionsType string
Uwaga: ta właściwość zastępuje właściwość contentDetails.enableClosedCaptions.

Ta właściwość wskazuje, czy w Twoim programie są włączone napisy, a jeśli tak, to jakiego typu:
  • closedCaptionsDisabled: napisy są wyłączone w przypadku transmisji na żywo.
  • closedCaptionsHttpPost: napisy wysyłasz za pomocą HTTP POST do adresu URL przetwarzania powiązanego z transmisją na żywo.
  • closedCaptionsEmbedded: napisy zostaną zakodowane w strumieniu wideo za pomocą formatów EIA-608 lub CEA-708.
contentDetails.projection string
Format rzutowania tej transmisji. Domyślna wartość tej właściwości to rectangular.

Prawidłowe wartości to:
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
Wskazuje, czy ta transmisja powinna być kodowana pod kątem strumieniowego przesyłania obrazu z małą latencją. Strumień o małym opóźnieniu może skrócić czas potrzebny na udostępnienie filmu użytkownikom oglądającym transmisję, ale może też wpływać na rozdzielczość u widzów transmisji.
contentDetails.latencyPreference string
Wskazuje, którego ustawienia opóźnienia użyć w przypadku tej transmisji. Możesz użyć tej właściwości zamiast właściwości enableLowLatency, która nie obsługuje ultraLow.

Strumień o małym opóźnieniu może skrócić czas potrzebny na to, aby film był widoczny dla użytkowników oglądających transmisję, ale może też wpływać na płynność odtwarzania.

Strumieni z bardzo małym opóźnieniem jeszcze bardziej skraca czas potrzebny na pojawienie się filmu dla widzów, co ułatwia interakcję z widzami, ale w przypadku napisów o bardzo niewielkim opóźnieniu interakcja z nimi jest łatwiejsza niż 8.

  • normal
  • low
  • ultraLow
contentDetails.enableAutoStart boolean
Wskazuje, czy ta transmisja ma się rozpoczynać automatycznie po rozpoczęciu przesyłania strumieniowego wideo na powiązanym urządzeniu live stream.
contentDetails.enableAutoStop boolean
Określa, czy ta transmisja powinna zakończyć się automatycznie około minuty po tym, jak właściciel kanału zatrzyma przesyłanie strumienia wideo na powiązanym kanale.
statistics object
Obiekt statistics zawiera statystyki związane z transmisją na żywo. Wartości tych statystyk mogą się zmieniać w trakcie transmisji i można je pobrać tylko wtedy, gdy transmisja jest na żywo.
statistics.totalChatCount unsigned long
Łączna liczba wiadomości na czacie na żywo powiązanych z transmisją. Właściwość i jej wartość są dostępne, jeśli transmisja jest widoczna dla użytkownika, ma włączoną funkcję czatu na żywo i co najmniej 1 wiadomość. Zwróć uwagę, że ta właściwość nie określa żadnej wartości po zakończeniu transmisji. W związku z tym ta właściwość nie będzie identyfikować liczby wiadomości na czacie w archiwalnym filmie z ukończonej transmisji na żywo.
monetizationDetails object
Obiekt monetizationDetails zawiera informacje o szczegółach zarabiania na strumieniu, takie jak włączenie automatu reklamowego lub opóźnienie wstawiania reklam w trakcie filmu.

monetizationDetails.cuepointSchedule object
Obiekt cuepointSchedule określa ustawienia automatyzacji reklam dla transmisji.
monetizationDetails.cuepointSchedule.enabled boolean
Ta wartość określa, czy reklamy są automatycznie wstawiane do transmisji. Jeśli wartość to true, YouTube automatycznie wstawia reklamy w trakcie transmisji. Harmonogram wyświetlania reklam będzie określany przez wartość innych pól obiektu monetizationDetails.cuepointSchedule.
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
Ta wartość określa, że YouTube nie powinien wstawiać reklam w trakcie transmisji do momentu wskazanej daty i godziny. Wartość jest określona w formacie ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Aby wstrzymać reklamy, musisz ustawić wartość na przyszłą datę i godzinę. Wartość tego pola możesz też ustawić na datę i godzinę w niedalekiej przyszłości, aby wstrzymane reklamy zostały wznowione po upływie czasu.
monetizationDetails.cuepointSchedule.scheduleStrategy string
Ta wartość określa strategię, której YouTube powinien używać do planowania punktów cue. Prawidłowe wartości to:
  • CONCURRENT: punkty wstawienia reklamy są zaplanowane w tym samym czasie dla wszystkich widzów
  • NON_CONCURRENT: punkty cue są zaplanowane na różne godziny dla różnych widzów. Dzięki temu reklamy mogą wyświetlać się z większą częstotliwością, co pozwala widzom otrzymywać punkty cue w odpowiednich momentach.
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
Ta wartość określa odstęp czasu w sekundach między automatycznym wstawianiem reklam podczas transmisji. Jeśli na przykład wartość wynosi 300, YouTube może wstawiać punkty wstawienia reklamy w trakcie filmu co 5 minut.

Pamiętaj, że ta wartość określa czas między początkiem kolejnych punktów wstawienia reklamy. Oznacza to, że przerwa nie jest mierzona od końca jednego punktu cue do początku następnego.