Panoramica dell'API YouTube Live Streaming

L'API YouTube Live Streaming ti consente di creare, aggiornare e gestire gli eventi dal vivo su YouTube. Utilizzando l'API, puoi pianificare eventi (trasmissioni) e associarli agli stream video, che rappresentano i contenuti effettivi delle trasmissioni.

L'API Live Streaming è composta dai componenti dell'API YouTube Data e dell'API YouTube Content ID. L'API di dati consente agli utenti di YouTube di gestire i propri account YouTube, mentre l'YouTube Content ID API consente le interazioni con il sistema di gestione dei diritti di YouTube. Tuttavia, tutte le risorse che compongono l'API Live Streaming vengono utilizzate solo per creare e gestire eventi dal vivo.

Questo documento è rivolto agli sviluppatori che desiderano scrivere applicazioni per facilitare la trasmissione live su YouTube. Illustra i concetti di base di YouTube e dell'API stessa. Fornisce inoltre una panoramica delle diverse funzioni supportate dall'API.

Concetti principali

annunci
Una trasmissione è un evento che può essere guardato su YouTube nel momento in cui si verifica. Le trasmissioni possono anche essere registrate e salvate come video di YouTube, in modo che gli utenti possano guardarle dopo che si sono verificate.
applicazioni.
Uno stream identifica i contenuti audio-video che vengono comunicati a YouTube. Ogni trasmissione è associata a un video stream.
cue point
Un cue point rappresenta un'interruzione pubblicitaria che può essere inserita in una trasmissione live.

Casi d'uso delle API

L'elenco seguente suggerisce diversi modi per utilizzare l'API nella tua applicazione:

  • Programmare le trasmissioni e definire le impostazioni di trasmissione. La tua applicazione potrebbe consentire agli utenti di predefinire le impostazioni di trasmissione e quindi di selezionare le impostazioni da applicare a una determinata trasmissione.

  • Associare video stream e trasmissioni.

  • Consente alle emittenti di definire contemporaneamente informazioni su una trasmissione e sul relativo video (utilizzando l'API di dati di YouTube).

  • Semplifica le transizioni tra gli stati di trasmissione (ad esempio testing o live) e consenti agli utenti di inserire cue point.

Prima di iniziare

  1. Devi avere un Account Google per accedere a Google API Console, richiedere una chiave API e registrare la tua applicazione.

  2. Registra la tua applicazione su Google in modo da poter inviare le richieste di API.

  3. Dopo aver registrato l'applicazione, seleziona YouTube Data API come uno dei servizi utilizzati dall'applicazione:

    1. Vai alla pagina API Console e seleziona il progetto che hai appena registrato.
    2. Visita la pagina API abilitate. Nell'elenco delle API, assicurati che lo stato sia ON per la YouTube Data API v3 e, se sei un partner per i contenuti di YouTube, per l'API YouTube Content ID.

  4. Acquisisci familiarità con i concetti principali del formato dati JSON (JavaScript Object Notation). JSON è un formato di dati comune, indipendente dal linguaggio, che fornisce una semplice rappresentazione testuale di strutture di dati arbitrarie. Per ulteriori informazioni, visita il sito json.org.

Autorizzazione delle richieste API

Come indicato in precedenza, l'API Live Streaming utilizza una funzionalità che tecnicamente fa parte dell'API YouTube Data o dell'API YouTube Content ID. Puoi utilizzare l'API Content ID per fornire a YouTube metadati, informazioni sulla proprietà e sulle norme relative alle tue risorse. Una trasmissione video in diretta è un esempio di risorsa. Inoltre, l'API ti consente di rivendicare i video e impostare norme relative agli annunci per i tuoi video.

Questa sezione illustra i requisiti di autorizzazione per le richieste inviate al Content ID API, che sono diversi da quelli per autorizzare altre richieste Live Streaming API.

Chiamata a Data API
La richiesta API deve essere autorizzata dall'Account Google proprietario del canale YouTube che trasmette.
Chiamata a Content ID API
La richiesta API deve essere autorizzata da un Account Google collegato al proprietario dei contenuti che possiede il canale YouTube per la trasmissione.

Risorse e tipi di risorse

Una risorsa è una singola entità di dati con un identificatore univoco. Nella tabella che segue vengono descritti i diversi tipi di risorse con cui interagisci usando Live Streaming API. Tecnicamente, tutte queste risorse sono effettivamente definito come parte del YouTube Data API o YouTube Content ID API. Tuttavia, liveBroadcast, liveStream e cuepoint risorse sono utilizzato solo per creare e gestire eventi dal vivo.

Risorse
liveBroadcast Contiene informazioni su un evento che stai trasmettendo su YouTube. R La risorsa liveBroadcast è un'estensione di una risorsa video di YouTube e imposta la metadati di video attinenti a una trasmissione live, ma non ad altri video di YouTube.

Di conseguenza, una risorsa liveBroadcast corrisponde esattamente a una risorsa video di YouTube. Infatti, liveBroadcast e la risorsa video condividono lo stesso ID. Dopo aver creato la trasmissione utilizzando l'API Live Streaming, puoi utilizzare API YouTube Data per fornire metadati aggiuntivi sul video.
liveStream Contiene informazioni sullo stream video che stai trasmettendo a YouTube. Stream fornisce i contenuti che saranno trasmessi agli utenti di YouTube. Una volta creata, una liveStream una risorsa può essere associata esattamente a una risorsa liveBroadcast. Analogamente, liveBroadcast risorsa può essere associata a una sola risorsa liveStream.
cuepoint Inserisce un cue point nello stream video della trasmissione, che potrebbe attivare un'interruzione pubblicitaria. Utilizza la liveBroadcasts.cuepoint per inserire un cue point durante una trasmissione.
video Rappresenta un singolo video di YouTube. Come indicato in precedenza, una risorsa liveBroadcast è un'estensione di una risorsa video. Puoi utilizzare la YouTube Data API per aggiornare i metadati sul video, ad esempio la località di registrazione o le regioni in cui sarà visibile la trasmissione.
videoAdvertisingOptions Definisce le impostazioni pubblicitarie per un video (o una trasmissione). Utilizzi il YouTube Content ID API per impostare le opzioni pubblicitarie.
asset Rappresenta una proprietà intellettuale, come un film o la puntata di un programma. In questo caso, la risorsa è il video trasmesso. Utilizzerai YouTube Content ID API per creare e gestire le risorse asset.
claim Collega un video a una risorsa corrispondente al video. Puoi creare una rivendicazione utilizzando YouTube Content ID API per identificarti come il proprietario del video trasmesso.
policy Definisce regole che specificano le circostanze in cui vuoi che i tuoi contenuti siano visibili su YouTube o ne venga bloccata la pubblicazione. Devi applicare una norma al tuo video trasmesso e puoi anche specificare una norma che YouTube applicherà ai video caricati dagli utenti che corrispondono al tuo video trasmesso.

Operazioni supportate

La seguente tabella mostra i diversi metodi supportati dall'API:

Operazioni
list Recupera (GET) un elenco di zero o più risorse.
insert Crea (POST) una nuova risorsa.
update Modifica (PUT) una risorsa esistente per riflettere i dati nella tua richiesta.
bind Collega una risorsa liveBroadcast a una risorsa liveStream o rimuove questo collegamento.
transition Modifica lo stato di una risorsa liveBroadcast e avvia eventuali processi associati al nuovo stato. Ad esempio, quando trasferisci lo stato di una trasmissione a testing, YouTube inizia a trasmettere il video allo stream monitor di quella trasmissione.
delete Rimuove (DELETE) una risorsa specifica.

La tabella seguente identifica le operazioni supportate per i diversi tipi di risorse. Le operazioni che inseriscono, aggiornano o eliminano risorse richiedono sempre l'autorizzazione dell'utente. In alcuni casi, i metodi list supportano le richieste sia autorizzate che non autorizzate, dove quelle non autorizzate recuperano solo i dati pubblici, mentre le richieste autorizzate possono anche recuperare le informazioni limitate all'utente attualmente autenticato.

Operazioni supportate
list insert update bind transition cuepoint delete
liveBroadcast
liveStream

Risorse parziali

L'API consente, e richiede effettivamente, il recupero di risorse parziali in modo che le applicazioni evitino il trasferimento, l'analisi e l'archiviazione di dati non necessari. Questo approccio garantisce anche che l'API utilizzi le risorse di rete, CPU e memoria in modo più efficiente.

Il parametro part è obbligatorio per qualsiasi richiesta API che recupera o restituisce una risorsa YouTube Data API. Il parametro identifica una o più proprietà di risorsa di primo livello (non nidificate) che devono essere incluse in una risposta dell'API. Ad esempio, una risorsa liveStream ha le seguenti parti:

  • snippet
  • cdn
  • status

Tutte queste parti sono oggetti che contengono proprietà nidificate, che si possono considerare come gruppi di campi di metadati che il server API potrebbe (o non potrebbe) recuperare. Di conseguenza, il parametro part richiede di selezionare i componenti delle risorse effettivamente utilizzati dalla tua applicazione. Questo requisito ha due scopi importanti:

  • Riduce la latenza impedendo al server API di dedicare del tempo al recupero dei campi di metadati non utilizzati dalla tua applicazione.
  • Consente di ridurre l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che l'applicazione potrebbe recuperare.

Nel tempo, man mano che le risorse aggiungeranno più parti, questi vantaggi aumenteranno solo in quanto la tua applicazione non richiederà proprietà introdotte di recente che non supporta.

Suggerimenti e best practice

Rivendica i tuoi contenuti

Se vuoi mostrare annunci durante la trasmissione, devi rivendicare la trasmissione video prima dell'inizio dell'evento. Per rivendicare i contenuti, devi essere un partner per i contenuti di YouTube che partecipa al programma Content ID.

La procedura per rivendicare un video trasmesso dal vivo è diversa dalla normale procedura per rivendicare un video. Quando rivendichi un video in diretta, devi creare la rivendicazione prima che il video esista effettivamente. L'API non supporta questa funzionalità e la durata di una trasmissione spiega le chiamate YouTube Content ID API che ti consentono di creare la tua rivendicazione.

Visualizzare l'anteprima e testare i contenuti

Una volta ricevuto il tuo stream video in entrata, YouTube può trasmettere quel video su due diversi stream in uscita:

  • Lo streaming del monitoraggio ti consente di visualizzare in anteprima (e testare) la trasmissione video. Si tratta di uno stream privato accessibile solo a te. Puoi eseguire la transizione di una trasmissione alla fase testing solo se lo stream di monitoraggio della trasmissione è abilitato. Lo stream di monitoraggio non mostra interruzioni pubblicitarie.

  • Lo stream di trasmissione è lo stream visibile al tuo pubblico. Puoi impostare lo stato di privacy della trasmissione su public, private o unlisted. Una trasmissione privata è visibile solo agli utenti che sono stati esplicitamente invitati a guardarla, mentre una trasmissione non in elenco è visibile a chiunque disponga di un link per visualizzarla.

    Puoi scegliere di ritardare lo stream della trasmissione in modo che non venga eseguito contemporaneamente allo stream di monitoraggio. Rinviando lo streaming della trasmissione, puoi avere un controllo più granulare sull'orario in cui inserisci i cue point nella trasmissione.

    Tuttavia, ritardare la trasmissione rende difficile per i presentatori dal vivo interagire con il pubblico. Inoltre, ritardare la trasmissione aumenta la probabilità che gli spettatori trovino dettagli chiave sull'evento da fonti diverse dalla tua trasmissione. Ad esempio, se stai trasmettendo un evento sportivo con un ritardo di 60 secondi, gli spettatori potrebbero venire a conoscenza dei momenti critici dell'evento da altre fonti di notizie in tempo reale prima di vederli effettivamente nella trasmissione.

YouTube consiglia di abilitare lo stream di monitoraggio per la trasmissione in modo da poter testare i contenuti. Dovresti scegliere se ritardare la trasmissione anche in base al tuo desiderio di controllare la sincronizzazione dei cue point invece di voler interagire con il pubblico o fornire la copertura in tempo reale di un evento.

Esecuzione di annunci mid-roll durante una trasmissione in streaming

Durante una trasmissione, puoi inserire un cue point per indicare che un'interruzione pubblicitaria deve iniziare nel formato il prima possibile o all'ora specificata. L'interruzione pubblicitaria consente a YouTube di pubblicare di annunci mid-roll durante la trasmissione.

Le interruzioni pubblicitarie hanno le seguenti caratteristiche:

  1. Ha un periodo di tempo predefinito, che puoi impostare utilizzando il metodocuepoint durationSecs proprietà. Al termine dell'interruzione pubblicitaria, gli spettatori tornano alla trasmissione live.

  2. Quando si verifica un'interruzione pubblicitaria, l'annuncio viene riprodotto nel video player solo per gli spettatori che guardano la trasmissione quando viene inserito il cue point. Un annuncio non viene pubblicato quando gli utenti aggiornano la pagina. dove è in riproduzione la trasmissione o quando i visitatori iniziano a guardarla dopo il cue point è stato inserito.

La sequenza di passaggi riportata di seguito riflette la best practice per inserire un'interruzione pubblicitaria durante la trasmissione:

Imposta offset temporali

Quando inserisci un cue point, puoi specificare che deve essere inserito immediatamente o che deve essere inserito in un punto specifico della trasmissione. Le opzioni disponibili dipendono dal fatto che per il tuo video non è in ritardo.

  • Se lo stream della trasmissione non subisce ritardi, puoi inserire il cue point immediatamente o utilizzare walltimeMs per far iniziare l'interruzione pubblicitaria in un determinato momento.

    • Per avviare immediatamente l'interruzione pubblicitaria, chiama il metodo liveBroadcasts.cuepoint. Nella risorsa nel corpo della richiesta, imposta della proprietà insertionOffsetTimeMs valore su 0 o non specificare un valore per quella proprietà e non specificare un valore per walltimeMs proprietà.

      Importante:tieni presente che gli spettatori non vedono l'annuncio risultante. contenuti. Potrebbe verificarsi un ritardo di circa 30 secondi prima che il contenuto dell'annuncio venga visibili agli utenti. Durante questo ritardo, lo stream trasmesso sarà ancora visibile al tuo spettatori e devi guardare lo stream per determinare quando il contenuto dell'annuncio anziché lo stream del monitor.

    • Per avviare l'interruzione pubblicitaria in un determinato momento, chiama liveBroadcasts.cuepoint e utilizza il metodo walltimeMs per specificare l'orario desiderato. Il valore della proprietà è un numero intero che rappresenta un timestamp dell'epoca.

  • Se lo stream della trasmissione subisce un ritardo, puoi inserire subito il cue point descritto sopra, specifica un'ora come descritto sopra, oppure specifica uno scarto con determinare quando inizierà l'interruzione pubblicitaria. L'offset temporale specifica un punto della trasmissione quando gli spettatori dovrebbero vedere un annuncio.

    Il valore di offset viene misurato in millisecondi dall'inizio del flusso di monitoraggio per la trasmissione. Tieni presente che se la tua trasmissione ha una fase di test, lo stream monitor inizia quando la trasmissione passa allo stato testing. In caso contrario, lo stream monitorato inizia quando la trasmissione passa allo stato live.

    Quando inserisci un cue point, imposta il valorecuepoint insertionOffsetTimeMs all'offset desiderato.

Calcolare il valore di offset temporale

Per recuperare il valore di offset, chiama la funzione getCurrentTime dell'API YouTube Player API per il player che sta riproducendo lo stream monitor. Utilizza il valore recuperato per inserire il cue point nello stream della trasmissione in quel momento.

I possibili valori per il tempo di offset possono essere calcolati come il seguente intervallo:

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

Δ è un buffer di cinque secondi all'inizio e alla fine dei possibili offset temporali quando YouTube non è in grado di inserire con precisione un cue point. Ad esempio:

  • Una trasmissione prevede una fase di test di cinque minuti.
  • Lo stream della trasmissione viene ritardato 60 secondi dopo lo stream monitor.
  • L'emittente sta inserendo il cue point quattro minuti dopo la transizione della trasmissione a live. Tre minuti dopo che la trasmissione in streaming diventa visibile.

In questo caso, l'intervallo possibile di tempi di offset è [(485,000), (535,000)].

Questi orari vengono specificati in millisecondi e vengono calcolati utilizzando i seguenti valori:

  • elapsed_time=540000: lo stream di monitoraggio è stato eseguito per nove volte minuti (540 secondi, 540.000 millisecondi) quando viene chiamato il metodo liveBroadcasts.cuepoint.
  • broadcast_delay=60000: lo stream della trasmissione ha un ritardo di 60 secondi o 60.000 millisecondi.
  • Δ=5000 - Il buffer di cinque secondi quando il cue point non può essere inserito in modo affidabile.

Risoluzione dei problemi e gestione degli errori

Le seguenti linee guida spiegano come risolvere eventuali problemi specifici. Per gli elenchi di errori che ogni metodo API potrebbe restituire, consulta la sezione API YouTube Live Streaming - Errori.

  • Quando una trasmissione passa da uno stato a un altro, potrebbe essere temporaneamente assegnato a un altro stato mentre YouTube completa le azioni associate alla transizione. Ad esempio, se invii una richiesta liveBroadcasts.transition per modificare lo stato di una trasmissione da ready a testing, YouTube imposterà lo stato della trasmissione su testStarting e quindi completerà le azioni associate alla modifica dello stato. Una volta completate tutte queste azioni, YouTube aggiornerà lo stato della trasmissione a testing, per indicare che la transizione è completata.

    Se una trasmissione si blocca con lo stato testStarting o liveStarting, devi chiamare il metodo liveBroadcasts.delete ed eliminare la trasmissione. quindi crea una nuova trasmissione, associala al tuo live streaming e continua con la procedura di test.

    Come indicato nella documentazione del metodo liveBroadcasts.transition, prima di chiamare questo metodo devi confermare che il valore della proprietà status.streamStatus per lo stream associato alla trasmissione sia active.