GetHLSStreamingSessionURL

Récupère une URL HTTP Live Streaming (HLS) pour le flux. Vous pouvez ensuite ouvrir l'URL dans un navigateur ou un lecteur multimédia pour afficher le contenu du flux.

Les StreamARN paramètres StreamName et sont facultatifs, mais vous devez spécifier le StreamName ou le StreamARN lorsque vous appelez cette opération d'API.

Un flux vidéo Amazon Kinesis doit répondre aux exigences suivantes pour fournir des données via HLS :

• Exigences relatives aux pistes de lecture vidéo.

• La conservation des données doit être supérieure à 0.

• La piste vidéo de chaque fragment doit contenir des données privées du codec au format AVC (Advanced Video Coding) pour le format H.264 ou HEVC pour le format H.265 (spécification MPEG-4 ISO/IEC 14496-15). Pour plus d'informations sur l'adaptation des données de flux à un format donné, voir Indicateurs d'adaptation NAL.

• La piste audio (le cas échéant) de chaque fragment doit contenir des données privées du codec au format AAC (spécification AAC ISO/IEC 13818-7).

Les sessions HLS Kinesis Video Streams contiennent des fragments au format MPEG-4 fragmenté (également appelé fMP4 ou CMAF) ou au format MPEG-2 (également appelés fragments TS, également pris en charge par la spécification HLS). Pour plus d'informations sur les types de fragments HLS, consultez la spécification HLS.

La procédure suivante explique comment utiliser le HLS avec Kinesis Video Streams :

1. Appelez l'GetDataEndpointAPI pour obtenir un point de terminaison. Envoyez ensuite les GetHLSStreamingSessionURL demandes à ce point de terminaison à l'aide du paramètre --endpoint-url.

2. Récupérez l'URL HLS à l'aide GetHLSStreamingSessionURL de. Kinesis Video Streams crée une session de streaming HLS à utiliser pour accéder au contenu d'un flux à l'aide du protocole HLS. GetHLSStreamingSessionURLrenvoie une URL authentifiée (qui inclut un jeton de session crypté) pour la playlist principale HLS de la session (la ressource racine nécessaire au streaming avec HLS).

   Note

   Ne partagez pas et ne stockez pas ce jeton dans un endroit où une entité non autorisée pourrait y accéder. Le jeton donne accès au contenu du flux. Protégez le jeton avec les mêmes mesures que celles que vous utiliseriez avec vos AWS informations d'identification.

   Le contenu multimédia mis à disposition via la liste de lecture comprend uniquement le flux, la plage horaire et le format demandés. Aucune autre donnée multimédia (telles que les trames situées en dehors de la fenêtre demandée ou les débits binaires alternatifs) n'est mise à disposition.

3. Fournissez l'URL (contenant le jeton de session crypté) de la liste de lecture principale HLS à un lecteur multimédia compatible avec le protocole HLS. Kinesis Video Streams met à disposition la liste de lecture multimédia HLS, le fragment d'initialisation et les fragments multimédia via l'URL de la playlist principale. Le fragment d'initialisation contient les données privées du codec pour le flux, ainsi que les autres données nécessaires à la configuration du décodeur et du rendu vidéo ou audio. Les fragments multimédia contiennent des images vidéo codées H.264 ou des échantillons audio codés au format AAC.

4. Le lecteur multimédia reçoit l'URL authentifiée et demande les métadonnées du flux et les données multimédia normalement. Lorsque le lecteur multimédia demande des données, il lance les actions suivantes :

   • GetHLS MasterPlaylist : récupère une liste de lecture principale HLS, qui contient l'URL de l'GetHLSMediaPlaylistaction pour chaque piste, ainsi que des métadonnées supplémentaires pour le lecteur multimédia, y compris le débit et la résolution estimés.

   • GetHLS MediaPlaylist : récupère une liste de lecture multimédia HLS, qui contient une URL pour accéder au fragment d'initialisation MP4 avec l'GetMP4InitFragmentaction, et des URL pour accéder aux fragments multimédia MP4 avec les actions. GetMP4MediaFragment La liste de lecture multimédia HLS contient également des métadonnées concernant le flux dont le lecteur a besoin pour le lire, par exemple s'il PlaybackMode est LIVE ouON_DEMAND. La liste de lecture multimédia HLS est généralement statique pour les sessions avec un PlaybackType deON_DEMAND. La liste de lecture multimédia HLS est continuellement mise à jour avec de nouveaux fragments pour les sessions avec un PlaybackType deLIVE. Il existe une liste de lecture multimédia HLS distincte pour la piste vidéo et pour la piste audio (le cas échéant) qui contient les URL multimédia MP4 pour la piste spécifique.

   • GetMP4 InitFragment : récupère le fragment d'initialisation MP4. Le lecteur multimédia charge généralement le fragment d'initialisation avant de charger tout fragment multimédia. Ce fragment contient les atomes MP4 fytp « » et moov « », ainsi que les atomes enfants nécessaires à l'initialisation du décodeur du lecteur multimédia.

     Le fragment d'initialisation ne correspond à aucun fragment d'un flux vidéo Kinesis. Il contient uniquement les données privées du codec pour le flux et la piste correspondante, dont le lecteur multimédia a besoin pour décoder les images multimédia.

   • GetMP4 MediaFragment : récupère les fragments multimédia MP4. Ces fragments contiennent les atomes « moof » et « mdat » MP4 et leurs atomes enfants, contenant les images multimédia du fragment codé et leurs horodatages.

     Note

     Les données privées du codec (CPD) contenues dans chaque fragment contiennent des informations d'initialisation spécifiques au codec, telles que la fréquence d'images, la résolution et le profil de codage, qui sont nécessaires pour décoder correctement le fragment. Pour TS et MP4, les modifications du CPD sont prises en charge pendant une session de streaming. Par conséquent, les fragments d'une session peuvent avoir des informations différentes dans le CPD sans interrompre la lecture. Pour chaque session de streaming, seules 500 modifications du CPD sont autorisées.

     Important

     Le suivi des modifications n'est pas pris en charge. Les pistes doivent rester cohérentes sur l'ensemble du support demandé. Le streaming échouera si les fragments du flux ne contiennent plus uniquement de la vidéo mais contiennent à la fois du son et de la vidéo, ou si une piste audio AAC est remplacée par une piste audio A-Law.

     Les données récupérées à l'aide de cette action sont facturables. Pour de plus amples informations, consultez Tarification .

   • GetTSFragment : récupère les fragments MPEG TS contenant à la fois des données d'initialisation et des données multimédia pour toutes les pistes du flux.

     Note

     Si tel ContainerFormat est le casMPEG_TS, cette API est utilisée à la place de GetMP4InitFragment et GetMP4MediaFragment pour récupérer le contenu multimédia du flux.

     Les données récupérées à l'aide de cette action sont facturables. Pour plus d'informations, consultez les tarifs de Kinesis Video Streams.

L'URL d'une session de streaming ne doit pas être partagée entre les joueurs. Le service peut ralentir une session si plusieurs lecteurs multimédias la partagent. Pour connaître les limites de connexion, consultez la section Limites de Kinesis Video Streams.

Vous pouvez contrôler la quantité de données consommée par le lecteur multimédia en surveillant la CloudWatch métrique GetMP4MediaFragment.OutgoingBytes Amazon. Pour plus d'informations sur l'utilisation CloudWatch de Kinesis Video Streams pour surveiller les Kinesis Video Streams, consultez la section Surveillance des Kinesis Video Streams. Pour plus d'informations sur les tarifs, consultez la section Tarification AWS et tarification d'Amazon Kinesis Video Streams. Des frais s'appliquent aux sessions HLS et aux AWS données sortantes.

Consultez les exemples de lecture vidéo dans le guide de documentation : Utilisez le AWS CLI pour récupérer l'URL d'une session de streaming HLS etExemple : utilisez HLS en HTML et JavaScript.

Pour plus d'informations sur le HLS, consultez la section HTTP Live Streaming sur le site Apple Developer.

Important

Si une erreur est générée après avoir appelé une API multimédia archivée Kinesis Video Streams, outre le code d'état HTTP et le corps de la réponse, elle inclut les informations suivantes :

• x-amz-ErrorTypeEn-tête HTTP : contient un type d'erreur plus spécifique en plus de ce que fournit le code d'état HTTP.

• x-amz-RequestIdEn-tête HTTP : si vous souhaitez signaler un problème à AWS, l'équipe d'assistance pourra mieux diagnostiquer le problème si vous lui donnez l'ID de demande.

Le code d'état HTTP et l' ErrorType en-tête peuvent être utilisés pour prendre des décisions programmatiques quant à savoir si les erreurs peuvent être réessayées et dans quelles conditions, ainsi que pour fournir des informations sur les actions que le programmeur client devra peut-être entreprendre pour réessayer avec succès.

Pour plus d'informations, consultez la section Erreurs au bas de cette rubrique, ainsi que les erreurs courantes.

Syntaxe de la demande

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"
}

Paramètres de demande URI

La demande n’utilise pas de paramètres URI.

Corps de la demande

Cette demande accepte les données suivantes au format JSON.

ContainerFormat

Spécifie le format à utiliser pour empaqueter le support. La spécification du format du FRAGMENTED_MP4 conteneur permet de regrouper le contenu multimédia en fragments MP4 (fMP4 ou CMAF). Il s'agit de l'emballage recommandé car les frais d'emballage sont minimes. L'autre option de format de conteneur estMPEG_TS. Le HLS prend en charge les segments MPEG TS depuis sa sortie et est parfois le seul package compatible sur les anciens lecteurs HLS. MPEG TS implique généralement une surcharge d'emballage de 5 à 25 %. Cela signifie que le MPEG TS nécessite généralement 5 à 25 % de bande passante et coûte plus cher que le fMP4.

L’argument par défaut est FRAGMENTED_MP4.

Type : chaîne

Valeurs valides : FRAGMENTED_MP4 | MPEG_TS

Obligatoire : non

DiscontinuityMode

Spécifie le moment où des indicateurs signalant les discontinuités entre les fragments sont ajoutés aux listes de lecture multimédia.

Les lecteurs multimédias établissent généralement une chronologie du contenu multimédia à lire, en fonction de l'horodatage de chaque fragment. Cela signifie qu'en cas de chevauchement ou d'écart entre les fragments (comme c'est généralement le cas si cette valeur HLSFragmentSelector est définie surSERVER_TIMESTAMP), la chronologie du lecteur multimédia présentera également de petits espaces entre les fragments à certains endroits et remplacera les images à d'autres endroits. Des lacunes dans la chronologie du lecteur multimédia peuvent entraîner un blocage de la lecture et les chevauchements peuvent provoquer des perturbations lors de la lecture. Lorsque des indicateurs de discontinuité apparaissent entre les fragments, le lecteur multimédia est censé réinitialiser la chronologie, ce qui permet de lire le fragment suivant immédiatement après le fragment précédent.

Les modes suivants sont pris en charge :

• ALWAYS: un marqueur de discontinuité est placé entre chaque fragment de la playlist multimédia HLS. Il est recommandé d'utiliser une valeur de ALWAYS si les horodatages des fragments ne sont pas exacts.

• NEVER: aucun marqueur de discontinuité n'est placé nulle part. Il est recommandé d'utiliser une valeur de NEVER pour garantir que la chronologie du lecteur multimédia corresponde le plus précisément possible aux horodatages du producteur.

• ON_DISCONTINUITY: un marqueur de discontinuité est placé entre les fragments présentant un écart ou un chevauchement de plus de 50 millisecondes. Pour la plupart des scénarios de lecture, il est recommandé d'utiliser une valeur égale à ON_DISCONTINUITY afin que la chronologie du lecteur multimédia ne soit réinitialisée qu'en cas de problème important avec la chronologie multimédia (par exemple, un fragment manquant).

La valeur par défaut HLSFragmentSelector est le ALWAYS moment défini sur SERVER_TIMESTAMP et le NEVER moment où il est défini surPRODUCER_TIMESTAMP.

Type : chaîne

Valeurs valides : ALWAYS | NEVER | ON_DISCONTINUITY

Obligatoire : non

DisplayFragmentTimestamp

Spécifie le moment où les horodatages de début du fragment doivent être inclus dans la liste de lecture multimédia HLS. Généralement, les lecteurs multimédias indiquent la position de la tête de lecture sous forme de temps par rapport au début du premier fragment de la session de lecture. Toutefois, lorsque les horodatages de début sont inclus dans la liste de lecture multimédia HLS, certains lecteurs multimédias peuvent indiquer la tête de lecture actuelle sous forme d'heure absolue sur la base des horodatages des fragments. Cela peut être utile pour créer une expérience de lecture qui indique aux spectateurs l'heure du média à l'horloge murale.

L’argument par défaut est NEVER. Dans HLSFragmentSelector ce casSERVER_TIMESTAMP, les horodatages seront les horodatages de début du serveur. De même, quand HLSFragmentSelector c'est le casPRODUCER_TIMESTAMP, les horodatages seront les horodatages de début du producteur.

Type : chaîne

Valeurs valides : ALWAYS | NEVER

Obligatoire : non

Expires

Durée en secondes avant l'expiration de la session demandée. Cette valeur peut être comprise entre 300 (5 minutes) et 43200 (12 heures).

Lorsqu'une session expire, aucun nouvel appel versGetHLSMasterPlaylist,,GetHLSMediaPlaylist, GetMP4InitFragmentGetMP4MediaFragment, ou GetTSFragment ne peut être effectué pour cette session.

La valeur par défaut est 300 (5 minutes).

Type : entier

Plage valide : valeur minimale de 300. Valeur maximale fixée à 43200.

Obligatoire : non

HLSFragmentSelector

La plage horaire du fragment demandé et la source des horodatages.

Ce paramètre est obligatoire si c'PlaybackModeest le cas ON_DEMAND ouLIVE_REPLAY. Ce paramètre est facultatif si tel PlaybackMode est le cas LIVE. Si PlaybackMode tel est le casLIVE, le FragmentSelectorType peut être défini, mais ne TimestampRange doit pas être défini. Si PlaybackMode c'est le cas ON_DEMAND ou les deuxLIVE_REPLAY, FragmentSelectorType et cela TimestampRange doit être défini.

Type : objet HLSFragmentSelector

Obligatoire : non

MaxMediaPlaylistFragmentResults

Nombre maximal de fragments renvoyés dans les listes de lecture multimédia HLS.

Lorsque PlaybackMode c'est le casLIVE, les fragments les plus récents sont renvoyés jusqu'à cette valeur. Lorsque PlaybackMode c'est le casON_DEMAND, les fragments les plus anciens sont renvoyés, jusqu'à ce nombre maximum.

Lorsqu'un plus grand nombre de fragments sont disponibles dans une playlist multimédia HLS en direct, les lecteurs vidéo mettent souvent le contenu en mémoire tampon avant de commencer la lecture. L'augmentation de la taille de la mémoire tampon augmente la latence de lecture, mais réduit le risque de rebuffering pendant la lecture. Nous recommandons qu'une playlist multimédia HLS en direct contienne un minimum de 3 fragments et un maximum de 10 fragments.

La valeur par défaut est de 5 fragments si PlaybackMode c'est LIVE ouLIVE_REPLAY, et de 1 000 si PlaybackMode c'est le casON_DEMAND.

La valeur maximale de 5 000 fragments correspond à plus de 80 minutes de vidéo sur des flux contenant des fragments d'une seconde, et à plus de 13 heures de vidéo sur des flux contenant des fragments de 10 secondes.

Type : long

Plage valide : valeur minimum de 1. Valeur maximale de 5 000.

Obligatoire : non

PlaybackMode

Qu'il s'agisse de récupérer des données en direct, des rediffusions en direct ou des données archivées à la demande.

Les caractéristiques des trois types de sessions sont les suivantes :

• LIVE: Pour les sessions de ce type, la liste de lecture multimédia HLS est continuellement mise à jour avec les derniers fragments dès qu'ils sont disponibles. Nous recommandons que le lecteur multimédia récupère une nouvelle liste de lecture à une seconde d'intervalle. Lorsque ce type de session est lu dans un lecteur multimédia, l'interface utilisateur affiche généralement une notification « en direct », sans aucune commande permettant de choisir la position à afficher dans la fenêtre de lecture.

  Note

  En LIVE mode, les fragments disponibles les plus récents sont inclus dans une liste de lecture multimédia HLS, même s'il existe un écart entre les fragments (c'est-à-dire s'il en manque un). Un tel écart peut provoquer l'arrêt d'un lecteur multimédia ou une interruption de la lecture. Dans ce mode, les fragments ne sont pas ajoutés à la liste de lecture multimédia HLS s'ils sont plus anciens que le fragment le plus récent de la liste de lecture. Si le fragment manquant devient disponible après l'ajout d'un fragment suivant à la liste de lecture, le fragment le plus ancien n'est pas ajouté et le vide n'est pas comblé.

• LIVE_REPLAY: pour les sessions de ce type, la liste de lecture multimédia HLS est mise à jour de la même manière qu'elle est mise à jour pour le LIVE mode, sauf qu'elle commence par inclure des fragments à partir d'une heure de début donnée. Au lieu d'ajouter des fragments au fur et à mesure de leur ingestion, des fragments sont ajoutés au fur et à mesure que la durée du fragment suivant s'écoule. Par exemple, si les fragments de la session durent deux secondes, un nouveau fragment est ajouté à la liste de lecture multimédia toutes les deux secondes. Ce mode est utile pour démarrer la lecture dès qu'un événement est détecté et continuer à diffuser en direct du contenu multimédia qui n'a pas encore été ingéré au moment de la création de la session. Ce mode est également utile pour diffuser du contenu multimédia précédemment archivé sans être limité par la limite de 1 000 fragments du ON_DEMAND mode.

• ON_DEMAND: pour les sessions de ce type, la liste de lecture multimédia HLS contient tous les fragments de la session, jusqu'au nombre spécifié dansMaxMediaPlaylistFragmentResults. La playlist ne doit être récupérée qu'une seule fois par session. Lorsque ce type de session est lu dans un lecteur multimédia, l'interface utilisateur affiche généralement une commande de nettoyage permettant de choisir la position à afficher dans la fenêtre de lecture.

Dans tous les modes de lecture, si FragmentSelectorType tel est le casPRODUCER_TIMESTAMP, et s'il existe plusieurs fragments portant le même horodatage de début, le fragment dont le numéro de fragment est le plus élevé (c'est-à-dire le fragment le plus récent) est inclus dans la liste de lecture multimédia HLS. Les autres fragments ne sont pas inclus. Les fragments qui ont des horodatages différents mais dont les durées se chevauchent sont toujours inclus dans la liste de lecture multimédia HLS. Cela peut entraîner un comportement inattendu dans le lecteur multimédia.

L’argument par défaut est LIVE.

Type : chaîne

Valeurs valides : LIVE | LIVE_REPLAY | ON_DEMAND

Obligatoire : non

StreamARN

Nom de ressource Amazon (ARN) du flux pour lequel vous souhaitez récupérer l'URL de la playlist principale HLS.

Vous devez spécifier le StreamName ou leStreamARN.

Type : chaîne

Contraintes de longueur : Longueur minimum de 1. Longueur maximum de 1024.

Modèle : arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/[0-9]+

Obligatoire : non

StreamName

Nom du flux pour lequel l'URL de la playlist principale HLS doit être récupérée.

Vous devez spécifier le StreamName ou leStreamARN.

Type : chaîne

Contraintes de longueur : longueur minimum de 1. Longueur maximum de 256.

Modèle : [a-zA-Z0-9_.-]+

Obligatoire : non

Syntaxe de la réponse

HTTP/1.1 200
Content-type: application/json

{
   "HLSStreamingSessionURL": "string"
}

Eléments de réponse

Si l’action aboutit, le service renvoie une réponse HTTP 200.

Les données suivantes sont renvoyées au format JSON par le service.

HLSStreamingSessionURL

URL (contenant le jeton de session) qu'un lecteur multimédia peut utiliser pour récupérer la playlist principale HLS.

Type : chaîne

Erreurs

Pour plus d'informations sur les erreurs courantes pour toutes les actions, consultez Erreurs courantes.

ClientLimitExceededException

Kinesis Video Streams a limité la demande car vous avez dépassé une limite. Essayez de passer l'appel plus tard. Pour plus d'informations sur les limites, consultez Kinesis Video Streams Limits.

Code d’état HTTP : 400

InvalidArgumentException

Un paramètre spécifié dépasse ses restrictions, n'est pas pris en charge ou ne peut pas être utilisé.

Code d’état HTTP : 400

InvalidCodecPrivateDataException

Les données privées du codec contenues dans au moins une des pistes du flux vidéo ne sont pas valides pour cette opération.

Code d’état HTTP : 400

MissingCodecPrivateDataException

Aucune donnée privée du codec n'a été trouvée dans au moins une des pistes du flux vidéo.

Code d’état HTTP : 400

NoDataRetentionException

GetImagesa été demandé pour un flux qui ne conserve pas de données (c'est-à-dire dont la valeur est DataRetentionInHours égale à 0).

Code d’état HTTP : 400

NotAuthorizedException

Code d'état : 403, l'appelant n'est pas autorisé à effectuer une opération sur le flux donné, ou le jeton a expiré.

Code d'état HTTP : 401

ResourceNotFoundException

GetImagesgénère cette erreur lorsque Kinesis Video Streams ne trouve pas le flux que vous avez spécifié.

GetHLSStreamingSessionURLet GetDASHStreamingSessionURL génère cette erreur si une session avec un PlaybackMode de ON_DEMAND ou LIVE_REPLAY est demandée pour un flux qui ne contient aucun fragment dans la plage de temps demandée, ou si une session avec un PlaybackMode of LIVE est demandée pour un flux qui ne contient aucun fragment au cours des 30 dernières secondes.

Code d’état HTTP : 404

UnsupportedStreamMediaTypeException

Le type de média (par exemple, vidéo h.264 ou h.265 ou audio AAC ou G.711) n'a pas pu être déterminé à partir des identifiants de codec des pistes du premier fragment d'une session de lecture. L'identifiant du codec pour la piste 1 doit être V_MPEG/ISO/AVC et, éventuellement, l'identifiant du codec pour la piste 2 doit être. A_AAC

Code d’état HTTP : 400

consultez aussi

Pour plus d'informations sur l'utilisation de cette API dans l'un des AWS SDK spécifiques au langage, consultez les pages suivantes :

• Interface de ligne de commande AWS

• AWS SDK pour .NET

• AWS SDK pour C++

• AWS SDK pour Go v2

• AWS SDK pour Java V2

• AWS SDK pour V3 JavaScript

• AWS SDK pour PHP V3

• AWS SDK pour Python

• AWS SDK pour Ruby V3