Diffusion en direct

La fonction de diffusion en direct de l'API Video de Vonage vous permet de diffuser une session vidéo à un large public à l'aide de la diffusion en direct HTTP (HLS) ou d'un flux RTMP.

Il y a plus de clients qui peuvent voir simultanément un flux HLS que de clients qui peuvent voir un flux HLS. session vidéo interactive en direct. Par exemple, vous pouvez fournir un flux HLS à un client si la session a atteint la limite de 15 000 connexions pour les diffusions interactives en direct. Les flux HLS prennent en charge un nombre illimité de spectateurs. Les flux RTMP sont limités par le nombre de spectateurs pris en charge par le fournisseur RTMP.

Vous pouvez utiliser la fonction de diffusion en continu RTMP pour fournir un flux vidéo à une plateforme qui prend en charge les flux RTMP, comme YouTube Live ou Facebook.

En outre, les clients qui ne prennent pas en charge WebRTC peuvent visualiser le flux HLS ou RTMP.

Une diffusion peut inclure jusqu'à 16 flux vidéo de la session (et jusqu'à 50 flux audio). Si la session comprend plus de 16 flux vidéo simultanément, les flux supplémentaires ne seront pas inclus dans la diffusion.

Un HLS est retardé de 15 à 20 secondes par rapport aux flux en direct de la session. Pendant le délai initial, le flux de diffusion n'est pas disponible. Ne fournissez pas l'URL de diffusion aux clients tant que le flux HLS ou RTMP n'est pas disponible.

Pour un flux RTMP, la plateforme Vonage introduit un temps de latence d'environ 5 secondes. Cependant, chaque plateforme de diffusion RTMP (telle que YouTube Live ou Facebook) ajoutera un temps de latence supplémentaire en fonction du traitement de la vidéo avant sa publication.

La fonction de streaming HLS et RTMP n'est disponible que pour les sessions routées (sessions qui utilisent le routeur média de Vonage). Pour plus d'informations, voir Le routeur média de Vonage et les modes média.

La lecture HLS n'est pas prise en charge par tous les navigateurs. Cependant, il existe un certain nombre de plugins, tels que Flowplayerqui offrent une prise en charge multi-navigateurs (en utilisant Flash Player dans les navigateurs qui ne prennent pas directement en charge la technologie HLS).

Les flux RTMP de Vonage ont les spécifications suivantes :

  • H.264 baseline, niveau 3.1, codec vidéo
  • Résolution de 640x480 pixels (SD paysage), 480x640 pixels (SD portrait), 1280x720 pixels (HD paysage), 720x1280 pixels (HD portrait), 1920x1080 pixels (FHD paysage) ou 1080x1920 pixels (HD portrait), à 25 images par seconde.
  • 2 Mbps à débit constant (CBR), avec un intervalle de 2 secondes entre les images clés
  • Audio AAC à 1 canal à 128 Kbps et une fréquence d'échantillonnage de 48 Khz Les flux publiés à partir de Safari s'affichent en tant qu'audio uniquement dans les diffusions en direct.

Voir le Page de tarification de Vonage pour plus de détails sur les prix des flux HLS et RTMP.

Démarrage et arrêt de la diffusion en direct

Utiliser le Video API REST pour démarrer et arrêter la diffusion en direct d'une session, et pour vérifier l'état d'une diffusion en direct.

Les flux HLS et RTMP s'arrêtent automatiquement 60 secondes après que le dernier client se soit déconnecté de la session. De plus, la durée maximale par défaut est de 4 heures (14 400 secondes) pour chaque flux HLS et RTMP (la diffusion en direct s'arrête automatiquement lorsque cette durée est atteinte). Vous pouvez modifier la durée maximale de la diffusion en définissant la propriété maxDuration lors de l'appel de la fonction commencer la diffusion Méthode REST. La durée maximale peut être comprise entre 60 secondes et 10 heures (36 000 secondes).

Remarque : Les diffusions en direct se terminent lors de la rotation du serveur pour la session. Vous pouvez relancer une diffusion en réponse à des événements de notification de rotation du serveur. Voir Rotation des serveurs et migration des sessions.

Vous pouvez limiter le débit maximum à utiliser pour la diffusion en définissant le paramètre maxBitrate lors de l'appel de la propriété commencer la diffusion méthode REST. Vous pouvez définir le débit maximal comme une valeur comprise entre 100 000 et 6 000 000 bits par seconde.

Configuration de la présentation vidéo pour les diffusions en direct

Lorsque vous utilisez la fonction de diffusion en direct, vous pouvez personnaliser la présentation des vidéos dans le flux HLS ou RTMP.

Par défaut, la fonction de diffusion en direct organise les vidéos de la session en mosaïque dans la vidéo HLS ou RTMP composée. La disposition est basée sur le nombre de vidéos dans la session. Par exemple, le schéma suivant illustre la disposition lorsqu'il y a 1, 2, 4 ou 5 flux dans une session :

Vonage video API default layout 1 Vonage video API default layout 2 Vonage video API default layout 4 Vonage video API default layout 5

C'est ce qu'on appelle la mise en page "la mieux adaptée". Vous pouvez également choisir parmi un certain nombre d'autres présentations prédéfinies. Pour les autres dispositions, vous attribuez un nom de classe à chaque flux vidéo afin de déterminer comment il apparaîtra dans la disposition. (Voir Types de mise en page prédéfinis.)

Vous pouvez également définir vos propres mises en page personnalisées à l'aide de CSS. Voir Définir des mises en page personnalisées.

Par défaut, la vidéo diffusée est de 640x480 pixels (paysage SD, format 4:3). Les vidéos individuelles sont disposées dans des rectangles de conteneur au sein de la vidéo composite. Par défaut, la vidéo est dessinée avec la propriété CSS object-fit définie sur contain. Par exemple, l'illustration suivante montre une disposition optimale avec deux vidéos SD paysage (4:3) (1 et 4) et deux vidéos HD paysage (16:9) (2 et 3) :

Vonage Video API layout aspect ratios

Vous pouvez modifier ce comportement en utilisant mises en page personnalisées.

Vous pouvez également configurer un flux de diffusion pour qu'il utilise une résolution de 480x640 (portrait SD, format 3:4), 1280x720 (paysage HD, format 16:9), 720x1280 (portrait HD, format 9:16), 1920x1080 (paysage FHD, format 16:9), 1080x1920 (portrait FHD, format 9:16) lorsque vous appelez le point de terminaison de la diffusion de départ du flux de diffusion. API REST de Vonage. Vous pouvez utiliser un format portrait pour les diffusions qui incluent des flux vidéo provenant d'appareils mobiles (qui utilisent souvent le format portrait).

Spécification du type de mise en page initiale

Lorsque vous démarrez la diffusion en direct d'une session, à l'aide du bouton API RESTvous pouvez, à titre facultatif, spécifier le type de mise en page initiale.

Régler le Content-Type à "application/json" et de définir le type de mise en page comme une propriété des données JSON envoyées dans la requête POST.

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "pip"
  }
}

Si vous utilisez une mise en page personnalisée (voir Définir des mises en page personnalisées), définir le type à la propriété "custom" et transmettre la feuille de style en tant que propriété supplémentaire - stylesheet:

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "custom",
    "stylesheet": "stream.instructor {position: absolute; width: 100%;  height:50%;}"
  }
}

Vous pouvez également spécifier un type de mise en page à utiliser lorsqu'il y a un flux de partage d'écran dans la session en définissant la propriété screenshareType de la propriété de mise en page (voir les dispositions de partage d'écran) :

{
  "sessionId": "2_MX44NTQ1MTF--bm1kTGQ0RjVHeGNQZE51VG5scGNzdVl0flB-",
  "layout": {
    "type": "bestFit",
    "screenshareType": "pip"
  },
  "name" : "archive_name",
  "outputMode" : "composed"
}

La demande renvoie un code d'erreur 400 si vous spécifiez un type non valide.

Si vous ne spécifiez pas de type de présentation initiale, le flux HLS ou RTMP utilise le type de présentation le mieux adapté. Si vous spécifiez un autre type de mise en page, veillez à appliquer les classes de mise en page appropriées aux flux de la session (voir Affectation de classes de présentation aux flux).

Voir Types de mise en page prédéfinis.

Changement dynamique du type de mise en page

Modification dynamique du type de mise en page lors d'une diffusion en direct Vous pouvez modifier dynamiquement le type de mise en page en appelant la fonction /broadcast/layout Point de terminaison REST.

Régler le Content-Type à "application/json" et inclure le type de mise en page comme propriété des données JSON dans la requête PUT :

{
  "type": "pip"
}

Si vous utilisez une mise en page personnalisée (voir Définir des mises en page personnalisées) fixer le type à la propriété "custom" et transmettre la feuille de style en tant que propriété supplémentaire - stylesheet:

{
  "type": "custom",
  "stylesheet": "stream.instructor {position: absolute; width: 100%;  height:50%;}"
}

Vous pouvez également spécifier un type de mise en page à utiliser lorsqu'il y a un flux de partage d'écran dans la session en définissant la propriété screenshareType (voir les dispositions de partage d'écran) :

{
  "type": "bestFit",
  "screenshareType": "pip"
}

La demande renvoie un code d'erreur 400 si vous spécifiez un type non valide.

Lorsque vous spécifiez un type de mise en page autre que le type de mise en page Best Fit par défaut, veillez à appliquer les classes de mise en page appropriées pour les flux de la session (voir Affectation de classes de présentation aux flux).

Sélection des flux à inclure dans une diffusion en direct

Lorsque vous lancez une diffusion en direct, si vous définissez le paramètre streamMode à "manual"Vous pouvez choisir les flux à inclure dans la diffusion. Vous pouvez ajouter et supprimer des flux pendant la diffusion. Vous pouvez également spécifier si la diffusion doit inclure l'audio ou la vidéo d'un flux (ou les deux). Voir la page Video API REST.

Activation de la fonctionnalité DVR dans les diffusions HLS

Les émissions HLS prennent en charge la fonctionnalité DVR, qui permet aux utilisateurs de revenir en arrière, de mettre en pause et de reprendre les émissions (dans les lecteurs qui prennent en charge la fonction DVR). Vous pouvez régler la fonction dvr à l'option true lors du lancement d'une diffusion en direct.

Lorsque le DVR est activé, l'URL HLS comprendra un champ ?DVR ajouté à la fin de la chaîne de requête.

La fonction DVR offre une fenêtre de deux heures pour la lecture de contenus diffusés. Pendant la diffusion, vous pouvez lire (et revenir en arrière) n'importe quel point de la diffusion jusqu'à deux heures avant l'heure actuelle. L'enregistrement DVR n'est plus disponible deux heures après l'arrêt de la diffusion.

Utilisation des métadonnées d'horodatage HLS pour synchroniser les événements

Le manifeste du flux HTTP en direct comprend un EXT-X-PROGRAM-DATE-TIME qui correspond à l'horodatage du début en temps réel de la capture du segment de streaming. Cette valeur est définie dans le fichier Spécification de la diffusion en direct par HTTP. Cette valeur est fixée à un ISO 8601:2004 valeur de la date et de l'heure, en UTC.

Par exemple, l'en-tête se présentera comme suit :

#EXT-X-PROGRAM-DATE-TIME:2021-09-02T11:45:00.810+00:00

Ces horodatages vous permettent de synchroniser les événements dans les applications clientes afin de tenir compte du retard dans le flux HLS. Par exemple, si vous souhaitez envoyer à un client un événement pour afficher un emoji à un moment précis du flux vidéo, le client peut utiliser l'horodatage pour retarder l'affichage de l'emoji en fonction du délai du flux reçu.

Diffusions HLS à faible latence

Pour configurer une diffusion HLS de manière à ce qu'elle prenne en charge le mode de faible latence, définissez le paramètre low-latency à l'option true quand démarrer une diffusion en direct.

Certains lecteurs HLS ne prennent pas en charge le mode faible latence.

Cette fonction est incompatible avec DVR diffusions HLS.

Diffusions simultanées

Pour lancer simultanément plusieurs diffusions en direct pour la même session, définissez le paramètre multiBroadcastTag au début de chaque diffusion en direct. Vous devez définir une chaîne unique pour chaque diffusion simultanée d'une session en cours.

Bien qu'il soit possible de spécifier plusieurs flux RTMP lors de l'utilisation de la fonction démarrer une diffusion en directils utiliseront chacun les mêmes options (telles que les flux et la disposition assignés). Cependant, lorsque vous lancez des diffusions simultanées (en appelant la méthode REST plusieurs fois, avec l'option multiBroadcastTag ), vous pouvez utiliser différentes mises en page et attribuer différents flux à chaque diffusion simultanée.

Diffusions audio et vidéo uniquement

Lorsque vous lancez une diffusion en direct à l'aide de la fonction API REST d'OpenTok, vous pouvez spécifier s'il doit inclure de l'audio, de la vidéo ou les deux. (Voir la page hasAudio et hasVideo options). Par défaut, les deux sont diffusés.

Remarque : Les diffusions audio uniquement incluront de la vidéo avec des images noires de 160x120 dans les flux RTMP. Certains points de terminaison, comme YouTube et Facebook, rejettent les flux RTMP audio uniquement.

Obtenir des informations sur les diffusions en direct

Utiliser le SDK de serveur ou API REST pour obtenir des informations sur une diffusion en direct ou pour dresser la liste des diffusions en direct.

Suivi des changements d'état de la diffusion en direct

Vous pouvez enregistrer une URL de rappel (webhook) pour recevoir des notifications de changement d'état pour les diffusions en direct d'un projet. d'un projet. Le statut d'une diffusion en continu en direct est défini sur ether "started" ou "stopped".

Pour enregistrer un rappel de diffusion pour un projet :

  1. Connectez-vous à votre Video API Account de Vonage.

  2. Dans le menu de gauche, sélectionnez le Account souhaité (si vous avez plusieurs comptes).

  3. Dans le menu de gauche, sélectionnez l'onglet Applications puis le projet pour lequel vous souhaitez enregistrer un rappel sécurisé.

  4. Faites défiler vers le bas jusqu'à Paramètres du projet. Cliquez sur le bouton Editer activer l'icône Rappel sécurisé bouton du curseur, et cliquez sur le bouton Économiser bouton.

Actuellement, vous devez activer les rappels sécurisés pour définir un rappel de surveillance de la diffusion. Si vous désactivez les rappels sécurisés, tout rappel de diffusion que vous définissez sera désactivé.

  1. Localiser le Surveillance de la radiodiffusion et cliquez sur le bouton Configurer bouton.

  2. Spécifiez l'URL de rappel et (éventuellement) un secret de signature.

    Pour plus d'informations sur les rappels sécurisés, voir cette page.

Lorsque le statut d'une diffusion change, le serveur envoie des requêtes HTTP POST à l'URL que vous avez fournie. Le Content-Type de la requête est application/json. Les données de la requête sont un objet JSON de la forme suivante :

{
  "id": "1748b707-0a81-464c-9759-c46ad10d3734",
  "sessionId": "2_MX4xMDBfjE0Mzc2NzY1NDgwMTJ-TjMzfn4",
  "applicationId": 100,
  "createdAt": 1437676551000,
  "updatedAt": 1437676551000,
  "event": "broadcast",
  "group": "status",
  "resolution": "640x480",
  "streamMode" : "auto",
  "streams" : [],
  "broadcastUrls": {
    "hls" : "http://server/fakepath/playlist.m3u8",
    "hlsStatus": "live",
    "rtmp": {
      "foo": {
        "serverUrl": "rtmps://myfooserver:443/myfooapp",
        "streamName": "myfoostream",
        "status": "live"
      },
      "bar": {
        "serverUrl": "rtmp://mybarserver:443/mybarapp",
        "streamName": "mybarstream",
        "status": "live"
      }
    }
  },
  "settings": {
    "hls": {
      "dvr": false,
      "lowLatency": false
    }
  },
  "status": "started"
}

L'objet JSON comprend les propriétés suivantes :

  • id - L'identifiant unique de la diffusion.

  • sessionId - L'identifiant de session de l'API Video.

  • applicationId - Votre ID de projet Video API.

  • group - Cette valeur est fixée à "broadcast".

  • event - Cette valeur est fixée à "status".

  • createdAt - Heure de début de la diffusion, exprimée en millisecondes depuis l'époque Unix (1er janvier 1970, 00:00:00 UTC).

  • updatedAt - Pour cette méthode GET, cet horodatage correspond à l'horodatage de createdAt.

  • resolution - La résolution de la diffusion (soit "640x480", "1280x720", "1920x1080", "480x640", "720x1280" ou "1080x1920").

  • status - L'état de la diffusion : soit "started", "stopped"ou "failed". Pour un "failed" Vérifier l'état de la reason de l'événement pour plus de détails.

  • reason - Pour une diffusion avec le status fixé à "failed"ce bien contiendra "Internal server failure".

  • broadcastUrls - Détails sur les flux de diffusion HLS et RTMP.

    Pour un flux HLS, l'URL est fournie sous la forme de l'élément hls les biens. Voir le Guide du développeur pour la diffusion en direct de Vonage pour plus d'informations sur l'utilisation de cette URL. L'adresse hlsStatus est définie sur l'une des valeurs suivantes :

    • "connecting" - Le serveur Vonage est en train de démarrer les transcodeurs. Il s'agit de l'état initial.
    • "ready" - Le serveur Vonage a été initialisé avec succès mais le CDN ne consomme pas de média.
    • "live" - Le serveur Vonage s'est initialisé avec succès et le CDN consomme des médias.
    • "ended" - Le flux source est terminé. Si le DVR est activé et qu'un média préenregistré est demandé, l'état passera à "live".
    • "error" - Il y a une erreur dans la plateforme Vonage.

    Pour chaque flux RTMP, l'URL du serveur RTMP et le nom du flux sont fournis, ainsi que l'état du flux RTMP.

    • status - Le statut du flux RTMP. Cette propriété est définie comme l'une des suivantes :

      • connecting - La plateforme Vonage est en train de se connecter au serveur RTMP distant. Il s'agit de l'état initial, et c'est l'état dans lequel vous commencez lorsque aucun flux n'est publié dans la session. Il devient "en direct" lorsqu'il y a des flux (ou il passe à l'un des autres états).
      • live - La plateforme Vonage s'est connectée avec succès au serveur RTMP distant et le média est en cours de diffusion.
      • offline - La plateforme Vonage n'a pas pu se connecter au serveur RTMP distant. Cela est dû à un serveur inaccessible ou à une erreur dans l'échange RTMP. Les causes incluent des connexions RTMP rejetées, des applications RTMP inexistantes, des noms de flux rejetés, des erreurs d'authentification, etc. Vérifiez que le serveur est en ligne et que vous avez fourni l'URL du serveur et le nom du flux corrects.
      • error - Il y a une erreur dans la plateforme Vonage.

    • serverUrl - L'URL du serveur RTMP.

    • streamName - Le nom du flux RTMP.

  • settings - Plus de détails sur le flux de diffusion HLS. Ce flux properties comprend un objet hls avec les propriétés suivantes :

  • multiBroadcastTag - La balise unique pour les diffusions simultanées (si une balise a été définie).

  • streamMode - Si tous les flux sont inclus dans la diffusion ("auto") ou vous sélectionnez les flux à inclure dans la diffusion ("manual"). Voir aussi Sélection des flux à inclure dans une diffusion en direct.

  • streams - Un tableau d'objets correspondant aux flux en cours de diffusion. Ce tableau n'est défini que pour une diffusion avec l'option status fixé à "started" et le streamMode fixé à "manual". Chaque objet du tableau comprend les propriétés suivantes :

    • streamId - L'identifiant du flux inclus dans la diffusion.
    • hasAudio - Indique si le son du flux est inclus dans la diffusion.
    • hasVideo - Si la vidéo du flux est incluse dans la diffusion.

Problèmes connus avec la fonction de diffusion en direct de Vonage

La fonction de diffusion en direct présente les problèmes connus suivants :

  • Lorsque vous arrêtez une diffusion en direct, les 5 dernières secondes (avant l'arrêt de la diffusion) du contenu de la session Vonage sont omises du flux de diffusion.