YouTube Live Streaming API – Übersicht

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

Das 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 YouTube-System zur Rechteverwaltung 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 zur Erleichterung der Liveübertragung auf YouTube entwickeln möchten. Darin werden die grundlegenden Konzepte von YouTube und der API selbst erklärt. Außerdem erhalten Sie einen Überblick über die verschiedenen Funktionen, die von der API unterstützt werden.

Wichtige Konzepte

Nachrichten an alle
Eine Sendung ist ein Ereignis, das währenddessen auf YouTube angesehen werden kann. Broadcasts können auch als YouTube-Videos aufgezeichnet und gespeichert werden, damit Nutzer sie später ansehen können.
Streams
Ein Stream bezeichnet den Audio-/Videoinhalt, der an YouTube übermittelt wird. Jede Übertragung ist einem Videostream zugeordnet.
Referenzpunkte
Ein Cue-Punkt ist eine Werbeunterbrechung, die in eine Liveübertragung eingefügt werden kann.

API-Anwendungsfälle

In der folgenden Liste werden mehrere Möglichkeiten zur Verwendung der API in Ihrer Anwendung vorgeschlagen:

  • Übertragungen planen und Übertragungseinstellungen festlegen Ihre App könnte Nutzern ermöglichen, Übertragungseinstellungen vorzudefinieren und dann die Einstellungen auszuwählen, die auf eine bestimmte Übertragung angewendet werden sollen.

  • Videostreams und Broadcasts verknüpfen

  • Mit der YouTube Data API können Sender gleichzeitig Informationen zu einer Übertragung und dem zugehörigen Video angeben.

  • Vereinfachen Sie die Übergänge zwischen Übertragungszuständen (testing, live usw.) und ermöglichen Sie Nutzern das Einfügen von Cue-Punkten.

Vorbereitung

  1. Sie benötigen ein Google-Konto, um auf Google API Console zugreifen, einen API-Schlüssel anfordern und Ihre Anwendung registrieren zu können.

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

  3. Wählen Sie nach der Registrierung Ihrer Anwendung den YouTube Data API als einen der Dienste aus, die Ihre Anwendung verwendet:

    1. Gehen Sie zu API Console und wählen Sie das Projekt aus, das Sie gerade registriert haben.
    2. Rufen Sie die Seite Aktivierte APIs auf. Vergewissere dich in der Liste der APIs, dass der Status für Version 3 der YouTube Data API und, wenn du YouTube-Contentpartner bist, für die YouTube Content ID API EIN lautet.

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

API-Anfragen autorisieren

Wie oben erwähnt, nutzt das 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 mit Metadaten, Informationen zu Eigentumsrechten und Richtlinien für deine Assets versorgen. Ein Beispiel für einen Inhalt ist eine Live-Videoübertragung. Mit der API kannst du auch Anspruch auf Videos erheben und Werberichtlinien 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 von dem Google-Konto autorisiert werden, zu dem der YouTube-Kanal gehört.
Content ID API aufrufen
Die API-Anfrage muss von einem Google-Konto autorisiert werden, das mit dem Rechteinhaber des YouTube-Kanals verknüpft ist, der übertragen wird.

Ressourcen und Ressourcentypen

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

Ressourcen
liveBroadcast Enthält Informationen zu einer Veranstaltung, die du auf YouTube überträgst. Eine liveBroadcast-Ressource ist eine Erweiterung einer YouTube-Videoressource und legt Videometadaten fest, die für eine Liveübertragung relevant sind, aber nicht für andere YouTube-Videos.

Daher entspricht eine Ressource vom Typ liveBroadcast genau einer YouTube-Videoressource. Tatsächlich haben die Ressource liveBroadcast und die Ressource video dieselbe ID. Nachdem du die Übertragung mit der Live Streaming API erstellt hast, kannst du mit der YouTube Data API zusätzliche Metadaten zum Video bereitstellen.
liveStream Enthält Informationen über den Video-Stream, den du an YouTube überträgst. Der Stream enthält die Inhalte, die für YouTube-Nutzer übertragen werden. Nach dem Erstellen kann eine liveStream-Ressource an genau eine liveBroadcast-Ressource gebunden werden. Ebenso kann die Ressource liveBroadcast nur an eine liveStream-Ressource gebunden werden.
cuepoint Fügt einen Cue-Punkt in den Videostream ein, der eine Werbeunterbrechung auslösen kann. Verwenden Sie die Methode liveBroadcasts.cuepoint, um während einer Übertragung einen Cue-Punkt einzufügen.
video Steht für ein einzelnes YouTube-Video. Wie oben erwähnt, ist eine liveBroadcast-Ressource eine Erweiterung einer video-Ressource. Mit der YouTube Data API kannst du die Metadaten des Videos aktualisieren, z. B. den Aufnahmeort oder die Regionen, in denen die Übertragung zu sehen sein wird.
videoAdvertisingOptions Legt die Einstellungen für Werbung für ein Video (oder eine Übertragung) fest. Mit YouTube Content ID API können Sie Werbeoptionen festlegen.
asset Sie stellen geistiges Eigentum dar, z. B. einen Film oder eine Folge einer Serie. In diesem Fall ist die Videoübertragung der Inhalt. Mit dem YouTube Content ID API erstellen und verwalten Sie asset Ressourcen.
claim Verknüpft ein Video mit einem Asset, mit dem das Video übereinstimmt. Du erhebst mithilfe der YouTube Content ID API einen Anspruch, um dich als Rechteinhaber der Videoübertragung zu identifizieren.
policy In diesen Regeln wird festgelegt, unter welchen Umständen deine Inhalte auf YouTube sichtbar sein oder nicht erscheinen sollen. Sie müssen eine Richtlinie auf Ihre Videoübertragung anwenden und auch eine Richtlinie angeben, die YouTube auf von Nutzern hochgeladene Videos anwendet, die mit Ihrer Videoübertragung übereinstimmen.

Unterstützte Vorgänge

In der folgenden Tabelle sind die verschiedenen von der API unterstützten Methoden aufgeführt:

Operations
list Ruft eine Liste mit null oder mehr Ressourcen ab (GET).
insert Erstellt (POST) eine neue Ressource.
update Ändert eine vorhandene Ressource (PUT), damit die Daten in Ihrer Anfrage widergespiegelt werden.
bind Verknüpft eine liveBroadcast-Ressource mit einer liveStream-Ressource oder entfernt einen solchen Link.
transition Ändert den Status einer liveBroadcast-Ressource und initiiert alle Prozesse, die mit dem neuen Status verknüpft sind. Wenn du beispielsweise den Status einer Übertragung auf testing änderst, beginnt YouTube damit, Videos an den Monitorstream dieser Übertragung zu übertragen.
delete Entfernt (DELETE) eine bestimmte Ressource.

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

Unterstützte Vorgänge
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

Teilressourcen

Die API ermöglicht und erfordert das Abrufen von Teilressourcen, sodass Anwendungen das Übertragen, Parsen und Speichern nicht benötigter Daten vermeiden. Dieser Ansatz stellt auch sicher, dass die API Netzwerk-, CPU- und Speicherressourcen effizienter nutzt.

Der part-Parameter ist ein erforderlicher Parameter für jede API-Anfrage, die eine YouTube Data API-Ressource abruft oder zurückgibt. Der Parameter gibt ein oder mehrere (nicht verschachtelte) Ressourceneigenschaften der obersten Ebene an, die in einer API-Antwort enthalten sein sollten. Eine liveStream-Ressource besteht beispielsweise aus folgenden Teilen:

  • snippet
  • cdn
  • status

Alle diese Teile sind Objekte, die verschachtelte Eigenschaften enthalten. Sie können sich diese Objekte als Gruppen von Metadatenfeldern vorstellen, die vom API-Server abgerufen werden (oder auch nicht). Daher müssen Sie für den Parameter part die Ressourcenkomponenten auswählen, die Ihre Anwendung tatsächlich verwendet. Diese Anforderung dient zwei wichtigen Zwecken:

  • Es reduziert die Latenz, da der API-Server keine Zeit damit verbringt, Metadatenfelder abzurufen, die nicht von Ihrer Anwendung verwendet werden.
  • Es reduziert die Bandbreitennutzung, indem die Menge an unnötigen Daten, die von Ihrer Anwendung möglicherweise abgerufen werden, reduziert (oder entfernt) wird.

Wenn die Ressourcen im Laufe der Zeit immer mehr Teile hinzufügen, werden diese Vorteile nur zunehmen, da Ihre Anwendung keine neu eingeführten Eigenschaften anfordert, die sie nicht unterstützt.

Tipps und Best Practices

Anspruch auf Inhalte erheben

Wenn während der Übertragung Anzeigen eingeblendet werden sollen, musst du vor Beginn der Veranstaltung Anspruch auf das übertragene Video erheben. Um Anspruch auf Inhalte erheben zu können, musst du YouTube-Contentpartner sein und am Content ID-Programm teilnehmen.

Das Verfahren, mit dem Anspruch auf ein Liveübertragungsvideo erhoben wird, unterscheidet sich von dem üblichen Verfahren. Wenn du Anspruch auf ein Livevideo erhebst, musst du diesen erst erheben, bevor das Video tatsächlich existiert. Die API unterstützt dies und in dem Dokument zur Lebensdauer einer Übertragung werden die YouTube Content ID API-Aufrufe erläutert, mit denen Sie Ihren Anspruch erstellen können.

Inhalte in der Vorschau ansehen und testen

Nach dem Empfang deines eingehenden Videostreams kann YouTube dieses Video an zwei verschiedene ausgehende Streams übertragen:

  • Mit der Stream-Übertragung können Sie eine Vorschau Ihrer Videoübertragung ansehen und testen. Er ist ein privater Stream, auf den nur Sie zugreifen können. Sie können eine Übertragung nur dann in die testing-Phase wechseln, wenn der Monitorstream der Übertragung aktiviert ist. Im Monitorstream werden keine Werbeunterbrechungen angezeigt.

  • Der Broadcast ist der Stream, der deinen Zuschauern angezeigt wird. Du kannst den Datenschutzstatus der Übertragung auf public, private oder unlisted festlegen. Eine private Übertragung ist nur für Nutzer sichtbar, die ausdrücklich zum Ansehen eingeladen wurden. Eine nicht gelistete Übertragung ist dagegen für alle Nutzer sichtbar, die über den entsprechenden Link verfügen.

    Sie können den Übertragungsstream verzögern, sodass er nicht gleichzeitig mit dem Monitorstream ausgeführt wird. Durch das Verzögern des Übertragungsstreams können Sie genauer steuern, wann Sie Cue-Punkte in die Übertragung einfügen.

    Eine Verzögerung der Übertragung erschwert den Vortragenden jedoch die Interaktion mit dem Publikum. Außerdem steigt bei einer Verzögerung der Übertragung die Wahrscheinlichkeit, dass Zuschauer wichtige Details zur Veranstaltung auch aus anderen Quellen als deiner Übertragung entdecken. Wenn Sie beispielsweise eine Sportveranstaltung mit 60 Sekunden Verzögerung übertragen, erfahren die Zuschauer möglicherweise von anderen Echtzeit-Nachrichtenquellen über kritische Momente im Ereignis, bevor sie sie tatsächlich in der Übertragung sehen.

YouTube empfiehlt, dass Sie den Monitor-Stream für Ihre Übertragung aktivieren, damit Sie Ihren Content testen können. Sie sollten festlegen, ob die Übertragung auch verzögert werden soll, wenn Sie das Timing der Cue-Punkte steuern möchten, und nicht, ob Sie mit Ihrem Publikum interagieren oder eine Echtzeit-Berichterstattung zu einem Ereignis bereitstellen möchten.

Mid-Roll-Anzeigen während eines Übertragungsstreams schalten

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

Werbeunterbrechungen haben folgende Eigenschaften:

  1. Sie hat eine vordefinierte Dauer, die Sie mit dem Attribut durationSecs der Ressource cuepoint festlegen. Nach Ende der Werbeunterbrechung kehren die Zuschauer zur Liveübertragung zurück.

  2. Bei einer Werbeunterbrechung wird im Videoplayer nur dann eine Anzeige für Zuschauer wiedergegeben, die sich die Übertragung ansehen, wenn der Cue-Punkt eingefügt wird. Eine Anzeige wird nicht ausgeliefert, wenn Nutzer die Seite aktualisieren, auf der die Übertragung wiedergegeben wird, oder wenn Besucher die Übertragung starten, nachdem der Cue-Punkt eingefügt wurde.

Die folgende Abfolge entspricht der Best Practice für das Einfügen einer Werbeunterbrechung während einer Übertragung:

Zeitverschiebungen festlegen

Beim Einfügen eines Cue-Punkts können Sie angeben, ob er sofort oder an einer bestimmten Stelle im Broadcast eingefügt werden soll. Die verfügbaren Optionen hängen davon ab, ob der Broadcast-Stream für dein Video verzögert ist.

  • Wenn Ihr Übertragungsstream nicht verzögert ist, können Sie den Cue-Punkt sofort einfügen oder das Attribut walltimeMs verwenden, um die Werbeunterbrechung zu einer bestimmten Zeit zu starten.

    • Wenn du die Werbeunterbrechung sofort starten möchtest, ruf die Methode liveBroadcasts.cuepoint auf. Legen Sie in der Ressource im Anfragetext den Wert des Attributs insertionOffsetTimeMs auf 0 fest oder geben Sie keinen Wert für dieses Attribut an und geben Sie keinen Wert für das Attribut walltimeMs an.

      Wichtig:Betrachter sehen die resultierenden Anzeigeninhalte nicht sofort. Es kann etwa 30 Sekunden dauern, bis der Anzeigeninhalt für Nutzer sichtbar wird. Während dieser Verzögerung ist der Stream für die Zuschauer weiterhin sichtbar und Sie müssen ihn sich ansehen, um festzustellen, wann der Anzeigeninhalt anstelle des Monitorstreams tatsächlich eingeblendet wird.

    • Wenn du die Werbeunterbrechung zu einem bestimmten Zeitpunkt starten möchtest, rufe die Methode liveBroadcasts.cuepoint auf und gib mit der Eigenschaft walltimeMs die gewünschte Zeit an. Der Attributwert ist eine Ganzzahl, die einen Epochenzeitstempel darstellt.

  • Wenn Ihr Broadcast-Stream verzögert ist, können Sie den Cue-Punkt wie oben beschrieben sofort einfügen, eine Uhrzeit wie oben beschrieben angeben oder einen Zeitversatz angeben, um festzulegen, wann die Werbeunterbrechung beginnt. Der Zeitversatz gibt einen Punkt in deiner Übertragung an, zu dem die Zuschauer eine Anzeige sehen sollten.

    Der Offset-Wert wird in Millisekunden ab Beginn des Monitorstreams für die Übertragung gemessen. Wenn Ihre Übertragung eine Testphase hat, beginnt der Monitoringstream, sobald die Übertragung in den Status testing übergeht. Andernfalls startet der Monitorstream, wenn die Übertragung in den Status live übergeht.

    Legen Sie beim Einfügen eines Cue-Punkts das Attribut insertionOffsetTimeMs der cuepoint-Ressource auf den gewünschten Offset fest.

Den Zeitversatzwert berechnen

Um den Offset-Wert abzurufen, rufst du die getCurrentTime-Funktion der YouTube Player API für den Player auf, in dem der Monitorstream wiedergegeben wird. Verwenden Sie den abgerufenen Wert, um den Cue-Punkt zu diesem Zeitpunkt in den Übertragungsstream einzufügen.

Die möglichen Werte für die Zeitverschiebung können wie folgt berechnet werden:

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

Δ ist ein fünfsekündiger Puffer am Anfang und Ende der möglichen Zeitverschiebungen, wenn YouTube einen Cue-Punkt nicht genau einfügen kann. Beispiel:

  • Eine Übertragung umfasst eine fünfminütige Testphase.
  • Der Übertragungsstream ist 60 Sekunden nach dem Überwachungsstream verzögert.
  • Der Sender fügt den Cue-Punkt vier Minuten nach dem Wechsel in den Status live ein. (Drei Minuten nachdem der Broadcast-Stream sichtbar wird)

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

Diese Zeiten werden in Millisekunden angegeben und mithilfe der folgenden Werte berechnet:

  • elapsed_time=540000: Der Monitorstream wurde neun Minuten (540 Sekunden, 540.000 Millisekunden) ausgeführt, nachdem die Methode liveBroadcasts.cuepoint aufgerufen wurde.
  • broadcast_delay=60000: Der Übertragungsstream ist um 60 Sekunden oder 60.000 Millisekunden verzögert.
  • Δ=5000: Der Fünf-Sekunden-Puffer, wenn der Cue-Punkt nicht zuverlässig eingefügt werden kann.

Fehlerbehebung und Fehlerbehandlung

In den folgenden Richtlinien wird erläutert, wie Sie spezifische Probleme lösen können. In der Fehlerdokumentation finden Sie eine Liste der Fehler, die von den einzelnen API-Methoden zurückgegeben werden können.

  • Wenn eine Übertragung von einem Status in einen anderen wechselt, kann ihr vorübergehend ein anderer Status zugewiesen werden, während YouTube die mit der Umstellung verknüpften Aktionen ausführt. Wenn du beispielsweise eine liveBroadcasts.transition-Anfrage sendest, um den Status einer Übertragung von ready zu 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. Die Umstellung ist damit abgeschlossen.

    Wenn eine Übertragung im Status testStarting oder liveStarting hängen bleibt, müssen Sie die Methode liveBroadcasts.delete aufrufen und die Übertragung löschen. Erstelle dann eine neue Übertragung, verbinde sie in deinem Livestream und fahre mit dem Test fort.

    Wie in der Dokumentation der Methode liveBroadcasts.transition erwähnt, sollten Sie prüfen, ob der Wert des Attributs status.streamStatus für den an Ihre Übertragung gebundenen Stream active lautet, bevor Sie diese Methode aufrufen.