Diffusion

Pour diffuser une vidéo en direct, vous devez avant tout créer un objet LiveVideo. L’objet LiveVideo représente la diffusion, et vous pouvez manipuler ses propriétés pour contrôler les paramètres de la diffusion. Lors de la création, l’API renvoie l’ID de l’objet LiveVideo et une URL de stream, que vous pouvez transmettre à votre encodeur et utiliser pour streamer les données vers l’objet LiveVideo.

Diffuser sur un utilisateur ou une utilisatrice

Pour diffuser sur un objet User, récupérez un token d’accès d’utilisateur·ice disposant de l’autorisation publish_video et envoyez une requête à :

POST /<USER_ID>/live_videos?status=LIVE_NOW

Reportez-vous à la référence de l’arête /live_videos pour savoir quels paramètres supplémentaires, tel qu’un titre ou une description, vous pouvez inclure pour décrire la diffusion.

En cas de réussite, l’API crée un objet LiveVideo sur l’utilisateur ou l’utilisatrice et renvoie une secure_stream_url et l’id de l’objet LiveVideo. La diffusion apparaît dans une publication sur le profil de l’utilisateur ou de l’utilisatrice dès que vous envoyez des données à l’URL de stream sécurisé. Vous pouvez interroger l’objet LiveVideo pour contrôler l’état de la diffusion et mettre fin à celle-ci.

Exemple de requête

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."

Exemple de réponse

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

Diffuser sur une Page

Pour diffuser une vidéo en direct sur une Page, récupérez le token d’accès de Page d’un admin de la Page disposant des autorisations pages_read_engagement et pages_manage_posts, puis envoyez une requête à :

POST /<PAGE_ID>/live_videos?status=LIVE_NOW

Reportez-vous à la référence de l’arête /live_videos pour savoir quels paramètres supplémentaires, tel qu’un titre ou une description, vous pouvez inclure pour décrire la diffusion.

En cas de réussite, l’API crée un objet LiveVideo sur la Page et renvoie une secure_stream_url et l’id de l’objet LiveVideo. La diffusion apparaît dans une publication sur la Page dès que vous envoyez des données à l’URL de stream sécurisé. Vous pouvez interroger l’objet LiveVideo pour contrôler l’état de la diffusion et mettre fin à celle-ci.

Exemple de requête

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"

Exemple de réponse

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

Obtenir les données de stream d’une diffusion

Vous pouvez lire un objet LiveVideo pour obtenir les URL d’aperçu du stream de la diffusion, ainsi que des données sur l’intégrité du stream, comme le débit binaire et la fréquence d’image. Les données sur l’état d’intégrité du stream étant actualisées toutes les deux secondes, limitez les requêtes à cette fréquence d’exécution. Une expiration du délai d’attente de stream sera détectée et signalée, si aucune donnée n’est reçue pendant quatre secondes.

Pour lire un objet LiveVideo, récupérez un token d’accès de Page ou d’utilisateur·ice approprié disposant de l’autorisation publish_video, puis envoyez une requête à :

GET /<LIVE_VIDEO_ID>?fields=<COMMA_SEPARATED_LIST_OF_FIELDS>

Utilisez le paramètre {fields} pour spécifier les champs d’objet LiveVideo que vous souhaitez obtenir. Par exemple, voici une requête pour obtenir le paramètre ingest_streams de l’objet LiveVideo, qui inclut des données sur l’intégrité du stream :

Exemple de requête

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

Exemple de réponse

{
  "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>" 
}

Propriétés de la réponse

Mettre fin à la diffusion

Pour mettre fin à une diffusion, arrêtez de streamer des données vidéo en direct entre votre encodeur et l’URL de stream ou envoyez une requête à :

POST /<LIVE_VIDEO_ID>?end_live_video=true

Cette requête définit le statut de l’objet LiveVideo sur VOD et l’enregistre en tant que vidéo à la demande pour pouvoir l’afficher ultérieurement.

En cas de réussite, l’API renvoie l’ID de l’objet LiveVideo.

Exemple de requête

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

Exemple de réponse

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

Vous pouvez envoyer une requête GET portant sur l’ID de l’objet LiveVideo pour confirmer que son statut a été défini sur VOD :

GET /<LIVE_VIDEO_ID>?fields=status

Exemple de réponse

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

Supprimer une diffusion

Pour supprimer une diffusion qui a pris fin et qui a été enregistrée en tant que VOD, envoyez une requête à :

DELETE /<LIVE_VIDEO_ID>

Exemple de requête

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

Exemple de réponse

{
  success: true
}

Lancement précis du direct

Le décodage des premières données du stream et le traitement des requêtes d’API associées peuvent entraîner un léger décalage de lancement du direct. C’est pourquoi les talents qui sont en direct ont parfois du mal à savoir exactement quand une diffusion a commencé. Pour remédier à ce problème, les objets LiveVideo peuvent être configurés de manière à accepter les données streamées sans toutefois les diffuser aux audiences, tant qu’un message RTMP de lancement n’est pas détecté dans les données du stream lui-même. Ainsi, toutes les personnes en mesure de prévisualiser la diffusion peuvent la voir, et l’encodeur peut contrôler avec précision l’heure à laquelle la diffusion est lancée pour une audience et la première image que cette audience voit.

Pour activer le lancement précis du direct, commencez par créer un objet LiveVideo normal, puis définissez son statut sur PREVIEW. Une fois l’objet LiveVideo créé, interrogez-le de manière à obtenir le champ secure_stream_url avec les champs imbriqués suivants :

secure_stream_url.inband_go_live(require_inband_signal)

Ainsi, vous activez le lancement précis du direct sur l’objet LiveVideo, et l’API vous renvoie une nouvelle URL de stream sécurisé sur laquelle vous pouvez streamer votre vidéo. Vous pouvez ignorer la première URL de stream sécurisé que vous avez reçue lors de la création de l’objet LiveVideo.

La diffusion est lancée et visible pour l’audience lorsque (1) le statut de la diffusion est défini sur LIVE (via un appel à l’API Graph ou une publication d’utilisateur ou d’utilisatrice dans Live Producer) et (2) l’encodeur envoie le message RTMP de lancement du direct.

Structure du message RTMP de lancement du direct

Un paquet AMF0 (type 0x12) contenant les éléments suivants :

• La chaîne onGoLive
• Un tableau ECMA (type 0x08) contenant une seule paire clé-valeur :

  • Clé : chaîne (type 0x02) timestamp
  • Valeur : nombre (type 0x00) représentant l’horodatage de la première image vidéo que le public verra

Pour plus d’informations, consultez les spécifications RTMP et AMF0.

Exemple de requête

Requête permettant d’activer le lancement précis du direct sur un objet 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..."

Exemple de réponse

URL de stream sécurisé pour un objet LiveVideo avec le lancement précis du direct activé.

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

Obtenir les données relatives aux codes d’erreur

Pour obtenir les données relatives aux codes d’erreur d’une diffusion, envoyez une requête à :

GET /<LIVE_VIDEO_ID>?fields=errors

L’API renvoie les éléments suivants : error code, type, message et timestamp.

Exemple de réponse

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

Exemple de réponse

{
  "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}"
}

Codes d’erreur courants de l’API Live Video

Codes d’erreur liés aux autorisations

Voir aussi

• Tokens d’accès
• Référence sur LiveVideo
• Référence sur Page
• Référence sur PageLiveVideos
• Référence sur les autorisations
• Référence sur User
• Référence sur UserLiveVideos