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 in realtà da 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 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 gli eventi dal vivo.

Questo documento è destinato agli sviluppatori che intendono scrivere applicazioni per facilitare la trasmissione in diretta su YouTube. Illustra i concetti basilari di YouTube e dell'API stessa. Offre inoltre una panoramica delle diverse funzioni supportate dall'API.

Concetti fondamentali

annunci
Una trasmissione rappresenta un evento che può essere guardato su YouTube man mano che si verifica. Le trasmissioni possono anche essere registrate e salvate come video di YouTube, in modo che gli utenti possano guardarle in seguito.
ruscelli
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 dal vivo.

Casi d'uso delle API

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

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

  • Associare video stream e trasmissioni.

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

  • Semplifica le transizioni tra stati di trasmissione (testing, live e così via) e consenti agli utenti di inserire cue point.

Prima di iniziare

  1. Per accedere a Google API Console, richiedere una chiave API e registrare l'applicazione è necessario un Account Google.

  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 API Console e seleziona il progetto che hai appena registrato.
    2. Visita la pagina relativa alle 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, la Content API di YouTube.

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

Autorizzazione delle richieste API

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

Questa sezione spiega i requisiti di autorizzazione per le richieste inviate a Content ID API, che sono diversi da quelli per l'autorizzazione di 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 proprietario del canale YouTube che trasmette.

Risorse e tipi di risorse

Una risorsa è una singola entità dati con un identificatore univoco. La tabella seguente descrive i diversi tipi di risorse con cui interagirai utilizzando Live Streaming API. Tecnicamente, tutte queste risorse vengono effettivamente definite come parte di YouTube Data API o di YouTube Content ID API. Tuttavia, le risorse liveBroadcast, liveStream e cuepoint vengono utilizzate solo per creare e gestire gli eventi dal vivo.

Risorse
liveBroadcast Contiene informazioni su un evento che stai trasmettendo su YouTube. Una risorsa liveBroadcast è un'estensione della risorsa video di YouTube e imposta i metadati video pertinenti a una trasmissione dal vivo, ma non ad altri video di YouTube.

Di conseguenza, una risorsa liveBroadcast corrisponde esattamente a una risorsa video di YouTube. Di fatto, la risorsa liveBroadcast e la risorsa video condividono lo stesso ID. Inoltre, dopo aver creato la trasmissione utilizzando l'API Live Streaming, puoi utilizzare l'API YouTube Data per fornire metadati aggiuntivi sul video.
liveStream Contiene informazioni sul video stream che stai trasmettendo a YouTube. Lo stream fornisce i contenuti che verranno trasmessi agli utenti di YouTube. Una volta creata, una risorsa liveStream può essere associata esattamente a una risorsa liveBroadcast. Analogamente, la risorsa liveBroadcast può essere associata a una sola risorsa liveStream.
cuepoint Inserisce un cue point nel video stream trasmesso, che potrebbe attivare un'interruzione pubblicitaria. Utilizza il metodo 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 l'API di dati di YouTube 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 di un video (o trasmissione). Utilizza YouTube Content ID API per impostare le opzioni pubblicitarie.
asset Rappresentano una proprietà intellettuale, ad esempio un film o una puntata di un programma. In questo caso, la risorsa video è l'asset. Utilizzerai il YouTube Content ID API per creare e gestire le risorse asset.
claim Collega un video a una risorsa corrispondente. Crei una rivendicazione utilizzando YouTube Content ID API per identificarti come proprietario del video trasmesso.
policy Definisce le regole che specificano le circostanze in cui vuoi che i tuoi contenuti siano visibili su YouTube o che non vengano visualizzati su YouTube. 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 tabella seguente mostra i diversi metodi supportati dall'API:

Suite operativa
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 richiesta.
bind Collega una risorsa liveBroadcast a una risorsa liveStream o rimuove questo collegamento.
transition Modifica lo stato di una risorsa liveBroadcast e avvia gli eventuali processi associati al nuovo stato. Ad esempio, quando esegui la transizione dello stato di una trasmissione a testing, YouTube inizia a trasmettere il video al flusso di monitoraggio della trasmissione.
delete Rimuove (DELETE) una risorsa specifica.

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

Operazioni supportate
list insert update bind transition cuepoint delete
livestreaming
live streaming

Risorse parziali

L'API consente, e in realtà richiede, il recupero di risorse parziali in modo che le applicazioni non trasferiscano, analizzino e archivino dati non necessari. Questo approccio garantisce inoltre che l'API utilizzi le risorse di rete, CPU e memoria in modo più efficiente.

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

  • snippet
  • cdn
  • status

Tutte queste parti sono oggetti che contengono proprietà nidificate e puoi considerarli come gruppi di campi di metadati che il server API potrebbe (o non dovrebbe) recuperare. Pertanto, il parametro part richiede la selezione dei componenti di risorse effettivamente utilizzati dalla tua applicazione. Questo requisito ha due scopi importanti:

  • Riduce la latenza impedendo al server API di perdere tempo per recuperare i campi di metadati che la tua applicazione non utilizza.
  • Riduce l'utilizzo della larghezza di banda riducendo (o eliminando) la quantità di dati non necessari che la tua applicazione potrebbe recuperare.

Nel tempo, man mano che le risorse aggiungono altre parti, questi vantaggi aumenteranno solo perché la tua applicazione non richiederà proprietà appena introdotte che non supportano.

Suggerimenti e best practice

Rivendica i tuoi contenuti

Se vuoi pubblicare annunci durante la trasmissione, devi rivendicare il video prima che inizi. Per rivendicare i contenuti, devi essere un partner di contenuti di YouTube che partecipa al programma Content ID.

La procedura di rivendicazione di un video in diretta è diversa dalla normale procedura di rivendicazione di un video. Quando rivendichi il video dal vivo, devi creare la rivendicazione prima che il video esista. L'API supporta questa operazione e il documento relativo alla durata di una trasmissione spiega le chiamate YouTube Content ID API che ti consentono di creare la tua rivendicazione.

Visualizza l'anteprima e testa i tuoi contenuti

Alla ricezione del video stream in entrata, YouTube può trasmettere il video su due diversi stream in uscita:

  • Lo stream monitor consente di visualizzare l'anteprima (e testare) della trasmissione video. Si tratta di uno stream privato accessibile solo a te. Puoi eseguire la transizione di una trasmissione alla fase testing solo se il relativo stream di monitoraggio è attivo. Il flusso di monitoraggio non mostra interruzioni pubblicitarie.

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

    Puoi scegliere di ritardare lo streaming trasmesso in modo che non venga eseguito contemporaneamente allo stream di monitoraggio. Ritardando lo streaming, puoi avere un controllo più granulare sul tempo in cui inserisci i cue point nella trasmissione.

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

YouTube ti consiglia di attivare lo stream monitor per la trasmissione in modo da poter testare i tuoi contenuti. Dovresti decidere se ritardare la trasmissione anche in base al tuo desiderio di controllare i tempi dei cue point, anziché in modo da interagire con il pubblico o fornire una copertura in tempo reale di un evento.

Esecuzione di annunci mid-roll durante un live streaming

Durante una trasmissione, puoi inserire un cue point per indicare che un'interruzione pubblicitaria deve iniziare la trasmissione il prima possibile o in una data specifica. L'interruzione pubblicitaria consente a YouTube di pubblicare gli annunci mid-roll durante la trasmissione.

Le interruzioni pubblicitarie hanno le seguenti caratteristiche:

  1. Ha una durata predefinita, che imposti utilizzando la proprietà durationSecs della risorsa cuepoint. Al termine dell'interruzione pubblicitaria, gli spettatori tornano alla trasmissione in diretta.

  2. Quando si verifica un'interruzione pubblicitaria, un 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 spettatori aggiornano la pagina in cui viene riprodotta o quando i visitatori iniziano a guardarlo dopo l'inserimento del cue point.

La sequenza di passaggi riportata di seguito rispecchia la best practice per l'inserimento di un'interruzione pubblicitaria durante la trasmissione:

Imposta le compensazioni del tempo

Quando inserisci un cue point, puoi specificare che debba essere inserito immediatamente o che debba essere inserito in un punto specifico della trasmissione. Le opzioni disponibili dipendono dal fatto che lo streaming di trasmissione del video sia ritardato.

  • Se il flusso di trasmissione non viene ritardato, puoi inserire immediatamente il cue point o utilizzare la proprietà walltimeMs per avviare 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 il valore della proprietà insertionOffsetTimeMs su 0 oppure non specificare un valore per la proprietà, né specificarne uno per la proprietà walltimeMs.

      Importante: tieni presente che gli spettatori non vedono immediatamente il contenuto dell'annuncio risultante. Potrebbe verificarsi un ritardo di circa 30 secondi prima che il contenuto dell'annuncio sia visibile agli utenti. Durante questo periodo, il live streaming sarà comunque visibile ai tuoi spettatori e dovrai decidere di guardare quando viene effettivamente mostrato il contenuto dell'annuncio invece del flusso di monitoraggio.

    • Per avviare l'interruzione pubblicitaria in un determinato momento, chiama il metodo liveBroadcasts.cuepoint e utilizza la proprietà walltimeMs per specificare l'ora desiderata. Il valore della proprietà è un numero intero che rappresenta un timestamp del periodo.

  • Se il tuo streaming di trasmissione è in ritardo, puoi inserire il cue point immediatamente come descritto sopra, specificare un orario come quello sopra descritto o indicare un offset temporale per determinare quando inizierà l'interruzione pubblicitaria. L'offset temporale specifica un punto nella trasmissione in cui i visualizzatori devono visualizzare un annuncio.

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

    Quando inserisci un cue point, imposta la proprietà insertionOffsetTimeMs della risorsa cuepoint con l'offset desiderato.

Calcolare il valore di offset temporale

Per recuperare il valore di offset, chiama la funzione getCurrentTime dell'API del player di YouTube per il player che riproduce lo stream di monitoraggio. Usa il valore recuperato per inserire in quel momento il cue point nello stream di trasmissione.

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

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

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

  • La trasmissione ha una fase di test di cinque minuti.
  • Lo stream trasmesso viene ritardato di 60 secondi dopo il monitoraggio.
  • L'emittente sta inserendo il cue point quattro minuti dopo la transizione dello stato a live. Si tratta di tre minuti dopo che il live streaming è diventato visibile.

In questo caso, l'intervallo di valori possibili è [(485,000), (535,000)].

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

  • elapsed_time=540000: il flusso del monitor viene eseguito per nove minuti (540 secondi, 540.000 millisecondi) quando viene richiamato il metodo liveBroadcasts.cuepoint.
  • broadcast_delay=60000: lo streaming dell'annuncio viene ritardato di 60 secondi o 60.000 millisecondi.
  • Δ=5000: il buffer di cinque secondi quando non è possibile inserire in modo affidabile il cue point.

Risoluzione dei problemi e gestione degli errori

Le seguenti linee guida spiegano come risolvere problemi specifici che potrebbero sorgere. Consulta anche la documentazione degli errori per un elenco degli errori che potrebbero essere restituiti da ogni metodo API.

  • Quando una trasmissione passa da uno stato a un altro, può essere temporaneamente assegnata 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, quindi completerà le azioni associate alla modifica dello stato. Una volta completate tutte queste azioni, YouTube aggiornerà lo stato della trasmissione su testing, indicando così il completamento della transizione.

    Se una trasmissione viene bloccata con lo stato testStarting o liveStarting, devi chiamare il metodo liveBroadcasts.delete ed eliminare la trasmissione. Quindi crea una nuova trasmissione, collegala al tuo live streaming e continua con la procedura di test.

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