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.

Cette page comprend les sections suivantes :

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 avec OpenTok. Par exemple, vous pouvez fournir un flux HLS à un client si la session OpenTok a atteint la limite de 15 000 connexions fixée pour les diffusions interactives en direct OpenTok. 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 fonctionnalité de diffusion RTMP pour transmettre un flux vidéo vers une plateforme prenant 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 issus de la session (et jusqu'à 50 flux audio). Si la session comprend plus de 16 flux vidéo simultanés, les flux supplémentaires ne seront pas inclus dans la diffusion.

Un flux HLS présente un décalage de 15 à 20 secondes par rapport aux flux en direct dans la session OpenTok ; le HLS à faible latence (LL-HLS) présente un décalage de 4 à 6 secondes par rapport aux flux en direct. Pendant ce délai initial, le flux de diffusion n'est pas disponible. Ne communiquez pas l'URL de diffusion aux clients tant que le flux HLS ou RTMP n'est pas disponible.

Un EXT-X-ENDLIST La balise est incluse dans les listes de lecture multimédia à la fin d'une diffusion HLS (afin que les applications de lecture puissent détecter la fin du flux).

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

La fonctionnalité de diffusion en continu HLS et RTMP n'est disponible que pour les sessions acheminées (c'est-à-dire celles qui utilisent l' OpenTok Media Router). Pour plus d'informations, consultez Le routeur multimédia OpenTok et les modes multimédia.

La lecture HLS est prise en charge de manière native par la plupart des navigateurs modernes. Pour les environnements ne bénéficiant pas d'une prise en charge native, des plugins tels que Flowplayer peut être utilisé pour assurer la compatibilité entre les navigateurs.

Les flux RTMP OpenTok présentent les caractéristiques 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 (FHD portrait), à 25 images par seconde.
  • Débit binaire vidéo
    • Débit binaire constant (CBR) de 2 Mbps jusqu'à une résolution HD (720p), avec un intervalle entre les images clés de 2 secondes
    • Débit binaire constant (CBR) de 4 Mbps pour une résolution FHD (1080p), avec un intervalle entre les images clés de 2 secondes
  • Son AAC mono à 128 kbps et une fréquence d'échantillonnage de 48 kHz

Vous pouvez limiter le débit binaire maximal utilisé pour la diffusion en configurant le maxBitrate propriété lors de l'appel de la méthode REST « start broadcast ».

Les flux HLS OpenTok présentent les caractéristiques 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.

  • Niveaux de qualité :
    Résolution Niveaux de qualité Débit binaire audio Débit binaire maximal de la couche HLS Max
    VGA 3 128 kbps 1 Mbps
    HD (720p) 4 128 kbps 2 Mbps
    FHD (1080p) 5 128 kbps 4 Mbps

  • Son AAC mono à 128 kbps et une fréquence d'échantillonnage de 48 kHz

Voir le Page des tarifs d'OpenTok pour plus d'informations sur les tarifs de diffusion en continu HLS et RTMP.

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

Utilisez l'API REST OpenTok pour commencer et arrêter diffusion en direct d'une séance, et pour vérifier le statut d'une diffusion en direct.

Les flux HLS et RTMP s'arrêtent automatiquement 60 secondes après la déconnexion du dernier client 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 configurant le maxDuration propriété lors de l'appel de la commencer la diffusion Méthode REST. Vous pouvez définir la durée maximale 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 disposition vidéo pour les diffusions en direct OpenTok

Lorsque vous utilisez la fonctionnalité de diffusion en direct d'OpenTok, vous pouvez personnaliser la disposition des vidéos dans le flux HLS ou RTMP.

Par défaut, la fonctionnalité de diffusion en direct d'OpenTok organise les vidéos de la session OpenTok sous forme de mosaïque dans la vidéo HLS ou RTMP composite. La disposition dépend du nombre de vidéos présentes dans la session. Par exemple, voici la disposition obtenue lorsqu’une session comporte 1, 2, 4 ou 5 flux :

C'est ce qu'on appelle la disposition « best fit ». Vous pouvez également choisir parmi plusieurs autres dispositions prédéfinies. Pour ces autres dispositions, vous devez attribuer un nom de classe à chaque flux vidéo OpenTok afin de déterminer son affichage 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éfinition des mises en page personnalisées.

Par défaut, la vidéo diffusée a une résolution de 640 × 480 pixels (SD en mode paysage, format 4:3). Les différentes vidéos OpenTok sont disposées dans des rectangles conteneurs au sein de la vidéo composite. Par défaut, la vidéo est affichée à l'aide du CSS object-fit est définie comme étant la propriété contain. Par exemple, l'illustration suivante présente une disposition optimale comprenant deux vidéos SD en mode paysage (4:3) (1 et 4) et deux vidéos HD en mode paysage (16:9) (2 et 3) :

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 (SD portrait, format 3:4), 1280x720 (HD paysage, format 16:9), 720 × 1 280 (HD portrait, format 9:16), 1 920 × 1 080 (FHD paysage, format 16:9) ou 1080 × 1920 (FHD portrait, format 9:16) lorsque vous appelez la méthode commencer la diffusion méthode de l'API REST d'OpenTok. Vous pouvez opter pour un format portrait pour les diffusions incluant 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 lancer la diffusion en direct d'une session, en utilisant l'API REST d'OpenTok, vous pouvez, si vous le souhaitez, spécifier le type de disposition initiale.

Régler le Content-Type à "application/json" et définir le type de structure en tant que 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éfinition des mises en page personnalisées), définissez le type à la propriété "custom" et de 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'un flux de partage d'écran est présent dans la session, en configurant le paramètre screenshareType de la propriété layout propriété (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.

Vous pouvez également spécifier le type de mise en page initiale au moment de lancer une diffusion à l'aide des SDK serveur OpenTok :

Si vous ne spécifiez pas de type de mise en page initial, le flux HLS ou RTMP utilise le type de mise en page le plus 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 OpenTok (voir Attribution de classes de mise en page aux flux OpenTok »).

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

Changement 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 OpenTok API REST /broadcast/layout.

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

{
  "type": "pip"
}

Si vous utilisez une mise en page personnalisée (voir Définition des mises en page personnalisées) fixer le type 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'un flux de partage d'écran est présent dans la session, en configurant le screenshareType propriété (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.

Vous pouvez également modifier le type de mise en page à l'aide des SDK serveur OpenTok :

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

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 ou supprimer des flux pendant la diffusion. Vous pouvez également préciser si la diffusion inclura l'audio ou la vidéo d'un flux (ou les deux). Voir Lancer une diffusion en direct et Sélection des flux à inclure dans une diffusion en direct.

Activation de la fonctionnalité DVR dans les diffusions HLS

Les diffusions HLS prennent en charge la fonctionnalité DVR, qui permet aux utilisateurs de revenir en arrière, de mettre en pause et de reprendre la diffusion (sur les lecteurs compatibles avec le DVR). Vous pouvez configurer le dvr à l'option true quand démarrer une diffusion en direct.

Lorsque la fonction DVR est activée, l'URL HLS comportera une chaîne de requête « ?DVR » ajoutée à la fin.

La fonction DVR permet de visionner les programmes diffusés dans un délai de deux heures. Pendant la diffusion, vous pouvez visionner (et revenir en arrière jusqu'à) n'importe quel moment de l'émission, dans la limite de deux heures avant l'heure actuelle. L'enregistrement DVR n'est plus disponible deux heures après la fin 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 en-tête, qui est défini sur l'horodatage du début en temps réel de la capture du segment de streaming. Ceci est défini dans le Spécification de la diffusion en direct par HTTP. Ceci est défini sur un ISO 8601:2004 valeur de date/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 décalage 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 décaler l'affichage de l'emoji en fonction du retard 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 une même session, configurez le multiBroadcastTag option lorsque au début de chaque diffusion en direct. Vous devez attribuer une chaîne de caractères unique à chaque diffusion simultanée d'une session en cours.

Bien que vous puissiez spécifier plusieurs flux RTMP lors du lancement d'une diffusion en direct, chacun d'entre eux utilisera les mêmes options (telles que les flux attribués et la mise en page). Cependant, lorsque vous lancez des diffusions simultanées (en appelant plusieurs fois la méthode REST, avec le multiBroadcastTag (ensemble d'options), 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 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 exclusivement audio incluront des images vidéo noires de 160 × 120 dans les flux RTMP. Certains terminaux, comme YouTube et Facebook, rejettent les flux RTMP exclusivement audio.

Obtenir des informations sur les diffusions en direct

Utilisez l'API REST OpenTok pour obtenir des informations concernant une diffusion en direct ou pour liste diffusions en direct. Ou utilisez les SDK serveur d'OpenTok :

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 le projet pour lequel vous souhaitez enregistrer un rappel sécurisé.

  4. Localiser le Surveillance des diffusions et cliquez sur le bouton Configurer bouton.

  5. 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",
  "projectId": 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.

  • projectId - 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 — Le statut 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 émission avec le status fixé à "failed", cette propriété affichera le message « Erreur interne du serveur ».

  • 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 avec OpenTok 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 OpenTok est en train de démarrer les transcodeurs. Il s'agit de l'état initial.
  • "ready" — Le serveur OpenTok s'est initialisé avec succès, mais le CDN ne récupère pas les fichiers multimédias.
  • "live" — Le serveur OpenTok s'est initialisé avec succès et le CDN est en train de diffuser le contenu multimédia.
  • "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" — Une erreur s'est produite sur la plateforme OpenTok.

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 OpenTok est en train de se connecter au serveur RTMP distant. Il s'agit de l'état initial ; c'est l'état qui s'affiche lorsque vous démarrez la session alors qu'aucun flux n'est publié. Il passe à « live » dès qu'il y a des flux (ou passe à l'un des autres états).
    • live — La plateforme OpenTok s'est connectée avec succès au serveur RTMP distant, et le flux multimédia est en cours de diffusion.
    • offline — La plateforme OpenTok n'a pas pu se connecter au serveur RTMP distant. Cela est dû à un serveur inaccessible ou à une erreur lors de la négociation RTMP. Les causes peuvent être notamment des connexions RTMP refusées, des Applications RTMP inexistantes, des noms de flux refusés, des erreurs d'authentification, etc. Vérifiez que le serveur est en ligne et que vous avez indiqué l'URL du serveur et le nom du flux corrects.
    • error — Une erreur s'est produite sur la plateforme OpenTok.

  • 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 liés à la fonctionnalité de diffusion en direct d'OpenTok

La fonctionnalité de diffusion en direct présente le problème connu suivant :

  • Lorsque vous interrompez une diffusion en direct, les 5 dernières secondes (avant l'interruption de la diffusion) du contenu issu de la session OpenTok sont omises du flux de diffusion.