Utilisation des métadonnées de streaming avec Kinesis Video Streams

Vous pouvez utiliser le SDK Amazon Kinesis Video Streams Producer pour intégrer des métadonnées au niveau du fragment individuel dans un flux vidéo Kinesis. Dans Kinesis Video Streams, les métadonnées sont une paire clé-valeur modifiable. Vous pouvez l'utiliser pour décrire le contenu du fragment, intégrer les mesures de capteur associées qui doivent être transférées avec le fragment lui-même ou répondre à d'autres besoins personnalisés. Les métadonnées sont mises à disposition dans le cadre des opérations d'API GetMedia ou GetMediaForFragmentList. Il est stocké avec les fragments pendant toute la durée de conservation du stream. Vos applications consommatrices peuvent lire, traiter et réagir en fonction des métadonnées à l'aide duBibliothèque d'analyseurs de flux vidéo Kinesis.

Il existe deux modes dans lequel les métadonnées peuvent être intégrées à des fragments dans un flux :

• Non persistant : vous pouvez apposer des métadonnées de manière ponctuelle ou ad hoc sur des fragments d'un flux, en fonction de critères spécifiques à l'entreprise qui se sont produits. Par exemple, une caméra intelligente détecte un mouvement et ajoute des métadonnées aux fragments correspondants contenant le mouvement avant de les envoyer vers son flux vidéo Kinesis. Vous pouvez appliquer les métadonnées au fragment selon le format suivant : Motion = true.

• Persistant : vous pouvez apposer des métadonnées sur des fragments consécutifs et successifs d'un flux en fonction d'un besoin continu. Par exemple, une caméra intelligente envoie les coordonnées de latitude et de longitude actuelles associées à tous les fragments qu'elle envoie à son flux vidéo Kinesis. Vous pouvez appliquer les métadonnées à tous les fragments selon le format suivant : Lat = 47.608013N , Long = -122.335167W.

Vous pouvez associer simultanément les métadonnées au même fragment dans ces deux modes, en fonction des besoins de votre application. Les métadonnées intégrées peuvent inclure les objets détectés, l'activité suivie, les coordonnées GPS ou d'autres données personnalisées que vous souhaitez associer aux fragments du flux. Les métadonnées sont codées sous forme de paires de chaînes clé-valeur.

Ajouter des métadonnées à un flux vidéo Kinesis

Les métadonnées que vous ajoutez à un flux vidéo Kinesis sont modélisées sous forme de balises MKV, qui sont implémentées sous forme de paires clé-valeur.

Les métadonnées peuvent être transitoires, pour marquer un événement dans le flux par exemple, ou persistantes, pour identifier les fragments dans lesquels un événement donné est en cours par exemple. Un élément de métadonnées persistant est conservé et est appliqué à chaque fragment consécutif jusqu'à son annulation.

Note

Les éléments de métadonnées ajoutés avec Bibliothèques Producteur sont distincts de la mise en œuvre des API de balisage au niveau du flux avec TagStream, UntagStream et ListTagsForStream.

API de métadonnées de streaming

Vous pouvez utiliser les opérations suivantes du kit SDK Producer pour mettre en œuvre les métadonnées de streaming.

PIC

PUBLIC_API STATUS putKinesisVideoFragmentMetadata(STREAM_HANDLE streamHandle, 
    PCHAR name, 
    PCHAR value, 
    BOOL persistent);

Kit SDK C++ Producer

/**
 * Appends a "tag" or metadata - a key/value string pair into the stream.
 */
bool putFragmentMetadata(const std::string& name, const std::string& value, bool persistent = true);

Kit SDK Java Producer

Vous pouvez utiliser le SDK Java Producer pour ajouter des métadonnées à un utilisateur MediaSource : MediaSourceSink.onCodecPrivateData

void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String metadataValue, final boolean persistent)
throws KinesisVideoException;

Métadonnées persistantes et non persistantes

Pour les métadonnées non persistantes, vous pouvez ajouter plusieurs éléments de métadonnées portant le même nom. Le kit SDK Producer recueille les éléments de métadonnées de la file d'attente des métadonnées jusqu'à ce qu'ils soient ajoutés au fragment suivant. La file d'attente des métadonnées est effacée lorsque les éléments de métadonnées sont appliqués au flux. Pour reproduire les métadonnées, appelez à nouveau putKinesisVideoFragmentMetadata ou putFragmentMetadata.

Pour les métadonnées persistants, le kit SDK Producer recueille les éléments des métadonnées dans la file d'attente des métadonnées de la même manière que pour les métadonnées non persistantes. Toutefois, les éléments de métadonnées ne sont pas supprimés de la file d'attente lorsqu'ils sont ajoutés au fragment suivant.

L'appel de putKinesisVideoFragmentMetadata ou putFragmentMetadata avec persistent défini sur true a le comportement suivant :

• L'appel de l'API place l'élément des métadonnées dans la file d'attente. Les métadonnées sont ajoutées sous la forme d'une balise MVK à chaque fragment tandis que l'élément se trouve dans la file d'attente.

• L'appel de l'API avec le même nom et une autre valeur en tant qu'élément de métadonnées précédemment ajouté remplace l'élément.

• L'appel de l'API avec une valeur vide supprime (annule) l'élément de métadonnées de la file d'attente des métadonnées.

Consommation de métadonnées intégrées dans un flux vidéo Kinesis

Pour utiliser les métadonnées d'un flux vidéo Kinesis, utilisez une implémentation de : MkvTagProcessor

public interface MkvTagProcessor {
        default void process(MkvTag mkvTag, Optional<FragmentMetadata> currentFragmentMetadata) {
            throw new NotImplementedException("Default FragmentMetadataVisitor.MkvTagProcessor");
        }
        default void clear() {
            throw new NotImplementedException("Default FragmentMetadataVisitor.MkvTagProcessor");
	    }
    }
}

Cette interface se trouve dans la classe FragmentMetadataVisitor de la Bibliothèque d'analyseurs de flux vidéo Kinesis.

La classe FragmentMetadataVisitor contient une implémentation de MkvTagProcessor :

public static final class BasicMkvTagProcessor implements FragmentMetadataVisitor.MkvTagProcessor {
    @Getter
    private List<MkvTag> tags = new ArrayList<>();

    @Override
    public void process(MkvTag mkvTag, Optional<FragmentMetadata> currentFragmentMetadata) {
        tags.add(mkvTag);
    }
    
    @Override
    public void clear() {
        tags.clear();
	}
}

La classe KinesisVideoRendererExample contient un exemple d'utilisation de BasicMkvTagProcessor. Dans l'exemple suivant, une BasicMkvTagProcessor est ajoutée au lien MediaProcessingArguments d'une application :

if (renderFragmentMetadata) {
    getMediaProcessingArguments = KinesisVideoRendererExample.GetMediaProcessingArguments.create(
        Optional.of(new FragmentMetadataVisitor.BasicMkvTagProcessor()));

La méthode BasicMkvTagProcessor.process est appelée lorsque les métadonnées de fragment arrivent. Vous pouvez récupérer les métadonnées accumulées avec GetTags. Pour récupérer un seul élément de métadonnées, appelez clear d'abord pour effacer les métadonnées collectées, puis récupérez à nouveau les éléments de métadonnées.

Limites de métadonnées de streaming

Quotas de métadonnées de fragmentsPour plus d'informations sur les limites applicables à l'ajout de métadonnées de streaming à un flux vidéo Kinesis, reportez-vous à