GetDASHStreamingSessionURL

Recupera una URL de MPEG Dynamic Adaptive Streaming a través de HTTP (DASH) de flujo. A continuación, puede abrir la URL en un reproductor multimedia para ver el contenido de la transmisión.

StreamNameTanto los parámetros como los StreamARN parámetros son opcionales, pero debe especificar el StreamName o el StreamARN al invocar esta operación de API.

Una transmisión de vídeo de Amazon Kinesis tiene los siguientes requisitos para proporcionar datos a través de MPEG-DASH:

• Los medios deben contener vídeo codificado h.264 o h.265 y, si lo desea, audio codificado AAC o G.711. En concreto, el ID del códec de la pista 1 debe ser V_MPEG/ISO/AVC (para h.264) o V_MPEGH/ISO/HEVC (H.265). Si lo desea, el ID del códec de la pista 2 debe ser A_AAC (para AAC) o A_MS/ACM (para G.711).

• La retención de datos debe ser mayor o igual que 0.

• La pista de vídeo de cada fragmento debe contener los datos privados del códec en la codificación de vídeo avanzada (AVC) para el formato H.264 y en HEVC para el formato H.265. Para obtener más información, consulte la especificación especificación ISO/IEC 14496-15 para MPEG. Si desea obtener más información sobre cómo adaptar datos de transmisiones a un determinado formato, consulte Referencia de marcas de adaptación de capa de abstracción de red (NAL).

• La pista de audio (si la hay) de cada fragmento debe contener los datos privados del códec en formato AAC (especificación ISO/IEC 13818-7 para AAC) o en formato MS Wave.

En el siguiente procedimiento se muestra cómo usar MPEG-DASH con Kinesis Video Streams:

1. Obtenga un punto final utilizando GetDataEndpoint, especificando GET_DASH_STREAMING_SESSION_URL el APIName parámetro.

2. Recupera la URL de MPEG-DASH usando. GetDASHStreamingSessionURL Kinesis Video Streams crea una sesión de transmisión MPEG-DASH que se utiliza para acceder al contenido de una transmisión mediante el protocolo MPEG-DASH. GetDASHStreamingSessionURLdevuelve una URL autenticada (que incluye un token de sesión cifrado) para el manifiesto MPEG-DASH de la sesión (el recurso raíz necesario para la transmisión con MPEG-DASH).

   nota

   No compartas ni guardes este token en un lugar donde pueda acceder a él una entidad no autorizada. El token proporciona acceso al contenido de la transmisión. Proteja el token con las mismas medidas que utiliza con sus AWS credenciales.

   El contenido multimedia que está disponible a través del manifiesto consiste únicamente en la transmisión, el intervalo de tiempo y el formato solicitados. No hay disponible ningún otro dato multimedia (como fotogramas fuera de la ventana solicitada o velocidades de bits alternativas).

3. Proporcione la URL (que contiene el token de sesión cifrado) del manifiesto MPEG-DASH a un reproductor multimedia que admita el protocolo MPEG-DASH. Kinesis Video Streams hace que el fragmento de inicialización y los fragmentos multimedia estén disponibles a través de la URL del manifiesto. El fragmento de inicialización contiene los datos privados del códec para la transmisión y otros datos necesarios para configurar el decodificador y el renderizador de vídeo o audio. Los fragmentos multimedia contienen cuadros de vídeo codificados o muestras de audio codificadas.

4. El reproductor multimedia recibe la URL autenticada y solicita los metadatos y los datos multimedia de la transmisión con normalidad. Cuando el reproductor multimedia solicita datos, ejecuta las siguientes acciones:

   • GetDashManifest: recupera un manifiesto DASH de MPEG, que contiene los metadatos del contenido multimedia que desea reproducir.

   • getMP4InitFragment: recupera el fragmento de inicialización de MP4. El reproductor multimedia normalmente carga el fragmento de inicialización antes de cargar cualquier fragmento multimedia. Este fragmento contiene los átomos MP4 fytp «» y moov «» y los átomos secundarios que se necesitan para inicializar el decodificador del reproductor multimedia.

     El fragmento de inicialización no se corresponde con un fragmento de una transmisión de vídeo de Kinesis. Contiene solo los datos privados del códec para la transmisión y la pista correspondiente, que el reproductor multimedia necesita para decodificar los fotogramas multimedia.

   • GetMP4MediaFragment: recupera fragmentos multimedia MP4. Estos fragmentos contienen los átomos MP4 moof «» y «mdat» y sus átomos secundarios, y contienen los fotogramas multimedia del fragmento codificado y sus marcas de tiempo.

     nota

     Una vez que el primer fragmento multimedia esté disponible en una sesión de streaming, cualquier fragmento que no contenga los mismos datos privados del códec generará un error cuando se carguen esos diferentes fragmentos multimedia. Por lo tanto, los datos privados del códec no deberían cambiar entre los fragmentos de una sesión. Esto también significa que la sesión falla si los fragmentos de una transmisión pasan de tener solo vídeo a tener audio y vídeo.

     Los datos recuperados con esta acción son facturables. Consulte los precios para obtener más información.

nota

Para conocer las restricciones que se aplican a las sesiones MPEG-DASH, consulte los límites de transmisión de Kinesis Video Streams.

Puede supervisar la cantidad de datos que consume el reproductor multimedia mediante la supervisión de la CloudWatch métrica de GetMP4MediaFragment.OutgoingBytes Amazon. Para obtener información sobre el uso CloudWatch para monitorear las Kinesis Video Streams, consulte Monitorear Kinesis Video Streams. Para obtener información sobre precios, consulte Precios y AWSprecios de Amazon Kinesis Video Streams. Se aplican cargos tanto por las sesiones de HLS como por AWS los datos salientes.

Para obtener más información sobre HLS, consulte HTTP Live Streaming en el sitio para desarrolladores de Apple.

importante

Si se produce un error después de invocar una API multimedia archivada de Kinesis Video Streams, además del código de estado HTTP y el cuerpo de la respuesta, se incluye la siguiente información:

• x-amz-ErrorTypeEncabezado HTTP: contiene un tipo de error más específico, además del que proporciona el código de estado HTTP.

• x-amz-RequestIdEncabezado HTTP: si desea informar de un problema al AWS equipo de soporte, puede diagnosticar mejor el problema si se le proporciona el ID de la solicitud.

Tanto el código de estado HTTP como el ErrorType encabezado se pueden utilizar para tomar decisiones programáticas sobre si los errores se pueden corregir y en qué condiciones, así como para proporcionar información sobre las acciones que el programador del cliente podría necesitar tomar para volver a intentarlo correctamente.

Para obtener más información, consulte la sección Errores al final de este tema, así como los errores comunes.

Sintaxis de la solicitud

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

{
   "DASHFragmentSelector": { 
      "FragmentSelectorType": "string",
      "TimestampRange": { 
         "EndTimestamp": number,
         "StartTimestamp": number
      }
   },
   "DisplayFragmentNumber": "string",
   "DisplayFragmentTimestamp": "string",
   "Expires": number,
   "MaxManifestFragmentResults": number,
   "PlaybackMode": "string",
   "StreamARN": "string",
   "StreamName": "string"
}

Parámetros de solicitud del URI

La solicitud no utiliza ningún parámetro de URI.

Cuerpo de la solicitud

La solicitud acepta los siguientes datos en formato JSON.

DASHFragmentSelector

El intervalo de tiempo del fragmento solicitado y la fuente de las marcas de tiempo.

Este parámetro es obligatorio si PlaybackMode es ON_DEMAND oLIVE_REPLAY. Este parámetro es opcional si lo PlaybackMode es LIVE. Si PlaybackMode es LIVE así, se FragmentSelectorType puede configurar, pero no se TimestampRange debe configurar. Si PlaybackMode es ON_DEMAND oLIVE_REPLAY, se TimestampRange deben configurar ambos FragmentSelectorType y.

Tipo: objeto DASHFragmentSelector

Obligatorio: no

DisplayFragmentNumber

Los fragmentos se identifican en el archivo de manifiesto en función de su número de secuencia en la sesión. Si DisplayFragmentNumber se establece enALWAYS, el número de fragmento de Kinesis Video Streams se añade a cada elemento S del archivo de manifiesto con el nombre de atributo «kvs:fn». Estos números de fragmentos se pueden usar para el registro o para usarse con otras API (por ejemplo, GetMedia yGetMediaForFragmentList). Se necesita un reproductor multimedia MPEG-DASH personalizado para aprovechar este atributo personalizado.

El valor predeterminado es NEVER.

Tipo: String

Valores válidos: ALWAYS | NEVER

Obligatorio: no

DisplayFragmentTimestamp

Según la especificación MPEG-DASH, la hora del reloj de pared de los fragmentos del archivo de manifiesto se puede obtener mediante los atributos del propio manifiesto. Sin embargo, por lo general, los reproductores multimedia compatibles con MPEG-DASH no gestionan adecuadamente las brechas en la cronología multimedia. Kinesis Video Streams ajusta la cronología multimedia del archivo de manifiesto para permitir la reproducción de contenido multimedia con discontinuidades. Por lo tanto, la hora del reloj de pared derivada del archivo de manifiesto puede ser inexacta. Si DisplayFragmentTimestamp se establece enALWAYS, la marca de tiempo exacta del fragmento se añade a cada elemento S del archivo de manifiesto con el nombre de atributo «kvs:ts». Se necesita un reproductor multimedia MPEG-DASH personalizado para aprovechar este atributo personalizado.

El valor predeterminado es NEVER. Cuando DASHFragmentSelector sea asíSERVER_TIMESTAMP, las marcas de tiempo serán las marcas de tiempo de inicio del servidor. Del mismo modo, cuando DASHFragmentSelector seaPRODUCER_TIMESTAMP, las marcas de tiempo serán las marcas de tiempo de inicio del productor.

Tipo: String

Valores válidos: ALWAYS | NEVER

Obligatorio: no

Expires

El tiempo en segundos hasta que caduque la sesión solicitada. Este valor puede estar comprendido entre 300 (5 minutos) y 43200 (12 horas).

Cuando una sesión caduca, no se pueden realizar nuevas llamadas a GetDashManifest esa sesión ni se GetMP4MediaFragment pueden realizar para ella. GetMP4InitFragment

El valor predeterminado es 300 (5 minutos).

Tipo: entero

Rango válido: valor mínimo de 300. Valor máximo de 43200.

Obligatorio: no

MaxManifestFragmentResults

El número máximo de fragmentos que se devuelven en el manifiesto MPEG-DASH.

Cuando PlaybackMode esLIVE, los fragmentos más recientes se devuelven hasta este valor. Cuando el PlaybackMode esON_DEMAND, se devuelven los fragmentos más antiguos, hasta este número máximo.

Cuando hay un mayor número de fragmentos disponibles en un manifiesto MPEG-DASH en vivo, los reproductores de vídeo suelen almacenar el contenido en búfer antes de iniciar la reproducción. Al aumentar el tamaño del búfer, se aumenta la latencia de reproducción, pero se reduce la probabilidad de que se produzca un realmacenamiento en búfer durante la reproducción. Recomendamos que un manifiesto MPEG-DASH activo tenga un mínimo de 3 fragmentos y un máximo de 10 fragmentos.

El valor predeterminado es 5 fragmentos si PlaybackMode es LIVE oLIVE_REPLAY, y 1000 si PlaybackMode esON_DEMAND.

El valor máximo de 1000 fragmentos corresponde a más de 16 minutos de vídeo en transmisiones con fragmentos de 1 segundo y a más de 2 horas y media de vídeo en transmisiones con fragmentos de 10 segundos.

Tipo: largo

Rango válido: valor mínimo de 1. Valor máximo de 5000.

Obligatorio: no

PlaybackMode

Ya sea para recuperar datos en directo, reproducidos en directo o archivados bajo demanda.

Las características de los tres tipos de sesiones son las siguientes:

• LIVE: Para las sesiones de este tipo, el manifiesto MPEG-DASH se actualiza continuamente con los fragmentos más recientes a medida que están disponibles. Recomendamos que el reproductor multimedia recupere un manifiesto nuevo en un intervalo de un segundo. Cuando este tipo de sesión se reproduce en un reproductor multimedia, la interfaz de usuario suele mostrar una notificación «en vivo», sin ningún control de depuración para elegir la posición en la ventana de reproducción que se va a mostrar.

  nota

  En el LIVE modo, los fragmentos más recientes disponibles se incluyen en un manifiesto MPEG-DASH, incluso si hay un espacio entre los fragmentos (es decir, si falta un fragmento). Un intervalo como este puede provocar que el reproductor multimedia se detenga o que la reproducción se interrumpa. En este modo, los fragmentos no se añaden al manifiesto MPEG-DASH si son más antiguos que el fragmento más reciente de la lista de reproducción. Si el fragmento que falta pasa a estar disponible después de añadir un fragmento posterior al manifiesto, el fragmento más antiguo no se añade y el espacio no se llena.

• LIVE_REPLAY: Para las sesiones de este tipo, el manifiesto MPEG-DASH se actualiza de forma similar a como se actualiza para el LIVE modo, excepto que comienza por incluir fragmentos de una hora de inicio determinada. En lugar de añadir fragmentos a medida que se ingieren, los fragmentos se añaden a medida que transcurre la duración del siguiente fragmento. Por ejemplo, si los fragmentos de la sesión duran dos segundos, se añade un fragmento nuevo al manifiesto cada dos segundos. Este modo es útil para poder iniciar la reproducción desde el momento en que se detecta un evento y continuar transmitiendo en directo contenido multimedia que aún no se haya ingerido en el momento de la creación de la sesión. Este modo también es útil para transmitir contenido multimedia previamente archivado sin estar limitado por el límite de 1000 fragmentos del ON_DEMAND modo.

• ON_DEMAND: Para las sesiones de este tipo, el manifiesto MPEG-DASH contiene todos los fragmentos de la sesión, hasta el número especificado en. MaxManifestFragmentResults El manifiesto se debe recuperar solo una vez para cada sesión. Cuando este tipo de sesión se reproduce en un reproductor multimedia, la interfaz de usuario suele mostrar un control depurador para elegir la posición que se mostrará en la ventana de reproducción.

En todos los modos de reproducción, si FragmentSelectorType es PRODUCER_TIMESTAMP así, y si hay varios fragmentos con la misma marca de tiempo de inicio, el fragmento que tenga el mayor número de fragmentos (es decir, el fragmento más reciente) se incluye en el manifiesto MPEG-DASH. Los otros fragmentos no están incluidos. Los fragmentos que tienen diferentes marcas de tiempo pero que tienen duraciones superpuestas se siguen incluyendo en el manifiesto MPEG-DASH. Esto puede provocar un comportamiento inesperado en el reproductor multimedia.

El valor predeterminado es LIVE.

Tipo: String

Valores válidos: LIVE | LIVE_REPLAY | ON_DEMAND

Obligatorio: no

StreamARN

El nombre de recurso de Amazon (ARN) de la que se recuperará la URL del manifiesto de MPEG-DASH.

Debe especificar el StreamName o elStreamARN.

Tipo: String

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 1024 caracteres.

Patrón: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

Obligatorio: no

StreamName

El nombre de la secuencia para la que se recuperará la URL del manifiesto de MPEG-DASH.

Debe especificar el StreamName o elStreamARN.

Tipo: String

Limitaciones de longitud: longitud mínima de 1. La longitud máxima es de 256 caracteres.

Patrón: [a-zA-Z0-9_.-]+

Obligatorio: no

Sintaxis de la respuesta

HTTP/1.1 200
Content-type: application/json

{
   "DASHStreamingSessionURL": "string"
}

Elementos de respuesta

Si la acción se realiza correctamente, el servicio devuelve una respuesta HTTP 200.

El servicio devuelve los datos siguientes en formato JSON.

DASHStreamingSessionURL

La URL (que contiene el token de sesión) que un reproductor multimedia puede usar para recuperar el manifiesto MPEG-DASH.

Tipo: String

Errores

Para obtener información sobre los errores comunes a todas las acciones, consulteErrores comunes.

ClientLimitExceededException

Kinesis Video Streams ha limitado la solicitud porque ha superado un límite. Intenta hacer la llamada más tarde. Para obtener información acerca de los límites, consulte los límites de Kinesis Video Streams.

Código de estado HTTP: 400

InvalidArgumentException

Un parámetro especificado supera sus restricciones, no se admite o no se puede utilizar.

Código de estado HTTP: 400

InvalidCodecPrivateDataException

Los datos privados del códec en al menos una de las pistas de la transmisión de vídeo no son válidos para esta operación.

Código de estado HTTP: 400

MissingCodecPrivateDataException

No se encontró ningún dato privado del códec en al menos una de las pistas de la transmisión de vídeo.

Código de estado HTTP: 400

NoDataRetentionException

Se solicitó una sesión de transmisión para una transmisión que no retiene datos (es decir, tiene un valor DataRetentionInHours de 0).

Código de estado HTTP: 400

NotAuthorizedException

Código de estado: 403, la persona que llama no está autorizada a realizar una operación en la transmisión dada o el token ha caducado.

Código de estado HTTP: 401

ResourceNotFoundException

GetImagesgenerará este error cuando Kinesis Video Streams no pueda encontrar la transmisión que especificó.

GetHLSStreamingSessionURLy GetDASHStreamingSessionURL genera este error si LIVE_REPLAY se solicita una sesión con un PlaybackMode de ON_DEMAND o para una transmisión que no tiene fragmentos dentro del intervalo de tiempo solicitado, o si LIVE se solicita una sesión con un PlaybackMode de para una transmisión que no tiene fragmentos en los últimos 30 segundos.

Código de estado HTTP: 404

UnsupportedStreamMediaTypeException

El tipo de soporte (por ejemplo, vídeo h.264 o h.265 o audio ACC o G.711) no se pudo determinar a partir de los identificadores de códec de las pistas del primer fragmento de una sesión de reproducción. El ID de códec de la pista 1 debe ser V_MPEG/ISO/AVC y, opcionalmente, el ID de códec de la pista 2 debe serlo. A_AAC

Código de estado HTTP: 400

Véase también

Para obtener más información sobre el uso de esta API en un SDK de AWS de un lenguaje específico, consulte:

• AWS Command Line Interface

• SDK de AWS para .NET

• AWS SDK para C++

• AWS SDK para Go

• AWS SDK para Java V2

• AWSSDK para JavaScript

• SDK de AWS para PHP V3

• SDK de AWS para Python

• SDK de AWS para Ruby V3