Trasmissione in diretta

Per trasmettere un video in diretta, devi prima creare un oggetto LiveVideo. L'oggetto LiveVideo rappresenta la trasmissione in diretta; puoi manipolare le proprietà dell'oggetto per controllare le impostazioni della trasmissione in diretta. Dopo la creazione, l'API restituirà l'ID dell'oggetto LiveVideo e un URL dello stream, che potrai passare al tuo codificatore e usare per trasmettere dati in streaming all'oggetto LiveVideo.

Trasmettere in diretta su un oggetto User

Per trasmettere in diretta su un oggetto User, ottieni un token d'accesso utente con l'autorizzazione publish_video e invia una richiesta a:

POST /<USER_ID>/live_videos?status=LIVE_NOW

Consulta il riferimento relativo ai segmenti /live_videos per scoprire quali parametri della stringa della query aggiuntivi puoi includere per descrivere la trasmissione, come un titolo o una descrizione.

In caso di azione eseguita correttamente, l'API creerà un oggetto LiveVideo sull'oggetto User e restituirà un secure_stream_url e l'id dell'oggetto LiveVideo. La trasmissione in diretta sarà visualizzata in un post sul profilo dell'utente non appena invierai i dati all'URL dello streaming sicuro. Puoi interrogare l'oggetto LiveVideo per monitorare lo stato della trasmissione e per terminarla.

Esempio di richiesta

curl -i -X POST \
 "https://graph.facebook.com/v21.0/<USER_ID>/live_videos
   ?status=LIVE_NOW
   &title=Today%27s%20Live%20Video
   &description=This%20is%20the%20live%20video%20for%20today."

Esempio di risposta

{
  "id": "1953020644813104",      //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

Trasmettere in diretta su una Pagina

Per trasmettere un video in diretta su una Page, ottieni un token d'accesso della Pagina di un amministratore della Pagina con le autorizzazioni pages_read_engagement e pages_manage_posts, quindi invia una richiesta a:

POST /<PAGE_ID>/live_videos?status=LIVE_NOW

Consulta il riferimento relativo ai segmenti /live_videos per scoprire quali parametri della stringa della query aggiuntivi puoi includere per descrivere la trasmissione, come un titolo o una descrizione.

In caso di azione eseguita correttamente, l'API creerà un oggetto LiveVideo sull'oggetto Page e restituirà un secure_stream_url e l'id dell'oggetto LiveVideo. La trasmissione in diretta sarà visualizzata in un post sulla Pagina non appena invierai i dati all'URL dello streaming sicuro. Puoi interrogare l'oggetto LiveVideo per monitorare lo stato della trasmissione e per terminarla.

Esempio di richiesta

curl -i -X POST \
  "https://graph.facebook.com/v21.0/<PAGE_ID>/live_videos
    ?status=LIVE_NOW
    &title=Today%27s%20Page%20Live%20Video
    &description=This%20is%20the%20live%20video%20for%20the%20Page%20for%20today"

Esempio di risposta

{
  "id": "1953020644813108",     //<LIVE_VIDEO_ID>
  "stream_url": "rtmp://rtmp-api.facebook...",
  "secure_stream_url":"rtmps://rtmp-api.facebook..."
}

Ottenere i dati di streaming della trasmissione in diretta

Puoi leggere un oggetto LiveVideo per ottenere gli URL di anteprima dello streaming della trasmissione in diretta e i dati sulla qualità dello streaming, come bitrate e frequenza dei fotogrammi. I dati sulla qualità dello streaming si aggiornano ogni 2 secondi, quindi limita le query a non più di una ogni 2 secondi. Ogni 4 secondi di mancata ricezione dei dati viene rilevato e segnalato un timeout dello streaming.

Per leggere un oggetto LiveVideo, ottieni un token d'accesso utente o della Pagina appropriato con l'autorizzazione publish_video, quindi invia una query a:

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

Usa il parametro {fields} per specificare i campi dell'oggetto LiveVideo che desideri vengano restituiti. Ad esempio, qui puoi vedere una richiesta per ottenere ingest_streams dell'oggetto LiveVideo, in cui sono inclusi i dati relativi alla qualità dello streaming:

Esempio di richiesta

curl -i -X GET \
  "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?fields=ingest_streams"

Esempio di risposta

{
  "ingest_streams": [
    {
      "stream_id": "0",
      "stream_url": "rtmp://rtmp-api.facebook...",
      "secure_stream_url": "rtmps://rtmp-api.facebook...",
      "is_master": true,
      "stream_health": {
        "video_bitrate": 4024116,
        "video_framerate": 60,
        "video_gop_size": 2000,
        "video_height": 720,
        "video_width": 1280,
        "audio_bitrate": 128745.4921875
      },
      "id": "1914910145231512"  // <INGEST_STREAM_ID>
    }
  ],
  "id": "<LIVE_VIDEO_ID>" 
}

Proprietà della risposta

Terminare una trasmissione in diretta

Per terminare una trasmissione in diretta, arresta lo streaming dei dati sul video in diretta dal codificatore all'URL di streaming o invia una richiesta a:

POST /<LIVE_VIDEO_ID>?end_live_video=true

In questo modo, lo stato dell'oggetto LiveVideo viene impostato su VOD e salvato come video on demand (VOD) per poter essere visualizzato in un secondo momento.

In caso di azione eseguita correttamente, l'API restituirà l'ID dell'oggetto LiveVideo.

Esempio di richiesta

curl -i -X POST \
  "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?end_live_video=true"

Esempio di risposta

{
  "id": "10213570560993813"  //<LIVE_VIDEO_ID>
}

Puoi eseguire un'operazione GET sull'ID del video in diretta per confermare l'impostazione del suo stato su VOD:

GET /<LIVE_VIDEO_ID>?fields=status

Esempio di risposta

{
  "status": "VOD",  // Broadcast ended, saved as VOD
  "id": "10213570560993813"    //<LIVE_VIDEO_ID>
}

Eliminare una trasmissione in diretta

Per eliminare una trasmissione terminata e salvata come VOD, invia una richiesta a:

DELETE /<LIVE_VIDEO_ID>

Esempio di richiesta

curl -i -X DELETE \
 "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>"

Esempio di risposta

{
  success: true
}

Trasmissione in diretta con precisione al fotogramma

L'inizio dello streaming di una trasmissione in diretta potrebbe subire un lieve ritardo dovuto al processo di decodifica dei dati di streaming iniziali e all'elaborazione di eventuali richieste API associate. Questo può rendere difficile per chi esegue lo streaming capire il momento esatto in cui inizia la trasmissione in diretta. Per evitare questo problema, gli oggetti LiveVideo possono essere impostati in modo da accettare i dati di streaming, ma senza avviare la trasmissione in diretta fino a quando non viene rilevato un messaggio RTMP di trasmissione in diretta nei dati di streaming stessi. Questo consente a chiunque sia in grado di visualizzare in anteprima una trasmissione in diretta di vederla, permettendo al contempo al codificatore per lo streaming di controllare con precisione sia il momento di inizio dello streaming della trasmissione per il pubblico sia il primo fotogramma visualizzato.

Per consentire la trasmissione in diretta con precisione al fotogramma, crea innanzitutto un oggetto LiveVideo come faresti normalmente e impostane lo stato su ANTEPRIMA. Una volta creato, interroga l'oggetto LiveVideo e richiedi il campo secure_stream_url con i seguenti campi nidificati:

secure_stream_url.inband_go_live(require_inband_signal)

In questo modo sarà abilitata la trasmissione in diretta con precisione al fotogramma sull'oggetto LiveVideo e l'API risponderà con un nuovo URL di streaming sicuro su cui trasmettere in diretta. Puoi ignorare l'URL di streaming sicuro che hai ricevuto al momento della creazione dell'oggetto LiveVideo.

Lo streaming della trasmissione in diretta inizierà e sarà visibile al pubblico dopo (1) l'impostazione dello stato della trasmissione su IN DIRETTA (tramite una chiamata all'API Graph o una pubblicazione da parte di un utente da Live Producer) e (2) l'invio del messaggio RTMP di trasmissione in diretta da parte del codificatore.

Struttura del messaggio RTMP di trasmissione in diretta

Un pacchetto AMF0 (tipo 0x12) contenente:

• la stringa onGoLive
• un array ECMA (tipo 0x08) contenente una singola coppia codice-valore:

  • Codice: stringa (tipo 0x02) timestamp
  • Valore: numero (tipo 0x00): la marca temporale del primo fotogramma del video che sarà visibile pubblicamente

Per maggiori informazioni, fai riferimento alle specifiche RTMP e AMF0.

Esempio di richiesta

Esempio di richiesta per abilitare la trasmissione in diretta con precisione al fotogramma su un LiveVideo.

curl -i -X GET \
   "https://graph.facebook.com/v21.0/LIVE_VIDEO_ID?fields=secure_stream_url.inband_go_live(require_inband_signal)&access_token=12345..."

Esempio di risposta

URL di streaming sicuro per un oggetto LiveVideo con trasmissione in diretta con precisione al fotogramma abilitata.

{
  "secure_stream_url": "rtmps://rtmp-pc.facebook.com:443/rtmp/LIVE_VIDEO_ID?s_bl=1&s_gl=1&...",
  "id": "LIVE_VIDEO_ID"
}

Ottenere i dati del codice di errore

Per ottenere i dati del codice di errore associati a una trasmissione in diretta, invia una richiesta a:

GET /<LIVE_VIDEO_ID>?fields=errors

L'API risponderà con error code, type, messagee un timestamp.

Esempio di risposta

curl -i -X GET \
 "https://graph.facebook.com/v21.0/<LIVE_VIDEO_ID>?fields=errors"

Esempio di risposta

{
  "errors": {
    "data": [
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 1969004,
        "error_type": "stream",
        "error_message": "Video signal lost",
        "creation_time": "2018-12-05T23:58:52+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      },
      {
        "error_code": 0,
        "error_type": "info",
        "error_message": "Live Service received the video signal",
        "creation_time": "2018-12-05T23:58:02+0000"
      }
    ]
  },
  "id": "{your-live-video-id}"
}

Codici di errore comuni dell'API Live Video

Codici di errore autorizzazione

Altri contenuti da consultare

• Token d'accesso
• Riferimento LiveVideo
• Riferimento Page
• Riferimento PageLiveVideos
• Riferimento autorizzazioni
• Riferimento User
• Riferimento UserLiveVideos