LiveStreams

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

Metodi

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

list
Restituisce un elenco di video stream che corrispondono ai parametri della richiesta API. Prova subito.
inserire
Crea un video stream. Lo stream ti permette di inviare il tuo video a YouTube per poterlo trasmettere al tuo pubblico. Prova subito.
Aggiorna
Aggiorna un video stream. Se le proprietà che vuoi modificare non possono essere aggiornate, devi creare un nuovo stream con le impostazioni corrette. Prova subito.
elimina
Elimina un video stream. 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à che vengono 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 dettagli di base sullo stream, tra cui il canale, il titolo e la descrizione.
snippet.publishedAt datetime
La data e l'ora di creazione dello 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 avere una lunghezza compresa tra 1 e 128 caratteri.
snippet.description string
La descrizione dello stream. Il valore non può contenere più di 10.000 caratteri.
snippet.isDefaultStream boolean
Questa proprietà verrà ritirata a partire dal 1° settembre 2020. In quel momento, YouTube interromperà la creazione di uno stream e di una trasmissione predefiniti quando un canale è abilitato per il live streaming. Per maggiori dettagli, leggi la comunicazione relativa al ritiro.
Questa proprietà indica se lo stream è predefinito per il canale.

Come funzionano gli stream predefiniti

Quando un canale YouTube è abilitato per il live streaming, YouTube crea uno stream e una trasmissione predefiniti per tale canale. Lo stream definisce il modo in cui il proprietario del canale invia i video dal vivo a YouTube, mentre la trasmissione è il modo in cui 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 del video e lo stream procede automaticamente.

Quando uno stream termina, YouTube converte la trasmissione completata in un video di YouTube, quindi 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 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 sulla modalità di streaming dei tuoi contenuti su YouTube.
cdn.format string
Questa proprietà è stata ritirata dal 18 aprile 2016 e non sarà più supportata a partire dal 17 agosto 2020. Le richieste che utilizzano ancora questa proprietà a partire da tale data non andranno a buon fine.

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

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

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

A seconda dell'applicazione o dello strumento che utilizzi per codificare il video stream, potresti dover inserire l'URL e il nome dello stream separatamente oppure potrebbe essere necessario concatenarli nel seguente formato: 
STREAM_URL/STREAM_NAME
cdn.ingestionInfo.rtmpsBackupIngestionAddress string
L'URL di importazione di backup da utilizzare per lo streaming 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 tuo video trasmesso in streaming. Devi anche impostare cdn.frameRate su variable.
    Consulta il Centro assistenza YouTube per informazioni sulle impostazioni consigliate per il codificatore.
cdn.frameRate string
La frequenza fotogrammi dei dati video in entrata.

I valori validi per questa proprietà sono:
  • 30fps
  • 60fps
  • variable: utilizza questa impostazione per indicare a YouTube che deve rilevare automaticamente la frequenza fotogrammi del video trasmesso in streaming. Devi anche impostare cdn.resolution su variable.
    Consulta il Centro assistenza YouTube per informazioni sulle impostazioni consigliate per il codificatore.
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: esiste una condizione di errore nello stream.
  • inactive: lo stream è in stato inattivo, ossia 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 integrità del live streaming, che potrebbero 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à è pari o inferiore a warning.
  • 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 in live streaming di YouTube non hanno informazioni sullo stato di integrità dello stream.
status.healthStatus.lastUpdateTimeSeconds unsigned long
L'ultima volta che lo stato di integrità dello stream è stato aggiornato. Il valore rispecchia un timestamp UNIX in secondi.
status.healthStatus.configurationIssues[] list
Questo oggetto contiene un elenco di problemi di configurazione che interessano il flusso.
status.healthStatus.configurationIssues[].type string
Identifica il tipo di errore che interessa il flusso.
status.healthStatus.configurationIssues[].severity string
Indica il livello di 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 LiveStream 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, tra cui l'URL di importazione dei sottotitoli codificati.
contentDetails.closedCaptionsIngestionUrl string
L'URL di importazione a cui vengono inviati i sottotitoli di questo stream.
contentDetails.isReusable boolean
Indica se lo stream è riutilizzabile, il che significa che può essere associato a più trasmissioni. Spesso, le emittenti riutilizzano lo stesso stream per molte trasmissioni diverse, a patto che si verifichino 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 dagli stream riutilizzabili per i seguenti motivi:
  • Uno stream non riutilizzabile può essere associato a una sola trasmissione.
  • Uno stream non riutilizzabile potrebbe essere eliminato da un processo automatizzato al termine della trasmissione.
  • Il metodo liveStreams.list non elenca gli stream non riutilizzabili se chiami il metodo e imposti il parametro mine su true. L'unico modo per utilizzarlo per recuperare la risorsa di uno stream non riutilizzabile è utilizzare il parametro id per identificare lo stream.