Ajouter des balises de génération d'images aux fragments Chemin d'accès à l'objet Amazon S3 (image)Récupération des métadonnées d'image Recommandations relatives aux URI Amazon S3 pour se protéger contre le ralentissement

Génération automatique d'images en temps réel

Amazon Kinesis Video Streams permet de transcoder et de diffuser des images. Kinesis Video Streams extrait automatiquement les images des données vidéo en temps réel et les diffuse dans le compartiment Amazon S3 que vous avez spécifié. La mise en œuvre de l'extraction automatique d'images en temps réel implique les étapes suivantes :

Création d'un compartiment S3 pour recevoir les images générées.
Configuration de la propriété ImageGenerationConfigurationstream qui indique à Kinesis Video Streams comment créer les images et où les envoyer.
Ajouter des balises de génération d'images : Kinesis Video Streams génère uniquement des images à l'aide de fragments dotés de la balise de génération d'image. Ces balises sont ajoutées lors du téléchargement d'une vidéo à l'aide du SDK Kinesis Video Streams Producer associé à la méthode. putKinesisVideoEventMetadata

Les procédures suivantes fournissent des instructions pour effectuer chacune de ces étapes.

Si vous utilisez une clé gérée par le client, assurez-vous que le rôle effectuant les PutMedia appels (uploader) dispose des autorisations suivantes qui sont requises pour chiffrer et déchiffrer les données, ainsi que pour accéder au compartiment Amazon S3.

kms:Encrypt
kms:GenerateDataKey
kms:Decrypt
s3:PutObject

Pour de plus amples informations, veuillez consulter Comment démarrer avec le chiffrement côté serveur ?.

Pour configurer la destination des images générées

Créez un compartiment de destination S3 dans lequel les images seront envoyées.

Suivez le guide de l'utilisateur Amazon S3 pour créer un compartiment Amazon S3.

Notez l'URI du bucket, dont vous aurez besoin à l'étape suivante lors de la mise à jour de la configuration de génération d'images du flux.
Vérifiez que vous les avez AWS CLI installés et configurés. Pour plus d'informations, consultez le guide de AWS Command Line Interface l'utilisateur de la version 2.

Créez un nouveau fichier appelé update-image-generation-input.json avec le contenu suivant en entrée. Mettez à jour les valeurs de l'espace réservé avec les valeurs que vous souhaitez utiliser. Pour connaître les valeurs maximales et minimales prises en charge, consultez l'UpdateImageGenerationConfigurationAPI.


{
   "StreamName": "demo-stream",
   "ImageGenerationConfiguration": {
      "Status": "ENABLED",
      "DestinationConfig": {
         "DestinationRegion": "us-east-1",
         "Uri": "s3://my-bucket-name"
      },
      "SamplingInterval": 200,
      "ImageSelectorType": "PRODUCER_TIMESTAMP",
      "Format": "JPEG",
      "FormatConfig": {
         "JPEGQuality": "80"
      },
      "WidthPixels": 320,
      "HeightPixels": 240
   }
}

Mettez à jour la configuration de génération d'images du flux à l'aide de l'UpdateImageGenerationConfigurationAPI et en joignant le fichier JSON en entrée, comme indiqué dans la commande suivante. Notez que le chemin du fichier pointe vers le fichier du répertoire en cours.
```
aws kinesisvideo update-image-generation-configuration \
  --cli-input-json file://./update-image-generation-input.json
```
En cas de succès, une réponse vide est renvoyée et rien n'est imprimé dans votre terminal.

Note
Le lancement du flux de production d'images prend au moins 1 minute après la mise à jour de la configuration de génération d'images. Patientez au moins 1 minute avant de télécharger la vidéo sur votre stream.
Vérifiez les paramètres de configuration. Utilisez le AWS CLI pour appeler l'DescribeImageGenerationConfigurationAPI de votre flux.
```
aws kinesisvideo describe-image-generation-configuration \
  --stream-name "demo-stream"
```

Kinesis Video Streams génère et diffuse des images uniquement pour les fragments dotés de la balise de génération d'image. Toutes les métadonnées de fragment supplémentaires fournies avec les balises de génération d'images Amazon S3 seront enregistrées en tant que métadonnées Amazon S3.

Note

Les balises de génération d'images font référence à des balises de métadonnées de fragments et non à des balises au niveau du flux.

Important

Les balises de génération d'images sont prises en compte dans le calcul de la limite de balises de métadonnées relatives aux fragments. Pour de plus amples informations, veuillez consulter Quotas du service de métadonnées en streaming.

Voici un exemple de ce à quoi ressemble la structure des balises de métadonnées des fragments à l'aide de l'mkvinfoutilitaire. La balise de génération d'image est une balise MKV simple avec une clé de AWS_KINESISVIDEO_IMAGE_GENERATION et aucune valeur. Pour plus d'informations, consultez l'exemple de balises vidéo dans la documentation de Matroska.


|+ Tags
| + Tag
|  // MANDATORY: Predefined MKV tag to trigger image generation for the fragment
|  + Simple
|   + Name: AWS_KINESISVIDEO_IMAGE_GENERATION

|  // OPTIONAL: S3 prefix which will be set as prefix for generated image.
|  + Simple
|   + Name: AWS_KINESISVIDEO_IMAGE_PREFIX 
|   + String: image_prefix_in_s3 // 256 bytes max

| // OPTIONAL: Key value pairs that will be persisted as S3 Image object metadata.
|  + Simple
|   + Name: CUSTOM_KEY_1 // Max 128 bytes
|   + String: CUSTOM_VALUE_1 // Max 256 bytes
|  + Simple
|   + Name: CUSTOM_KEY_2 // Max 128 bytes
|   + String: CUSTOM_VALUE_2 // Max 256 bytes

Ajouter des balises de génération d'images aux fragments

Kinesis Video Streams génère et diffuse des images uniquement pour les fragments dotés de la balise de génération d'image. Kinesis Video Streams reconnaît ces balises MKV spéciales et lance le flux de production d'images en fonction de la configuration de traitement d'image du flux.

Lorsque vous utilisez le SDK Kinesis Video Streams Producer pour télécharger du contenu multimédia, vous utilisez cette méthode pour ajouter putKinesisVideoEventMetadata la balise de génération d'image à chaque fragment que vous souhaitez baliser. Un nouveau fragment commence lorsqu'il putFrame est appelé par un cadre contenant le keyframe drapeau.

Si vous mettez en ligne une vidéo préenregistrée, elle peut être mise en ligne à une vitesse différente de celle à laquelle elle a été enregistrée, en fonction de la vitesse de votre réseau. Nous vous recommandons d'utiliser l'horodatage du producteur pour configurer la génération d'images si vous souhaitez générer des images à intervalles réguliers en fonction des horodatages d'origine de la vidéo, et de ne pas utiliser les horodatages du serveur générés en fonction de la fréquence à laquelle Amazon Kinesis Video Streams a reçu votre vidéo.

Pour voir un exemple complet de ce code, consultez l'exemple de VideoOnlyRealtimeStreamingSamplecode dans GitHub.


// Setup sample frame
MEMSET(frameBuffer, 0x00, frameSize);
frame.frameData = frameBuffer;
frame.version = FRAME_CURRENT_VERSION;
frame.trackId = DEFAULT_VIDEO_TRACK_ID;
frame.duration = HUNDREDS_OF_NANOS_IN_A_SECOND / DEFAULT_FPS_VALUE;
frame.decodingTs = defaultGetTime(); // current time
frame.presentationTs = frame.decodingTs;

Frame eofr = EOFR_FRAME_INITIALIZER;

while(defaultGetTime() > streamStopTime) {
    frame.index = frameIndex;
    frame.flags = fileIndex % DEFAULT_KEY_FRAME_INTERVAL == 0 ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE;
    frame.size = SIZEOF(frameBuffer);

    CHK_STATUS(readFrameData(&frame, frameFilePath));

    // 1. End the previous fragment
    if (frame.flags == FRAME_FLAG_KEY_FRAME && !firstFrame) {
        putKinesisVideoFrame(streamHandle, &eofr);
    }

    // 2. putFrame call
    CHK_STATUS(putKinesisVideoFrame(streamHandle, &frame));

    if (frame.flags == FRAME_FLAG_KEY_FRAME) {
        // 3. Adding the image generation tag
        CHK_STATUS(putKinesisVideoEventMetadata(streamHandle, STREAM_EVENT_TYPE_IMAGE_GENERATION, NULL);)

        // 4. Adding fragment metadata
        for (n = 1; n <= 5; n++) {
            SNPRINTF(metadataKey, METADATA_MAX_KEY_LENGTH, "SAMPLE_KEY_%d", n);
            SNPRINTF(metadataValue, METADATA_MAX_VALUE_LENGTH, "SAMPLE_VALUE_%d", frame.index + n);
            CHK_STATUS(putKinesisVideoFragmentMetadata(streamHandle, metadataKey, metadataValue, FALSE));
        }
    }
    defaultThreadSleep(frame.duration);

    frame.decodingTs += frame.duration;
    frame.presentationTs = frame.decodingTs;
    frameIndex++;
    fileIndex++;
    fileIndex = fileIndex % NUMBER_OF_FRAME_FILES;
    firstFrame = TRUE;
}

// 5. End the final fragment
putKinesisVideoFrame(streamHandle, &eofr);

Les éléments de l'exemple de code pour configurer des exemples de cadres sont expliqués comme suit :

Chaque fragment doit se terminer par une fin de fragment (eofr). Cette instruction indique que chaque fois qu'une nouvelle image-clé est reçue, signalant le début de l'image suivante, placez un eofr avant d'ajouter l'image suivante dans le flux.
Insérez l'image actuelle dans le flux.
Ajoutez la balise de génération d'image. La putKinesisVideoEventMetadata méthode peut être appelée à tout moment après l'putFrame(keyFrame)appel et avant leputFrame(eofr). Il ne doit être appelé qu'une seule fois par fragment. Comme chaque fragment ne comportera qu'une seule image-clé, nous l'appelons actuellement pour des raisons de simplicité. La valeur renvoyée pour putKinesisVideoEventMetadata est vérifiée pour un code de réussite (0).
Ajoutez d'autres métadonnées de fragments personnalisées, que Kinesis Video Streams transformera en métadonnées d'objets Amazon S3.
Terminez le dernier fragment de cette session de téléchargement.

Utilisation des exemples pour ajouter des balises de génération d'images

Vous pouvez utiliser le kvs_gstreamer_audio_video_sample SDK C++ Producer si vous souhaitez une option de ligne de commande pour ajouter des balises de génération d'images. Activez cette fonctionnalité en ajoutant l'-e bothargument -e image ou, comme indiqué dans l'exemple suivant.


./kvs_gstreamer_audio_video_sample stream-name \
  -f video-to-upload.mp4 \
  -e both

Pour plus d'informations sur cet exemple d'application, consultez le logiciel Amazon Kinesis Video Streams CPP Producer GStreamer , le plugin et le fichier JNI README dans. GitHub

Chemin d'accès à l'objet Amazon S3 (image)

Le chemin de l'objet S3 décrit l'emplacement dans le compartiment S3 configuré où l'image générée sera livrée. Il utilise le format suivant :


ImagePrefix_AccountID_StreamName_ImageTimecode_RandomID.file-extension

Les éléments du chemin de l'objet sont définis comme suit :

ImagePrefix- Valeur de AWS_KINESISVIDEO_IMAGE_PREFIX s'il est présent.
AccountID- L' Compte AWS identifiant sous lequel le flux est créé.
StreamName- Nom du flux à partir duquel l'image est générée.
ImageTimecode- Code temporel d'époque (en millisecondes) dans le fragment dans lequel l'image est générée.
RandomID- GUID aléatoire.
file-extension- JPG ou PNG selon le format d'image demandé.

Dans cet exemple, le chemin de l'objet pour les images générées sera le suivant :


111122223333_demo-stream_16907729324_f20f9add-75e7-4399-a30f-fc7aefb1bab7.jpg

Récupération des métadonnées d'image

Vous pouvez utiliser la console S3 ou la CLI pour récupérer les métadonnées des images générées.

Kinesis Video Streams définit le numéro du fragment, l'horodatage du producteur et du serveur, ainsi que les métadonnées du type de contenu de l'image générée, le tout formaté en tant que métadonnées d'objet Amazon S3. Si des balises MKV supplémentaires sont présentes, elles seront également ajoutées en tant que métadonnées d'objet Amazon S3. L'exemple suivant montre comment utiliser la commande API head-object d'Amazon S3 pour récupérer les métadonnées de l'objet. La réponse inclut les métadonnées créées par Kinesis Video Streams.


aws s3api head-object --bucket my-bucket-name --key 111122223333_demo-stream_1690707290324_f20f9add-7e57-4399-a30f-fc7aefb1bab7.jpg
{
    "AcceptRanges": "bytes",
    "LastModified": "2023-07-30T08:54:51+00:00",
    "ContentLength": 22693,
    "ETag": "\"63e03cb6d57f77e2db984c1d344b1083\"",
    "ContentType": "image/jpeg",
    "ServerSideEncryption": "AES256",
    "Metadata": {
        "aws_kinesisvideo_producer_timestamp": "1690707290324",
        "aws_kinesisvideo_server_timestamp": "1690707289209",
        "aws_kinesisvideo_fragment_number": "91343852333182036507421233921329142742245756394"
    }
}

Pour plus d'informations sur les métadonnées des objets S3, consultezhttps://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingMetadata.html.

Recommandations relatives aux URI Amazon S3 pour se protéger contre le ralentissement

Si vous écrivez des milliers d'images sur Amazon S3, il existe un risque de limitation. Pour plus d'informations, consultez Limites de demande de publication du préfixe S3.

Un préfixe Amazon S3 commence par une limite de 3 500 requêtes PUT par seconde, puis augmentera progressivement au fil du temps pour les préfixes uniques. Évitez d'utiliser des dates et des heures comme préfixes Amazon S3. Les données à code temporel auront un impact sur un préfixe à la fois et changeront également régulièrement, invalidant ainsi les mises à l'échelle des préfixes précédentes.

Pour permettre un dimensionnement Amazon S3 plus rapide et cohérent, nous vous recommandons d'ajouter un préfixe aléatoire, tel qu'un code hexadécimal ou un UUID, à l'URI de destination Amazon S3. Par exemple, les préfixes de code hexadécimal répartiront naturellement vos demandes de manière aléatoire entre 16 préfixes différents (un préfixe pour chaque caractère hexadécimal unique), ce qui autorisera 56 000 requêtes PUT par seconde après le redimensionnement automatique d'Amazon S3.

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

Extraire des images à partir de flux vidéo

Résolution des problèmes