Démarrage d'un enregistrement d'archive avec l'API Video

L'API Video de Vonage vous permet d'archiver, de sauvegarder et de récupérer des sessions.

Flux de travail de base

Flux de travail de base pour l'enregistrement

Vous pouvez créer un enregistrement d'archive pour une session à l'aide de l'une des options suivantes SDK de serveur. Lorsque vous créez une archive, l'enregistrement commence.

Vous ne pouvez créer une archive que pour les sessions auxquelles au moins un client est connecté. (Un client doit commencer à publier un flux dans la minute qui suit, sinon l'enregistrement de l'archive s'arrête).

Lorsque les clients commencent et arrêtent de publier des flux, ceux-ci sont enregistrés.

Le nombre d'archives que vous pouvez enregistrer n'est toutefois pas limité, sessions automatiquement archivées redémarre un nouvel enregistrement toutes les 4 heures jusqu'à ce que l'enregistrement s'arrête.

Les SDK du serveur comprennent des méthodes pour les éléments suivants :

• Démarrage d'un enregistrement d'archives
• Arrêt d'un enregistrement d'archives
• Lister les enregistrements d'archives
• Récupération d'informations sur l'enregistrement des archives
• Suppression d'une archive

Lorsque vous arrêtez l'enregistrement d'une archive, la plate-forme vidéo de Vonage crée un fichier MP4 ou (dans le cas d'archives de flux individuels) un fichier ZIP. (Voir Archives individuelles de flux et composées.)

Événements du client et transfert de l'interface utilisateur

Lorsqu'un enregistrement d'archive démarre et s'arrête, des événements sont émis dans les clients. Par exemple, le client OpenTok.js La bibliothèque comprend archiveStarted et archiveStopped envoyés par l'objet Session.

Archives composées ou individuelles en un coup d'œil

• Archives composées sont les règles par défaut. Vonage rend un seul MP4 (H.264/AAC) en utilisant tous les flux publiés et les règles de mise en page que vous avez configurées. Ils sont immédiatement lisibles et automatiquement utilisés pour sessions automatiquement archivées. Les archives composées enregistrent jusqu'à 16 flux vidéo simultanés (et jusqu'à 50 flux audio).
• Archives individuelles des cours d'eau produire un fichier ZIP contenant un fichier multimédia pour chaque flux ( .webm ou .mkv) et un manifeste JSON. Choisissez cette option si vous envisagez de post-traiter ou de remixer les flux. Les archives individuelles peuvent capturer jusqu'à 50 flux vidéo (et jusqu'à 50 flux audio), mais elles nécessitent un traitement en aval avant la lecture et ne sont pas prises en charge pour l'archivage automatique.
• Spécifiez le format en définissant outputMode à composed (par défaut) ou individual lorsque vous appelez l'API REST d'archivage ou un SDK de serveur. La comparaison ci-dessous détaille les différences.

Durée d'enregistrement des archives

La durée maximale d'un enregistrement d'archive est de 4 heures (14 400 secondes). Cette durée d'enregistrement correspond au temps cumulé pendant lequel les flux sont publiés (et enregistrés).

Pendant que les flux sont publiés (et enregistrés), l'état de l'archive est défini comme suit "started". (Voir Changement de statut des archives).

Lorsqu'une archive est en cours d'enregistrement sans qu'aucun flux n'ait été publié, le statut est défini comme suit "paused".

Le maximum total La durée d'un enregistrement d'archive, y compris les états "démarré" et "en pause", est de 12 heures (43 200 secondes). Les enregistrements s'arrêtent automatiquement au bout d'une heure (3 600 secondes) d'inactivité (lorsqu'aucun client ne publie de flux).

Notes :

• Archivage automatique des sessions donner lieu à un ou plusieurs enregistrements consécutifs, d'une durée maximale de 4 heures chacun.
• Les archives en cours se terminent pendant la rotation des serveurs (à l'exception des archives automatiques, qui redémarrent automatiquement lorsque la session migre pendant la rotation des serveurs). Vous pouvez redémarrer les archives en réponse aux événements de notification de la rotation des serveurs. Voir Rotation des serveurs et migration des sessions.

Stockage d'enregistrements d'archives

Utilisez votre Account Vonage pour spécifier une cible vers laquelle les fichiers d'enregistrement d'archives terminées seront téléchargés.

Il peut s'agir de votre propre bac Amazon S3, d'un bac d'un fournisseur de stockage compatible S3 autre qu'Amazon ou d'un conteneur Windows Azure.

Pour les fournisseurs de stockage compatibles S3 autres qu'Amazon S3, nous prenons en charge Cloudian et Google Cloud Storage (accessibles via l'API AWS S3). D'autres services compatibles S3 peuvent présenter des limitations de fonctionnalités.

Voir Utilisation du stockage S3 avec l'archivage Video API de Vonage et l'utilisation d'un conteneur Windows Azure avec l'archivage de l'API Video de Vonage.

Lorsque l'enregistrement des archives est terminé (le changement d'état de l'enregistrement des archives est fixé à "stopped"), nous essaierons de télécharger le fichier d'enregistrement de l'archive vers la cible spécifiée (par exemple un fichier Seau S3 ou Conteneur Azure) jusqu'à 72 heures après la création de l'enregistrement d'archive (ou au moins 6 heures si la fonction de repli est activée), en réessayant plusieurs fois par le biais d'une politique de planification du téléchargement distribué.

Si le téléchargement vers la cible spécifiée est réussi, l'état de l'enregistrement de l'archive est défini comme suit "uploaded".

Si vous ne définissez pas de Seau Amazon S3 ou Conteneur Azureou si le téléchargement vers le bac/conteneur spécifié échoue (après plusieurs tentatives), les archives enregistrées peuvent être téléchargées à partir du nuage de Vonage. Dans ce cas, l'état de l'enregistrement des archives est réglé sur "available". Les archives disponibles sur le nuage de Vonage peuvent être téléchargées pendant 72 heures à partir du moment où elles ont été créées. Vous recevrez également un e-mail signalant l'échec du téléchargement à l'adresse e-mail indiquée sur votre Account Vonage.

Pour empêcher le stockage de secours dans le nuage de Vonage, ouvrez une session dans votre Account VonagePour cela, allez dans Applications > Sélectionnez votre application vidéo et désactivez l'option de stockage des enregistrements d'archives.

Si le téléchargement vers la cible spécifiée échoue (après plusieurs tentatives) et que le repli vers le stockage Vonage est désactivé, l'état de l'enregistrement d'archive est défini comme suit "failed".

Vous ne pouvez pas accéder à l'enregistrement d'archive tant qu'il n'est pas téléchargé sur votre cible spécifiée ou disponible sur le stockage de Vonage.

Pour les archives stockées dans le nuage de Vonage, l'URL de téléchargement est fournie dans la section url de l'enregistrement d'archive lorsque le statut est défini sur "available".

Chaque URL de téléchargement utilisée avec le stockage de secours des enregistrements d'archives est une URL pré-signée qui utilise des informations d'identification de sécurité pour accorder une autorisation limitée dans le temps de télécharger l'archive.

Après 10 minutes, l'URL pré-signée expire et une nouvelle URL pré-signée doit être demandée à l'aide de l'API REST ou d'une méthode serveur pour récupérer l'URL de téléchargement.

Pour des raisons de sécurité, l'URL de téléchargement n'est disponible qu'à partir des appels à l'API REST ou des méthodes SDK du serveur pour archives des listes (qui nécessitent les informations d'identification de votre compte).

Archives audio et vidéo uniquement

Lorsque vous créez un enregistrement d'archive à l'aide de l'un des SDK de Vonage Video Server, vous pouvez spécifier s'il doit enregistrer l'audio, la vidéo ou les deux. (La valeur par défaut est d'enregistrer les deux).

Archives individuelles de flux et composées

Le fichier de sortie de l'enregistrement des archives peut avoir l'un des formats suivants :

Choisissez l'archivage composé lorsque vous souhaitez que Vonage fournisse un MP4 lisible dès la fin de l'enregistrement. Choisissez l'archivage de flux individuels lorsque vous avez besoin de captures de flux bruts pour l'édition, la conformité ou des expériences de lecture personnalisées.

Archives composées

L'enregistrement d'archive est un fichier MP4 unique composé de tous les flux. Il s'agit du réglage par défaut. Il est également utilisé pour sessions automatiquement archivées.

Le fichier MP4 utilise la vidéo H.264 et l'audio AAC (à 128 Kbps et une fréquence d'échantillonnage de 48 Khz).

Vous pouvez personnaliser la présentation d'une archive composée, en ajustant la disposition visuelle des flux et les flux qui sont affichés. Voir aussi Personnalisation de la présentation vidéo pour les archives composées.

Par défaut, les archives composées ont une résolution de 640x480 pixels (paysage SD). Pour définir une archive composée avec une résolution de 480x640 (SD portrait), 1280x720 (HD paysage), 720x1280 (HD portrait), 1920x1080 (FHD paysage), 1080x1920 (FHD portrait), définissez l'attribut resolution à la propriété 480x640, 1280x720, 1920x1080, 720x1280ou 1080x1920 lors de l'appel de la méthode de démarrage de l'archive du SDK du serveur vidéo de Vonage. Il se peut que vous souhaitiez utiliser un format portrait lors de l'enregistrement d'archives comprenant des flux vidéo provenant d'appareils mobiles (qui utilisent souvent le format portrait).

Vous pouvez définir le débit vidéo maximal d'un enregistrement d'archive composé afin de contrôler la taille de l'archive. Régler le maxBitrate lors de l'appel de l'option créer une nouvelle archive méthode. Spécifiez un débit, en bits par seconde, compris entre 100 000 et 6 000 000. Ce paramètre ne s'applique qu'à la méthode vidéo débit binaire de l'archive. Si l'archive de sortie contient de l'audio, ces bits seront exclus de la limite. Cette option n'est disponible que pour les archives composées (pas pour les archives de flux individuels). Lorsque vous définissez le débit maximum, l'archive utilise un débit constant.

Vous pouvez définir le paramètre de quantification (QP) pour une archive composée, afin d'ajuster le compromis entre la qualité vidéo et la taille du fichier. Régler le paramètre de quantification (QP) quantizationParameter lors de l'appel de l'option créer une nouvelle archive méthode. Le réglage du paramètre de quantification permet à l'archive d'utiliser un débit variable et une quantification constante de la compression, ce qui permet d'obtenir un niveau de qualité constant lors des changements de scène. Les valeurs valides sont comprises entre 15 et 40, et 20 à 30 produisent des résultats raisonnables sans grande différence de qualité perceptive. Des valeurs QP plus faibles produisent une quantification plus fine de la compression vidéo, ce qui se traduit par une qualité vidéo accrue (en conservant plus de détails vidéo) et une taille de fichier plus importante. Des valeurs QP plus élevées produisent une quantification plus grossière de la compression vidéo, ce qui diminue la qualité vidéo et réduit la taille du fichier. Il n'est pas possible de définir à la fois l'option quantizationParameter et la propriété maxBitrate ce qui entraînerait une erreur.

Remarque : Actuellement, le réglage du paramètre de quantification n'est disponible que dans l'API REST, et non dans les SDK du serveur de l'API Video de Vonage.

Par défaut, si vous ne définissez pas quantizationParameter ou maxBitrate lors de la création d'une archive composée, l'archive utilise un encodage à débit variable avec un paramètre de quantification de 19 (très haute qualité).

Enregistrements d'archives de flux individuels

L'archive est un fichier conteneur ZIP contenant plusieurs fichiers multimédias individuels pour chaque flux, ainsi qu'un fichier de métadonnées JSON pour la synchronisation vidéo.

Vous pouvez spécifier ce format lorsque vous utilisez l'un des SDK du serveur vidéo de Vonage pour démarrer l'archive. Ce format n'est pas disponible pour sessions automatiquement archivées.

Travailler avec des enregistrements d'archives de flux individuels

Le mode d'archivage des flux individuels est destiné à être utilisé avec un outil de post-traitement, afin de produire un contenu personnalisé généré par votre application. Les développeurs doivent tenir compte de certaines considérations lorsqu'ils choisissent d'utiliser cette fonctionnalité.

Conteneurs de flux individuels

Les archives de flux individuels sont livrées sous forme d'archives ZIP, contenant des fichiers pour chaque flux audio-vidéo :

• Chaque conteneur de flux dans l'archive correspond à un flux publié sur la plate-forme vidéo de Vonage. L'ID de flux de l'éditeur correspond au nom de fichier correspondant, et chaque ID de flux est déclaré dans le fichier manifeste des archives.

Lorsqu'un flux est interrompu et repris en raison d'une reconnexion automatique ou lorsqu'un flux est ajouté et supprimé de manière répétée dans une archive manuelle du mode fluxL'archive ZIP comprendra des fichiers distincts pour chacun des segments du cours d'eau.

• Les conteneurs de flux sont soit de type .webmou .mkven fonction de la configuration de votre application. Archives pour les applications pour lesquelles VP8 est défini comme l'option codec vidéo préféré avoir webm et les applications pour lesquelles H.264 est le codec vidéo préféré utilisent l'option mkv format. Voir aussi Notes sur l'archivage des vidéos VP9 pour plus de détails sur la vidéo VP9 en indivi

• Les conteneurs d'archives de flux individuels sont une capture de toutes les données vidéo et audio reçues par le serveur d'archives. Ce média n'est pas traité et, par conséquent, dans la plupart des cas, le conteneur n'est pas adapté à une lecture directe.

Le conteneur de flux est traité comme un flux de transport - tous les médias reçus par le serveur d'archives sont écrits directement dans le fichier, sans inspection ni post-traitement. Cette conception a des implications pour la consommation en aval des conteneurs de flux. Dans la plupart des cas, la lecture directe d'un conteneur d'archive individuel ne sera pas possible ou posera des problèmes en raison du contenu du conteneur :

• Les dimensions déclarées pour l'en-tête du flux sont rarement correctes. Actuellement, les en-têtes du conteneur affichent une piste vidéo de 640x480 pixels, quelles que soient les dimensions des images vidéo encodées.

• Les dimensions des images vidéo changent au fil du temps. Il peut également s'agir de modifications du rapport hauteur/largeur, en particulier dans le cas des flux de partage d'écran.

• Les trames audio et vidéo peuvent ne pas arriver avec des horodatages monotones ; les fréquences d'images ne sont pas toujours cohérentes. Ceci est particulièrement important si la piste vidéo ou audio est désactivée pendant un certain temps, en utilisant l'une des méthodes suivantes publishVideo ou publishAudio les propriétés de l'éditeur.

Les horodatages de présentation des trames (PTS) sont écrits sur la base des horodatages NTP pris au moment de la capture, décalés par l'horodatage de la première trame reçue. Même si le son d'une piste est coupé, puis rétabli, le décalage de l'horodatage doit rester constant pendant toute la durée du flux. Lors du décodage en post-traitement, il y aura un écart de PTS entre les images consécutives pendant la durée de la mise en sourdine de la piste : il n'y a pas d'images "silencieuses" dans le conteneur.

Pour produire un contenu visualisable à partir de fichiers d'archivage de flux individuels, vous devez faire passer le média par un post-processeur afin de réparer les conteneurs de flux individuels ou de multiplexer/composer plusieurs conteneurs en un produit final.

Manifeste d'enregistrement de flux individuels

Les archives de flux individuelles comprennent un fichier de métadonnées JSON, qui fournit des informations sur les enregistrements de flux inclus dans l'archive. Ce fichier a le format suivant :

{
  "createdAt" : 1429305105162,
  "files" : [
    {
      "connectionData" : "connection data for this stream's connection",
      "filename" : "a1475893-99f5-4f02-b697-5d69e8e30d19.webm",
      "size" : 5558064,
      "startTimeOffset" : 3119,
      "stopTimeOffset" : 48765,
      "streamId" : "a1475893-99f5-4f02-b697-5d69e8e30d19",
      "videoType": "camera"
    },
    {
      "connectionData" : "connection data for this stream's connection",
      "filename" : "5ab71b7b-d998-4683-ad2b-7769d6533666.webm",
      "size" : 5396527,
      "startTimeOffset" : 2799,
      "stopTimeOffset" : 48764,
      "streamId" : "5ab71b7b-d998-4683-ad2b-7769d6533666",
      "videoType": "screen"
    }
  ],
  "id" : "297b9c62-78b3-4152-9e98-7e167354c9e6",
  "name" : "archive name",
  "partnerId" : 123456,
  "sessionId" : "2_MX4xMDB-fjE0MjkzMDQ3NzY3NTZ-WUpRUGVFUmhFSkRmVGljeU5zVnJpaXYxfn4"
}

Sélection des flux à inclure dans les archives

Lorsque vous démarrez une archive, si vous avez défini l'option streamMode à manualvous pouvez choisir les flux à inclure dans l'archive.

Vous pouvez ajouter et supprimer des flux pendant l'enregistrement de l'archive. Vous pouvez également spécifier si l'enregistrement de l'archive doit inclure l'audio ou la vidéo d'un flux (ou les deux).

Dans le cas contraire, avec le streamMode fixé à auto (par défaut), tous les flux sont inclus (avec l'audio et la vidéo) dans l'archive. Voir Lancer un enregistrement d'archive et Sélectionner les flux à inclure dans une archive.

Cependant, dans une archive composée, il y a une limite de 16 flux vidéo et 50 flux audio inclus en même temps (pour les modes de flux automatique et manuel), et les flux sont inclus sur la base des critères suivants règles de hiérarchisation des cours d'eau. Pour les archives en mode flux manuel, les mises à jour de flux sont envoyées en tant que Changement de statut des archives.

Archivage automatique des sessions d'enregistrement

Vous pouvez faire en sorte qu'une session soit automatiquement archivée en le spécifiant lors de la création de la session, à l'aide de l'un des SDK du serveur vidéo de Vonage.

L'archivage d'une session archivée automatiquement commence dès qu'un client se connecte à la session.

Les sessions automatiquement archivées comprennent à la fois l'audio et la vidéo, et enregistrent tous les flux dans le même fichier MP4 (composé).

Toutefois, si l'enregistrement dure plus de 4 heures (14 400 secondes), la session est enregistrée dans plusieurs fichiers MP4 consécutifs, d'une durée maximale de 4 heures chacun, jusqu'à ce que l'enregistrement soit arrêté. Les archives automatiques consécutives d'une session se chevauchent légèrement, de sorte qu'aucune donnée enregistrée n'est manquée.

Vous pouvez appeler la méthode SDK côté serveur de Vonage Video pour lister les archives et transmettre le fichier sessionID pour dresser la liste des archives correspondant à l'identifiant de session spécifié.

Vous pouvez ensuite déterminer l'ordre des différents fichiers MP4 en consultant le fichier createdAt de chaque archive répertoriée dans les données JSON renvoyées.

Vous ne pouvez pas arrêter une archive automatique à l'aide des SDK du serveur. Les archives automatiques s'arrêtent 60 secondes après que le dernier client se soit déconnecté de la session ou 60 minutes après que le dernier client ait cessé de publier un flux dans la session.

Vous devez absolument éviter de réutiliser les identifiants de session si vous utilisez l'archivage automatique. La réutilisation d'un identifiant de session peut entraîner l'échec de l'archivage automatique si un précédent archivage automatique de la session a expiré.

N'utilisez pas les archives automatiques pour les sessions de courte durée, telles que celles utilisées pour les appels préalables ou les tests de connectivité. En effet, les archives automatiques s'arrêtent 60 secondes après que le dernier client s'est déconnecté de la session ou 60 minutes après que le dernier client a cessé de publier un flux dans la session (si le client reste connecté après la publication).

Post-traitement des archives composées

Les enregistrements d'archives vidéo ont une durée d'enregistrement des archives jusqu'à 4 heures et 14 400 secondes. Par conséquent, une session vidéo plus longue ne sera pas enregistrée dans un seul fichier d'archive. Pour éviter de perdre une partie de la session, utilisez la fonction sessions automatiquement archivées qui permet de générer plusieurs fichiers pour couvrir l'ensemble de la session. Il est également possible d'utiliser la fonction archives simultanées pour commencer un deuxième enregistrement avant de terminer le précédent. Dans les deux cas, ces archives sont générées avec un court chevauchement entre la fin d'un fichier et le début du suivant.

Si vous préférez avoir un seul fichier contenant l'ensemble de la session, vous pouvez utiliser l'option Post-traitement des archives composées qui fusionne des enregistrements consécutifs qui se chevauchent et tente de rendre la transition aussi fluide que possible. Vous pouvez utiliser cet outil pour générer un fichier unique mais plus long qui contient des médias provenant de plusieurs fichiers d'archive plus courts. Pour plus de détails, voir le guide du développeur Post-traitement des archives composées. L'outil est disponible à l'adresse suivante https://github.com/Vonage/archive-post-processing.

Vous pouvez également utiliser cet outil avec des enregistrements vidéo qui ne sont pas créés en tant qu'archives vidéo Vonage, à condition qu'il y ait un certain chevauchement des médias et que les enregistrements vidéo remplissent une série de caractéristiques, telles que l'utilisation des codecs H264 et AAC LC pour la vidéo et l'audio.

Enregistrements simultanés d'archives

Pour enregistrer simultanément plusieurs archives pour la même session, réglez le paramètre multiArchiveTag au démarrage de chaque archive. Vous devez définir une chaîne unique pour chaque enregistrement simultané d'une session en cours.

Vous pouvez utiliser différentes présentations et attribuer différents flux à chaque enregistrement d'archive simultané.

En sessions automatiquement archivées, fixer le multiArchiveTag pour lancer une nouvelle archive simultanée qui est archivée en même temps que les archives automatiques. Les archives automatiques démarrent et se terminent lorsque la session démarre et s'arrête d'elle-même (en suivant les règles des archives automatiques), tandis que vous arrêtez séparément les archives lancées manuellement.

Changement de l'état de l'enregistrement des archives

Vous pouvez enregistrer une URL de rappel pour recevoir une notification lorsque l'état d'une archive change. Le statut d'une archive est défini comme suit :

Utilisez votre Account Vonage pour spécifier une URL de rappel. Lorsqu'un statut d'archive change, le serveur envoie des requêtes HTTP POST à l'URL que vous spécifiez. L'adresse Content-Type pour la demande est application/json. Les données de la demande sont un objet JSON de la forme suivante :

{
    "id" : "b40ef09b-3811-4726-b508-e41a0f96c68f",
    "event": "archive",
    "createdAt" : 1384221380000,
    "duration" : 328,
    "name" : "Foo",
    "partnerId" : 123456,
    "reason" : "",
    "resolution" : "640x480",
    "sessionId" : "2_MX40NzIwMzJ-flR1ZSBPY3QgMjkgMTI6MTM6MjMgUERUIDIwMTN-MC45NDQ2MzE2NH4",
    "size" : 18023312,
    "status" : "available",
    "url" : "https://tokbox.com.archive2.s3.amazonaws.com/123456/b40ef09b-3811-4726-b508-e41a0f96c68f/archive.mp4"
}

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

Vous pouvez également consulter l'état des archives dans votre Account Vonage :

1. Accédez au tableau de bord de votre Account Vonage.
2. Dans la liste des applications située à gauche de la page, sélectionnez l'application qui contiendra les sessions que vous archivez.
3. Dans la section archivage, cliquez sur l'onglet Liste des archives. Les détails des archives de l'application sont répertoriés.

Sécurité de l'enregistrement des archives

Vous pouvez sécuriser vos archives de la manière suivante :

• Désactiver le repli du stockage de l'enregistrement des archives - Par défaut, Vonage stocke un fichier d'archive sur les serveurs Vonage s'il n'a pas pu télécharger le fichier sur le serveur S3 ou Azure spécifié. Pour empêcher ce stockage de repli (qui est activé par défaut), connectez-vous à votre Account Vonage, sélectionnez l'application et définissez l'option pour désactiver le repli du stockage des archives.
• Utiliser le cryptage Vonage - Cela vous permet de créer des archives Vonage où les données ne sont jamais au repos dans un état non crypté. Parmi les méthodes disponibles pour sécuriser vos enregistrements Vonage, c'est celle qui offre le plus haut niveau de sécurité. Cette fonction est disponible en tant que module complémentaire. Pour plus d'informations, voir la documentation sur le cryptage de Vonage.
• Utiliser le cryptage côté serveur Amazon S3 - Ce système utilise des clés de chiffrement gérées par Amazon S3 pour le chiffrement. En savoir plus sur le cryptage côté serveur d'Amazon S3 ici.

Combiner l'archivage avec Experience Composer

Il est possible de combiner l'archivage et la Compositeur d'expérience.