YouTube Live Streaming API – Übersicht

Mit der YouTube Live Streaming API kannst du Live-Veranstaltungen auf YouTube erstellen, aktualisieren und verwalten. Verwende diese API, um Veranstaltungen (Übertragungen) zu planen und mit Videostreams zu verknüpfen, die den eigentlichen Übertragungsinhalt repräsentieren.

Die Live Streaming API besteht aus Komponenten der YouTube Data API und der YouTube Content ID API. Mit der Data API können YouTube-Nutzer ihre YouTube-Konten verwalten, während die YouTube Content ID API Interaktionen mit dem Rechteverwaltungssystem von YouTube ermöglicht. Alle Ressourcen, aus denen die Live Streaming API besteht, werden jedoch nur zum Erstellen und Verwalten von Live-Veranstaltungen verwendet.

Dieses Dokument richtet sich an Entwickler, die Anwendungen schreiben möchten, um Liveübertragungen auf YouTube zu ermöglichen. Es werden grundlegende Konzepte von YouTube und der API selbst erläutert. Außerdem wird ein Überblick über die verschiedenen Funktionen gegeben, die von der API unterstützt werden.

Wichtige Konzepte

Übertragungen

Eine Übertragung ist eine Veranstaltung, die auf YouTube live angesehen werden kann. Übertragungen können auch aufgezeichnet und als YouTube-Videos gespeichert werden, damit Nutzer sie sich später ansehen können.

Streams

Ein Stream gibt die Audio- und Videoinhalte an, die an YouTube gesendet werden. Jede Übertragung ist mit einem Videostream verknüpft.

Cuepoints

Ein cuepoint ist eine Werbeunterbrechung, die in eine Live-Übertragung eingefügt werden kann.

Anwendungsfälle für die API

In der folgenden Liste sind einige Möglichkeiten zur Verwendung der API in deiner Anwendung aufgeführt:

• Übertragungen planen und Übertragungseinstellungen festlegen Mit deiner Anwendung können Nutzer Übertragungseinstellungen vordefinieren und dann die Einstellungen auswählen, die auf eine bestimmte Übertragung angewendet werden sollen.

• Videostreams und Übertragungen verknüpfen

• Übertrager können gleichzeitig Informationen zu einer Übertragung und ihrem Video (mit der YouTube Data API) definieren.

• Übergänge zwischen Übertragungsstatus (z. B. testing oder live) vereinfachen und Nutzern ermöglichen, Cuepoints einzufügen

Vorbereitung

1. Du benötigst ein Google-Konto, um auf die Google Cloud console zuzugreifen, einen API-Schlüssel anzufordern und deine Anwendung zu registrieren.

2. Registriere deine Anwendung bei Google, um API-Anfragen über die Anwendung einreichen zu können.

3. Nach der Registrierung deiner Anwendung wähle die YouTube Data API als einen der Dienste aus, die von deiner Anwendung verwendet werden:

   1. Rufe die Cloud console auf und wähle das Projekt aus, das du gerade registriert hast.
   2. Rufe die Seite „Aktivierte APIs“ auf. Prüfe in der Liste der APIs, ob der Status für die YouTube Data API v3 und, falls du YouTube-Content-Partner bist, für die YouTube Content ID API auf EIN gesetzt ist.

4. Mache dich mit den grundlegenden Konzepten des Datenformats JavaScript Object Notation (JSON) vertraut. JSON ist ein gängiges sprachunabhängiges Datenformat, das eine einfache Textdarstellung beliebiger Datenstrukturen bietet. Weitere Informationen findest du unter json.org.

API-Anfragen autorisieren

Wie oben erwähnt, verwendet die Live Streaming API Funktionen, die technisch entweder Teil der YouTube Data API oder der YouTube Content ID API sind. Mit der Content ID API kannst du YouTube Metadaten, Informationen zur Inhaberschaft und Richtlinieninformationen für deine Assets zur Verfügung stellen. Eine Live-Videoübertragung ist ein Beispiel für ein Asset. Mit der API kannst du auch Ansprüche auf Videos erheben und Anzeigenrichtlinien für deine Videos festlegen.

In diesem Abschnitt werden die Autorisierungsanforderungen für Anfragen an die Content ID API erläutert, die sich von den Anforderungen für die Autorisierung anderer Live Streaming API Anfragen unterscheiden.

Data API aufrufen

Die API-Anfrage muss vom Google-Konto des Inhabers des YouTube-Kanals für die Übertragung autorisiert werden.

Content ID API aufrufen

Die API-Anfrage muss von einem Google-Konto autorisiert werden, das mit dem Rechteinhaber verknüpft ist, der Inhaber des YouTube-Kanals für die Übertragung ist.

Ressourcen und Ressourcentypen

Eine Ressource ist eine individuelle Datenentität mit einer eindeutigen Kennung. In der folgenden Tabelle werden die verschiedenen Ressourcentypen beschrieben, mit denen du über die Live Streaming API interagierst. Technisch gesehen sind alle diese Ressourcen tatsächlich als Teil entweder der YouTube Data API oder der YouTube Content ID API definiert. Die Ressourcen liveBroadcast, liveStream und cuepoint werden jedoch nur zum Erstellen und Verwalten von Live-Veranstaltungen verwendet.

Unterstützte Vorgänge

In der folgenden Tabelle sind die verschiedenen Methoden aufgeführt, die von der API unterstützt werden:

In der folgenden Tabelle sind die Vorgänge aufgeführt, die für verschiedene Ressourcentypen unterstützt werden. Für Vorgänge, mit denen Ressourcen eingefügt, aktualisiert oder gelöscht werden, ist immer eine Nutzerautorisierung erforderlich. In einigen Fällen unterstützen list-Methoden sowohl autorisierte als auch nicht autorisierte Anfragen. Bei nicht autorisierten Anfragen werden nur öffentliche Daten abgerufen, während bei autorisierten Anfragen auch Informationen abgerufen werden können, die auf den authentifizierten Nutzer beschränkt sind.

Teilressourcen

Die API ermöglicht und erfordert sogar das Abrufen von Teilressourcen, damit Anwendungen das Übertragen, Parsen und Speichern unnötiger Daten vermeiden. Dieser Ansatz sorgt auch dafür, dass die API Netzwerk-, CPU- und Arbeitsspeicherressourcen effizienter nutzt.

Der part Parameter ist ein Pflichtparameter für jede API-Anfrage, die eine YouTube Data API Ressource abruft oder zurückgibt. Der Parameter gibt eine oder mehrere Ressourcenattribute der obersten Ebene (nicht verschachtelt) an, die in einer API-Antwort enthalten sein sollen. Eine liveStream-Ressource hat beispielsweise die folgenden Teile:

• snippet
• cdn
• status

Alle diese Teile sind Objekte, die verschachtelte Attribute enthalten. Du kannst dir diese Objekte als Gruppen von Metadatenfeldern vorstellen, die der API-Server möglicherweise abruft. Daher musst du mit dem Parameter part die Ressourcenkomponenten auswählen, die deine Anwendung tatsächlich verwendet. Diese Anforderung erfüllt zwei wichtige Zwecke:

• Sie reduziert die Latenz, da der API-Server keine Zeit mit dem Abrufen von Metadatenfeldern verbringt, die deine Anwendung nicht verwendet.
• Sie reduziert die Bandbreitennutzung, indem die Menge unnötiger Daten, die deine Anwendung möglicherweise abruft, reduziert (oder ganz vermieden) wird.

Im Laufe der Zeit, wenn Ressourcen weitere Teile hinzufügen, werden diese Vorteile nur noch größer, da deine Anwendung keine neu eingeführten Attribute anfordert, die sie nicht unterstützt.

Tipps und Best Practices

Anspruch auf deine Inhalte erheben

Wenn du während deiner Übertragung Anzeigen einblenden möchtest, musst du vor Beginn der Veranstaltung Anspruch auf das Übertragungsvideo erheben. Um Anspruch auf Inhalte zu erheben, musst du ein YouTube-Content-Partner sein und am Content ID Programm teilnehmen.

Der Vorgang zum Beanspruchen deines Liveübertragungsvideos unterscheidet sich vom normalen Vorgang zum Beanspruchen eines Videos. Wenn du Anspruch auf ein Live-Video erheben möchtest, musst du den Anspruch erstellen, bevor das Video tatsächlich vorhanden ist. Die API unterstützt dies und im Dokument Lebenszyklus einer Übertragung werden die YouTube Content ID API Aufrufe erläutert, mit denen du deinen Anspruch erstellen kannst.

Inhalte in der Vorschau ansehen und testen

Nachdem YouTube deinen eingehenden Videostream empfangen hat, kann das Video in zwei verschiedenen ausgehenden Streams übertragen werden:

• Mit dem Monitorstream kannst du deine Videoübertragung in der Vorschau ansehen und testen. Es handelt sich um einen privaten Stream, auf den nur du zugreifen kannst. Du kannst eine Übertragung nur dann in die Phase testing überführen, wenn der Monitorstream der Übertragung aktiviert ist. Im Monitorstream werden keine Werbeunterbrechungen angezeigt.

• Der Übertragungsstream ist der Stream, der für dein Publikum sichtbar ist. Du kannst den Datenschutzstatus der Übertragung auf public, private oder unlisted setzen. Eine private Übertragung ist nur für Nutzer sichtbar, die ausdrücklich eingeladen wurden, sie anzusehen. Eine nicht gelistete Übertragung ist für alle sichtbar, die einen Link dazu haben.

  Du kannst den Übertragungsstream verzögern, damit er nicht gleichzeitig mit dem Monitorstream ausgeführt wird. Wenn du den Übertragungsstream verzögerst, hast du mehr Kontrolle über den Zeitpunkt, zu dem du Cuepoints in die Übertragung einfügst.

  Wenn du den Übertragungsstream verzögerst, können deine Live-Moderatoren jedoch nur schwer mit den Zuschauern interagieren. Außerdem steigt die Wahrscheinlichkeit, dass Zuschauer wichtige Details zur Veranstaltung aus anderen Quellen als deiner Übertragung erfahren. Wenn du beispielsweise eine Sportveranstaltung mit einer Verzögerung von 60 Sekunden überträgst, erfahren Zuschauer möglicherweise von anderen Echtzeit-Nachrichtenquellen von wichtigen Momenten der Veranstaltung, bevor sie sie in der Übertragung sehen.

YouTube empfiehlt, den Monitorstream für deine Übertragung zu aktivieren, damit du deine Inhalte testen kannst. Du solltest entscheiden, ob du deine Übertragung auch verzögern möchtest. Dabei solltest du abwägen, ob du die Zeitpunkte für Cuepoints lieber selbst bestimmen möchtest oder lieber mit deinem Publikum interagieren oder in Echtzeit über eine Veranstaltung berichten möchtest.

Mid-Roll-Anzeigen während einer Übertragung einblenden

Während einer Übertragung kannst du einen cuepoint einfügen, um anzugeben, dass eine Werbeunterbrechung in der Übertragung so bald wie möglich oder zu einem bestimmten Zeitpunkt beginnen soll. Durch die Werbeunterbrechung kann YouTube Mid-Roll-Anzeigen während der Übertragung einblenden.

Werbeunterbrechungen haben die folgenden Eigenschaften:

1. Sie haben eine vordefinierte Länge, die du mit dem cuepoint Ressource's durationSecs Attribut festlegst. Nach der Werbeunterbrechung kehren die Zuschauer zur Live-Übertragung zurück.

2. Wenn eine Werbeunterbrechung stattfindet, wird eine Anzeige nur im Videoplayer für Zuschauer eingeblendet, die sich die Übertragung ansehen, wenn der Cuepoint eingefügt wird. Eine Anzeige wird nicht eingeblendet, wenn Zuschauer die Seite aktualisieren auf der die Übertragung wiedergegeben wird, oder wenn Besucher die Übertragung ansehen, nachdem der Cuepoint eingefügt wurde.

Die folgende Schrittfolge entspricht der Best Practice zum Einfügen einer Werbeunterbrechung während deiner Übertragung:

Zeitstempel festlegen

Wenn du einen Cuepoint einfügst, kannst du angeben, dass er sofort oder dass er an einer bestimmten Stelle in der Übertragung eingefügt werden soll. Die Optionen hängen davon ab, ob der Übertragungsstream für dein Video verzögert ist.

• Wenn dein Übertragungsstream nicht verzögert ist, kannst du den Cuepoint sofort einfügen oder mit dem walltimeMs Attribut festlegen, dass die Werbeunterbrechung zu einem bestimmten Zeitpunkt beginnen soll.

  • Rufe die Methode liveBroadcasts.cuepoint auf, um die Werbeunterbrechung sofort zu starten. Setze in der Ressource im Anfragetext den Wert des Attributs insertionOffsetTimeMs auf 0 oder gib keinen Wert für dieses Attribut und gib keinen Wert für das Attribut walltimeMs an.

    Wichtig:Die Zuschauer sehen die resultierenden Anzeigen inhalte nicht sofort. Es kann etwa 30 Sekunden dauern, bis die Anzeigeninhalte für Nutzer sichtbar sind. Während dieser Verzögerung ist dein Übertragungsstream weiterhin für deine Zuschauer sichtbar. Du musst den Übertragungsstream ansehen, um zu sehen, wann die Anzeigeninhalte anstelle deines Monitorstreams angezeigt werden.

  • Wenn die Werbeunterbrechung zu einem bestimmten Zeitpunkt beginnen soll, rufe die liveBroadcasts.cuepoint Methode auf und gib mit dem walltimeMs Attribut den gewünschten Zeitpunkt an. Der Attributwert ist eine Ganzzahl, die einen Epoch-Zeitstempel darstellt.

• Wenn dein Übertragungsstream verzögert ist, kannst du den Cuepoint wie oben beschrieben sofort einfügen, eine Uhrzeit wie oben beschrieben angeben oder einen Zeitstempel angeben, um festzulegen, wann die Werbeunterbrechung beginnen soll. Der Zeitstempel gibt einen Zeitpunkt in deiner Übertragung an, zu dem Zuschauer eine Anzeige sehen sollen.

  Der Zeitstempel wird in Millisekunden ab dem Beginn des Monitorstreams für deine Übertragung gemessen. Wenn deine Übertragung eine Testphase hat, beginnt der Monitorstream wenn deine Übertragung in den testing Status übergeht. Andernfalls beginnt der Monitorstream, wenn deine Übertragung in den Status live übergeht.

  Setze beim Einfügen eines Cuepoints das Attribut cuepoint der Ressource insertionOffsetTimeMs auf den gewünschten Zeitstempel.

Zeitstempel berechnen

Rufe die Funktion getCurrentTime der YouTube Player API für den Player auf, der den Monitorstream wiedergibt, um den Zeitstempel abzurufen. Verwende den abgerufenen Wert, um den Cuepoint zu diesem Zeitpunkt in den Übertragungsstream einzufügen.

Die möglichen Werte für die Zeitstempel können als folgender Bereich berechnet werden:

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

Das Δ ist ein Puffer von fünf Sekunden am Anfang und Ende der möglichen Zeitstempel, wenn YouTube einen Cuepoint nicht genau einfügen kann. Beispiel:

• Eine Übertragung hat eine Testphase von fünf Minuten.
• Der Übertragungsstream wird 60 Sekunden nach dem Monitorstream verzögert.
• Der Übertrager fügt den Cuepoint vier Minuten ein, nachdem die Übertragung in den Status live übergegangen ist. Das sind drei Minuten, nachdem der Übertragungsstream sichtbar wurde.

In diesem Fall ist der mögliche Bereich der Zeitstempel [(485,000), (535,000)].

Diese Zeiten werden in Millisekunden angegeben und mit den folgenden Werten berechnet:

• elapsed_time=540000 – Der Monitorstream wurde neun Minuten lang (540 Sekunden, 540.000 Millisekunden) ausgeführt, als die liveBroadcasts.cuepoint Methode aufgerufen wurde.
• broadcast_delay=60000 – Der Übertragungsstream wird um 60 Sekunden oder 60.000 Millisekunden verzögert.
• Δ=5000 – Der Puffer von fünf Sekunden, wenn der Cuepoint nicht zuverlässig eingefügt werden kann.

Problembehebung und Fehlerbehandlung

In den folgenden Richtlinien wird erläutert, wie du bestimmte Probleme beheben kannst, die auftreten können. Die Listen der Fehler, die von den einzelnen API-Methoden zurückgegeben werden können, findest du unter YouTube Live Streaming API – Fehler.

• Wenn eine Übertragung von einem Status in einen anderen übergeht, kann ihr vorübergehend ein anderer Status zugewiesen werden, während YouTube die mit dem Übergang verbundenen Aktionen ausführt. Wenn du beispielsweise eine liveBroadcasts.transition-Anfrage sendest, um den Status einer Übertragung von ready in testing zu ändern, setzt YouTube den Status der Übertragung auf testStarting und führt dann die mit der Statusänderung verbundenen Aktionen aus. Wenn alle diese Aktionen abgeschlossen sind, aktualisiert YouTube den Status der Übertragung auf testing und gibt damit an, dass der Übergang abgeschlossen ist.

  Wenn eine Übertragung mit dem Status testStarting oder liveStarting hängen bleibt, musst du die Methode liveBroadcasts.delete aufrufen und die Übertragung löschen. Erstelle dann eine neue Übertragung, verknüpfe sie mit deinem Livestream und setze den Testvorgang fort.

  Wie in der Dokumentation der Methode liveBroadcasts.transition erwähnt, solltest du bestätigen, dass der Wert des Attributs status.streamStatus für den mit deiner Übertragung verknüpften Stream active ist, bevor du diese Methode aufrufst.