LiveBroadcasts

L'API ora supporta la possibilità di contrassegnare le tue trasmissioni dal vivo come "destinate ai bambini" e la risorsa liveBroadcast ora contiene una proprietà che identifica lo stato "destinato ai bambini" di quella trasmissione dal vivo. Il 10 gennaio 2020 sono stati aggiornati anche i Termini di servizio dei servizi API di YouTube e le Norme per gli sviluppatori. Per saperne di più, consulta le cronologie delle revisioni del servizio API YouTube Live Streaming e i Termini di servizio dei servizi API di YouTube.

Una risorsa liveBroadcast rappresenta un evento che verrà trasmesso in streaming su YouTube tramite video in diretta.

Metodi

L'API supporta i seguenti metodi per le risorse liveBroadcasts:

list
Restituisci un elenco di trasmissioni di YouTube che corrispondono ai parametri della richiesta API. Prova subito.
inserisci
Crea una trasmissione. Prova subito.
aggiornamento
Aggiorna una trasmissione. Ad esempio, puoi modificare le impostazioni di trasmissione definite nell'oggetto contentDetails della risorsa liveBroadcast. Prova subito.
elimina
Elimina una trasmissione. Prova subito.
associazione
Associa una trasmissione di YouTube a uno stream o rimuove l'associazione esistente tra una trasmissione e uno stream. Una trasmissione può essere associata a un solo stream video, mentre uno stream video può essere associato a più di una trasmissione. Prova subito.
transizione
Modifica lo stato di una trasmissione dal vivo su YouTube e avvia le procedure associate al nuovo stato. Ad esempio, quando passi allo stato testing di una trasmissione, YouTube inizia a trasmettere il video allo stream monitor della trasmissione. Prima di chiamare questo metodo, devi confermare che il valore della proprietà status.streamStatus per lo stream associato alla tua trasmissione sia active. Prova subito.
cuepoint
Inserisci un cue point in una trasmissione dal vivo. Il cue point potrebbe attivare un'interruzione pubblicitaria.

Rappresentazione delle risorse

La seguente struttura JSON mostra il formato di una risorsa liveBroadcasts:

{
  "kind": "youtube#liveBroadcast",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "thumbnails": {
      (key): {
        "url": string,
        "width": unsigned integer,
        "height": unsigned integer
      }
    },
    "scheduledStartTime": datetime,
    "scheduledEndTime": datetime,
    "actualStartTime": datetime,
    "actualEndTime": datetime,
    "isDefaultBroadcast": boolean,
    "liveChatId": string
  },
  "status": {
    "lifeCycleStatus": string,
    "privacyStatus": string,
    "recordingStatus": string,
    "madeForKids": string,
    "selfDeclaredMadeForKids": string,
  },
  "contentDetails": {
    "boundStreamId": string,
    "boundStreamLastUpdateTimeMs": datetime,
    "monitorStream": {
      "enableMonitorStream": boolean,
      "broadcastStreamDelayMs": unsigned integer,
      "embedHtml": string
    },
    "enableEmbed": boolean,
    "enableDvr": boolean,
    "recordFromStart": boolean,
    "enableClosedCaptions": boolean,
    "closedCaptionsType": string,
    "projection": string,
    "enableLowLatency": boolean,
    "latencyPreference": boolean,
    "enableAutoStart": boolean,
    "enableAutoStop": boolean
  },
  "statistics": {
    "totalChatCount": unsigned long
  },
  "monetizationDetails": {
    "cuepointSchedule": {
      "enabled": boolean,
      "pauseAdsUntil": datetime,
      "scheduleStrategy": string,
      "repeatIntervalSecs": unsigned integer,
    }
  }
}

Proprietà

La tabella seguente definisce le proprietà visualizzate in questa risorsa:

Proprietà
kind string
Identifica il tipo di risorsa API. Il valore sarà youtube#liveBroadcast.
etag etag
L'ETag di questa risorsa.
id string
L'ID assegnato da YouTube per identificare in modo univoco la trasmissione.
snippet object
L'oggetto snippet contiene i dettagli di base dell'evento, tra cui il titolo, la descrizione, l'ora di inizio e l'ora di fine.
snippet.publishedAt datetime
La data e l'ora in cui la trasmissione è stata aggiunta alla programmazione delle trasmissioni dal vivo di YouTube. Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.channelId string
L'ID utilizzato da YouTube per identificare in modo univoco il canale che pubblica la trasmissione.
snippet.title string
Il titolo della trasmissione. Tieni presente che la trasmissione rappresenta esattamente un video di YouTube. Puoi impostare questo campo modificando la risorsa di trasmissione o impostando il campo title della risorsa video corrispondente.
snippet.description string
La descrizione della trasmissione. Come per title, puoi impostare questo campo modificando la risorsa di trasmissione o impostando il campo description della risorsa video corrispondente.
snippet.thumbnails object
Una mappa di immagini in miniatura associate alla trasmissione. Per ogni oggetto nidificato in questo oggetto, la chiave è il nome dell'immagine in miniatura, mentre il valore è un oggetto che contiene altre informazioni sulla miniatura.
snippet.thumbnails.(key) object
Le coppie chiave-valore valide sono:
  • default: l'immagine in miniatura predefinita. La miniatura predefinita di un video, o una risorsa che si riferisce a un video, come un elemento di una playlist o un risultato di ricerca, è larga 120 px e alta 90 px. La miniatura predefinita per un canale è di 88 px di larghezza e 88 px di altezza.
  • medium: una versione a risoluzione più elevata dell'immagine in miniatura. Per un video (o una risorsa che fa riferimento a un video), questa immagine è larga 320 px e alta 180 px. Per un canale, questa immagine è larga 240 px e alta 240 px.
  • high: una versione ad alta risoluzione dell'immagine in miniatura. Per un video (o una risorsa che fa riferimento a un video), questa immagine è larga 480 px e alta 360 px. Per un canale, questa immagine è larga 800 px e alta 800 px.
snippet.thumbnails.(key).url string
L'URL dell'immagine.
snippet.thumbnails.(key).width unsigned integer
La larghezza dell'immagine.
snippet.thumbnails.(key).height unsigned integer
L'altezza dell'immagine.
snippet.scheduledStartTime datetime
La data e l'ora in cui è programmata l'inizio della trasmissione. Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Creator Studio supporta la possibilità di creare una trasmissione senza programmare un'ora di inizio. In questo caso, la trasmissione inizia ogni volta che il proprietario del canale avvia lo streaming. Per queste trasmissioni, il valore datetime corrisponde al tempo UNIX pari a zero e non può essere modificato tramite l'API o in Creator Studio.
snippet.scheduledEndTime datetime
La data e l'ora in cui è programmata la fine della trasmissione. Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ). Se una risorsa liveBroadcast non specifica un valore per questa proprietà, la trasmissione è programmata per continuare a tempo indeterminato. Allo stesso modo, se non specifichi un valore per questa proprietà, YouTube tratterà la trasmissione come se andrà avanti a tempo indeterminato.
snippet.actualStartTime datetime
La data e l'ora in cui è iniziata la trasmissione. Questa informazione è disponibile solo quando lo stato della trasmissione è live. Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.actualEndTime datetime
La data e l'ora in cui la trasmissione è effettivamente terminata. Questa informazione è disponibile solo quando lo stato della trasmissione è complete. Il valore è specificato nel formato ISO 8601 (YYYY-MM-DDThh:mm:ss.sZ).
snippet.isDefaultBroadcast boolean
Questa proprietà verrà ritirata a partire dal 1° settembre 2020. Da quel momento, YouTube interromperà la creazione di uno stream e di una trasmissione predefiniti quando un canale è abilitato per il live streaming. Per ulteriori dettagli, consulta l'annuncio relativo al ritiro.
Questa proprietà indica se la trasmissione è la trasmissione predefinita.

Come funzionano le trasmissioni predefinite

Quando un canale YouTube è abilitato per il live streaming, YouTube crea uno stream e una trasmissione predefiniti per quel canale. Lo stream definisce il modo in cui il proprietario del canale invia il video in diretta a YouTube e la trasmissione è il modo in cui gli spettatori possono visualizzare lo stream predefinito. Il proprietario di un canale può utilizzare i metodi liveStreams.list e liveBroadcasts.list per identificare queste risorse.

Quando un canale avvia lo streaming del video per impostazione predefinita, il video è visibile sulla trasmissione predefinita del canale. Al termine dello stream, YouTube converte la trasmissione completata in un video di YouTube e assegna al video un ID video di YouTube.

Una volta completata la conversione, il video viene incluso nell'elenco dei video caricati del canale. Il video non è disponibile subito dopo la fine della trasmissione e la durata del ritardo è correlata all'effettiva durata della trasmissione.
snippet.liveChatId string
L'ID della chat dal vivo di YouTube della trasmissione. Con questo ID, puoi utilizzare i metodi della risorsa liveChatMessage per recuperare, inserire o eliminare i messaggi di chat. Puoi anche aggiungere o rimuovere moderatori della chat, impedire agli utenti di partecipare alle chat dal vivo o rimuovere le esclusioni esistenti.
status object
L'oggetto status contiene informazioni sullo stato dell'evento.
status.lifeCycleStatus string
Lo stato della trasmissione. Lo stato può essere aggiornato utilizzando il metodo liveBroadcasts.transition dell'API.

I valori validi per questa proprietà sono:
  • complete - La trasmissione è terminata.
  • created - La trasmissione ha impostazioni incomplete, quindi non è pronta per la transizione allo stato live o testing, ma è stata creata ed è altrimenti valida.
  • live - La trasmissione è attiva.
  • liveStarting - La trasmissione è in fase di transizione allo stato live.
  • ready - Le impostazioni di trasmissione sono complete e la trasmissione può passare allo stato live o testing.
  • revoked - Questa trasmissione è stata rimossa da un'azione dell'amministratore.
  • testStarting - La trasmissione è in fase di transizione allo stato testing.
  • testing - La trasmissione è visibile solo al partner.
status.privacyStatus string
Lo stato della privacy della trasmissione. Tieni presente che la trasmissione rappresenta esattamente un video di YouTube, pertanto le impostazioni della privacy sono identiche a quelle supportate per i video. Inoltre, puoi impostare questo campo modificando la risorsa di trasmissione o impostando il campo privacyStatus della risorsa video corrispondente.

I valori validi per questa proprietà sono:
  • private
  • public
  • unlisted
status.recordingStatus string
Lo stato della registrazione della trasmissione.

I valori validi per questa proprietà sono:
  • notRecording
  • recorded
  • recording
status.madeForKids boolean
Questo valore indica se la trasmissione è designata come rivolta ai minori. Il valore di questa proprietà è di sola lettura.
status.selfDeclaredMadeForKids boolean
In una richiesta liveBroadcasts.insert, questa proprietà consente al proprietario del canale di designare la trasmissione come rivolta ai minori. In una richiesta liveBroadcasts.list, il valore della proprietà viene restituito solo se il proprietario del canale ha autorizzato la richiesta API.
contentDetails object
L'oggetto contentDetails contiene informazioni sui contenuti video dell'evento, ad esempio se i contenuti possono essere mostrati in un video player incorporato o se saranno archiviati e quindi disponibili per la visualizzazione al termine dell'evento.
contentDetails.boundStreamId string
Questo valore identifica in modo univoco il live stream associato alla trasmissione.
contentDetails.boundStreamLastUpdateTimeMs datetime
La data e l'ora dell'ultimo aggiornamento del live streaming a cui fa riferimento boundStreamId.
contentDetails.monitorStream object
L'oggetto monitorStream contiene informazioni sullo stream monitor, che l'emittente può utilizzare per esaminare i contenuti dell'evento prima che lo streaming della trasmissione venga mostrato pubblicamente.
contentDetails.monitorStream.enableMonitorStream boolean
Questo valore determina se lo stream monitor è abilitato per la trasmissione. Se lo stream monitor è abilitato, YouTube trasmetterà i contenuti dell'evento su uno stream speciale destinato esclusivamente alla fruizione da parte dell'emittente. L'autore della trasmissione può utilizzare lo stream per esaminare i contenuti dell'evento e anche per identificare il momento ottimale in cui inserire i cue point.

Devi impostare questo valore su true se intendi avere uno stage testing per la trasmissione o se vuoi avere un ritardo di trasmissione dell'evento. Inoltre, se il valore di questa proprietà è true, devi eseguire la transizione della trasmissione allo stato testing prima di poterla passare allo stato live. Se il valore della proprietà è false, la trasmissione non può avere uno stage testing, quindi puoi passare direttamente allo stato live.

Quando update a broadcast, è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part. Tuttavia, quando esegui insert a broadcast, la proprietà è facoltativa e ha un valore predefinito di true.

Importante:questa proprietà non può essere aggiornata una volta che la trasmissione è nello stato testing o live.
contentDetails.monitorStream.broadcastStreamDelayMs unsigned integer
Se hai impostato la proprietà enableMonitorStream su true, questa proprietà determina la durata del ritardo della trasmissione dal vivo.

Quando update a broadcast, è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part. Tuttavia, quando esegui insert a broadcast, la proprietà è facoltativa e ha un valore predefinito di 0. Questo valore indica che la trasmissione non ha un ritardo di trasmissione. Nota:questa proprietà non può essere aggiornata una volta che la trasmissione è in stato testing o live.
contentDetails.monitorStream.embedHtml string
Codice HTML che incorpora un player che riproduce lo stream monitor.
contentDetails.enableEmbed boolean
Questa impostazione indica se la trasmissione video può essere riprodotta in un player incorporato. Se scegli di archiviare il video (utilizzando la proprietà enableArchive), questa impostazione verrà applicata anche al video archiviato.

Quando update a broadcast, è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part. Tuttavia, quando esegui insert a broadcast, la proprietà è facoltativa e ha un valore predefinito di true.

Nota: questa proprietà non può essere aggiornata una volta che la trasmissione è in stato testing o live.
contentDetails.enableDvr boolean
Questa impostazione determina se gli spettatori possono accedere ai controlli DVR mentre guardano il video. I controlli DVR consentono allo spettatore di controllare l'esperienza di riproduzione del video mettendo in pausa, riavvolgendo o mandando avanti i contenuti. Il valore predefinito di questa proprietà è true.

Quando update a broadcast, è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part. Tuttavia, quando esegui insert a broadcast, la proprietà è facoltativa e ha un valore predefinito di true.

Importante: devi impostare il valore su true e anche il valore della proprietà enableArchive su true se vuoi rendere disponibile la riproduzione immediatamente dopo la fine della trasmissione. Inoltre, questa proprietà non può essere aggiornata una volta che la trasmissione è nello stato testing o live.
contentDetails.recordFromStart boolean
Questa impostazione indica se YouTube inizia automaticamente a registrare la trasmissione dopo che lo stato dell'evento diventa Dal vivo.

Il valore predefinito di questa proprietà è true e può essere impostato su false solo se il canale di trasmissione può disattivare le registrazioni per le trasmissioni dal vivo.

Se il tuo canale non dispone dell'autorizzazione per disattivare le registrazioni e provi a inserire una trasmissione con la proprietà recordFromStart impostata su false, l'API restituirà un errore Forbidden. Inoltre, se il tuo canale non dispone di questa autorizzazione e tenti di aggiornare una trasmissione per impostare la proprietà recordFromStart su false, l'API restituirà un errore modificationNotAllowed.

Quando update a broadcast, è necessario impostare questa proprietà se la richiesta API include la parte contentDetails nel valore del parametro part. Tuttavia, quando esegui insert a broadcast, la proprietà è facoltativa e ha un valore predefinito di true.

Importante:devi anche impostare il valore della proprietà enableDvr su true se vuoi che la riproduzione sia disponibile immediatamente dopo la fine della trasmissione. Se imposti il valore di questa proprietà su true, ma non imposti anche la proprietà enableDvr su true, potrebbe verificarsi un ritardo di circa un giorno prima che il video archiviato sia disponibile per la riproduzione.

Nota: questa proprietà non può essere aggiornata una volta che la trasmissione è in stato testing o live.
contentDetails.enableClosedCaptions boolean
Questa proprietà è stata ritirata il 17 dicembre 2015. Utilizza la proprietà contentDetails.closedCaptionsType.

Questa impostazione indica se i sottotitoli HTTP POST sono attivi per questa trasmissione. Per i client API che utilizzano già questa proprietà:
  • Impostare il valore della proprietà su true equivale a impostare la proprietà contentDetails.closedCaptionsType su closedCaptionsHttpPost.
  • Impostare il valore della proprietà su false equivale a impostare la proprietà contentDetails.closedCaptionsType su closedCaptionsDisabled.
contentDetails.closedCaptionsType string
Nota: questa proprietà sostituisce la proprietà contentDetails.enableClosedCaptions.

Questa proprietà indica se i sottotitoli sono abilitati per la tua trasmissione e, in questo caso, che tipo di sottotitoli stai fornendo:
  • closedCaptionsDisabled: i sottotitoli codificati sono disattivati per la trasmissione dal vivo.
  • closedCaptionsHttpPost: I sottotitoli verranno inviati, tramite HTTP POST, a un URL di importazione associato al tuo live streaming.
  • closedCaptionsEmbedded: i sottotitoli verranno codificati nel video stream utilizzando i formati EIA-608 e/o CEA-708.
contentDetails.projection string
Il formato di proiezione della trasmissione. Il valore predefinito della proprietà è rectangular.

I valori validi per questa proprietà sono:
  • 360
  • rectangular
contentDetails.enableLowLatency boolean
Indica se la trasmissione deve essere codificata per lo streaming a bassa latenza. Uno stream a bassa latenza può ridurre il tempo necessario affinché il video sia visibile agli utenti che guardano una trasmissione, ma può anche incidere sulla risoluzione degli spettatori dello stream.
contentDetails.latencyPreference string
Indica quale impostazione di latenza utilizzare per questa trasmissione. È possibile utilizzare questa proprietà al posto di enableLowLatency, che non supporta ultraLow.

Uno stream a bassa latenza può ridurre il tempo necessario per rendere visibile il video agli utenti che guardano una trasmissione, ma può influire anche sulla fluidità della riproduzione.

Uno stream a latenza molto bassa riduce ulteriormente il tempo necessario per rendere visibile il video agli spettatori, semplificando l'interazione con gli spettatori, mentre i valori di latenza molto bassa non supportano i sottotitoli codificati superiori a 0:
8
  • normal
  • low
  • ultraLow
contentDetails.enableAutoStart boolean
Indica se la trasmissione deve iniziare automaticamente quando avvii lo streaming video nell'live stream.
contentDetails.enableAutoStop boolean
Indica se la trasmissione deve interrompersi automaticamente circa un minuto dopo che il proprietario del canale ha interrotto lo streaming del video sullo stream video associato.
statistics object
L'oggetto statistics contiene statistiche relative a una trasmissione dal vivo. I valori di queste statistiche possono cambiare durante la trasmissione e possono essere recuperati solo mentre la trasmissione è in diretta.
statistics.totalChatCount unsigned long
Il numero totale di messaggi della chat dal vivo associati alla trasmissione. La proprietà e il relativo valore sono presenti se la trasmissione è visibile all'utente, ha attivato la funzionalità di chat dal vivo e ha almeno un messaggio. Tieni presente che questa proprietà non specifica un valore al termine della trasmissione. Pertanto, questa proprietà non identificherebbe il numero di messaggi di chat relativi a un video archiviato di una trasmissione dal vivo completata.
monetizationDetails object
L'oggetto monetizationDetails contiene informazioni sui dettagli di monetizzazione dello stream, ad esempio se l'automazione degli annunci è attivo o se l'inserimento degli annunci mid-roll è ritardato.

monetizationDetails.cuepointSchedule object
L'oggetto cuepointSchedule specifica le impostazioni di automazione degli annunci per la trasmissione.
monetizationDetails.cuepointSchedule.enabled boolean
Questo valore determina se gli annunci vengono inseriti automaticamente nella trasmissione. Se il valore è true, YouTube inserirà automaticamente gli annunci mid-roll nella trasmissione. La pianificazione della pubblicazione degli annunci sarà determinata dal valore degli altri campi nell'oggetto monetizationDetails.cuepointSchedule.
monetizationDetails.cuepointSchedule.pauseAdsUntil datetime
Questo valore specifica che YouTube non deve inserire annunci mid-roll nella trasmissione prima della data e dell'ora specificate. Il valore è specificato nel formato ISO 8601 (AAAA-MM-GGThh:mm:ss.sZ). Per mettere in pausa gli annunci, il valore deve essere impostato su una data/ora futura; il valore del campo può anche essere impostato su una data/ora futura per riattivare gli annunci al passare del tempo.
monetizationDetails.cuepointSchedule.scheduleStrategy string
Questo valore specifica la strategia che YouTube deve seguire per pianificare i cue point. I valori validi sono:
  • CONCURRENT: i cue point sono programmati contemporaneamente per tutti gli spettatori
  • NON_CONCURRENT: i cue point sono programmati in orari diversi per spettatori differenti. Questo approccio consente di pubblicare gli annunci con una frequenza superiore, consentendo agli spettatori di ricevere cue point quando sono idonei.
monetizationDetails.cuepointSchedule.repeatIntervalSecs unsigned integer
Questo valore specifica l'intervallo, in secondi, tra l'inserimento automatico di annunci durante una trasmissione. Ad esempio, se il valore è 300, YouTube può inserire i cue point degli annunci mid-roll a intervalli di cinque minuti.

Tieni presente che il valore specifica il tempo che intercorre tra l'inizio dei cue point successivi. Ciò significa che l'intervallo non viene misurato dalla fine di un cue point all'inizio di quello successivo.