GetHLSStreamingSessionURL

Recupera una URL HTTP Live Streaming (HLS) de transmisión. A continuación, puede abrir la URL en un navegador o 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 HLS:

• Para la transmisión de vídeo, el soporte debe contener vídeo codificado en H.264 o H.265 y, opcionalmente, audio codificado en AAC. Específicamente, el ID de códec de la pista 1 debe ser V_MPEG/ISO/AVC (para H.264) o V_MPEG/ISO/HEVC (para H.265). De manera opcional, el ID del códec de la pista 2 debe ser. A_AAC Para la transmisión solo de audio, el ID del códec de la pista 1 debe serA_AAC.

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

• La pista de vídeo de cada fragmento debe contener datos privados del códec en la codificación de vídeo avanzada (AVC) para el formato H.264 o en HEVC para el formato H.265 (especificación MPEG-4 ISO/IEC 14496-15). 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 está presente) de cada fragmento debe contener datos privados del códec en formato AAC (especificación AAC ISO/IEC 13818-7).

Las sesiones HLS de Kinesis Video Streams contienen fragmentos en formato MPEG-4 fragmentado (también denominado fMP4 o CMAF) o en formato MPEG-2 (también denominados fragmentos TS, que también admite la especificación HLS). Para obtener más información sobre los tipos de fragmentos de HLS, consulte la especificación HLS.

El siguiente procedimiento muestra cómo usar HLS con Kinesis Video Streams:

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

2. Recupere la URL de HLS medianteGetHLSStreamingSessionURL. Kinesis Video Streams crea una sesión de transmisión HLS que se utiliza para acceder al contenido de una transmisión mediante el protocolo HLS. GetHLSStreamingSessionURLdevuelve una URL autenticada (que incluye un token de sesión cifrado) para la lista de reproducción maestra de HLS de la sesión (el recurso raíz necesario para la transmisión con HLS).

   nota

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

   El contenido multimedia que está disponible a través de la lista de reproducción 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) de la lista de reproducción maestra de HLS a un reproductor multimedia que admita el protocolo HLS. Kinesis Video Streams hace que la lista de reproducción multimedia, el fragmento de inicialización y los fragmentos multimedia de HLS estén disponibles a través de la URL de la lista de reproducción maestra. 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 fotogramas de vídeo codificados en H.264 o muestras de audio codificadas en AAC.

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:

   • getHLSMasterPlaylist: recupera una lista de reproducción maestra de HLS, que contiene una URL para la GetHLSMediaPlaylist acción de cada pista y metadatos adicionales para el reproductor multimedia, incluida la velocidad de bits y la resolución estimadas.

   • getHLSMediaPlaylist: recupera una lista de reproducción multimedia de HLS, que contiene una URL para acceder al fragmento de inicialización de MP4 con la GetMP4InitFragment acción y URL para acceder a los fragmentos multimedia MP4 con las acciones. GetMP4MediaFragment La lista de reproducción multimedia de HLS también contiene metadatos sobre la transmisión que el reproductor necesita para reproducirla, por ejemplo, si PlaybackMode es LIVE oON_DEMAND. La lista de reproducción multimedia de HLS suele ser estática para las sesiones con un PlaybackType deON_DEMAND. La lista de reproducción multimedia de HLS se actualiza continuamente con nuevos fragmentos para las sesiones con un PlaybackType deLIVE. Hay una lista de reproducción multimedia HLS distinta para la pista de vídeo y la pista de audio (si corresponde) que contiene las URL multimedia MP4 de la pista específica.

   • 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

     Para la sesión de transmisión de HLS, se admiten los cambios de datos privados (CPD) del códec durante la pista. Una vez que el primer fragmento multimedia esté disponible en una sesión de streaming, los fragmentos pueden contener cambios de CPD para cada pista. Por lo tanto, los fragmentos de una sesión pueden tener una resolución, velocidad de bits u otra información diferente en el CPD sin interrumpir la reproducción. Sin embargo, cualquier cambio realizado en el número de pista o en el formato del códec de la pista puede generar un error cuando se carguen esos diferentes fragmentos multimedia. Por ejemplo, la transmisión fallará si los fragmentos de la transmisión pasan de tener solo vídeo a tener tanto audio como vídeo, o si una pista de audio AAC se cambia a una pista de audio ALAW. Para cada sesión de streaming, solo se permiten 500 cambios de CPD.

     Los datos recuperados con esta acción son facturables. Para obtener información, consulte Precios de .

   • GetTSFragment: recupera fragmentos de MPEG TS que contienen datos de inicialización y multimedia de todas las pistas de la transmisión.

     nota

     Si ContainerFormat es asíMPEG_TS, esta API se usa en lugar de GetMP4InitFragment y GetMP4MediaFragment para recuperar contenido multimedia de transmisión.

     Los datos recuperados con esta acción son facturables. Para obtener más información, consulte los Precios de Kinesis Video Streams.

Los jugadores no deben compartir la URL de una sesión de streaming. El servicio puede ralentizar una sesión si varios reproductores multimedia la comparten. Para conocer los límites de conexión, consulte los límites 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 quieres informar de un problemaAWS, el equipo de soporte puede diagnosticar mejor el problema si se le proporciona el identificador 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 /getHLSStreamingSessionURL HTTP/1.1
Content-type: application/json

{
   "ContainerFormat": "string",
   "DiscontinuityMode": "string",
   "DisplayFragmentTimestamp": "string",
   "Expires": number,
   "HLSFragmentSelector": { 
      "FragmentSelectorType": "string",
      "TimestampRange": { 
         "EndTimestamp": number,
         "StartTimestamp": number
      }
   },
   "MaxMediaPlaylistFragmentResults": 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.

ContainerFormat

Especifica el formato que se debe utilizar para empaquetar los medios. Al especificar el formato del FRAGMENTED_MP4 contenedor, se empaqueta el contenido multimedia en fragmentos MP4 (fMP4 o CMAF). Este es el embalaje recomendado porque los gastos de embalaje son mínimos. La otra opción de formato de contenedor esMPEG_TS. HLS admite fragmentos de MPEG TS desde su lanzamiento y, a veces, es el único paquete compatible con los reproductores HLS más antiguos. El MPEG TS normalmente tiene una sobrecarga de empaquetado del 5 al 25 por ciento. Esto significa que MPEG TS normalmente requiere entre un 5 y un 25 por ciento más de ancho de banda y coste que FMP4.

El valor predeterminado es FRAGMENTED_MP4.

Tipo: String

Valores válidos: FRAGMENTED_MP4 | MPEG_TS

Obligatorio: no

DiscontinuityMode

Especifica cuándo se añaden a las listas de reproducción multimedia las marcas que marcan las discontinuidades entre fragmentos.

Los reproductores multimedia suelen crear una cronología del contenido multimedia para reproducirlo, en función de las marcas de tiempo de cada fragmento. Esto significa que si hay alguna superposición o espacio entre los fragmentos (como es habitual si HLSFragmentSelector se establece asíSERVER_TIMESTAMP), la línea temporal del reproductor multimedia también tendrá pequeños espacios entre los fragmentos en algunos lugares y sobrescribirá los fotogramas en otros lugares. Los huecos en la cronología del reproductor multimedia pueden provocar que la reproducción se detenga y las superposiciones pueden provocar fluctuaciones en la reproducción. Cuando hay marcas de discontinuidad entre los fragmentos, se espera que el reproductor multimedia restablezca la línea temporal, lo que hará que el siguiente fragmento se reproduzca inmediatamente después del fragmento anterior.

Se admiten los siguientes modos:

• ALWAYS: se coloca un marcador de discontinuidad entre cada fragmento de la lista de reproducción multimedia del HLS. Se recomienda utilizar un valor de ALWAYS si las marcas de tiempo de los fragmentos no son precisas.

• NEVER: no hay marcadores de discontinuidad en ninguna parte. Se recomienda utilizar un valor de NEVER para garantizar que la cronología del reproductor multimedia se corresponda con la mayor precisión posible con las marcas de tiempo del productor.

• ON_DISCONTINUITY: se coloca un marcador de discontinuidad entre los fragmentos que tienen un espacio o superposición de más de 50 milisegundos. Para la mayoría de los escenarios de reproducción, se recomienda utilizar un valor de para ON_DISCONTINUITY que la cronología del reproductor multimedia solo se restablezca cuando haya un problema importante con la cronología multimedia (por ejemplo, falta un fragmento).

El valor predeterminado HLSFragmentSelector es ALWAYS cuándo se SERVER_TIMESTAMP establece en y NEVER cuándo se establece enPRODUCER_TIMESTAMP.

Tipo: String

Valores válidos: ALWAYS | NEVER | ON_DISCONTINUITY

Obligatorio: no

DisplayFragmentTimestamp

Especifica cuándo deben incluirse las marcas de tiempo de inicio de los fragmentos en la lista de reproducción multimedia de HLS. Normalmente, los reproductores multimedia indican la posición del cabezal de reproducción como un tiempo relativo al inicio del primer fragmento de la sesión de reproducción. Sin embargo, cuando las marcas de tiempo de inicio se incluyen en la lista de reproducción multimedia de HLS, algunos reproductores multimedia pueden indicar el tiempo de reproducción actual como una hora absoluta en función de las marcas de tiempo de los fragmentos. Esto puede resultar útil para crear una experiencia de reproducción que muestre a los espectadores la hora del contenido multimedia en el reloj de pared.

El valor predeterminado es NEVER. Cuando HLSFragmentSelector sea asíSERVER_TIMESTAMP, las marcas de tiempo serán las marcas de tiempo de inicio del servidor. Del mismo modo, cuando HLSFragmentSelector 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 GetHLSMasterPlaylistGetHLSMediaPlaylist,GetMP4InitFragment,GetMP4MediaFragment, ni se GetTSFragment pueden realizar nuevas llamadas para esa sesión.

El valor predeterminado es 300 (5 minutos).

Tipo: entero

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

Obligatorio: no

HLSFragmentSelector

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 HLSFragmentSelector

Obligatorio: no

MaxMediaPlaylistFragmentResults

El número máximo de fragmentos que se devuelven en las listas de reproducción multimedia de HLS.

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 una lista de reproducción multimedia de HLS 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 una lista de reproducción multimedia de HLS en vivo 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 5000 fragmentos corresponde a más de 80 minutos de vídeo en transmisiones con fragmentos de 1 segundo y a más de 13 horas 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, la lista de reproducción multimedia de HLS se actualiza continuamente con los fragmentos más recientes a medida que están disponibles. Recomendamos que el reproductor multimedia recupere una nueva lista de reproducción 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 una lista de reproducción multimedia de HLS, 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 a la lista de reproducción multimedia de HLS 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 a la lista de reproducción, el fragmento más antiguo no se añade y el espacio no se llena.

• LIVE_REPLAY: Para las sesiones de este tipo, la lista de reproducción multimedia de HLS se actualiza de forma similar a como se actualiza para LIVE el 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 a la lista de reproducción multimedia 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, la lista de reproducción multimedia de HLS contiene todos los fragmentos de la sesión, hasta el número especificado enMaxMediaPlaylistFragmentResults. La lista de reproducción solo se debe recuperar una vez por 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 la lista de reproducción multimedia de HLS. Los otros fragmentos no están incluidos. Los fragmentos que tienen marcas de tiempo diferentes pero que tienen duraciones superpuestas se siguen incluyendo en la lista de reproducción multimedia de HLS. 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 transmisión para el que se recuperará la URL de lista de reproducción maestra de HLS.

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 transmisión para la que se recuperará la URL de lista de reproducción maestra de HLS.

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

{
   "HLSStreamingSessionURL": "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.

HLSStreamingSessionURL

La URL (que contiene el token de sesión) que un reproductor multimedia puede utilizar para recuperar la lista de reproducción maestra de HLS.

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