GetHLSStreamingSessionURL - Amazon Kinesis Video Streams
Syntaxe de la requêteURIParamètres de demandeCorps de la requêteSyntaxe de la réponseEléments de réponseErreursconsultez aussi

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

GetHLSStreamingSessionURL

Récupère une diffusion HTTP en direct (HLS) URL pour le flux. Vous pouvez ensuite l'ouvrir 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 API opération.

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

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

La procédure suivante indique comment utiliser HLS Kinesis Video Streams :

  1. Appelez le GetDataEndpoint API 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 HLS URL l'utilisationGetHLSStreamingSessionURL. Kinesis Video Streams crée HLS une session de streaming à utiliser pour accéder au contenu d'un flux à l'aide HLS du protocole. GetHLSStreamingSessionURLrenvoie une valeur authentifiée URL (qui inclut un jeton de session crypté) pour la playlist HLS principale de la session (la ressource racine nécessaire au streaming avecHLS).

    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 le URL (contenant le jeton de session crypté) de la liste de lecture HLS principale à un lecteur multimédia compatible avec le HLS protocole. Kinesis Video Streams met à disposition HLS la liste de lecture multimédia, le fragment d'initialisation et les fragments multimédia via la liste de lecture principale. URL 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 en H.264 ou des échantillons audio AAC codés.

  4. Le lecteur multimédia reçoit les données authentifiées URL 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 :

    • G etHLSMaster Playlist : récupère une playlist HLS principale, qui contient une description de l'GetHLSMediaPlaylistaction URL 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.

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

    • Obtenir MP4InitFragment : récupère le fragment d'MP4initialisation. Le lecteur multimédia charge généralement le fragment d'initialisation avant de charger tout fragment multimédia. Ce fragment contient les MP4 atomes « 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.

    • Obtenir MP4MediaFragment : récupère des fragments MP4 multimédia. Ces fragments contiennent les atomes « moof » et « mdat » et leurs MP4 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 etMP4, les CPD modifications sont prises en charge lors d'une session de streaming. Par conséquent, les fragments d'une session peuvent contenir des informations différentes CPD sans interrompre la lecture. Pour chaque session de streaming, seules 500 CPD modifications 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 AAC audio est remplacée par une piste audio A-Law.

      Les données récupérées grâce à cette action sont facturables. Pour de plus amples informations, consultez Tarification .

    • G etTSFragment : Récupère MPEG les fragments 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, API il est utilisé à la place de GetMP4InitFragment et GetMP4MediaFragment pour récupérer le contenu multimédia du flux.

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

Une session de streaming ne URL doit pas être partagée entre joueurs. Le service peut ralentir une session si plusieurs lecteurs multimédias la partagent. Pour connaître les limites de connexion, consultez la section Quotas 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 HLS sessions 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 une session de HLS streaming URL etExemple : utilisation HLS dans HTML et JavaScript.

Pour plus d'informationsHLS, consultez la section Diffusion en HTTP direct sur le site Apple Developer.

Important

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

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

  • x-amz-RequestIdHTTPen-tête : si vous souhaitez signaler un problème à AWS, l'équipe d'assistance peut mieux diagnostiquer le problème si elle reçoit l'identifiant de demande.

Le code d'HTTPétat 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 requête

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

URIParamètres de demande

La demande n'utilise aucun URI paramètre.

Corps de la requête

La demande accepte le JSON format des données suivantes.

ContainerFormat

Spécifie le format à utiliser pour le packaging du support. La spécification du format du FRAGMENTED_MP4 conteneur permet de regrouper le contenu multimédia en MP4 fragments (f MP4 ouCMAF). Il s'agit de l'emballage recommandé car les frais d'emballage sont minimes. L'autre option de format de conteneur estMPEG_TS. HLSsupporte MPEG les parties TS depuis sa sortie et est parfois le seul package compatible avec les anciens HLS joueurs. MPEGTS a généralement des frais d'emballage de 5 à 25 %. Cela signifie que MPEG TS nécessite généralement 5 à 25 % de bande passante et de coûts supplémentaires par rapport à f. MP4

L’argument par défaut est FRAGMENTED_MP4.

Type : String

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 HLS multimédia. 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 : String

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 HLS multimédia. 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 HLS multimédia, 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, lorsque HLSFragmentSelector c'est le casPRODUCER_TIMESTAMP, les horodatages seront les horodatages de début du producteur.

Type : String

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 s'il l' PlaybackMode est 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

Le nombre maximum de fragments renvoyés dans les listes de lecture HLS multimédia.

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.

Lorsque le nombre de fragments disponibles dans une playlist HLS multimédia en direct est élevé, les lecteurs vidéo mettent souvent le contenu en mémoire tampon avant de démarrer 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 HLS multimédia 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, en direct ou 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 HLS multimédia 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 derniers fragments disponibles sont inclus dans une liste de lecture HLS multimédia, 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 HLS multimédia 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 HLS multimédia 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 HLS multimédia 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 HLS multimédia. 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 : String

Valeurs valides : LIVE | LIVE_REPLAY | ON_DEMAND

Obligatoire : non

StreamARN

Le nom de ressource Amazon (ARN) du stream pour lequel vous souhaitez récupérer la playlist HLS principaleURL.

Vous devez spécifier le StreamName ou leStreamARN.

Type : String

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 vous souhaitez récupérer la playlist HLS principaleURL.

Vous devez spécifier le StreamName ou leStreamARN.

Type : String

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 sous JSON forme formatée par le service.

HLSStreamingSessionURL

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

Type : String

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 la section Quotas Kinesis Video Streams.

HTTPCode de statut : 400

InvalidArgumentException

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

HTTPCode de statut : 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.

HTTPCode de statut : 400

MissingCodecPrivateDataException

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

HTTPCode de statut : 400

NoDataRetentionException

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

HTTPCode de statut : 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é.

HTTPCode de statut : 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.

HTTPCode de statut : 404

UnsupportedStreamMediaTypeException

Le type de média (par exemple, vidéo h.264 ou h.265 ou audio G.711) n'a pas pu être déterminé à partir du codec IDs des pistes du premier fragment d'une session de lecture. AAC 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

HTTPCode de statut : 400

consultez aussi

Pour plus d'informations sur son utilisation API dans l'une des langues spécifiques AWS SDKs, consultez ce qui suit :