GetHLSStreamingSessionURL

Recupera una transmisión HTTP en vivo (HLS) URL de la transmisión. A continuación, puede abrirla URL en un navegador o reproductor multimedia para ver el contenido de la transmisión.

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

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

• Requisitos de pista de reproducción de vídeo.

• 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 HEVC para el formato H.265 (especificación MPEG -4ISO/IEC14496-15). Para obtener información sobre cómo adaptar los datos de transmisión a un formato determinado, consulte Indicadores de adaptación. NAL

• La pista de audio (si está presente) de cada fragmento debe contener datos privados del códec en ese AAC formato (AACespecificaciónISO/IEC13818-7).

Las sesiones de Kinesis Video HLS Streams contienen fragmentos en forma -4 MPEG fragmentada (también denominada MP4 f CMAF o) o MPEG -2 (también denominada fragmentos TS, que también admite HLS la especificación). Para obtener más información sobre los tipos de HLS fragmentos, consulte la especificación. HLS

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

1. Llame al GetDataEndpoint API para obtener un punto final. A continuación, envíe las GetHLSStreamingSessionURL solicitudes a este punto final mediante el parámetro --endpoint-url.

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

   nota

   No compartas ni guardes este token 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 otros datos multimedia disponibles (como fotogramas fuera de la ventana solicitada o velocidades de bits alternativas).

3. Proporcione la lista de reproducción HLS maestra URL (que contiene el token de sesión cifrado) a un reproductor multimedia compatible con el HLS protocolo. Kinesis Video Streams hace que HLS la lista de reproducción multimedia, el fragmento de inicialización y los fragmentos multimedia estén disponibles a través de la lista de reproducción maestra. URL El fragmento de inicialización contiene los datos privados del códec de 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 formato H.264. AAC

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

   • Lista de etHLSMasterreproducción G: recupera una lista de reproducción HLS maestra, 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.

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

   • ObtenerMP4InitFragment: recupera el fragmento de MP4 inicialización. El reproductor multimedia suele cargar el fragmento de inicialización antes de cargar cualquier fragmento multimedia. Este fragmento contiene los átomos fytp «» y moov «» y los MP4 átomos secundarios necesarios para inicializar el decodificador del reproductor multimedia.

     El fragmento de inicialización no corresponde a 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.

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

     nota

     Los datos privados del códec (CPD) contenidos en cada fragmento contienen información de inicialización específica del códec, como la velocidad de fotogramas, la resolución y el perfil de codificación, que son necesarios para decodificar correctamente el fragmento. Tanto para TS como para los MP4 CPD cambios se admiten durante una sesión de streaming. Por lo tanto, los fragmentos de una sesión pueden contener una información diferente CPD sin interrumpir la reproducción. Para cada sesión de streaming, solo se permiten 500 CPD cambios.

     importante

     No se admiten los cambios de seguimiento. Las pistas deben permanecer consistentes en todo el contenido multimedia consultado. La transmisión fallará si los fragmentos de la transmisión pasan de tener solo vídeo a tener audio y vídeo, o si una pista de AAC audio pasa a ser una pista de audio A-Law.

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

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

     nota

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

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

No se URL debe compartir una sesión de streaming entre jugadores. El servicio puede limitar una sesión si varios reproductores multimedia la comparten. Para conocer los límites de conexión, consulte Cuotas de Kinesis Video Streams.

Puedes monitorizar la cantidad de datos que consume el reproductor multimedia supervisando la CloudWatch métrica de GetMP4MediaFragment.OutgoingBytes Amazon. Para obtener información sobre cómo CloudWatch monitorizar Kinesis Video Streams, consulte Supervisión de Kinesis Video Streams. Para obtener información sobre precios, consulte Precios AWS y precios de Amazon Kinesis Video Streams. Se aplican cargos tanto por HLS las sesiones como por AWS los datos salientes.

Consulte los ejemplos de reproducción de vídeo en la guía de documentación: Usa el AWS CLI para recuperar una sesión de HLS streaming URL yEjemplo: úsalo HLS en HTML y JavaScript.

Para obtener más informaciónHLS, consulte Transmisión HTTP en directo en el sitio para desarrolladores de Apple.

importante

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

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

• x-amz-RequestIdHTTPencabezado: si desea informar de un problema AWS, el equipo de soporte puede diagnosticar mejor el problema si se le proporciona el identificador de solicitud.

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

Para obtener más información, consulte la sección de errores al final de este tema, así como la sección 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"
}

URIParámetros de solicitud

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

Cuerpo de la solicitud

La solicitud acepta los siguientes datos en JSON formato.

ContainerFormat

Especifica el formato que se debe utilizar para empaquetar los medios. Al especificar el formato del FRAGMENTED_MP4 contenedor, se empaquetan los medios en MP4 fragmentos (f MP4 oCMAF). Este es el embalaje recomendado porque los gastos generales de embalaje son mínimos. La otra opción de formato de contenedor esMPEG_TS. HLSha sido compatible con fragmentos de MPEG TS desde su lanzamiento y, a veces, es el único paquete compatible con HLS los reproductores más antiguos. MPEGPor lo general, TS tiene un coste de embalaje del 5 al 25 por ciento. Esto significa que, por lo general, MPEG TS requiere entre un 5 y un 25 por ciento más de ancho de banda y un costo que f. MP4

El valor predeterminado es FRAGMENTED_MP4.

Tipo: cadena

Valores válidos: FRAGMENTED_MP4 | MPEG_TS

Obligatorio: no

DiscontinuityMode

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

Los reproductores multimedia suelen crear una cronología del contenido multimedia que se va a reproducir, en función de las marcas temporales de cada fragmento. Esto significa que, si hay algún solapamiento o espacio entre los fragmentos (como es habitual si HLSFragmentSelector está configurado de esta formaSERVER_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 línea temporal del reproductor multimedia pueden provocar que la reproducción se detenga y las superposiciones pueden provocar que la reproducción sea inestable. Cuando hay indicadores de discontinuidad entre los fragmentos, se espera que el reproductor multimedia restablezca la línea temporal y, por lo tanto, 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 HLS multimedia. Se recomienda utilizar un valor de ALWAYS si las marcas de tiempo de los fragmentos no son precisas.

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

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

El valor predeterminado HLSFragmentSelector es ALWAYS cuando está configurado SERVER_TIMESTAMP en y NEVER cuando está configurado enPRODUCER_TIMESTAMP.

Tipo: cadena

Valores válidos: ALWAYS | NEVER | ON_DISCONTINUITY

Obligatorio: no

DisplayFragmentTimestamp

Especifica cuándo deben incluirse las marcas horarias de inicio del fragmento en la lista de reproducción HLS multimedia. 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 HLS multimedia, algunos reproductores multimedia pueden indicar el cabezal de reproducción actual como una hora absoluta en función de las marcas de tiempo del fragmento. Esto puede resultar útil para crear una experiencia de reproducción que muestre a los espectadores la hora exacta del contenido multimedia en un reloj de pared.

El valor predeterminado es NEVER. Si HLSFragmentSelector es asíSERVER_TIMESTAMP, las marcas horarias serán las marcas horarias de inicio del servidor. Del mismo modo, cuando HLSFragmentSelector esPRODUCER_TIMESTAMP, las marcas de tiempo serán las marcas de tiempo de inicio del productor.

Tipo: cadena

Valores válidos: ALWAYS | NEVER

Obligatorio: no

Expires

El tiempo en segundos que falta para que caduque la sesión solicitada. Este valor puede estar 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 43 200.

Obligatorio: no

HLSFragmentSelector

El intervalo de tiempo del fragmento solicitado y el origen de las marcas de tiempo.

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

Tipo: objeto HLSFragmentSelector

Obligatorio: no

MaxMediaPlaylistFragmentResults

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

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

Cuando hay un número mayor de fragmentos disponibles en una lista de reproducción HLS multimedia en directo, los reproductores de vídeo suelen almacenar el contenido en búfer antes de iniciar la reproducción. Si se aumenta el tamaño del búfer, se aumenta la latencia de reproducción, pero se reduce la probabilidad de que se vuelva a almacenar en búfer durante la reproducción. Recomendamos que una lista de reproducción HLS multimedia en directo tenga un mínimo de 3 fragmentos y un máximo de 10 fragmentos.

El valor predeterminado es de 5 fragmentos si PlaybackMode es LIVE o LIVE_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 las transmisiones con fragmentos de 1 segundo y a más de 13 horas de vídeo en las 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, reproducirlos en directo o archivados bajo demanda.

Entre las características de los tres tipos de sesiones se incluyen las siguientes:

• LIVE: En las sesiones de este tipo, la lista de reproducción HLS multimedia se actualiza continuamente con los fragmentos más recientes a medida que están disponibles. Se recomienda que el reproductor multimedia recupere una nueva lista de reproducción en un intervalo de un segundo. Cuando se reproduce este tipo de sesión en un reproductor multimedia, la interfaz de usuario suele mostrar una notificación «en directo», sin necesidad de controlar el deslizador para seleccionar la posición en la ventana de reproducción en la que desea visualizarla.

  nota

  En el LIVE modo, los fragmentos más recientes disponibles se incluyen en una lista de reproducción HLS multimedia, incluso si hay un espacio entre los fragmentos (es decir, si falta un fragmento). Un espacio como este puede provocar que el reproductor multimedia se detenga o que se interrumpa la reproducción. En este modo, los fragmentos no se añaden a la lista de reproducción HLS multimedia 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 otro fragmento a la lista de reproducción, el fragmento más antiguo no se añade y el espacio no se rellena.

• LIVE_REPLAY: en las sesiones de este tipo, la lista de reproducción HLS multimedia se actualiza de forma similar a como se actualiza para el LIVE modo, con la salvedad de 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 resulta útil para poder iniciar la reproducción desde el momento en que se detecta un evento y continuar retransmitiendo 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 establecido en el ON_DEMAND modo.

• ON_DEMAND: Para sesiones de este tipo, la lista de reproducción HLS multimedia 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 de barra para seleccionar la posición de la ventana de reproducción que se va a mostrar.

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 HLS lista de reproducción multimedia. Los demás fragmentos no están incluidos. Los fragmentos que tienen marcas de tiempo diferentes pero que tienen duraciones superpuestas se siguen incluyendo en la HLS lista de reproducción multimedia. Esto puede provocar un comportamiento inesperado en el reproductor multimedia.

El valor predeterminado es LIVE.

Tipo: cadena

Valores válidos: LIVE | LIVE_REPLAY | ON_DEMAND

Obligatorio: no

StreamARN

El nombre del recurso de Amazon (ARN) de la transmisión de la que se va a recuperar la lista de reproducción HLS maestraURL.

Debe especificar el StreamName o elStreamARN.

Tipo: cadena

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 transmisión de la que se va a recuperar la lista de reproducción HLS maestraURL.

Debe especificar el StreamName o elStreamARN.

Tipo: cadena

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 de HTTP 200.

El servicio devuelve los siguientes datos en JSON formato.

HLSStreamingSessionURL

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

Tipo: cadena

Errores

Para obtener información acerca de los errores comunes a todas las acciones, consulte Errores comunes.

ClientLimitExceededException

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

HTTPCódigo de estado: 400

InvalidArgumentException

Un parámetro específico supera sus restricciones, no se admite o no se puede usar.

HTTPCódigo de estado: 400

InvalidCodecPrivateDataException

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

HTTPCódigo de estado: 400

MissingCodecPrivateDataException

No se encontraron datos privados del códec en al menos una de las pistas de la transmisión de vídeo.

HTTPCódigo de estado: 400

NoDataRetentionException

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

HTTPCódigo de estado: 400

NotAuthorizedException

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

HTTPCódigo de estado: 401

ResourceNotFoundException

GetImagesmostrará este error cuando Kinesis Video Streams no encuentre la transmisión que ha especificado.

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

HTTPCódigo de estado: 404

UnsupportedStreamMediaTypeException

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

HTTPCódigo de estado: 400

Véase también

Para obtener más información sobre cómo usarlo API en uno de los idiomas específicos AWS SDKs, consulte lo siguiente:

• Interfaz de la línea de comandos de AWS

• AWS SDKpara. NET

• AWS SDKpara C++

• AWS SDKpara Go v2

• AWS SDKpara Java V2

• AWS SDKpara JavaScript V3

• AWS SDKpara PHP V3

• AWS SDKpara Python

• AWS SDKpara Ruby V3