LiveStreams

Una risorsa 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 una o più risorse liveBroadcast.

Metodi

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

list
Restituisce un elenco di stream video che corrispondono ai parametri di richiesta dell'API. Prova subito.
insert
Crea uno stream video. Lo stream ti consente di inviare il video a YouTube, che può poi trasmetterlo al tuo pubblico. Prova subito.
update
Aggiorna uno stream video. Se le proprietà che vuoi modificare non possono essere aggiornate, devi creare un nuovo stream con le impostazioni appropriate. Prova subito.
elimina
Elimina uno stream video. Prova subito.

Rappresentazione delle risorse

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

{
  "kind": "youtube#liveStream",
  "etag": etag,
  "id": string,
  "snippet": {
    "publishedAt": datetime,
    "channelId": string,
    "title": string,
    "description": string,
    "isDefaultStream": boolean
  },
  "cdn": {
    "ingestionType": string,
    "ingestionInfo": {
      "streamName": string,
      "ingestionAddress": string,
      "backupIngestionAddress": string
    },
    "resolution": string,
    "frameRate": string
  },
  "status": {
    "streamStatus": string,
    "healthStatus": {
      "status": string,
      "lastUpdateTimeSeconds": unsigned long,
      "configurationIssues": [
        {
          "type": string,
          "severity": string,
          "reason": string,
          "description": string
        }
      ]
    }
  },
  "contentDetails": {
    "closedCaptionsIngestionUrl": string,
    "isReusable": boolean
  }
}

Proprietà

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

Proprietà
kind string
Identifica il tipo di risorsa API. Il valore sarà youtube#liveStream.
etag etag
L'ETag di questa risorsa.
id string
L'ID assegnato da YouTube per identificare in modo univoco lo stream.
snippet object
L'oggetto snippet contiene i dettagli di base dello stream, tra cui canale, titolo e descrizione.
snippet.publishedAt datetime
La data e l'ora in cui è stato creato lo stream. 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 trasmette lo stream.
snippet.title string
Il titolo dello stream. Il valore deve essere compreso tra 1 e 128 caratteri.
snippet.description string
La descrizione dello stream. Il valore non può essere più lungo di 10000 caratteri.
snippet.isDefaultStream boolean
Questa proprietà verrà ritirata a partire dal 1° settembre 2020. A quel punto, YouTube interromperà la creazione di uno stream e di una trasmissione predefiniti quando un canale sarà abilitato al live streaming. Per scoprire di più, consulta l'annuncio sul ritiro.
Questa proprietà indica se lo stream è quello predefinito per il canale.

Come funzionano gli stream predefiniti

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

Lo stream predefinito di un canale esiste a tempo indeterminato, non ha un'ora di inizio o di fine associata e non può essere eliminato. Il proprietario del canale deve solo iniziare a inviare i bit video e lo stream continuerà automaticamente.

Al termine di uno stream, YouTube converte la trasmissione completata in un video di YouTube e assegna al video un ID video di YouTube. Al termine della conversione, il video viene incluso nell'elenco dei video caricati del canale. Il video non è disponibile immediatamente al termine della trasmissione e la durata del ritardo è correlata alla durata effettiva della trasmissione.
cdn object
L'oggetto cdn definisce le impostazioni della rete CDN (Content Delivery Network) del live streaming. Queste impostazioni forniscono dettagli sul modo in cui trasmetti i tuoi contenuti in streaming su YouTube.
cdn.format string
Questa proprietà è stata ritirata dal 18 aprile 2016 e non sarà più supportata dal 17 agosto 2020. Le richieste che utilizzano ancora questa proprietà come di quella data non andranno a buon fine.

Utilizza invece le proprietà cdn.frameRate e cdn.resolution per specificare la frequenza dei fotogrammi e la risoluzione separatamente.
cdn.ingestionType string
Il metodo o il protocollo utilizzato per trasmettere lo stream video.

I valori validi per questa proprietà sono:
  • dash
  • hls
  • rtmp (incluso RTMPS)
cdn.ingestionInfo object
L'oggetto ingestionInfo contiene le informazioni fornite da YouTube necessarie per trasmettere lo stream a YouTube.
cdn.ingestionInfo.streamName string
Il nome dello stream assegnato da YouTube allo stream video.
cdn.ingestionInfo.ingestionAddress string
L'URL di importazione principale da utilizzare per trasmettere in streaming i video su YouTube se utilizzi RTMP, DASH o HLS. Devi trasmettere in streaming il video a questo URL.

A seconda dell'applicazione o dello strumento che utilizzi per codificare lo stream video, potresti dover inserire l'URL e il nome dello stream separatamente oppure concatenarli nel seguente formato: 
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.backupIngestionAddress string
L'URL di importazione da backup da utilizzare per trasmettere in streaming i video su YouTube se utilizzi RTMP, DASH o HLS. Hai la possibilità di trasmettere in streaming contemporaneamente i contenuti che invii al ingestionAddress su questo URL.
cdn.ingestionInfo.rtmpsIngestionAddress string
L'URL di importazione principale da utilizzare per trasmettere in streaming i video su YouTube se utilizzi RTMPS. Devi riprodurre in streaming il video su questo URL.

A seconda dell'applicazione o dello strumento che utilizzi per codificare lo stream video, potresti dover inserire l'URL e il nome dello stream separatamente o potresti doverli concatenare nel seguente formato: 
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.rtmpsBackupIngestionAddress string
L'URL di importazione da backup da utilizzare per trasmettere in streaming i video su YouTube se utilizzi RTMPS.
cdn.resolution string
La risoluzione dei dati video in entrata.

I valori validi per questa proprietà sono:
  • 240p
  • 360p
  • 480p
  • 720p
  • 1080p
  • 1440p
  • 2160p
  • variable: utilizza questa impostazione per indicare che YouTube deve rilevare automaticamente la risoluzione del video in streaming. Devi anche impostare cdn.frameRate su variable.
    Per le impostazioni consigliate per il codificatore, consulta il Centro assistenza YouTube.
cdn.frameRate string
La frequenza dei fotogrammi dei dati video in entrata.

I valori validi per questa proprietà sono:
  • 30fps
  • 60fps
  • variable: utilizza questa impostazione per indicare a YouTube di rilevare automaticamente la frequenza dei fotogrammi del video in streaming. Devi anche impostare cdn.resolution su variable.
    Per le impostazioni consigliate per il codificatore, consulta il Centro assistenza YouTube.
status object
L'oggetto status contiene informazioni sullo stato del live streaming.
status.streamStatus string
Lo stato dello stream.

I valori validi per questa proprietà sono:
  • active: lo stream è in stato attivo, il che significa che l'utente sta ricevendo dati tramite lo stream.
  • created: lo stream è stato creato, ma non ha impostazioni CDN valide.
  • error: nello stream esiste una condizione di errore.
  • inactive: lo stream è in stato non attivo, il che significa che l'utente non riceve dati tramite lo stream.
  • ready: lo stream ha impostazioni CDN valide.
status.healthStatus object
Questo oggetto contiene informazioni sullo stato di salute del live streaming, che possono essere utilizzate per identificare, diagnosticare e risolvere i problemi di streaming.
status.healthStatus.status string
Il codice di stato di questo stream.

I valori validi per questa proprietà sono:
  • good: non sono presenti problemi di configurazione per i quali la gravità è warning o peggiore.
  • ok: non sono presenti problemi di configurazione per i quali la gravità è error.
  • bad: lo stream presenta alcuni problemi per i quali la gravità è error.
  • noData: i server di backend del live streaming di YouTube non hanno informazioni sullo stato dello stream.
status.healthStatus.lastUpdateTimeSeconds unsigned long
L'ultima volta che è stato aggiornato lo stato di integrità dello stream. Il valore riflette un timestamp UNIX in secondi.
status.healthStatus.configurationIssues[] list
Questo oggetto contiene un elenco di problemi di configurazione che interessano lo stream.
status.healthStatus.configurationIssues[].type string
Identifica il tipo di errore che interessa lo stream.
status.healthStatus.configurationIssues[].severity string
Indica la gravità del problema per lo stream.

I valori validi per questa proprietà sono:
  • info: il video viene trasmesso agli spettatori senza effetti negativi sul rendimento.
  • warning: il video viene trasmesso agli spettatori, ma il rendimento non è ottimale.
  • error: il video non può essere trasmesso agli spettatori.
status.healthStatus.configurationIssues[].reason string
Una breve descrizione del problema. Il documento Problemi di configurazione per le risorse di live streaming identifica il motivo associato a ogni tipo di problema di configurazione.
status.healthStatus.configurationIssues[].description string
Una descrizione dettagliata del problema. Se possibile, la descrizione fornisce informazioni su come risolvere il problema. Il documento Problemi di configurazione per le risorse LiveStream elenca tutti i tipi di problemi di configurazione e le relative descrizioni.
contentDetails object
L'oggetto content_details contiene informazioni sullo stream, incluso l'URL di importazione dei sottotitoli codificati.
contentDetails.closedCaptionsIngestionUrl string
L'URL di importazione a cui vengono inviati i sottotitoli codificati di questo stream.
contentDetails.isReusable boolean
Indica se lo stream è riutilizzabile, il che significa che può essere associato a più trasmissioni. È normale che le emittenti riutilizzino lo stesso stream per molte trasmissioni diverse se queste si verificano in momenti diversi.

Se imposti questo valore su false, lo stream non sarà riutilizzabile, il che significa che può essere associato a una sola trasmissione. Gli stream non riutilizzabili differiscono da quelli riutilizzabili nei seguenti modi:
  • Uno stream non riutilizzabile può essere associato a una sola trasmissione.
  • Uno stream non riutilizzabile potrebbe essere eliminato da un processo automatico al termine della trasmissione.
  • Il metodo liveStreams.list non elenca gli stream non riutilizzabili se lo chiami e imposti il parametro mine su true. L'unico modo per utilizzare questo metodo per recuperare la risorsa per uno stream non riutilizzabile è utilizzare il parametro id per identificare lo stream.