Sintassi della richiesta Parametri della richiesta URI:Corpo della richiesta Sintassi della risposta Elementi di risposta Errori Vedi anche

GetDASHStreamingSessionURL

Recuperare un URL MPEG Dynamic Adaptive Streaming over HTTP (DASH) per il flusso. Puoi quindi aprire l'URL in un lettore multimediale per visualizzare il contenuto del flusso.

Entrambi iStreamNamee laStreamARNi parametri sono facoltativi, ma è necessario specificare ilStreamNameo ilStreamARNquando si richiama questa operazione API.

Un flusso video Amazon Kinesis prevede i seguenti requisiti per la visualizzazione di dati tramite MPEG-DASH:

Il supporto deve contenere video con codifica h.264 o h.265 e, facoltativamente, audio con codifica G.711 o AAC. Nello specifico, l'ID codec della traccia 1 deve essere V_MPEG/ISO/AVC (per h.264) o V_MPEGH/ISO/HEVC (per H.265). In alternativa, l'ID codec della traccia 2 deve essere A_AAC (per AAC) o A_MS/ACM (per G.711).
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:

Ottieni un endpoint usandoGetDataEndpoint, specificandoGET_DASH_STREAMING_SESSION_URLperAPINameParametro .
Recuperare l'URL MPEG-DASH utilizzandoGetDASHStreamingSessionURL. Kinesis Video Streams crea una sessione di streaming MPEG-DASH da utilizzare per accedere al contenuto in un flusso utilizzando il protocollo MPEG-DASH.GetDASHStreamingSessionURLrestituisce un URL autenticato (che include un token di sessione crittografato) per MPEG-DASH della sessionemanifesto(la risorsa principale necessaria per lo streaming con MPEG-DASH).

Nota
Non condividere o memorizzare questo token dove un'entità non autorizzata può accedervi. Il token fornisce accesso al contenuto dello stream. Proteggete il token con le stesse misure utilizzate con le credenziali AWS.

Il supporto reso disponibile tramite il manifest è costituito solo dal flusso richiesto, dall'intervallo di tempo e dal formato. Non sono disponibili altri dati multimediali (come fotogrammi esterni alla finestra richiesta o bitrate alternativi).
Fornire l'URL (contenente il token di sessione crittografato) per il manifesto MPEG-DASH a un lettore multimediale che supporta il protocollo MPEG-DASH. Kinesis Video Streams rende disponibili il frammento di inizializzazione e i frammenti multimediali tramite l'URL manifesto. Il frammento di inizializzazione contiene i dati privati del codec per lo stream e altri dati necessari per configurare il decoder e il renderer video o audio. I frammenti multimediali contengono fotogrammi video codificati o campioni audio codificati.
Il lettore multimediale riceve l'URL autenticato e richiede normalmente metadati e dati multimediali in streaming. Quando il lettore multimediale richiede dati, chiama le seguenti azioni:
- Ottieni DashManifest: Recupera un manifest MPEG DASH, che contiene i metadati per il supporto che si desidera riprodurre.
- GetMP4InitFragment: Recupera il frammento di inizializzazione MP4. Il lettore multimediale in genere carica il frammento di inizializzazione prima di caricare eventuali frammenti multimediali. Questo frammento contiene il»fytp«e»moov«Atomi MP4 e gli atomi infantili necessari per inizializzare il decoder del lettore multimediale.
  
  Il frammento di inizializzazione non corrisponde a un frammento in un flusso video Kinesis. Contiene solo i dati privati del codec per lo stream e il rispettivo brano, di cui il lettore multimediale deve decodificare i fotogrammi multimediali.
- GetMP4MediaFragment: Recupera frammenti multimediali MP4. Questi frammenti contengono il»moof«e»mdat«Gli atomi MP4 e i loro atomi figlio, contenenti i fotogrammi multimediali del frammento codificato e i relativi timestamp.
  
  Nota
  Dopo che il primo frammento multimediale è stato reso disponibile in una sessione di streaming, tutti i frammenti che non contengono gli stessi dati privati del codec causano la restituzione di un errore quando vengono caricati questi diversi frammenti multimediali. Pertanto, i dati privati del codec non dovrebbero cambiare tra i frammenti in una sessione. Ciò significa anche che la sessione non riesce se i frammenti in un flusso cambiano dall'avere solo video a quelli audio e video.
  
  I dati recuperati con questa azione sono fatturabili. Consulta .Prezziper dettagli dettagliati.

Nota

Per le restrizioni applicabili alle sessioni MPEG-DASH, vedereLimiti per Kinesis Video Streams.

È possibile monitorare la quantità di dati consumata dal lettore multimediale monitorando ilGetMP4MediaFragment.OutgoingBytesAmazon CloudWatch Parametro. Per informazioni sull'uso di CloudWatch per monitorare Kinesis Video Streams, vedereMonitoraggio di Kinesis Video Streams. Per informazioni sui prezzi, consultaPrezzi di Amazon Kinesis Video StreamsePrezzi AWS Pricing. Si applicano addebiti sia per le sessioni HLS che per i dati AWS in uscita.

Per ulteriori informazioni su HLS, consultaStreaming HTTP LivesulSito Apple Developer.

Importante

Se viene generato un errore dopo aver richiamato un'API multimediale archiviata 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 si desidera segnalare un problema ad AWS, il team di supporto può diagnosticare meglio il problema se viene fornito il Request Id.

Il codice di stato HTTP e il ErrorType header può essere utilizzato per prendere decisioni programmatiche sul fatto che gli errori siano retrattili e in quali condizioni, oltre a fornire informazioni sulle azioni che il programmatore client potrebbe dover intraprendere per riprovare con successo.

Per ulteriori informazioni, consulta la .Errorinella parte inferiore di questo argomento, nonché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 temporale del frammento richiesto e la fonte dei timestamp.

Questo parametro è richiesto sePlaybackModeèON_DEMANDoLIVE_REPLAY. Questo parametro è facoltativo se PlaybackMode è LIVE. SePlaybackModeèLIVE, ilFragmentSelectorTypepuò essere impostato, ma ilTimestampRangenon dovrebbe essere impostato. SePlaybackModeèON_DEMANDoLIVE_REPLAY, entrambiFragmentSelectorTypeeTimestampRangedeve essere impostato.

Tipo: DASHFragmentSelector oggetto

: campo obbligatorio No

DisplayFragmentNumber

I frammenti vengono identificati nel file manifesto in base al numero di sequenza nella sessione. Se DisplayFragmentNumber è impostato su .ALWAYS, il numero del frammento 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 l'uso con altre API (ad es.GetMediaeGetMediaForFragmentList). Per sfruttare questi attributi personalizzati è necessario un lettore multimediale MPEG-DASH personalizzato.

Il valore di default è NEVER.

Type: Stringa

Valori validi: ALWAYS | NEVER

: campo obbligatorio No

DisplayFragmentTimestamp

Secondo la specifica MPEG-DASH, il tempo dell'orologio da parete dei frammenti nel file manifesto può essere derivato utilizzando attributi nel manifest 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 dei supporti con discontinuità. Pertanto, il tempo dell'orologio da parete derivato dal file manifesto potrebbe essere impreciso. Se DisplayFragmentTimestamp è impostato su .ALWAYS, il timestamp del frammento accurato viene aggiunto a ciascun elemento S nel file manifest con il nome dell'attributo «kvs:ts». Per sfruttare questo attributo personalizzato è necessario un lettore multimediale MPEG-DASH personalizzato.

Il valore di default è NEVER. QuandoDASHFragmentSelectorèSERVER_TIMESTAMP, i timestamp saranno i timestamp di avvio del server. Allo stesso modo, quandoDASHFragmentSelectorèPRODUCER_TIMESTAMP, i timestamp saranno i timestamp iniziali del produttore.

Type: Stringa

Valori validi: ALWAYS | NEVER

: campo obbligatorio No

Expires

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

Quando una sessione scade, nessuna nuova chiamata aGetDashManifest,GetMP4InitFragment, oppureGetMP4MediaFragmentpuò essere fatto per quella sessione.

Il valore predefinito è 300 (5 minuti).

Type: Numero intero

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

: campo obbligatorio No

MaxManifestFragmentResults

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

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

Quando c'è un numero maggiore di frammenti disponibili in un manifesto MPEG-DASH live, i lettori video spesso eseguono il buffer dei contenuti prima di iniziare la riproduzione. L'aumento delle dimensioni del buffer aumenta la latenza di riproduzione, ma diminuisce la probabilità che si verifichi un rebuffering durante la riproduzione. Raccomandiamo che un manifesto MPEG-DASH vivo abbia un minimo di 3 frammenti e un massimo di 10 frammenti.

Il valore predefinito è 5 frammenti sePlaybackModeèLIVEoLIVE_REPLAY, e 1.000 sePlaybackModeèON_DEMAND.

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

Type: Lungo

Intervallo valido: Valore minimo di 1. Valore massimo pari a 5000.

: campo obbligatorio No

PlaybackMode

Se recuperare dati live, live replay o archiviati su richiesta.

Le caratteristiche dei tre tipi di sessioni includono:

LIVE : Per le 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 manifest in un intervallo di un secondo. Quando questo tipo di sessione viene riprodotto in un lettore multimediale, l'interfaccia utente in genere visualizza una notifica «live», senza alcun controllo di scrubber per scegliere la posizione nella finestra di riproduzione da visualizzare.

Nota
Nello statoLIVEmodalità, i frammenti più recenti disponibili sono inclusi in un manifesto MPEG-DASH, anche se c'è uno spazio tra i frammenti (cioè se manca un frammento). Un divario come questo potrebbe causare l'arresto di un lettore multimediale o causare 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 precedente non viene aggiunto e lo spazio non viene riempito.
LIVE_REPLAY : Per le sessioni di questo tipo, il manifesto MPEG-DASH viene aggiornato in modo simile a come viene aggiornatoLIVEmodalità tranne che inizia includendo frammenti da un determinato orario di inizio. Invece di aggiungere frammenti quando vengono ingeriti, vengono aggiunti frammenti man mano che trascorre la durata del frammento successivo. Ad esempio, se i frammenti della sessione sono lunghi due secondi, viene aggiunto un nuovo frammento al manifest ogni due secondi. Questa modalità è utile per poter avviare la riproduzione da quando viene rilevato un evento e continuare il live streaming multimediale che non è ancora stato ingerito al momento della creazione della sessione. Questa modalità è utile anche per eseguire lo streaming di supporti precedentemente archiviati senza essere limitata dal limite di 1.000 frammenti nelON_DEMANDmodalità.
ON_DEMAND : per le sessioni di questo tipo, il manifesto MPEG-DASH contiene tutti i frammenti per la sessione, fino al numero specificato inMaxManifestFragmentResults. Il manifest deve essere recuperato una sola volta per ogni sessione. Quando questo tipo di sessione viene riprodotto in un lettore multimediale, l'interfaccia utente in genere visualizza un controllo di scrubber per scegliere la posizione nella finestra di riproduzione da visualizzare.

In tutte le modalità di riproduzione, seFragmentSelectorTypeèPRODUCER_TIMESTAMPe se ci sono più frammenti con lo stesso timestamp iniziale, il frammento con il numero di frammento più grande (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 comportamenti imprevisti nel lettore multimediale.

Il valore predefinito è LIVE.

Type: Stringa

Valori validi: LIVE | LIVE_REPLAY | ON_DEMAND

: campo obbligatorio No

StreamARN

L'ARN del flusso per cui recuperare l'URL del manifesto MPEG-DASH.

È necessario specificare ilStreamNameo ilStreamARN.

Type: Stringa

Vincoli 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 ilStreamNameo ilStreamARN.

Type: Stringa

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

Type: 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 di, consultaLimiti per 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 sono stati trovati dati privati codec in almeno una delle tracce del flusso video.

Codice di stato HTTP: 400

NoDataRetentionException

È stata richiesta una sessione di streaming per un flusso che non conservi alcun dato (ovvero ha unDataRetentionInHoursdi 0).

Codice di stato HTTP: 400

NotAuthorizedException

Codice di stato: 403, Il chiamante non è autorizzato a eseguire un'operazione sul flusso 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.

GetHLSStreamingSessionURLeGetDASHStreamingSessionURLgenera questo errore se una sessione con unPlaybackModediON_DEMANDoLIVE_REPLAYè richiesto per uno stream che non ha frammenti nell'intervallo di tempo richiesto o se una sessione con unPlaybackModediLIVEè richiesto per uno stream che non ha 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 ACC o G.711) non può essere determinato dagli ID codec delle tracce nel primo frammento per una sessione di riproduzione. L'ID codec per il brano 1 dovrebbe essereV_MPEG/ISO/AVCe, facoltativamente, l'ID codec per il brano 2 dovrebbe essereA_AAC.

Codice di stato HTTP: 400

Vedi anche

Per ulteriori informazioni sull'utilizzo di questa API in uno degli SDK AWS specifici della lingua, consulta quanto segue:

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

GetClip

GetHLSStreamingSessionURL