Panoramica dell'API YouTube Live Streaming

L'API YouTube Live Streaming ti consente di creare, aggiornare e gestire le live 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 è in realtà composta da componenti dell'API YouTube Data e dell'API YouTube Content ID. L'API Data consente agli utenti di YouTube di gestire i propri account YouTube, mentre il 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 live.

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

Concetti principali

Trasmissioni

Una trasmissione rappresenta un evento che può essere guardato su YouTube mentre si svolge. Le trasmissioni possono anche essere registrate e salvate come video di YouTube in modo che gli utenti possano guardarle dopo che si sono svolte.

Stream

Uno stream identifica i contenuti audio-video che vengono comunicati a YouTube. Ogni trasmissione è associata a uno stream video.

Cuepoint

Un cuepoint rappresenta un'interruzione pubblicitaria che può essere inserita in una trasmissione live.

Casi d'uso dell'API

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

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

• Associare stream video e trasmissioni.

• Consentire ai broadcaster di definire contemporaneamente le informazioni su una trasmissione e sul relativo video (utilizzando l'API YouTube Data).

• Semplificare le transizioni tra gli stati di trasmissione (ad esempio, testing o live) e consentire agli utenti di inserire cuepoint.

Prima di iniziare

1. Per accedere a Google Cloud console, richiedere una chiave API e registrare la tua applicazione, devi avere un Account Google.

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

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

   1. Vai al Cloud 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 l'API YouTube Data v3 e, se sei un partner di contenuti di YouTube, per l'API YouTube Content ID.

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

Autorizzazione delle richieste API

Come indicato sopra, l'API Live Streaming utilizza funzionalità che fanno tecnicamente 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 informazioni sulle norme per le tue risorse. Una trasmissione video in diretta è un esempio di risorsa. L'API ti consente anche 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 a Content ID API, che sono diversi dai requisiti per l'autorizzazione di altre richieste Live Streaming API.

Chiamare il Data API

La richiesta API deve essere autorizzata dall'Account Google proprietario del canale YouTube di trasmissione.

Chiamare il Content ID API

La richiesta API deve essere autorizzata da un Account Google collegato al proprietario dei contenuti proprietario del canale YouTube di trasmissione.

Risorse e tipi di risorse

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

Risorse
liveBroadcast	Contiene informazioni su un evento che stai trasmettendo su YouTube. Una risorsa liveBroadcast è un'estensione di una risorsa video di YouTube e imposta i metadati del video pertinenti 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, la risorsa liveBroadcast e la risorsa video condividono lo stesso ID. 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 sullo stream video 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 a esattamente una risorsa liveBroadcast. Allo stesso modo, la risorsa liveBroadcast può essere associata a una sola risorsa liveStream.
cuepoint	Inserisce un cuepoint nello stream video della trasmissione, che potrebbe attivare un'interruzione pubblicitaria. Utilizza il liveBroadcasts.cuepoint metodo per inserire un cuepoint durante una trasmissione.
video	Rappresenta un singolo video di YouTube. Come indicato sopra, una risorsa liveBroadcast è un'estensione di una risorsa video. Puoi utilizzare l'API YouTube Data per aggiornare i metadati del video, ad esempio la località di registrazione o le regioni in cui la trasmissione sarà visibile.
videoAdvertisingOptions	Definisce le impostazioni pubblicitarie per un video (o una trasmissione). Utilizza il YouTube Content ID API per impostare le opzioni pubblicitarie.
asset	Rappresenta una proprietà intellettuale, ad esempio un film o una puntata di un programma. In questo caso, il video della trasmissione è la risorsa. Utilizzerai il YouTube Content ID API per creare e gestire le risorse asset.
claim	Collega un video a una risorsa a cui corrisponde il video. Crea una rivendicazione utilizzando il YouTube Content ID API per identificarti come proprietario del video della trasmissione.
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 video della trasmissione e puoi anche specificare una norma che YouTube applicherà ai video caricati dagli utenti che corrispondono al video della trasmissione.

Operazioni supportate

La tabella seguente 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 in modo che rifletta i dati nella richiesta.
bind	Collega una risorsa liveBroadcast a una risorsa liveStream o rimuove un link di questo tipo.
transition	Modifica lo stato di una risorsa liveBroadcast e avvia tutti i processi associati al nuovo stato. Ad esempio, quando modifichi lo stato di una trasmissione in testing, YouTube inizia a trasmettere il video allo stream di monitoraggio della 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 le risorse richiedono sempre l'autorizzazione dell'utente. In alcuni casi, i metodi list supportano sia le richieste autorizzate sia quelle non autorizzate. Le richieste non autorizzate recuperano solo i dati pubblici, mentre le richieste autorizzate possono recuperare anche le informazioni limitate all'utente autenticato.

Operazioni supportate
	list	insert	update	bind	transition	cuepoint	delete
liveBroadcast
liveStream

Risorse parziali

L'API consente e richiede il recupero di risorse parziali in modo che le applicazioni evitino di trasferire, analizzare e archiviare 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 risorse di primo livello (non nidificate) da includere 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 e puoi considerarli come gruppi di campi di metadati che il server API potrebbe (o meno) recuperare. Pertanto, il parametro part richiede di selezionare i componenti delle risorse effettivamente utilizzati dall'applicazione. Questo requisito ha due scopi importanti:

• Riduce la latenza impedendo al server API di perdere tempo a recuperare i campi di metadati che l'applicazione non utilizza.
• Riduce 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 aggiungono altre parti, questi vantaggi aumenteranno, poiché l'applicazione non richiederà le proprietà appena introdotte che non supporta.

Suggerimenti e best practice

Rivendicare i contenuti

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

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

Visualizzare l'anteprima e testare i contenuti

Dopo aver ricevuto lo stream video in entrata, YouTube può trasmettere il video su due stream in uscita diversi:

• Lo stream di monitoraggio ti consente di visualizzare l'anteprima (e testare) la trasmissione video. È uno stream privato accessibile solo a te. Puoi modificare lo stato di una trasmissione in testing solo se lo stream di monitoraggio della trasmissione è abilitato. Lo stream di monitoraggio non mostra le 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 invitati esplicitamente a guardarla, mentre una trasmissione non in elenco è visibile a chiunque abbia un link per visualizzarla.

  Puoi scegliere di ritardare lo stream di trasmissione in modo che non venga eseguito contemporaneamente allo stream di monitoraggio. Ritardando lo stream di trasmissione, puoi avere un controllo più preciso sul momento in cui inserisci i cuepoint nella trasmissione.

  Tuttavia, ritardare lo stream di trasmissione rende difficile l'interazione dei presentatori live con il pubblico di spettatori. Inoltre, ritardare la trasmissione aumenta la probabilità che gli spettatori scoprano i dettagli chiave dell'evento da fonti diverse dalla trasmissione. Ad esempio, se trasmetti un evento sportivo con un ritardo di 60 secondi, gli spettatori potrebbero scoprire i momenti critici dell'evento da altre fonti di notizie in tempo reale prima di vederli nella trasmissione.

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

Pubblicare annunci mid-roll durante uno stream di trasmissione

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

Le interruzioni pubblicitarie hanno le seguenti caratteristiche:

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

2. Quando si verifica un'interruzione pubblicitaria, un annuncio viene riprodotto solo nel video player per gli spettatori che guardano la trasmissione quando viene inserito il cuepoint. Un annuncio non viene pubblicato quando gli spettatori aggiornano la pagina dove viene riprodotta la trasmissione o quando i visitatori iniziano a guardare la trasmissione dopo l' inserimento del cuepoint.

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

Impostare gli offset temporali

Quando inserisci un cuepoint, puoi specificare che deve essere inserito immediatamente o che deve essere inserito in un punto specifico della trasmissione. Le opzioni dipendono dal fatto che lo stream di trasmissione del video sia ritardato o meno.

• Se lo stream di trasmissione non è ritardato, puoi inserire immediatamente il cuepoint o utilizzare la walltimeMs proprietà per far iniziare l'interruzione pubblicitaria in un momento specifico.

  • 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 questa proprietà e non specificare un valore per la proprietà walltimeMs.

    Importante: tieni presente che gli spettatori non vedono immediatamente i contenuti dell'annuncio risultante. Potrebbe esserci un ritardo di circa 30 secondi prima che i contenuti dell'annuncio siano visibili agli utenti. Durante questo ritardo, lo stream di trasmissione sarà comunque visibile agli spettatori e dovrai guardare lo stream di trasmissione per determinare quando i contenuti dell'annuncio vengono effettivamente visualizzati anziché lo stream di monitoraggio.

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

• Se lo stream di trasmissione è ritardato, puoi inserire immediatamente il cuepoint come descritto sopra, specificare un'ora come descritto sopra oppure specificare un offset temporale per determinare quando inizierà l'interruzione pubblicitaria. L'offset temporale specifica un punto della trasmissione in cui gli spettatori dovrebbero vedere un annuncio.

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

  Quando inserisci un cuepoint, imposta la proprietà della risorsa cuepointinsertionOffsetTimeMs sull'offset desiderato.

Calcolare il valore dell'offset temporale

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

I valori possibili per l'offset temporale possono essere calcolati come l'intervallo seguente:

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

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

• Una trasmissione ha una fase di test di cinque minuti.
• Lo stream di trasmissione è ritardato di 60 secondi rispetto allo stream di monitoraggio.
• Il broadcaster inserisce il cuepoint quattro minuti dopo che la trasmissione passa allo stato live status. Ciò significa tre minuti dopo che lo stream di trasmissione diventa visibile.

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

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

• elapsed_time=540000 : lo stream di monitoraggio è in esecuzione da nove minuti (540 secondi, 540.000 millisecondi) quando viene chiamato il metodo liveBroadcasts.cuepoint.
• broadcast_delay=60000 : lo stream di trasmissione è ritardato di 60 secondi, ovvero 60.000 millisecondi.
• Δ=5000 : il buffer di cinque secondi quando il cuepoint non può essere inserito in modo affidabile.

Risoluzione dei problemi e gestione degli errori

Le seguenti linee guida spiegano come risolvere problemi specifici che potrebbero verificarsi. Per gli elenchi degli errori che ogni metodo API potrebbe restituire, consulta API YouTube Live Streaming - Errori.

• Quando una trasmissione passa da uno stato all'altro, potrebbe essere assegnato temporaneamente 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 poi completerà le azioni associate alla modifica dello stato. Una volta completate tutte queste azioni, YouTube aggiornerà lo stato della trasmissione a testing, indicando che la transizione è completa.

  Se una trasmissione rimane bloccata con lo stato testStarting o liveStarting, devi chiamare il metodo liveBroadcasts.delete ed eliminare la trasmissione. Poi 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 verificare che il valore della proprietà status.streamStatus per lo stream associato alla trasmissione sia active.