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.

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. Allerdings werden alle Ressourcen, aus denen die Live Streaming API besteht, nur zum Erstellen und Verwalten von Live-Veranstaltungen verwendet.

Dieses Dokument richtet sich an Entwickler, die Anwendungen zur Erleichterung der Liveübertragung auf YouTube erstellen möchten. Darin werden die grundlegenden Konzepte von YouTube und der API selbst erläutert. Außerdem erhalten Sie einen Überblick über die verschiedenen Funktionen, die von der API unterstützt werden.

Wichtige Konzepte

Nachrichten an alle

Eine Übertragung steht für ein Ereignis, das auf YouTube in Echtzeit 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 bezeichnet die Audio- und Videoinhalte, die an YouTube übertragen werden. Jede Übertragung ist einem Videostream zugeordnet.

Cue-Punkte

Ein Cue-Punkt steht für eine Werbeunterbrechung, die in eine Liveübertragung eingefügt werden kann.

API-Anwendungsfälle

In der folgenden Liste finden Sie mehrere Möglichkeiten, die API in Ihrer Anwendung zu verwenden:

• Übertragungen planen und Übertragungseinstellungen festlegen In Ihrer App können Nutzer die Einstellungen für die Übertragung vordefinieren und dann die Einstellungen auswählen, die auf eine bestimmte Übertragung angewendet werden sollen.

• Videostreams und Übertragungen verknüpfen.

• Ermöglichen Sie Sendern, Informationen zu einer Übertragung und dem zugehörigen Video gleichzeitig zu definieren (mithilfe der YouTube Data API).

• Vereinfachen Sie Übergänge zwischen Übertragungsstatus (z. B. testing oder live) und ermöglichen Sie Nutzern, Cue-Punkte einzufügen.

Vorbereitung

1. Sie benötigen ein Google-Konto, um auf die Google API Console zuzugreifen, einen API-Schlüssel anzufordern und Ihre Anwendung zu registrieren.

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

3. Nachdem Sie Ihre Anwendung registriert haben, wählen Sie YouTube Data API als einen der Dienste aus, den Ihre Anwendung verwendet:

   1. Rufen Sie die API Console auf und wählen Sie das Projekt aus, das Sie gerade registriert haben.
   2. Rufen Sie die Seite Aktivierte APIs auf. Prüfe in der Liste der APIs, ob Version 3 der YouTube Data API und, wenn du ein YouTube Content-Partner bist, die YouTube Content ID API EIN.

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 finden Sie unter json.org.

API-Anfragen autorisieren

Wie oben erwähnt, verwendet die Live Streaming API Funktionen, die technisch Teil der YouTube Data API oder der YouTube Content ID API sind. Mit der Content ID API kannst du YouTube Metadaten, Informationen zu Eigentumsrechten und Richtlinien für deine Inhalte zur Verfügung stellen. (Eine Live-Videoübertragung ist ein Beispiel für einen Inhalt.) Mit der API kannst du auch Anspruch auf Videos erheben und Anzeigenrichtlinien für deine Videos festlegen.

In diesem Abschnitt werden die Anforderungen an die Autorisierung 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, der übertragen wird.

Content ID API aufrufen

Die API-Anfrage muss von einem Google-Konto autorisiert werden, das mit dem Rechteinhaber verknüpft ist, dem der YouTube-Kanal gehört, über den die Übertragung läuft.

Ressourcen und Ressourcentypen

Eine Ressource ist ein individuelles Datenobjekt mit einer eindeutigen ID. In der folgenden Tabelle werden die verschiedene Arten von Ressourcen, mit denen Sie interagieren werden, Live Streaming API Technisch gesehen sind diese Ressourcen tatsächlich als Teil des YouTube Data API oder die YouTube Content ID API. Die liveBroadcast, liveStream und cuepoint Ressourcen sind werden nur zum Erstellen und Verwalten von Live-Veranstaltungen verwendet.

Ressourcen
liveBroadcast	Enthält Informationen zu einer Veranstaltung, die du auf YouTube veröffentlichst. A liveBroadcast ist eine Erweiterung einer YouTube-Videoressource und legt Videos fest. Metadaten, die für eine Liveübertragung relevant sind, aber nicht für andere YouTube-Videos. Daher entspricht eine liveBroadcast-Ressource genau einer YouTube-Videoressource. Die liveBroadcast Ressource und die Ressource video teilen sich den dieselbe ID. Nachdem du die Übertragung mit der Live Streaming API erstellt hast, kannst du die Funktion YouTube Data API, um zusätzliche Metadaten zum Video bereitzustellen
liveStream	Enthält Informationen zum Video-Stream, den du an YouTube überträgst. Der Stream liefert die Inhalte, die für die YouTube-Nutzer gesendet werden. Nach der Erstellung kann eine liveStream-Ressource an genau eine liveBroadcast-Ressource gebunden werden. Entsprechend kann die Ressource liveBroadcast nur an eine einzige liveStream-Ressource gebunden werden.
cuepoint	Fügt einen Cue-Punkt in den Videostream der Übertragung ein, der eine Werbeunterbrechung auslösen kann Verwenden Sie die Methode liveBroadcasts.cuepoint -Methode zum Einfügen eines Cue-Punkts während einer Übertragung.
video	Bezeichnet ein einzelnes YouTube-Video. Wie oben erwähnt, ist eine liveBroadcast-Ressource eine Erweiterung einer video-Ressource. Mit der YouTube Data API kannst du Metadaten zum Video aktualisieren, z. B. den Aufnahmeort oder die Regionen, in denen die Übertragung angesehen werden kann.
videoAdvertisingOptions	Definiert die Werbeeinstellungen für ein Video oder eine Übertragung. Verwenden Sie YouTube Content ID API, um Werbeoptionen festzulegen.
asset	Inhalte, die geistiges Eigentum enthalten, zum Beispiel einen Film oder eine Folge einer Serie. In diesem Fall ist das übertragene Video 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 über die YouTube Content ID API einen Anspruch, um dich als Inhaber des übertragenen Videos zu identifizieren.
policy	Definiert Regeln, die angeben, unter welchen Umständen Ihre Inhalte auf YouTube angesehen oder blockiert werden sollen. Du musst eine Richtlinie auf deine Videoübertragung anwenden und auch eine Richtlinie festlegen, die YouTube auf von Nutzern hochgeladene Videos anwendet, die mit deinem Videoübertragung übereinstimmen.

Unterstützte Vorgänge

Die folgende Tabelle zeigt die verschiedenen Methoden, die von der API unterstützt werden:

Vorgänge
list	Ruft eine Liste mit null oder mehr Ressourcen ab (GET).
insert	Erstellt (POST) eine neue Ressource.
update	Ändert (PUT) eine vorhandene Ressource, um Daten in Ihrer Anfrage widerzuspiegeln.
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 mit dem neuen Status verknüpften Prozesse. Wenn Sie beispielsweise den Status einer Übertragung auf testing ändern, beginnt YouTube mit der Übertragung von Video an den Monitorstream dieser Übertragung.
delete	Entfernt (DELETE) eine bestimmte Ressource.

In der folgenden Tabelle sind die Vorgänge aufgeführt, die für verschiedene Ressourcentypen unterstützt werden. Vorgänge zum Einfügen, Aktualisieren oder Löschen von Ressourcen 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 die 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 Parameter part ist ein erforderlicher Parameter für jede API-Anfrage, die eine YouTube Data API-Ressource abruft oder zurückgibt. Der Parameter gibt mindestens ein (nicht verschachteltes) übergeordnetes Ressourcenattribut an, das in einer API-Antwort enthalten sein sollte. Eine Ressource vom Typ liveStream besteht beispielsweise aus folgenden Teilen:

• snippet
• cdn
• status

All diese Teile sind Objekte, die verschachtelte Eigenschaften enthalten. Sie können sich diese Objekte als Gruppen von Metadatenfeldern vorstellen, die der API-Server abrufen könnte (oder nicht). Daher müssen Sie für den Parameter part die Ressourcenkomponenten auswählen, die Ihre Anwendung tatsächlich verwendet. Diese Anforderung erfüllt zwei wichtige Zwecke:

• Es verringert die Latenz, da der API-Server keine Zeit für das Abrufen von Metadatenfeldern benötigt, die nicht von Ihrer Anwendung verwendet werden.
• Sie reduziert die Bandbreitennutzung, indem die Menge unnötiger Daten, die Ihre Anwendung möglicherweise abrufen könnte, reduziert (oder beseitigt) wird.

Wenn im Laufe der Zeit Ressourcen hinzugefügt werden, werden diese Vorteile nur zunehmen, da Ihre Anwendung keine neu eingeführten Properties anfordert, die nicht unterstützt werden.

Tipps und Best Practices

Anspruch auf Inhalte erheben

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

Die Vorgehensweise zum Erheben von Ansprüchen auf ein Video in einer Liveübertragung unterscheidet sich von der üblichen Vorgehensweise zum Erheben von Ansprüchen auf ein Video. Wenn du Anspruch auf ein Live-Video erhebst, musst du erst Anspruch auf das Video erheben, bevor es tatsächlich existiert. Dies wird von der API unterstützt. Im Dokument Lebensdauer einer Übertragung werden die YouTube Content ID API-Aufrufe erläutert, mit denen du deinen Anspruch erheben kannst.

Inhalte als Vorschau ansehen und testen

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

• Mit dem Monitor-Stream können Sie eine Vorschau der Videoübertragung ansehen und testen. Es ist ein privater Stream, auf den nur du zugreifen kannst. Sie können eine Übertragung nur in die testing-Phase übergehen, wenn der Monitor-Stream der Übertragung aktiviert ist. Im Monitorstream werden keine Werbeunterbrechungen angezeigt.

• Der Übertragungsstream ist der Stream, der für Ihr Publikum sichtbar ist. Sie können den Datenschutzstatus der Übertragung entweder auf public, private oder unlisted setzen. (Private Übertragungen sind nur für Nutzer sichtbar, die explizit dazu eingeladen wurden. Nicht gelistete Übertragungen sind dagegen für alle sichtbar, die über einen Link verfügen.)

  Sie können den Übertragungsstream so verzögern, dass er nicht gleichzeitig mit dem Monitor-Stream ausgeführt wird. Durch Verzögern des Übertragungs-Streams können Sie genauer steuern, wann Sie Cue-Punkte in die Übertragung einfügen.

  Dadurch wird es deinen Live-Moderatoren jedoch erschwert, mit deinem Publikum zu interagieren. Eine verzögerte Übertragung erhöht außerdem die Wahrscheinlichkeit, dass Zuschauer wichtige Details zu dem Ereignis aus anderen Quellen als der Übertragung erfahren. Wenn du beispielsweise eine Sportveranstaltung mit einer Verzögerung von 60 Sekunden überträgst, können Zuschauer von anderen Echtzeitnachrichtenquellen über wichtige Momente des Ereignisses erfahren, bevor sie sie tatsächlich in der Übertragung sehen.

YouTube empfiehlt, den Monitorstream für Ihre Übertragung zu aktivieren, damit Sie Ihre Inhalte testen können. Du solltest auch entscheiden, ob du die Übertragung auch verschieben möchtest, wenn du das Timing der Cue-Punkte steuern möchtest, anstatt mit deinem Publikum zu interagieren oder eine Echtzeit-Berichterstattung über ein Ereignis anzubieten.

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

Während einer Übertragung können Sie einen Cue-Punkt einfügen, um anzugeben, dass eine Werbeunterbrechung in der Übertragung beginnen soll. so schnell wie möglich oder zu einem bestimmten Zeitpunkt die Übertragung starten. Mit der Werbeunterbrechung kann YouTube Mid-Roll-Anzeigen während der Übertragung.

Werbeunterbrechungen haben folgende Eigenschaften:

1. Sie hat eine vordefinierte Zeitdauer, die Sie mit der Methode cuepoint der Ressource festlegen. durationSecs Property. Nach der Werbeunterbrechung kehren die Zuschauer zur Liveübertragung zurück.

2. Bei einer Werbeunterbrechung wird eine Anzeige nur für Zuschauer, die sich das Video ansehen, im Videoplayer wiedergegeben. wenn der Cue-Punkt eingefügt wird. Eine Anzeige wird nicht geschaltet, wenn Betrachter die Seite aktualisieren wo die Übertragung läuft oder wenn Besucher die Übertragung nach dem Cuepoint wurde eingefügt.

Die folgende Reihenfolge entspricht den Best Practices zum Einfügen einer Werbeunterbrechung während der Übertragung:

Zeitverschiebungen festlegen

Beim Einfügen eines Cue-Punkts können Sie angeben, dass er sofort eingefügt werden soll an einer bestimmten Stelle in der Übertragung eingefügt werden. Ihre Optionen hängen davon ab, Der Übertragungs-Stream für dein Video ist verzögert.

• Wenn Ihr Übertragungsstream nicht verzögert wird, können Sie den Cue-Punkt sofort einfügen oder walltimeMs können Sie festlegen, dass die Werbeunterbrechung zu einem bestimmten Zeitpunkt beginnt.

  • Wenn die Werbeunterbrechung sofort starten soll, kannst du die Methode liveBroadcasts.cuepoint aufrufen. Im Ressource im Anfragetext muss der Parameter insertionOffsetTimeMs Property Wert auf 0 festlegen oder keinen Wert für dieses Attribut angeben und nicht einen Wert für walltimeMs Property.

    Wichtig:Nutzer sehen die eingeblendete Anzeige nicht. sofort Inhalte veröffentlichen. Es kann etwa 30 Sekunden dauern, bis der Anzeigeninhalt für Nutzer sichtbar. Während dieser Verzögerung ist der Stream weiterhin für Ihr und Sie müssen den Übertragungsstream ansehen, um zu ermitteln, statt Ihres Monitor-Streams.

  • Um die Werbeunterbrechung zu einem bestimmten Zeitpunkt zu starten, kannst du die liveBroadcasts.cuepoint aufrufen. und verwenden Sie die Methode walltimeMs um die gewünschte Zeit anzugeben. Der Eigenschaftswert ist eine Ganzzahl, die einen Epochenzeitstempel.

• Wenn Ihr Übertragungsstream verzögert ist, können Sie den Cue-Punkt sofort einfügen, wie oben beschrieben, geben Sie wie oben beschrieben eine Uhrzeit an. Alternativ können Sie auch einen Zeitversatz angeben, bestimmen, wann die Werbeunterbrechung beginnt. Der Zeitversatz gibt einen Punkt in deiner Übertragung an. wann Nutzer eine Anzeige sehen sollen.

  Der Offset-Wert wird in Millisekunden ab Beginn des Monitor-Streams für Ihre Übertragung. Wenn Ihre Übertragung eine Testphase hat, beginnt, wenn die Übertragung in den Status testing wechselt. Andernfalls werden Ihre Beobachten Sie den Stream, wenn die Übertragung in den Status live wechselt.

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

Zeitverschiebungswert berechnen

Rufe zum Abrufen des Offset-Werts die Funktion getCurrentTime der YouTube Player API für den Player auf, der den Monitorstream wiedergibt. Verwenden Sie den abgerufenen Wert, um den Cue-Punkt zu diesem Zeitpunkt in den Übertragungsstream einzufügen.

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

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

Δ ist ein 5-sekündiger Zwischenspeicher am Anfang und Ende möglicher Zeitverschiebungen, wenn YouTube keinen genauen Cue-Punkt einfügen kann. Beispiel:

• Eine Übertragung hat eine fünfminütige Testphase.
• Der Übertragungsstream wird 60 Sekunden nach dem Monitorstream verzögert.
• Der Broadcaster fügt den Cue-Punkt vier Minuten nach dem Übergang der Übertragung zu live-Status. Dies ist drei Minuten, nachdem der Übertragungs-Stream sichtbar wird.

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

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

• elapsed_time=540000: Der Monitorstream wurde neun Geräte lang gelaufen. Minuten (540 Sekunden, 540.000 Millisekunden), wenn die Methode liveBroadcasts.cuepoint aufgerufen wird.
• broadcast_delay=60000: Der Übertragungsstream wird um 60 Sekunden oder 60.000 Millisekunden verzögert.
• Δ=5000: Der fünf Sekunden lange Zwischenspeicher, 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 beheben können. Für Listen von Fehlern, die von den einzelnen API-Methoden zurückgegeben werden können, siehe YouTube Live Streaming API – Fehler.

• Wenn eine Übertragung von einem Status in einen anderen wechselt, wird ihr unter Umständen vorübergehend ein anderer Status zugewiesen, während YouTube die mit der Umstellung verbundenen Aktionen ausführt. Wenn Sie beispielsweise eine liveBroadcasts.transition-Anfrage senden, um den Status einer Übertragung von ready zu testing zu ändern, setzt YouTube den Status der Übertragung auf testStarting und führt anschließend die mit der Statusänderung verbundenen Aktionen aus. Wenn alle diese Aktionen ausgeführt wurden, aktualisiert YouTube den Status der Übertragung in testing. Damit wird angegeben, dass die Umstellung abgeschlossen ist.

  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 mit deinem Livestream und fahre mit dem Test fort.

  Wie in der Dokumentation der Methode liveBroadcasts.transition angegeben, solltest du vor dem Aufrufen dieser Methode überprüfen, ob der Wert der Eigenschaft status.streamStatus für den an deine Übertragung gebundenen Stream active lautet.