GetHLSStreamingSessionURL - Amazon Kinesis Video Streams

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 URL HTTP Live Streaming (HLS) per lo stream. È quindi possibile aprire l'URL in un browser o un lettore multimediale per visualizzare il contenuto dello streaming.

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

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

  • Il supporto deve contenere video con codifica h.264 o h.265 e, facoltativamente, audio con codifica AAC. Nello specifico, l'ID codec della traccia 1 dovrebbe essereV_MPEG/ISO/AVC(per h.264) oV_MPEG/ISO/HEVC(per h.265). Facoltativamente, l'ID codec della traccia 2 dovrebbe essereA_AAC.

  • La conservazione dei dati deve essere superiore a 0.

  • La traccia video di ogni frammento deve contenere dati codec privati in Advanced Video Coding (AVC) per il formato H.264 o HEVC per il formato H.265 (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 (Specifiche AAC ISO/IEC 13818-7).

Le sessioni HLS di Kinesis Video Streams contengono frammenti nel formato MPEG-4 frammentato (chiamato anche FMP4 o CMAF) o nel modulo MPEG-2 (chiamato anche chunks TS, che la specifica HLS supporta anche). Per ulteriori informazioni sui tipi di frammento HLS, consultaSpecifica HLS.

La procedura seguente mostra come utilizzare HLS con Kinesis Video Streams:

  1. Ottieni un endpoint usandoGetDataEndpoint, specificandoGET_HLS_STREAMING_SESSION_URLperAPINameParametro .

  2. Recupero dell'URL HLS utilizzandoGetHLSStreamingSessionURL. Kinesis Video Streams crea una sessione di streaming HLS da utilizzare per accedere al contenuto in un flusso utilizzando il protocollo HLS.GetHLSStreamingSessionURLrestituisce un URL autenticato (che include un token di sessione crittografato) per l'HLS della sessionemaster playlist(la risorsa principale necessaria per lo streaming con HLS).

    Nota

    Non condividere o memorizzare questo token in cui un'entità non autorizzata potrebbe accedervi. Il token fornisce accesso al contenuto dello stream. Proteggi il token con le stesse misure che utilizzerai con le tue credenziali AWS.

    Il supporto reso disponibile tramite la playlist è 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).

  3. Fornire l'URL (contenente il token di sessione crittografato) per la playlist master HLS a un lettore multimediale che supporta il protocollo HLS. Kinesis Video Streams rende disponibili la playlist multimediale HLS, il frammento di inizializzazione e i frammenti multimediali tramite l'URL della playlist principale. 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 con codifica H.264 o campioni audio con codifica AAC.

  4. 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:

    • GetHLSMasterPlaylist: Recupera una playlist master HLS, che contiene un URL perGetHLSMediaPlaylistazione per ogni traccia e metadati aggiuntivi per il lettore multimediale, inclusi bitrate e risoluzione stimati.

    • Playlist di GetHLSMediaPlaylist: Recupera una playlist multimediale HLS, che contiene un URL per accedere al frammento di inizializzazione MP4 conGetMP4InitFragmentazione e URL per accedere ai frammenti multimediali MP4 conGetMP4MediaFragmentoperazioni. La playlist multimediale HLS contiene anche metadati relativi allo stream di cui il lettore deve riprodurlo, ad esempio sePlaybackModeèLIVEoON_DEMAND. La playlist multimediale HLS è tipicamente statica per le sessioni conPlaybackTypediON_DEMAND. La playlist multimediale HLS viene costantemente aggiornata con nuovi frammenti per le sessioni conPlaybackTypediLIVE. Esiste una playlist multimediale HLS distinta per la traccia video e la traccia audio (se applicabile) che contiene URL multimediali MP4 per la traccia specifica.

    • GetMP4InitFragment: 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 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 ulteriori informazioni dettagliate.

    • Frammento GetTSFragment: Recupera frammenti MPEG TS contenenti dati di inizializzazione e supporti per tutte le tracce del flusso.

      Nota

      Se il fileContainerFormatèMPEG_TS, questa API viene utilizzata al posto diGetMP4InitFragmenteGetMP4MediaFragmentper recuperare i contenuti multimediali in streaming.

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

L'URL di una sessione di streaming non deve essere condiviso tra i giocatori. Il servizio potrebbe limitare una sessione se più lettori multimediali la condividono. Per i limiti di connessione, consultaLimiti per Kinesis Video Streams.

È possibile monitorare la quantità di dati consumata dal lettore multimediale monitorando ilGetMP4MediaFragment.OutgoingBytesAmazon CloudWatch Parametro. Per ulteriori 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 di AWS. Si applicano addebiti sia per le sessioni HLS che per i dati AWS in uscita.

Per ulteriori informazioni su HLS, consultaStreaming in tempo reale HTTPsulSito 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 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 .Errorisezione in fondo a 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" }

Parametri della richiesta URI:

La richiesta non utilizza parametri URI.

Corpo della richiesta

La richiesta accetta i seguenti dati in formato JSON.

ContainerFormat

Specifica il formato da utilizzare per il confezionamento del supporto. Specificazione delFRAGMENTED_MP4container format impacchetta il supporto in frammenti MP4 (FMP4 o CMAF). Questa è la confezione consigliata perché c'è un sovraccarico minimo di imballaggio. L'altra opzione per il formato contenitore èMPEG_TS. HLS ha supportato i blocchi MPEG TS da quando è stato rilasciato ed è talvolta l'unico pacchetto supportato sui lettori HLS più vecchi. MPEG TS in genere ha un sovraccarico di imballaggio del 5-25%. Ciò significa che MPEG TS richiede in genere il 5-25% di larghezza di banda e costi in più rispetto a FMP4.

Il valore predefinito è FRAGMENTED_MP4.

Type: Stringa

Valori validi: FRAGMENTED_MP4 | MPEG_TS

: campo obbligatorio No

DiscontinuityMode

Specifica quando i flag che contrassegnano le discontinuità tra i frammenti vengono aggiunti alle playlist multimediali.

I lettori multimediali in genere creano una timeline di 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 è tipico seHLSFragmentSelectorè impostato su .SERVER_TIMESTAMP), la timeline del lettore multimediale avrà 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 lo stallo della riproduzione e le sovrapposizioni possono causare la riproduzione inquietante. Quando ci sono flag di discontinuità tra i frammenti, si prevede che il lettore multimediale ripristini la timeline, con conseguente riproduzione del frammento successivo immediatamente dopo il frammento precedente.

Sono supportate le seguenti modalità:

  • ALWAYS: un marcatore di discontinuità è posizionato tra ogni frammento della playlist multimediale HLS. Si consiglia di utilizzare un valore diALWAYSse i timestamp del frammento non sono accurati.

  • NEVER: nessun pennarello di discontinuità è posizionato ovunque. Si consiglia di utilizzare un valore diNEVERper garantire che la timeline del lettore multimediale mappi in modo più accurato ai timestamp del produttore.

  • ON_DISCONTINUITY: un marcatore di discontinuità è posizionato tra 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 diON_DISCONTINUITYin modo che la timeline del lettore multimediale venga reimpostata solo quando si verifica un problema significativo con la timeline multimediale (ad esempio un frammento mancante).

Il valore predefinito èALWAYSquandoHLSFragmentSelectorè impostato su .SERVER_TIMESTAMP, eNEVERquando è impostato suPRODUCER_TIMESTAMP.

Type: Stringa

Valori validi: ALWAYS | NEVER | ON_DISCONTINUITY

: campo obbligatorio No

DisplayFragmentTimestamp

Specifica 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 tempo rispetto all'inizio del primo frammento nella sessione di riproduzione. Tuttavia, quando i timestamp iniziali sono inclusi nella playlist multimediale HLS, alcuni lettori multimediali potrebbero segnalare la testina di riproduzione corrente come un tempo assoluto basato sui timestamp del frammento. Questo può essere utile per creare un'esperienza di riproduzione che mostra agli spettatori l'ora dell'orologio da parete del supporto.

Il valore predefinito è NEVER. QuandoHLSFragmentSelectorèSERVER_TIMESTAMP, i timestamp saranno i timestamp di avvio del server. Allo stesso modo, quandoHLSFragmentSelectorè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 aGetHLSMasterPlaylist,GetHLSMediaPlaylist,GetMP4InitFragment,GetMP4MediaFragment, oppureGetTSFragmentpuò 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

HLSFragmentSelector

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: HLSFragmentSelector oggetto

: campo obbligatorio No

MaxMediaPlaylistFragmentResults

Il numero massimo di frammenti restituiti nelle playlist multimediali HLS.

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 è disponibile un numero maggiore di frammenti disponibili in una playlist multimediale HLS 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. Consigliamo che una playlist multimediale HLS live 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 5.000 frammenti corrisponde a più di 80 minuti di video su stream con frammenti di 1 secondo e più di 13 ore di video su stream 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 quanto segue:

  • LIVE : Per le sessioni di questo tipo, la playlist multimediale HLS viene continuamente aggiornata con i frammenti più recenti man mano che diventano disponibili. Si consiglia al lettore multimediale di recuperare una nuova playlist 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 una playlist multimediale HLS, 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 alla playlist multimediale HLS 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 precedente non viene aggiunto e lo spazio non viene riempito.

  • LIVE_REPLAY : Per le sessioni di questo tipo, la playlist multimediale HLS viene aggiornata in modo simile a come viene aggiornataLIVEmodalità 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 alla playlist multimediale 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, la playlist multimediale HLS contiene tutti i frammenti per la sessione, fino al numero specificato inMaxMediaPlaylistFragmentResults. La playlist deve essere recuperata 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) è incluso nella playlist multimediale HLS. Gli altri frammenti non sono inclusi. I frammenti con timestamp diversi ma con durate sovrapposte sono ancora inclusi nella playlist multimediale HLS. Ciò può portare a comportamenti inaspettati nel lettore multimediale.

Il valore predefinito è LIVE.

Type: Stringa

Valori validi: LIVE | LIVE_REPLAY | ON_DEMAND

: campo obbligatorio No

StreamARN

L'ARN dello stream per cui recuperare l'URL della playlist principale HLS.

È 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 cui recuperare l'URL della playlist principale HLS.

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

HLSStreamingSessionURL

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

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 ulteriori informazioni sui limiti, 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 conDataRetentionInHoursdi 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: