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
-
Sie benötigen ein Google-Konto, um auf Google API Console zugreifen, einen API-Schlüssel anfordern und Ihre Anwendung registrieren zu können.
-
Registriere deine Anwendung bei Google, um API-Anfragen über die Anwendung einreichen zu können.
-
Wählen Sie nach der Registrierung Ihrer Anwendung den YouTube Data API als einen der Dienste aus, die Ihre Anwendung verwendet:
- Gehen Sie zu API Console und wählen Sie das Projekt aus, das Sie gerade registriert haben.
- 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.
-
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
oderunlisted
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:
-
Sie hat eine vordefinierte Dauer, die Sie mit dem Attribut
durationSecs
der Ressourcecuepoint
festlegen. Nach Ende der Werbeunterbrechung kehren die Zuschauer zur Liveübertragung zurück. -
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 AttributsinsertionOffsetTimeMs
auf0
fest oder geben Sie keinen Wert für dieses Attribut an und geben Sie keinen Wert für das AttributwalltimeMs
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 EigenschaftwalltimeMs
die gewünschte Zeit an. Der Attributwert ist eine Ganzzahl, die einen Epochenzeitstempel darstellt.
-
Wenn du die Werbeunterbrechung sofort starten möchtest, ruf die Methode
-
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 Statuslive
übergeht.Legen Sie beim Einfügen eines Cue-Punkts das Attribut
insertionOffsetTimeMs
dercuepoint
-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 MethodeliveBroadcasts.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 vonready
zutesting
zu ändern, setzt YouTube den Status der Übertragung auftestStarting
und führt dann die mit der Statusänderung verbundenen Aktionen aus. Wenn alle diese Aktionen abgeschlossen sind, aktualisiert YouTube den Status der Übertragung auftesting
. Die Umstellung ist damit abgeschlossen.Wenn eine Übertragung im Status
testStarting
oderliveStarting
hängen bleibt, müssen Sie die MethodeliveBroadcasts.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 Attributsstatus.streamStatus
für den an Ihre Übertragung gebundenen Streamactive
lautet, bevor Sie diese Methode aufrufen.