Amazon Kinesis Video Streams
Guía para desarrolladores

Uso de metadatos de streaming con Transmisión de vídeo de Kinesis

Puede utilizar el SDK de Producer de Amazon Transmisión de vídeo de Kinesis para insertar los metadatos en el nivel de los fragmentos individuales de una Transmisión de vídeo de Kinesis. Los metadatos de Transmisión de vídeo de Kinesis son un par clave-valor mutable. Puede utilizarlos para describir el contenido del fragmento, insertar lecturas de sensores asociados que se deban transferir junto con el fragmento o satisfacer otras necesidades personalizadas. Los metadatos están disponibles como parte de las operaciones de API de GetMedia o de GetMediaForFragmentList. Se almacenan junto con los fragmentos durante todo el periodo de retención de la secuencia. Las aplicaciones consumidoras pueden leer, procesar y realizar acciones basadas en los metadatos usando la Kinesis Video Stream Parser Library.

Hay dos formas de insertar los metadatos con los fragmentos de una secuencia:

  • No persistente: puede asociar metadatos ad hoc a los fragmentos de una secuencia en función de los criterios específicos del negocio. Un ejemplo es una cámara inteligente que detecta movimiento y añade metadatos a los fragmentos correspondientes que contienen el movimiento antes de enviarlos a su Transmisión de vídeo de Kinesis. Puede aplicar los metadatos al fragmento en el siguiente formato: Motion = true.

  • Persistente: puede asociar metadatos a fragmentos sucesivos y consecutivos de una secuencia si hay una necesidad continuada. Un ejemplo es una cámara inteligente que envía las coordenadas de latitud y longitud actuales asociadas a todos los fragmentos que envía a su Transmisión de vídeo de Kinesis. Puede aplicar los metadatos a todos los fragmentos en el siguiente formato: Lat = 47.608013N , Long = -122.335167W.

Puede asociar metadatos simultáneamente en los dos modos al mismo fragmento en función de las necesidades de la aplicación. Los metadatos insertados podrían incluir los objetos detectados, las actividades monitorizadas, las coordenadas GPS o cualquier otro dato personalizado que se desee asociar a los fragmentos de la secuencia. Los metadatos se codifican como pares de cadenas clave-valor.

Adición de metadatos a una transmisión de vídeo de Kinesis

Los metadatos que se añaden a una Transmisión de vídeo de Kinesis tienen el formato de las etiquetas de MKV, que se implementan como pares clave-valor.

Los metadatos pueden ser transitorios, como los que marcan un evento dentro de la secuencia, o persistentes, como los que identifican los fragmentos en los que se está produciendo un evento concreto. Un elemento de metadatos persistente se conserva y se aplica a todos los fragmentos consecutivos hasta que se cancela.

nota

Los elementos de metadatos añadidos usando el Producer Libraries son distintos de las API de etiquetado de nivel de secuencia que se implementan con TagStream, UntagStream y ListTagsForStream.

API de metadatos de streaming

Puede utilizar las siguientes operaciones del SDK de Producer para implementar los metadatos de streaming.

PIC

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

SDK de 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);

SDK de Java Producer

Con el SDK de Java Producer, se añaden los metadatos a un MediaSource usando MediaSourceSink.onCodecPrivateData:

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

Metadatos persistentes y no persistentes

En el caso de los metadatos no persistentes, puede agregar varios elementos de metadatos con el mismo nombre. El SDK de Producer recopila los elementos de metadatos de la cola de metadatos hasta que se anexan al siguiente fragmento. La cola de metadatos se vacía a medida que los elementos de metadatos se aplican a la secuencia. Para repetir los metadatos, llame de nuevo a putKinesisVideoFragmentMetadata o a putFragmentMetadata.

En el caso de los metadatos persistentes, el SDK de Producer recopila los elementos de metadatos de la cola de metadatos de la misma forma que para los metadatos no persistentes. Sin embargo, los elementos de metadatos no se eliminan de la cola cuando se anexan al siguiente fragmento.

Llamar a putKinesisVideoFragmentMetadata o putFragmentMetadata con persistent establecido como true provoca el siguiente comportamiento:

  • Llamar a la API coloca el elemento de metadatos en la cola. Los metadatos se añaden como etiqueta de MKV a todos los fragmentos mientras el elemento está en la cola.

  • Llamar a la API con el mismo nombre y con un valor diferente del de un elemento de metadatos añadido anteriormente sobrescribe el elemento.

  • Llamar a la API con un valor vacío elimina (cancela) el elemento de metadatos de la cola de metadatos.

Consumo de metadatos insertados en una transmisión de vídeo de Kinesis

Para consumir los metadatos de una Transmisión de vídeo de Kinesis, utilice una implementación 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"); } } }

La interfaz se encuentra en la clase FragmentMetadataVisitor de la Kinesis Video Stream Parser Library.

La clase FragmentMetadataVisitor contiene una implementación 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 clase KinesisVideoRendererExample contiene un ejemplo del uso de un BasicMkvTagProcessor. En el siguiente ejemplo, se añade un BasicMkvTagProcessor a los MediaProcessingArguments de una aplicación:

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

Se llama al método BasicMkvTagProcessor.process cuando llegan los metadatos del fragmento. Puede recuperar los metadatos acumulados con GetTags. Si desea recuperar un único elemento de metadatos, llame primero a clear para borrar los metadatos recopilados y, a continuación, recupere de nuevo los elementos de metadatos.

Limitaciones de los metadatos de streaming

Las siguientes limitaciones afectan a la adición de metadatos de streaming a una Transmisión de vídeo de Kinesis:

  • Puede anexar hasta 10 elementos de metadatos a un fragmento.

  • Un nombre de metadatos de fragmento puede tener hasta 128 bytes de longitud.

  • Un valor de metadatos de fragmento puede tener hasta 256 bytes de longitud.

  • Un nombre de metadatos de fragmento no puede empezar por la cadena "AWS". Si se añade este tipo de elemento de metadatos, el método putFragmentMetadata del PIC devuelve un error STATUS_INVALID_METADATA_NAME (código de error 0x52000077). La aplicación puede hacer caso omiso del error (el PIC no añade el elemento de metadatos) o responder a él.