GetDASHStreamingSessionURL

Recupera un URL MPEG Dynamic Adaptive Streaming over HTTP (DASH) per lo stream. È quindi possibile aprire l'URL in un lettore multimediale per visualizzare i contenuti dello streaming.

StreamNameSia i parametri che i StreamARN parametri sono facoltativi, ma è necessario specificare StreamName o il StreamARN quando si richiama questa operazione API.

Uno stream video di Amazon Kinesis presenta i seguenti requisiti per la fornitura di dati tramite MPEG-DASH:

• Requisiti per la riproduzione dei brani video.

• La conservazione dei dati deve essere superiore a 0.

• La traccia video di ogni frammento deve contenere i dati codec privati in Advanced Video Coding (AVC) per il formato H.264 e HEVC per il formato H.265. Per ulteriori informazioni, consulta Specifica MPEG-4 ISO/IEC 14496-15. Per informazioni sull'adattamento dei dati di flusso a un dato formato, vedi i contrassegni di adattamento NAL.

• La traccia audio (se presente) di ogni frammento deve contenere dati codec privati in formato AAC (Specifica AAC ISO/IEC 13818-7) o in formato MS Wave.

La procedura seguente mostra come utilizzare MPEG-DASH con Kinesis Video Streams:

1. Chiama l'GetDataEndpointAPI per ottenere un endpoint. Quindi invia le GetDASHStreamingSessionURL richieste a questo endpoint utilizzando il parametro --endpoint-url.

2. Recupera l'URL MPEG-DASH utilizzando. GetDASHStreamingSessionURL Kinesis Video Streams crea una sessione di streaming MPEG-DASH da utilizzare per accedere ai contenuti di uno stream utilizzando il protocollo MPEG-DASH. GetDASHStreamingSessionURLrestituisce un URL autenticato (che include un token di sessione crittografato) per il manifesto MPEG-DASH della sessione (la risorsa principale necessaria per lo streaming con MPEG-DASH).

   Nota

   Non condividere o archiviare questo token dove un'entità non autorizzata può accedervi. Il token fornisce l'accesso al contenuto dello stream. Proteggi il token con le stesse misure che usi con le tue AWS credenziali.

   I file multimediali resi disponibili tramite il manifesto sono costituiti solo dallo stream, dall'intervallo di tempo e dal formato richiesti. Nessun altro dato multimediale (come frame esterni alla finestra richiesta o bitrate alternativi) viene reso disponibile.

3. Fornite l'URL (contenente il token di sessione crittografato) per il manifesto MPEG-DASH a un lettore multimediale che supporti il protocollo MPEG-DASH. Kinesis Video Streams rende disponibili il frammento di inizializzazione e i frammenti multimediali tramite l'URL del manifesto. Il frammento di inizializzazione contiene i dati privati del codec per lo stream e altri dati necessari per configurare il decodificatore e il renderer video o audio. I frammenti multimediali contengono fotogrammi video codificati o campioni audio codificati.

4. Il lettore multimediale riceve l'URL autenticato e richiede lo streaming di metadati e dati multimediali normalmente. Quando il lettore multimediale richiede dati, richiama le seguenti azioni:

   • GetDASHManifest: recupera un manifesto MPEG DASH, che contiene i metadati per i file multimediali che si desidera riprodurre.

   • Get MP4InitFragment: recupera il frammento di inizializzazione. MP4 Il lettore multimediale in genere carica il frammento di inizializzazione prima di caricare qualsiasi frammento multimediale. Questo frammento contiene gli atomi "fytp" e "moov" e MP4 gli atomi secondari necessari per inizializzare il decoder del lettore multimediale.

     Il frammento di inizializzazione non corrisponde a un frammento in uno stream video Kinesis. Contiene solo i dati privati del codec per lo stream e la rispettiva traccia, necessari al lettore multimediale per decodificare i frame multimediali.

   • Get MP4MediaFragment: MP4 recupera i frammenti multimediali. Questi frammenti contengono gli atomi "" e moof "mdat" e i relativi MP4 atomi secondari, contenenti i frame multimediali del frammento codificato e i relativi timestamp.

     Importante

     I dati privati del codec (CPD) contenuti in ogni frammento contengono informazioni di inizializzazione specifiche del codec, come la frequenza dei fotogrammi, la risoluzione e il profilo di codifica, necessarie per decodificare correttamente il frammento. Le modifiche CPD non sono supportate durante una sessione di streaming. Il CPD deve rimanere coerente attraverso i media interrogati.

     Importante

     Le modifiche alla traccia non sono supportate. Le tracce devono rimanere coerenti su tutti i file multimediali interrogati. Lo streaming fallirà se i frammenti dello stream passano da un formato contenente solo video ad avere sia audio che video, o se una traccia audio AAC viene sostituita da una traccia audio A-Law.

     I dati recuperati con questa azione sono fatturabili. Per maggiori dettagli, consulta la sezione Prezzi.

Nota

Per le restrizioni che si applicano alle sessioni MPEG-DASH, consulta le quote di Kinesis Video Streams.

Puoi monitorare la quantità di dati consumata dal lettore multimediale monitorando la CloudWatch metrica di GetMP4MediaFragment.OutgoingBytes Amazon. Per informazioni sull'utilizzo per CloudWatch monitorare Kinesis Video Streams, consulta Monitoring Kinesis Video Streams. Per informazioni sui prezzi, consulta Prezzi e prezzi di Amazon Kinesis Video Streams AWS . Si applicano i costi sia per le sessioni HLS che per i dati in uscita AWS .

Per ulteriori informazioni su HLS, consulta HTTP Live Streaming sul sito Apple Developer.

Importante

Se viene generato un errore dopo aver richiamato un'API multimediale archiviata di Kinesis Video Streams, oltre al codice di stato HTTP e al corpo della risposta, include le seguenti informazioni:

• x-amz-ErrorTypeIntestazione HTTP: contiene un tipo di errore più specifico oltre a quello fornito dal codice di stato HTTP.

• x-amz-RequestIdIntestazione HTTP: se desideri segnalare un problema al team di supporto, puoi diagnosticare meglio AWS il problema se fornisci il Request Id.

Sia il codice di stato HTTP che l' ErrorType intestazione possono essere utilizzati per prendere decisioni programmatiche sulla possibilità di riprovare gli errori e in quali condizioni, oltre a fornire informazioni sulle azioni che il programmatore del client potrebbe dover intraprendere per riprovare con successo.

Per ulteriori informazioni, consulta la sezione Errori nella parte inferiore di questo argomento, oltre a Errori comuni.

Sintassi della richiesta

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

Parametri della richiesta URI:

La richiesta non utilizza parametri URI.

Corpo della richiesta

La richiesta accetta i seguenti dati in formato JSON.

DASHFragmentSelector

L'intervallo di tempo del frammento richiesto e l'origine dei timestamp.

Questo parametro è obbligatorio se PlaybackMode è o. ON_DEMAND LIVE_REPLAY Questo parametro è facoltativo se lo PlaybackMode è LIVE. Se PlaybackMode sìLIVE, FragmentSelectorType può essere impostato, ma non TimestampRange deve essere impostato. Se PlaybackMode è ON_DEMAND oLIVE_REPLAY, entrambi FragmentSelectorType TimestampRange devono essere impostati.

Tipo: oggetto DASHFragmentSelector

Campo obbligatorio: no

DisplayFragmentNumber

I frammenti vengono identificati nel file manifesto in base al numero di sequenza nella sessione. Se DisplayFragmentNumber è impostato suALWAYS, il numero di frammento di Kinesis Video Streams viene aggiunto a ciascun elemento S nel file manifest con il nome dell'attributo «kvs:fn». Questi numeri di frammento possono essere utilizzati per la registrazione o per essere utilizzati con altri (ad esempio e). APIs GetMedia GetMediaForFragmentList È necessario un lettore multimediale MPEG-DASH personalizzato per sfruttare questi attributi personalizzati.

Il valore predefinito è NEVER.

Tipo: stringa

Valori validi: ALWAYS | NEVER

Campo obbligatorio: no

DisplayFragmentTimestamp

Secondo le specifiche MPEG-DASH, l'ora da parete dei frammenti nel file manifest può essere derivata utilizzando gli attributi presenti nel manifesto stesso. Tuttavia, in genere, i lettori multimediali compatibili con MPEG-DASH non gestiscono correttamente le lacune nella timeline multimediale. Kinesis Video Streams regola la timeline multimediale nel file manifesto per consentire la riproduzione di contenuti multimediali con discontinuità. Pertanto, l'ora dell'orologio da parete derivata dal file manifest potrebbe essere imprecisa. Se DisplayFragmentTimestamp è impostato suALWAYS, il timestamp preciso del frammento viene aggiunto a ogni elemento S nel file manifest con il nome dell'attributo «kvs:ts». È necessario un lettore multimediale MPEG-DASH personalizzato per sfruttare questo attributo personalizzato.

Il valore predefinito è NEVER. In caso DASHFragmentSelector affermativoSERVER_TIMESTAMP, i timestamp saranno i timestamp di inizio del server. Allo stesso modo, quando DASHFragmentSelector è cosìPRODUCER_TIMESTAMP, i timestamp saranno i timestamp di inizio del produttore.

Tipo: stringa

Valori validi: ALWAYS | NEVER

Campo obbligatorio: no

Expires

Il tempo in secondi che manca alla scadenza della sessione richiesta. Questo valore può essere compreso tra 300 (5 minuti) e 43200 (12 ore).

Quando una sessione scade, non è GetMP4MediaFragment possibile effettuare nuove chiamate a GetDashManifestGetMP4InitFragment, o per quella sessione.

Il valore predefinito è 300 (5 minuti).

Tipo: integer

Intervallo valido: valore minimo di 300. valore massimo pari a 43200.

Campo obbligatorio: no

MaxManifestFragmentResults

Il numero massimo di frammenti restituiti nel manifesto MPEG-DASH.

Quando PlaybackMode èLIVE, vengono restituiti i frammenti più recenti fino a questo valore. Quando PlaybackMode èON_DEMAND, vengono restituiti i frammenti più vecchi, fino a questo numero massimo.

Quando il numero di frammenti disponibili in un manifesto MPEG-DASH live è elevato, i lettori video spesso memorizzano il contenuto nel buffer prima di iniziare la riproduzione. L'aumento della dimensione del buffer aumenta la latenza di riproduzione, ma diminuisce la probabilità che si verifichi il rebuffering durante la riproduzione. Si consiglia che un manifesto MPEG-DASH live contenga un minimo di 3 frammenti e un massimo di 10 frammenti.

L'impostazione predefinita è 5 frammenti se è LIVE o LIVE_REPLAY e 1.000 se lo PlaybackMode è. PlaybackMode ON_DEMAND

Il valore massimo di 1.000 frammenti corrisponde a più di 16 minuti di video in stream con frammenti di 1 secondo e più di 2 ore e mezza di video in stream con frammenti di 10 secondi.

Tipo: long

Intervallo valido: valore minimo di 1. Valore massimo di 5000.

Campo obbligatorio: no

PlaybackMode

Sia che si tratti di recuperare dati live, replay dal vivo o archiviati su richiesta.

Le caratteristiche dei tre tipi di sessioni includono quanto segue:

• LIVE: Per sessioni di questo tipo, il manifesto MPEG-DASH viene continuamente aggiornato con i frammenti più recenti non appena diventano disponibili. Si consiglia al lettore multimediale di recuperare un nuovo manifesto a intervalli di un secondo. Quando questo tipo di sessione viene riprodotta in un lettore multimediale, l'interfaccia utente in genere visualizza una notifica «live», senza alcun controllo di scorrimento per scegliere la posizione da visualizzare nella finestra di riproduzione.

  Nota

  In LIVE modalità, i frammenti più recenti disponibili sono inclusi in un manifesto MPEG-DASH, anche se c'è uno spazio tra i frammenti (ovvero se manca un frammento). Un intervallo come questo potrebbe causare l'arresto di un lettore multimediale o un salto nella riproduzione. In questa modalità, i frammenti non vengono aggiunti al manifesto MPEG-DASH se sono più vecchi del frammento più recente della playlist. Se il frammento mancante diventa disponibile dopo l'aggiunta di un frammento successivo al manifesto, il frammento più vecchio non viene aggiunto e lo spazio vuoto non viene colmato.

• LIVE_REPLAY: Per le sessioni di questo tipo, il manifesto MPEG-DASH viene aggiornato in modo analogo a come viene aggiornato per la LIVE modalità, tranne per il fatto che inizia includendo i frammenti a partire da una determinata ora di inizio. Invece di aggiungere i frammenti man mano che vengono ingeriti, i frammenti vengono aggiunti man mano che trascorre la durata del frammento successivo. Ad esempio, se i frammenti della sessione durano due secondi, un nuovo frammento viene aggiunto al manifesto ogni due secondi. Questa modalità è utile per poter avviare la riproduzione dal momento in cui viene rilevato un evento e continuare lo streaming live di contenuti multimediali che non sono ancora stati acquisiti al momento della creazione della sessione. Questa modalità è utile anche per lo streaming di contenuti multimediali precedentemente archiviati senza essere limitata dal limite di 1.000 frammenti previsto dalla modalità. ON_DEMAND

• ON_DEMAND: Per le sessioni di questo tipo, il manifesto MPEG-DASH contiene tutti i frammenti della sessione, fino al numero specificato in. MaxManifestFragmentResults Il manifesto deve essere recuperato solo una volta per ogni sessione. Quando questo tipo di sessione viene riprodotta in un lettore multimediale, l'interfaccia utente in genere visualizza un controllo a scorrimento per scegliere la posizione da visualizzare nella finestra di riproduzione.

In tutte le modalità di riproduzione, se sì FragmentSelectorTypePRODUCER_TIMESTAMP, e se sono presenti più frammenti con lo stesso timestamp di inizio, il frammento con il numero di frammento maggiore (ovvero il frammento più recente) viene incluso nel manifesto MPEG-DASH. Gli altri frammenti non sono inclusi. I frammenti con timestamp diversi ma con durate sovrapposte sono ancora inclusi nel manifesto MPEG-DASH. Ciò può portare a un comportamento imprevisto nel lettore multimediale.

Il valore predefinito è LIVE.

Tipo: stringa

Valori validi: LIVE | LIVE_REPLAY | ON_DEMAND

Campo obbligatorio: no

StreamARN

L'Amazon Resource Name (ARN) dello stream per il quale recuperare l'URL del manifesto MPEG-DASH.

È necessario specificare il o il. StreamName StreamARN

Tipo: stringa

Limitazioni di lunghezza: lunghezza minima pari a 1. La lunghezza massima è 1024 caratteri.

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

Campo obbligatorio: no

StreamName

Il nome dello stream per il quale recuperare l'URL del manifesto MPEG-DASH.

È necessario specificare il o il. StreamName StreamARN

Tipo: stringa

Limitazioni di lunghezza: lunghezza minima pari a 1. La lunghezza massima è 256 caratteri.

Modello: [a-zA-Z0-9_.-]+

Campo obbligatorio: no

Sintassi della risposta

HTTP/1.1 200
Content-type: application/json

{
   "DASHStreamingSessionURL": "string"
}

Elementi di risposta

Se l'operazione riesce, il servizio restituisce una risposta HTTP 200.

I dati seguenti vengono restituiti in formato JSON mediante il servizio.

DASHStreamingSessionURL

L'URL (contenente il token di sessione) che un lettore multimediale può utilizzare per recuperare il manifesto MPEG-DASH.

Tipo: stringa

Errori

Per informazioni sugli errori comuni a tutte le operazioni, consultare Errori comuni.

ClientLimitExceededException

Kinesis Video Streams ha limitato la richiesta perché hai superato un limite. Prova a effettuare la chiamata più tardi. Per informazioni sui limiti, consulta la sezione Quote di Kinesis Video Streams.

Codice di stato HTTP: 400

InvalidArgumentException

Un parametro specificato supera le restrizioni, non è supportato o non può essere utilizzato.

Codice di stato HTTP: 400

InvalidCodecPrivateDataException

I dati privati del codec in almeno una delle tracce del flusso video non sono validi per questa operazione.

Codice di stato HTTP: 400

MissingCodecPrivateDataException

Non è stato trovato alcun dato privato del codec in almeno una delle tracce del flusso video.

Codice di stato HTTP: 400

NoDataRetentionException

GetImagesè stato richiesto per uno stream che non conserva dati (ovvero ha un valore DataRetentionInHours pari a 0).

Codice di stato HTTP: 400

NotAuthorizedException

Codice di stato: 403, il chiamante non è autorizzato a eseguire un'operazione sullo stream specificato o il token è scaduto.

Codice di stato HTTP: 401

ResourceNotFoundException

GetImagesgenererà questo errore quando Kinesis Video Streams non riesce a trovare lo stream specificato.

GetHLSStreamingSessionURLe GetDASHStreamingSessionURL genera questo errore se LIVE_REPLAY viene richiesta una sessione con un PlaybackMode of ON_DEMAND o per uno stream che non contiene frammenti nell'intervallo di tempo richiesto, o se LIVE viene richiesta una sessione con un PlaybackMode of per uno stream che non contiene frammenti negli ultimi 30 secondi.

Codice di stato HTTP: 404

UnsupportedStreamMediaTypeException

Il tipo di supporto (ad esempio, video h.264 o h.265 o audio AAC o G.711) non può essere determinato dal codec IDs delle tracce nel primo frammento per una sessione di riproduzione. L'ID del codec per la traccia 1 dovrebbe essere V_MPEG/ISO/AVC e, facoltativamente, l'ID del codec per la traccia 2 dovrebbe essere. A_AAC

Codice di stato HTTP: 400

Vedi anche

Per ulteriori informazioni sull'utilizzo di questa API in una delle lingue AWS SDKs specifiche, consulta quanto segue:

• Interfaccia a riga di comando AWS

• AWS SDK per.NET

• AWS SDK per C++

• AWS SDK per Go v2

• AWS SDK per Java V2

• AWS SDK per V3 JavaScript

• AWS SDK per PHP V3

• AWS SDK per Python

• AWS SDK per Ruby V3