GetHLSStreamingSessionURL - Flusso di video Amazon Kinesis
Sintassi della richiestaURIParametri della richiestaCorpo della richiestaSintassi della rispostaElementi di rispostaErroriVedi anche

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

GetHLSStreamingSessionURL

Recupera un HTTP Live Streaming (HLS) URL per lo stream. È quindi possibile aprirlo URL in un browser o lettore multimediale per visualizzare i contenuti dello streaming.

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

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

Le sessioni di Kinesis HLS Video Streams contengono frammenti MPEG nel formato frammentato -4 (MP4chiamato anche CMAF f o) MPEG o nel formato -2 (chiamato anche blocchi TS, supportato anche dalla specifica). HLS Per ulteriori informazioni sui tipi di HLS frammento, consulta le specifiche. HLS

La procedura seguente mostra come utilizzare HLS Kinesis Video Streams:

  1. Chiamali GetDataEndpoint API per ottenere un endpoint. Quindi invia le GetHLSStreamingSessionURL richieste a questo endpoint utilizzando il parametro --endpoint-url.

  2. HLSURLGetHLSStreamingSessionURLRecupera l'utilizzo. Kinesis Video Streams HLS crea una sessione di streaming da utilizzare per accedere ai contenuti di uno stream HLS utilizzando il protocollo. GetHLSStreamingSessionURLrestituisce un file autenticato URL (che include un token di sessione crittografato) per la playlist HLS principale della sessione (la risorsa principale necessaria per lo streaming con). HLS

    Nota

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

    I file multimediali resi disponibili tramite la playlist sono costituiti solo dallo stream, dall'intervallo di tempo e dal formato richiesti. Non sono disponibili altri dati multimediali (come frame esterni alla finestra richiesta o bitrate alternativi).

  3. Fornisci il file URL (contenente il token di sessione crittografato) per la playlist HLS principale a un lettore multimediale che supporti il HLS protocollo. Kinesis Video Streams HLS rende disponibili la playlist multimediale, il frammento di inizializzazione e i frammenti multimediali tramite la playlist principale. URL Il frammento di inizializzazione contiene i dati privati del codec per lo streaming e altri dati necessari per configurare il decodificatore e il renderer video o audio. I frammenti multimediali contengono fotogrammi video con codifica H.264 o campioni audio con codifica. AAC

  4. Il lettore multimediale riceve i metadati e i dati multimediali autenticati URL e trasmette normalmente i metadati e i dati multimediali. Quando il lettore multimediale richiede dati, richiama le seguenti azioni:

    • G etHLSMaster Playlist: recupera una playlist HLS principale, che contiene un'GetHLSMediaPlaylistazione URL per ogni traccia e metadati aggiuntivi per il lettore multimediale, tra cui bitrate e risoluzione stimati.

    • etHLSMediaPlaylist G: recupera una playlist HLS multimediale, che contiene un frammento di inizializzazione URL per accedere al frammento di MP4 inizializzazione con l'GetMP4InitFragmentazione e URLs per accedere ai frammenti multimediali con le MP4 azioni. GetMP4MediaFragment La playlist HLS multimediale contiene anche metadati sullo stream di cui il lettore ha bisogno per riprodurla, ad esempio se è o. PlaybackMode LIVE ON_DEMAND La playlist HLS multimediale è in genere statica per le sessioni con un PlaybackType diON_DEMAND. La playlist HLS multimediale viene continuamente aggiornata con nuovi frammenti per le sessioni con un PlaybackType di. LIVE Esiste una playlist HLS multimediale distinta per la traccia video e la traccia audio (se applicabile) che contiene i MP4 file multimediali URLs per la traccia specifica.

    • GetMP4InitFragment: recupera il frammento di MP4 inizializzazione. 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.

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

      Nota

      Il codec private data (CPD) contenuto in ogni frammento contiene informazioni di inizializzazione specifiche del codec, come la frequenza dei fotogrammi, la risoluzione e il profilo di codifica, necessarie per decodificare correttamente il frammento. Sia per TS che per, le modifiche sono supportate durante una sessione di streamingMP4. CPD Pertanto, i frammenti di una sessione possono contenere informazioni diverse CPD senza interrompere la riproduzione. Per ogni sessione di streaming, sono consentite solo 500 CPD modifiche.

      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 AAC audio viene trasformata in una traccia audio A-Law.

      I dati recuperati con questa azione sono fatturabili. Per informazioni, consulta Prezzi di .

    • GetTSFragment: Recupera MPEG i frammenti TS contenenti sia i dati di inizializzazione che quelli multimediali per tutte le tracce dello stream.

      Nota

      Se ContainerFormat èMPEG_TS, API viene utilizzato al posto di GetMP4InitFragment e per recuperare i contenuti multimediali GetMP4MediaFragment in streaming.

      I dati recuperati con questa azione sono fatturabili. Per ulteriori informazioni, consulta i prezzi di Kinesis Video Streams.

Una sessione di streaming non URL deve essere condivisa tra giocatori. Il servizio potrebbe rallentare una sessione se la condividono più lettori multimediali. Per i limiti di connessione, vedi 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 costi sia per le HLS sessioni che per i dati in uscita AWS .

Guarda gli esempi di riproduzione video nella guida alla documentazione: Usa il AWS CLI per recuperare una HLS sessione di streaming URL e. Esempio: da utilizzare HLS in HTML e JavaScript

Per ulteriori informazioniHLS, consulta HTTPLive Streaming sul sito per sviluppatori Apple.

Importante

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

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

  • x-amz-RequestIdHTTPheader: se desideri segnalare un problema AWS, il team di supporto può diagnosticare meglio il problema se gli viene fornito il Request Id.

Sia il codice di HTTP stato 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, consultate la sezione Errori nella parte inferiore di questo argomento, nonché Errori comuni.

Sintassi della richiesta

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

URIParametri della richiesta

La richiesta non utilizza alcun URI parametro.

Corpo della richiesta

La richiesta accetta i seguenti dati nel JSON formato.

ContainerFormat

Speciifica quale formato deve essere usato per impacchettare il supporto. Specificando il formato del FRAGMENTED_MP4 contenitore, il supporto viene confezionato in MP4 frammenti (f MP4 o). CMAF Questa è la confezione consigliata perché le spese di imballaggio sono minime. L'altra opzione di formato del contenitore èMPEG_TS. HLSsupporta MPEG i blocchi TS da quando è stato rilasciato e a volte è l'unico pacchetto supportato dai lettori più vecchiHLS. MPEGTS ha in genere un costo di imballaggio del 5-25%. Ciò significa che MPEG TS richiede in genere il 5-25 percento in più di larghezza di banda e costi rispetto a f. MP4

Il valore predefinito è FRAGMENTED_MP4.

Tipo: stringa

Valori validi: FRAGMENTED_MP4 | MPEG_TS

Campo obbligatorio: no

DiscontinuityMode

Speciifica quando i flag che indicano le discontinuità tra i frammenti vengono aggiunti alle playlist multimediali.

I lettori multimediali in genere creano una sequenza temporale dei contenuti multimediali da riprodurre, in base ai timestamp di ciascun frammento. Ciò significa che se c'è una sovrapposizione o uno spazio tra i frammenti (come in genere se HLSFragmentSelector è impostata suSERVER_TIMESTAMP), la timeline del lettore multimediale presenterà anche piccoli spazi tra i frammenti in alcuni punti e sovrascriverà i fotogrammi in altri punti. Le lacune nella timeline del lettore multimediale possono causare il blocco della riproduzione e le sovrapposizioni possono causare nervosismo nella riproduzione. Quando sono presenti segnali di discontinuità tra i frammenti, si prevede che il lettore multimediale reimposti la timeline, in modo che il frammento successivo venga riprodotto immediatamente dopo il frammento precedente.

Sono supportate le seguenti modalità:

  • ALWAYS: un indicatore di discontinuità viene inserito tra ogni frammento della playlist multimediale. HLS Si consiglia di utilizzare un valore pari a ALWAYS se i timestamp del frammento non sono accurati.

  • NEVER: nessun indicatore di discontinuità viene posizionato da nessuna parte. Si consiglia di utilizzare un valore di per NEVER garantire che la timeline del lettore multimediale corrisponda con la massima precisione ai timestamp del produttore.

  • ON_DISCONTINUITY: un marker di discontinuità viene posizionato tra i frammenti che presentano uno spazio o una sovrapposizione di oltre 50 millisecondi. Per la maggior parte degli scenari di riproduzione, si consiglia di utilizzare un valore pari a in ON_DISCONTINUITY modo che la timeline del lettore multimediale venga reimpostata solo in caso di problemi significativi con la timeline multimediale (ad esempio un frammento mancante).

L'impostazione predefinita è ALWAYS quando HLSFragmentSelector è impostata suSERVER_TIMESTAMP, e NEVER quando è impostata su. PRODUCER_TIMESTAMP

Tipo: stringa

Valori validi: ALWAYS | NEVER | ON_DISCONTINUITY

Campo obbligatorio: no

DisplayFragmentTimestamp

Speciifica quando i timestamp di inizio del frammento devono essere inclusi nella playlist multimediale. HLS In genere, i lettori multimediali segnalano la posizione della testina di riproduzione come un orario relativo all'inizio del primo frammento della sessione di riproduzione. Tuttavia, quando i timestamp di inizio sono inclusi nella playlist HLS multimediale, alcuni lettori multimediali potrebbero riportare la testina di riproduzione corrente come orario assoluto in base ai timestamp del frammento. Questo può essere utile per creare un'esperienza di riproduzione che mostri agli spettatori l'ora dell'orologio da parete del file multimediale.

Il valore predefinito è NEVER. In caso HLSFragmentSelector affermativoSERVER_TIMESTAMP, i timestamp saranno i timestamp di inizio del server. Allo stesso modo, quando HLSFragmentSelector è 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 è GetTSFragment possibile effettuare nuove chiamate a GetHLSMasterPlaylist GetHLSMediaPlaylistGetMP4InitFragment,GetMP4MediaFragment,, 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

HLSFragmentSelector

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 HLSFragmentSelector

Campo obbligatorio: no

MaxMediaPlaylistFragmentResults

Il numero massimo di frammenti restituiti nelle playlist HLS multimediali.

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 c'è un numero maggiore di frammenti disponibili in una playlist HLS multimediale dal vivo, 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. È consigliabile che una playlist HLS multimediale dal vivo contenga un minimo di 3 frammenti e un massimo di 10 frammenti.

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

Il valore massimo di 5.000 frammenti corrisponde a più di 80 minuti di video in stream con frammenti di 1 secondo e a più di 13 ore 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, la playlist HLS multimediale viene continuamente aggiornata con i frammenti più recenti non appena diventano disponibili. Si consiglia al lettore multimediale di recuperare una nuova playlist a intervalli di un secondo. Quando questo tipo di sessione viene riprodotta in un lettore multimediale, l'interfaccia utente in genere visualizza una notifica «dal vivo», senza alcun controllo di scorrimento per la scelta della posizione nella finestra di riproduzione da visualizzare.

    Nota

    In LIVE modalità, i frammenti più recenti disponibili vengono inclusi in una playlist HLS multimediale, 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 alla playlist HLS multimediale se sono più vecchi del frammento più recente della playlist. Se il frammento mancante diventa disponibile dopo l'aggiunta di un frammento successivo alla playlist, il frammento più vecchio non viene aggiunto e lo spazio vuoto non viene colmato.

  • LIVE_REPLAY: Per le sessioni di questo tipo, la playlist HLS multimediale viene aggiornata in modo analogo a come viene aggiornata per la LIVE modalità, tranne per il fatto che inizia includendo i frammenti di 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, viene aggiunto un nuovo frammento alla playlist multimediale 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 sessioni di questo tipo, la playlist HLS multimediale contiene tutti i frammenti della sessione, fino al numero specificato in. MaxMediaPlaylistFragmentResults La playlist deve essere recuperata solo una volta per ogni sessione. Quando questo tipo di sessione viene riprodotta in un lettore multimediale, l'interfaccia utente in genere visualizza un comando 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 maggior numero di frammenti (ovvero il frammento più recente) viene incluso nella playlist multimediale. HLS Gli altri frammenti non sono inclusi. I frammenti con timestamp diversi ma con durate sovrapposte sono comunque inclusi nella playlist multimediale. HLS 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 la playlist HLS URL principale.

Devi specificare il StreamName o ilStreamARN.

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 la playlist HLS URL principale.

È necessario specificare il StreamName o ilStreamARN.

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

{
   "HLSStreamingSessionURL": "string"
}

Elementi di risposta

Se l'azione ha esito positivo, il servizio restituisce una risposta di HTTP 200.

I seguenti dati vengono restituiti in JSON formato dal servizio.

HLSStreamingSessionURL

Il URL (contenente il token di sessione) che un lettore multimediale può utilizzare per recuperare la playlist HLS principale.

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.

HTTPCodice di stato: 400

InvalidArgumentException

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

HTTPCodice di stato: 400

InvalidCodecPrivateDataException

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

HTTPCodice di stato: 400

MissingCodecPrivateDataException

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

HTTPCodice di stato: 400

NoDataRetentionException

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

HTTPCodice di stato: 400

NotAuthorizedException

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

HTTPCodice di stato: 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.

HTTPCodice di stato: 404

UnsupportedStreamMediaTypeException

Il tipo di supporto (ad esempio, video h.264 o h.265 o AAC audio G.711) non può essere determinato dal codec IDs delle tracce del primo frammento di 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

HTTPCodice di stato: 400

Vedi anche

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