Enregistrer des contenus Politique relative aux compartiments pour StorageConfiguration Fichiers de métadonnées JSON Lecture de contenu enregistré à partir de compartiments privés Résolution des problèmes Problème connu

Enregistrement composite (diffusion en temps réel)

Ce document explique comment utiliser la fonction d’enregistrement composite dans un montage côté serveur. L’enregistrement composite vous permet de générer des enregistrements HLS d’une scène IVS. Pour ce faire, il combine efficacement tous les diffuseurs de publication en une seule vue à l’aide d’un serveur IVS, puis enregistre la vidéo obtenue dans un compartiment S3.

Prérequis

Pour utiliser l'enregistrement composite, vous devez disposer d'une scène avec des éditeurs actifs et d'un compartiment S3 à utiliser comme destination d'enregistrement. Nous décrivons ci-dessous un flux de travail possible qui utilise EventBridge des événements pour enregistrer une composition dans un compartiment S3. Vous pouvez également démarrer et arrêter des montages en fonction de la logique de votre propre application.

Créez une scène IVS et des jetons de participation pour chaque diffuseur de publication.
Créez un EncoderConfiguration(un objet représentant la manière dont la vidéo enregistrée doit être rendue).
Créez un compartiment S3 et un StorageConfiguration(où le contenu de l'enregistrement sera stocké).
Joignez-vous à la scène et diffusez dessus.
Lorsque vous recevez un EventBridge événement publié par un participant, appelez StartCompositionavec un DestinationConfiguration objet S3 comme destination
Au bout de quelques secondes, vous devriez être en mesure de voir que les segments HLS sont conservés dans vos compartiments S3.

Enregistrer une scène dans un compartiment S3 à l’aide d’un montage côté serveur.

Remarque : un montage s’arrête automatiquement après 60 secondes d’inactivité de la part du diffuseur de publication participant à la scène. À ce stade, le montage prend fin et passe à un état STOPPED. Un montage est automatiquement supprimé après quelques minutes passées dans l’état STOPPED. Pour plus de détails, consultez la section Cycle de vie des montages dans Montage côté serveur.

Exemple d'enregistrement composite : StartComposition avec une destination de compartiment S3

L'exemple ci-dessous montre un appel typique au StartCompositionpoint de terminaison, spécifiant S3 comme seule destination pour la composition. Une fois que le montage passe à un état ACTIVE, les segments vidéo et les métadonnées commencent à être écrits dans le compartiment S3 spécifié par l’objet storageConfiguration. Pour créer des montages avec différentes mises en page, consultez la rubrique « Mises en page » de la section Montage côté serveur ainsi que la Référence de l’API de diffusion en temps réel IVS.

Demande


POST /StartComposition HTTP/1.1
Content-type: application/json

{
   "destinations": [
      {
         "s3": {
            "encoderConfigurationArns": [
              "arn:aws:ivs:ap-northeast-1:927810967299:encoder-configuration/PAAwglkRtjge"
            ],
            "storageConfigurationArn": "arn:aws:ivs:ap-northeast-1:927810967299:storage-configuration/ZBcEbgbE24Cq"
         }
      }
   ],
   "idempotencyToken": "db1i782f1g9",
   "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr"
}

Réponse


{
    "composition": {
        "arn": "arn:aws:ivs:ap-northeast-1:927810967299:composition/s2AdaGUbvQgp",
        "destinations": [
            {
                "configuration": {
                    "name": "",
                    "s3": {
                        "encoderConfigurationArns": [
                            "arn:aws:ivs:ap-northeast-1:927810967299:encoder-configuration/PAAwglkRtjge"
                        ],
                        "recordingConfiguration": {
                            "format": "HLS"
                        },
                        "storageConfigurationArn": "arn:aws:ivs:ap-northeast-1:927810967299:storage-configuration/ZBcEbgbE24Cq"
                    }
                },
                "detail": {
                    "s3": {
                        "recordingPrefix": "MNALAcH9j2EJ/s2AdaGUbvQgp/2pBRKrNgX1ff/composite"
                    }
                },
                "id": "2pBRKrNgX1ff",
                "state": "STARTING"
            }
        ],
        "layout": null,
        "stageArn": "arn:aws:ivs:ap-northeast-1:927810967299:stage/WyGkzNFGwiwr",
        "startTime": "2023-11-01T06:25:37Z",
        "state": "STARTING",
        "tags": {}
    }
}

Le recordingPrefix champ présent dans la StartComposition réponse peut être utilisé pour déterminer où le contenu de l'enregistrement sera stocké.

Enregistrer des contenus

Lorsque la composition passe à un ACTIVE état, vous commencez à voir des segments vidéo HLS et des fichiers de métadonnées être écrits dans le compartiment S3 fourni lors de l'appel StartComposition. Ce contenu sont disponibles pour le post-traitement ou la lecture en tant que vidéo à la demande.

Notez qu’une fois qu’un montage est mis en ligne, un événement « IVS Composition State Change » est émis et l’écriture des fichiers manifestes ainsi que des segments vidéo peut être rapide. Nous vous recommandons de ne lire ou de ne traiter les flux enregistrés qu’après réception de l’événement « Changement d’état du montage IVS (fin de session) ». Pour plus de détails, voir Utilisation EventBridge avec le streaming en temps réel IVS.

Voici un exemple de structure de répertoire et de contenu d’un enregistrement d’une session IVS en direct :


MNALAcH9j2EJ/s2AdaGUbvQgp/2pBRKrNgX1ff/composite
   events
      recording-started.json
      recording-ended.json
   media
      hls

Le dossier events contient les fichiers de métadonnées correspondant à l’événement d’enregistrement. Les fichiers de métadonnées JSON sont générés lorsque l’enregistrement démarre, se termine avec succès ou se termine avec des échecs :

events/recording-started.json
events/recording-ended.json
events/recording-failed.json

Un fichier events contiendra recording-started.json et recording-ended.json ou recording-failed.json.

Ceux-ci contiennent des métadonnées relatives à la session enregistrée et à ses formats de sortie. Les détails JSON sont fournis ci-dessous.

Le dossier media contient le contenu multimédia pris en charge. Le sous-dossier hls contient tous les fichiers multimédia et manifestes générés au cours de la session de montage et est lisible avec le lecteur Amazon IVS. Le manifeste HLS se trouve dans le dossier multivariant.m3u8.

Politique relative aux compartiments pour StorageConfiguration

Lorsqu'un StorageConfiguration objet est créé, IVS aura accès pour écrire du contenu dans le compartiment S3 spécifié. Cet accès est accordé en apportant des modifications à la politique du compartiment S3. Si la politique du compartiment est modifiée de manière à supprimer l’accès d’IVS, les enregistrements en cours et les nouveaux enregistrements échoueront.

L’exemple ci-dessous montre une politique de compartiment S3 qui permet à IVS d’écrire dans le compartiment S3 :


{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "CompositeWrite-y1d212y",
            "Effect": "Allow",
            "Principal": {
                "Service": "ivs-composite.ap-northeast-1.amazonaws.com"
            },
            "Action": [
                "s3:PutObject",
                "s3:PutObjectAcl"
            ],
            "Resource": "arn:aws:s3:::my-s3-bucket/*",
            "Condition": {
                "StringEquals": {
                    "s3:x-amz-acl": "bucket-owner-full-control"
                },
                "Bool": {
                    "aws:SecureTransport": "true"
                }
            }
        }
    ]
}

Fichiers de métadonnées JSON

Ces métadonnées sont au format JSON. Il contient les informations suivantes :

Champ	Type	Obligatoire	Description
`stage_arn`	chaîne	Oui	ARN de la scène utilisée comme source du montage.
`media`	objet	Oui	Objet contenant les objets énumérés du contenu multimédia disponibles pour cet enregistrement. Valeurs valides : `"hls"`.
`hls`	objet	Oui	Champ énuméré qui décrit la sortie du format Apple HLS.
`duration_ms`	entier	Conditionnel	Durée du contenu HLS enregistré en millisecondes. Celle-ci n’est disponible que lorsque `recording_status` est `"RECORDING_ENDED"` ou `"RECORDING_ENDED_WITH_FAILURE"`. Si un échec s’est produit avant l’enregistrement, la valeur est 0.
`path`	chaîne	Oui	Chemin relatif depuis le préfixe S3 où le contenu HLS est stocké.
`playlist`	chaîne	Oui	Nom du fichier de la liste de lecture principale HLS.
`renditions`	objet	Oui	Tableau des rendus (variante HLS) d’objets de métadonnées. Il y a toujours au moins un rendu.
`path`	chaîne	Oui	Chemin relatif depuis le préfixe S3 où le contenu HLS est stocké pour ce rendu.
`playlist`	chaîne	Oui	Nom du fichier de la liste de lecture des médias pour ce rendu.
`resolution_height`	ent	Conditionnel	Hauteur de résolution en pixels de la vidéo encodée. Cette option n’est disponible que lorsque le rendu contient une piste vidéo.
`resolution_width`	ent	Conditionnel	Largeur de résolution en pixels de la vidéo encodée. Cette option n’est disponible que lorsque le rendu contient une piste vidéo.
`recording_ended_at`	chaîne	Conditionnel	Horodatage RFC 3339 UTC à la fin de l’enregistrement. Disponible uniquement lorsque `recording_status` est `"RECORDING_ENDED"` ou `"RECORDING_ENDED_WITH_FAILURE"`. `recording_started_at` et `recording_ended_at` sont des horodatages lorsque ces événements sont générés et peuvent ne pas correspondre exactement aux horodatages du segment vidéo HLS. Pour déterminer avec précision la durée d’un enregistrement, utilisez le champ `duration_ms`.
`recording_started_at`	chaîne	Conditionnel	Horodatage RFC 3339 UTC lorsque l’enregistrement a démarré. Ceci n’est pas disponible quand `recording_status` est à l’état `RECORDING_START_FAILED`. Veuillez lire la note ci-dessus relative à `recording_ended_at`.
`recording_status`	chaîne	Oui	Statut de l’enregistrement. Valeurs valides: `"RECORDING_STARTED"`, `"RECORDING_ENDED"`, `"RECORDING_START_FAILED"`, `"RECORDING_ENDED_WITH_FAILURE"`.
`recording_status_message`	chaîne	Conditionnel	Informations descriptives sur le statut. Disponible uniquement lorsque `recording_status` est `"RECORDING_ENDED"` ou `"RECORDING_ENDED_WITH_FAILURE"`.
`version`	chaîne	Oui	Version du schéma des métadonnées.

Exemple : recording-started.json


{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-11-01T06:01:36Z",
  "recording_status": "RECORDING_STARTED",
  "media": {
    "hls": {
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

Exemple : recording-ended.json


{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-10-27T17:00:44Z",
  "recording_ended_at": "2023-10-27T17:08:24Z",
  "recording_status": "RECORDING_ENDED",
  "media": {
    "hls": {
      "duration_ms": 460315,
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

Exemple : recording-failed.json


{
  "version": "v1",
  "stage_arn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/aAbBcCdDeE12",
  "recording_started_at": "2023-10-27T17:00:44Z",
  "recording_ended_at": "2023-10-27T17:08:24Z",
  "recording_status": "RECORDING_ENDED_WITH_FAILURE",
  "media": {
    "hls": {
      "duration_ms": 460315,
      "path": "media/hls",
      "playlist": "multivariant.m3u8",
      "renditions": [
        {
          "path": "720p30-abcdeABCDE12",
          "playlist": "playlist.m3u8",
          "resolution_width": 1280,
          "resolution_height": 720
        }
      ]
    }
  }
}

Lecture de contenu enregistré à partir de compartiments privés

Par défaut, le contenu enregistré est privé ; par conséquent, ces objets sont inaccessibles à la lecture à l’aide de l’URL directe S3. Si vous essayez d’ouvrir la liste de lecture multivariée HLS (fichier m3u8) pour la lecture à l’aide du lecteur IVS ou d’un autre lecteur, vous obtiendrez une erreur (par exemple, « Vous n’avez pas l’autorisation d’accéder à la ressource demandée »). Vous pouvez plutôt lire ces fichiers avec le CloudFront CDN (Content Delivery Network) Amazon.

CloudFront les distributions peuvent être configurées pour diffuser du contenu à partir de buckets privés. Cela est généralement préférable à des compartiments librement accessibles où les lectures contournent les commandes proposées par CloudFront. Vous pouvez configurer votre distribution pour qu'elle soit servie à partir d'un compartiment privé en créant un contrôle d'accès à l'origine (OAC), qui est un CloudFront utilisateur spécial doté d'autorisations de lecture sur le compartiment d'origine privé. Vous pouvez créer l'OAC après avoir créé votre distribution, via la CloudFront console ou l'API. Consultez la section Création d'un nouveau contrôle d'accès à l'origine dans le manuel Amazon CloudFront Developer Guide.

Configuration de la lecture CloudFront avec CORS activé

Cet exemple explique comment un développeur peut configurer une CloudFront distribution avec CORS activé, permettant ainsi la lecture de ses enregistrements depuis n'importe quel domaine. Cela est particulièrement utile pendant la phase de développement. N’hésitez pas à modifier l’exemple ci-dessous pour l’adapter à vos besoins de production.

Étape 1 : Créer un compartiment S3

Créez un compartiment S3 qui sera utilisé pour stocker les enregistrements. Notez que le compartiment doit se trouver dans la même région que celle que vous utilisez pour votre flux de travail IVS.

Ajouter une poilitque d’autorisation CORS au compartiment :

Dans la console AWS, accédez à l’onglet Autorisations du compartiment S3.

Copiez la stratégie CORS ci-dessous et collez-la sous Partage de ressources inter-origines (CORS). Cela permettra d’activer l’accès CORS sur le compartiment S3.


[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "PUT",
            "POST",
            "DELETE",
            "GET"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "x-amz-server-side-encryption",
            "x-amz-request-id",
            "x-amz-id-2"
        ]
    }
]

Étape 2 : Création d'une CloudFront distribution

Consultez la section Création d'une CloudFront distribution dans le guide du CloudFront développeur.

Dans la console AWS, entrez les informations suivantes :

Pour ce champ …	Choisissez ceci...
Domaine de l’origine	Compartiment S3 que vous avez créé à l’étape précédente
Accès à l’origine	Paramètres de contrôle d’accès à l’origine (recommandés)
Comportement du cache par défaut : politique de protocole du visualiseur	Redirect HTTP to HTTPS
Comportement du cache par défaut : méthodes HTTP autorisées	GET, HEAD et OPTIONS
Comportement de cache par défaut : clé de cache et demandes d’origine	CachingDisabled politique
Comportement du cache par défaut : politique de demande d’origine	CORS-S3Origin
Comportement du cache par défaut : politique des en-têtes de réponse	SimpleCORS
Pare-feu d’application Web	Activez les protections de sécurité

Enregistrez ensuite la CloudFront distribution.

Étape 3 : Configurer la stratégie de compartiment S3

Supprimez tout StorageConfiguration ce que vous avez configuré pour le compartiment S3. Cela supprimera toutes les politiques de compartiment qui ont été automatiquement ajoutées au moment de la création de la politique pour ce compartiment.
Accédez à votre CloudFront distribution, assurez-vous que tous les champs de distribution sont dans les états définis à l'étape précédente, puis copiez la politique de compartiment (utilisez le bouton Copier la politique).
Accédez à votre compartiment S3. Dans l’onglet Autorisations, sélectionnez Modifier la politique de compartiment puis collez la politique de compartiment que vous avez copiée à l’étape précédente. Après cette étape, la politique de compartiment doit inclure cette CloudFront politique exclusivement.
Créez un StorageConfiguration, en spécifiant le compartiment S3.

Une fois StorageConfiguration le créé, vous verrez deux éléments dans la politique du compartiment S3, l'un permettant CloudFront de lire le contenu et l'autre permettant à IVS d'écrire du contenu. Un exemple de politique de compartiment finale, avec CloudFront accès IVS, est présenté dans Exemple : Stratégie de compartiment S3 avec CloudFront accès IVS.

Étape 4 : Lire des enregistrements

Après avoir correctement configuré la CloudFront distribution et mis à jour la politique relative aux compartiments, vous devriez être en mesure de lire les enregistrements à l'aide du lecteur IVS :

Démarrez correctement un montage et assurez-vous qu’un enregistrement est stocké dans le compartiment S3.
Après avoir suivi les étapes 1 à 3 de cet exemple, les fichiers vidéo devraient être disponibles pour la consommation via l' CloudFront URL. Votre CloudFront URL est le nom du domaine de distribution dans l'onglet Détails de la CloudFront console Amazon. Elle doit ressembler à ceci :

a1b23cdef4ghij.cloudfront.net
Pour lire la vidéo enregistrée via la CloudFront distribution, recherchez la clé d'objet de votre multivariant.m3u8 fichier dans le compartiment s3. Elle doit ressembler à ceci :

FDew6Szq5iTt/9NIpWJHj0wPT/fjFKbylPb3k4/composite/media/hls/multivariant.m3u8
Ajoutez la clé de l'objet à la fin de votre CloudFront URL. Votre URL finale ressemblera à ce qui suit :

https://a1b23cdef4ghij.cloudfront.net/FDew6Szq5iTt/9NIpWJHj0wPT/fjFKbylPb3k4/composite/media/hls/multivariant.m3u8
Vous pouvez désormais ajouter l’URL finale à l’attribut source d’un lecteur IVS pour visionner l’enregistrement complet. Pour visionner la vidéo enregistrée, vous pouvez utiliser la démonstration fournie dans la section Démarrer du Guide Web : SDK du lecteur IVS.

Exemple : politique de compartiment S3 avec CloudFront accès IVS

L'extrait ci-dessous illustre une politique de compartiment S3 qui permet CloudFront de lire le contenu dans le compartiment privé et IVS d'écrire du contenu dans le compartiment. Remarque : ne faites pas un copier/coller de l’extrait ci-dessous dans votre propre compartiment. Votre politique doit contenir les identifiants correspondant à votre CloudFront distribution et StorageConfiguration.


{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CompositeWrite-7eiKaIGkC9DO",
      "Effect": "Allow",
      "Principal": {
        "Service": "ivs-composite.ap-northeast-1.amazonaws.com"
      },
      "Action": [
        "s3:PutObject",
        "s3:PutObjectAcl"
      ],
      "Resource": "arn:aws:s3:::eicheane-test-1026-2-ivs-recordings/*",
      "Condition": {
        "StringEquals": {
          "s3:x-amz-acl": "bucket-owner-full-control"
        },
        "Bool": {
          "aws:SecureTransport": "true"
        }
      }
    },
    {
      "Sid": "AllowCloudFrontServicePrincipal",
      "Effect": "Allow",
      "Principal": {
        "Service": "cloudfront.amazonaws.com"
      },
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::eicheane-test-1026-2-ivs-recordings/*",
      "Condition": {
        "StringEquals": {
          "AWS:SourceArn": "arn:aws:cloudfront::844311324168:distribution/E1NG4YMW5MN25A"
        }
      }
    }
  ]
}

Résolution des problèmes

La composition n'est pas écrite dans le compartiment S3 : assurez-vous que le compartiment S3 et les StorageConfiguration objets sont créés et se trouvent dans la même région. Assurez-vous également qu'IVS a accès au bucket en vérifiant votre politique de bucket ; voir Bucket Policy pour StorageConfiguration.
Je ne trouve pas de composition lorsque je l'interprète ListCompositions. Les compositions sont des ressources éphémères. Une fois qu’ils sont passés à un état final, ils sont automatiquement supprimés au bout de quelques minutes.
Mon montage s’arrête automatiquement : un montage s’arrête automatiquement si aucun diffuseur de publication n’est présent sur la scène pendant plus de 60 secondes.

Problème connu

La liste de lecture multimédia écrite par enregistrement composite possède la balise #EXT-X-PLAYLIST-TYPE:EVENT pendant que le montage est en cours. Lorsque le montage est terminé, la balise est mise à jour vers #EXT-X-PLAYLIST-TYPE:VOD. Pour une expérience de lecture fluide, nous vous recommandons de n’utiliser cette liste de lecture qu’une fois le montage terminé avec succès.

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Montage côté serveur

Support OBS et WHIP