GetDASHStreamingSessionURL

Récupère une URL MPEG Dynamic Adaptive Streaming over HTTP (DASH) pour le flux. Vous pouvez ensuite ouvrir l'URL dans 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 MPEG-DASH :

• 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 de codec en Advanced Video Coding (AVC) pour le format H.264 et en HEVC pour le format H.265. Pour plus d'informations, consultez la section MPEG-4 spécification ISO/CEI 14496-15. Pour plus d'informations sur l'adaptation des données de flux à un format donné, voir Indicateurs d'adaptation NAL.

• Le cas échéant, la piste audio de chaque fragment doit contenir des données privées de codec au format AAC (AAC specification ISO/IEC 13818-7) ou MS Wave.

La procédure suivante montre comment utiliser le MPEG-DASH avec Kinesis Video Streams :

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

2. Récupérez l'URL MPEG-DASH à l'aide de. GetDASHStreamingSessionURL Kinesis Video Streams crée une session de streaming MPEG-DASH à utiliser pour accéder au contenu d'un flux à l'aide du protocole MPEG-DASH. GetDASHStreamingSessionURLrenvoie une URL authentifiée (qui inclut un jeton de session crypté) pour le manifeste MPEG-DASH de la session (la ressource racine nécessaire au streaming avec MPEG-DASH).

   Note

   Ne partagez pas et ne stockez pas ce jeton dans un endroit où une entité non autorisée peut 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 utilisez avec vos AWS informations d'identification.

   Le média mis à disposition via le manifeste 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é) du manifeste MPEG-DASH à un lecteur multimédia compatible avec le protocole MPEG-DASH. Kinesis Video Streams met le fragment d'initialisation et les fragments multimédia à disposition via l'URL du manifeste. 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 ou des échantillons audio codés.

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 :

   • GetDashManifest : récupère un manifeste MPEG DASH, qui contient les métadonnées du média que vous souhaitez lire.

   • 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 pour initialiser le 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.

     Important

     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. Les modifications du CPD ne sont pas prises en charge pendant une session de streaming. Le CPD doit rester cohérent à travers les médias interrogés.

     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. Consultez les tarifs pour plus de détails.

Note

Pour connaître les restrictions applicables aux sessions MPEG-DASH, consultez Kinesis Video Streams Limits.

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.

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, vous pouvez 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 /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"
}

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.

DASHFragmentSelector

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 DASHFragmentSelector

Obligatoire : non

DisplayFragmentNumber

Les fragments sont identifiés dans le fichier manifeste en fonction de leur numéro de séquence dans la session. Si DisplayFragmentNumber cette valeur est définie surALWAYS, le numéro de fragment Kinesis Video Streams est ajouté à chaque élément S du fichier manifeste avec le nom d'attribut « kvs:fn ». Ces numéros de fragments peuvent être utilisés pour la journalisation ou pour être utilisés avec d'autres API (par exemple GetMedia etGetMediaForFragmentList). Un lecteur multimédia MPEG-DASH personnalisé est nécessaire pour tirer parti de cet attribut personnalisé.

La valeur par défaut est NEVER.

Type : chaîne

Valeurs valides : ALWAYS | NEVER

Obligatoire : non

DisplayFragmentTimestamp

Selon la spécification MPEG-DASH, l'heure d'horloge murale des fragments du fichier manifeste peut être dérivée à l'aide des attributs du manifeste lui-même. Cependant, les lecteurs multimédias compatibles MPEG-DASH ne gèrent généralement pas correctement les lacunes de la chronologie multimédia. Kinesis Video Streams ajuste la chronologie multimédia dans le fichier manifeste pour permettre la lecture de fichiers multimédias présentant des discontinuités. Par conséquent, l'heure de l'horloge murale dérivée du fichier manifeste peut être inexacte. Si DisplayFragmentTimestamp cette valeur est définie surALWAYS, l'horodatage exact du fragment est ajouté à chaque élément S du fichier manifeste avec le nom d'attribut « kvs:ts ». Un lecteur multimédia MPEG-DASH personnalisé est nécessaire pour tirer parti de cet attribut personnalisé.

La valeur par défaut est NEVER. Dans DASHFragmentSelector ce casSERVER_TIMESTAMP, les horodatages seront les horodatages de début du serveur. De même, lorsque DASHFragmentSelector 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 ne GetMP4MediaFragment peut être effectué ou effectué pour cette session. GetDashManifest GetMP4InitFragment

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

Type : entier

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

Obligatoire : non

MaxManifestFragmentResults

Nombre maximal de fragments renvoyés dans le manifeste MPEG-DASH.

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 manifeste MPEG-DASH en direct contient un plus grand nombre de fragments, 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'un manifeste MPEG-DASH actif 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 1 000 fragments correspond à plus de 16 minutes de vidéo sur des flux contenant des fragments d'une seconde, et à plus de 2 heures et demie 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, le manifeste MPEG-DASH est continuellement mis à jour avec les derniers fragments dès qu'ils sont disponibles. Nous recommandons que le lecteur multimédia récupère un nouveau manifeste à 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 un manifeste MPEG-DASH, 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 au manifeste MPEG-DASH 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 au manifeste, le fragment le plus ancien n'est pas ajouté et le vide n'est pas comblé.

• LIVE_REPLAY: Pour les sessions de ce type, le manifeste MPEG-DASH est mis à jour de la même manière qu'il est mis à jour pour le LIVE mode, sauf qu'il 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é au manifeste 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, le manifeste MPEG-DASH contient tous les fragments de la session, jusqu'au nombre spécifié dans. MaxManifestFragmentResults Le manifeste ne doit être récupéré 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 le manifeste MPEG-DASH. 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 le manifeste MPEG-DASH. 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 du manifeste MPEG-DASH.

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 du manifeste MPEG-DASH 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

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

DASHStreamingSessionURL

URL (contenant le jeton de session) qu'un lecteur multimédia peut utiliser pour récupérer le manifeste MPEG-DASH.

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 qui a une DataRetentionInHours valeur de 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