GetDASHStreamingSessionURL - 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.

GetDASHStreamingSessionURL

Récupère un flux adaptatif MPEG dynamique sur HTTP (DASH) URL pour le flux. Vous pouvez ensuite l'ouvrir 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 API opération.

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

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

  1. Appelez le GetDataEndpoint API 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 le MPEG - DASH URL en utilisantGetDASHStreamingSessionURL. Kinesis Video Streams crée MPEG une DASH session de diffusion à utiliser pour accéder au contenu d'un flux à l'aide MPEG du protocole DASH -. GetDASHStreamingSessionURLrenvoie un fichier authentifié URL (qui inclut un jeton de session crypté) pour le DASH manifeste de MPEG 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 le URL (contenant le jeton de session crypté) pour le DASH manifeste MPEG - à un lecteur multimédia compatible avec le DASH protocole MPEG -. Kinesis Video Streams met le fragment d'initialisation et les fragments multimédia à disposition via le manifeste. 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 ou des échantillons audio 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 etDASHManifest : Récupère un MPEG DASH manifeste qui contient les métadonnées du média que vous souhaitez lire.

    • 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 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.

    • 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.

      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. CPDles modifications ne sont pas prises en charge pendant une session de streaming. Ils CPD doivent rester cohérents à 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 AAC audio est remplacée par une piste audio A-Law.

      Les données récupérées grâce à cette action sont facturables. Consultez les tarifs pour plus de détails.

Note

Pour connaître les restrictions applicables aux MPEG DASH sessions, 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.

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, vous pouvez mieux diagnostiquer le problème si vous lui donnez l'ID 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 /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"
}

URIParamètres de demande

La demande n'utilise aucun URI paramètre.

Corps de la requête

La demande accepte les données suivantes au JSON format suivant.

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 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 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 APIs (par exemple GetMedia etGetMediaForFragmentList). Un lecteur DASH multimédia personnalisé MPEG est nécessaire pour tirer parti de cet attribut personnalisé.

La valeur par défaut est NEVER.

Type : String

Valeurs valides : ALWAYS | NEVER

Obligatoire : non

DisplayFragmentTimestamp

Selon la DASH spécification MPEG -, l'heure de l'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 DASH compatibles ne gèrent généralement pas correctement les lacunes de la chronologie multimédia. MPEG 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 DASH multimédia personnalisé MPEG 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 : 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 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

Le nombre maximum de fragments renvoyés dans le DASH manifeste MPEG -.

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 DASH manifeste en direct MPEG 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 DASH manifeste en direct MPEG 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, 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, le DASH manifeste MPEG - 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 MPEG DASH manifeste, 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 MPEG DASH manifeste 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 DASH manifeste MPEG - 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 DASH manifeste MPEG - contient tous les fragments de la session, jusqu'au nombre spécifié dansMaxManifestFragmentResults. 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 : String

Valeurs valides : LIVE | LIVE_REPLAY | ON_DEMAND

Obligatoire : non

StreamARN

Le nom de ressource Amazon (ARN) du flux pour lequel vous souhaitez récupérer le DASH manifeste MPEG -URL.

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 le MPEG DASH manifeste doit être récupéréURL.

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

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

DASHStreamingSessionURL

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

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 :