Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Guida per gli sviluppatori
Amazon Kinesis Video Streams: Guida per gli sviluppatori Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.
Amazon's trademarks and trade dress may not be used in connection with any product or service that is not Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may or may not be affiliated with, connected to, or sponsored by Amazon. Amazon Kinesis Video Streams Guida per gli sviluppatori
Table of Contents
Che cos'è Amazon Kinesis Video Streams? ...... 1 Primo utilizzo di Kinesis Video Streams? ...... 2 Requisiti di sistema ...... 3 Requisiti della videocamera ...... 3 Sistemi operativi testati ...... 3 Requisiti di storage per l'SDK ...... 4 Come funziona ...... 5 Producer Library e API ...... 6 API Kinesis Video Streams ...... 6 Producer Library ...... 8 Video Playback (Riproduzione video) ...... 9 Riproduzione di video con HLS ...... 9 Riproduzione video con MPEG-DASH ...... 13 Utilizzo dei metadati di streaming ...... 15 Aggiunta di metadati a Kinesis Video Stream ...... 16 Consumo dei metadati incorporati in Kinesis Video Stream ...... 17 Limitazioni dello streaming di metadati ...... 18 Modello di dati ...... 18 Elementi di intestazione del flusso ...... 19 Streaming dei dati della traccia ...... 22 Elementi di intestazione del frame ...... 23 Dati del frame MKV ...... 23 Nozioni di base ...... 24 Fase 1: impostazione di un account ...... 24 Registrazione ad AWS ...... 24 Creazione di un utente IAM amministratore ...... 25 Per creare una chiave account AWS ...... 25 Fase successiva ...... 26 Fase 2: creazione di un flusso video Kinesis ...... 26 Creazione di un flusso video tramite console ...... 26 Creazione di un flusso video tramite AWS CLI ...... 26 Fase successiva ...... 26 Fase 3: invio dei dati al flusso video Kinesis ...... 27 Fase successiva ...... 27 Fase 4: consumo di dati multimediali ...... 27 Visualizzazione dei dati multimediali nella console ...... 27 Consumo dei dati dei media tramite HLS ...... 27 Fase successiva ...... 27 Fasi successive ...... 28 Sicurezza ...... 29 Protezione dei dati ...... 29 Cos'è la crittografia lato server per Kinesis Video Streams? ...... 30 Considerazioni su costi, regioni e prestazioni ...... 30 Cosa devo fare per iniziare a utilizzare la crittografia lato server? ...... 31 Creazione e utilizzo di chiavi master AWS KMS generate dall'utente ...... 31 Autorizzazioni per l'uso di chiavi master AWS KMS generate dall'utente ...... 32 Controllo dell'accesso alle risorse Kinesis Video Streams che utilizzano IAM ...... 33 Sintassi delle policy ...... 33 Operazioni per Kinesis Video Streams ...... 34 Amazon Resource Name (ARN) per Kinesis Video Streams ...... 34 Concessione dell'accesso ad altri account IAM a un flusso di video Kinesis ...... 35 Policy di esempio ...... 35 Controllo dell'accesso alle risorse Kinesis Video Streams utilizzando AWS IoT ...... 37 IoT ThingName come nome del flusso ...... 37
iii Amazon Kinesis Video Streams Guida per gli sviluppatori
IoT CertificateID come nome del flusso ...... 42 Monitoraggio ...... 43 Convalida della conformità ...... 43 Flessibilità ...... 44 Sicurezza dell'infrastruttura ...... 44 Best practice di sicurezza ...... 44 Implementazione dell'accesso ai privilegi minimi ...... 44 Uso di ruoli IAM ...... 45 Uso di CloudTrail per il monitoraggio delle chiamate API ...... 45 Producer Library ...... 46 Client Kinesis Video Streams Producer ...... 46 Kinesis Video Streams Producer Library ...... 47 Argomenti correlati ...... 47 Java Producer Library ...... 47 Procedura: utilizzo dell'SDK Java Producer ...... 48 Fase 1: download e configurazione del codice ...... 48 Fase 2: scrittura e analisi del codice ...... 49 Fase 3: esecuzione e verifica del codice ...... 50 Android Producer Library ...... 51 Procedura: utilizzo dell'SDK del producer Android ...... 51 Fase 1: download e configurazione del codice ...... 53 Fase 2: analisi del codice ...... 54 Fase 3: esecuzione e verifica del codice ...... 55 C++ Producer Library ...... 56 Modello di oggetto ...... 56 Inserimento di dati multimediali nel flusso ...... 56 Interfacce di richiamata ...... 57 Procedura: utilizzo dell'SDK del producer C++ ...... 57 Fase 1: download e configurazione del codice ...... 59 Fase 2: scrittura e analisi del codice ...... 59 Fase 3: esecuzione e verifica del codice ...... 64 Utilizzo di C++ Producer SDK come GStreamer Plugin ...... 64 Utilizzo dell'SDK C++ Producer come plugin GStreamer in un container Docker ...... 64 Uso del logging ...... 65 C Producer Library ...... 65 Modello di oggetto ...... 65 Inserimento di dati multimediali nel flusso ...... 66 Procedura: utilizzo dell'SDK del producer C ...... 66 Fase 1: Download del codice ...... 68 Fase 2: scrittura e analisi del codice ...... 68 Fase 3: esecuzione e verifica del codice ...... 70 Riferimento ...... 72 Limiti dell'SDK producer ...... 72 Documentazione di riferimento per il codice di errore ...... 74 Flag di adattamento del NAL ...... 101 Strutture del producer ...... 102 Strutture di flussi ...... 104 Callback ...... 115 Libreria parser del flusso ...... 121 Procedura: utilizzo della libreria parser del flusso video Kinesis ...... 121 Prerequisiti ...... 121 Fase 1: download e configurazione del codice ...... 122 Fase successiva ...... 122 Fase 2: scrittura e analisi del codice ...... 122 StreamingMkvReader ...... 122 FragmentMetadataVisitor ...... 123 OutputSegmentMerger ...... 124
iv Amazon Kinesis Video Streams Guida per gli sviluppatori
KinesisVideoExample ...... 125 Fase successiva ...... 127 Fase 3: esecuzione e verifica del codice ...... 127 Esempi ...... 128 Esempi: invio di dati a Kinesis Video Streams ...... 128 Esempi: recupero dei dati da Kinesis Video Streams ...... 128 Esempi: riproduzione di dati video ...... 128 Prerequisites ...... 128 GStreamer ...... 129 Scaricare, creare e configurare l'elementoGStreamer ...... 130 Esecuzione dell'elementoGStreamer ...... 130 Comandi di avvio ...... 130 Esecuzione dell'elemento GStreamer in un container Docker ...... 132 Parametri del server ...... 135 APIPutMedia ...... 138 Fase 1: download e configurazione del codice ...... 138 Fase 2: scrittura e analisi del codice ...... 139 Fase 3: esecuzione e verifica del codice ...... 140 RTSP e Docker ...... 141 Prerequisites ...... 141 Creazione dell'immagine Docker ...... 141 Eseguire l'applicazione di esempio RTSP ...... 142 Renderer ...... 142 Prerequisites ...... 143 Esecuzione dell'esempio di Renderer ...... 143 Come funziona ...... 143 SageMaker ...... 144 Prerequisites ...... 145 Creazione dell'applicazione ...... 146 Monitoraggio dell'applicazione ...... 147 Ampliamento dell'applicazione ...... 149 Pulizia dell'applicazione ...... 149 Monitoraggio ...... 151 Monitoraggio dei parametri di con CloudWatch ...... 151 CloudWatchGuida ai parametri di ...... 159 Registrazione delle chiamate API con CloudTrail ...... 162 Kinesis Video Streams e CloudTrail ...... 162 Esempio: Voci di file di log Amazon Kinesis Video Streams ...... 163 Limiti ...... 167 Limiti API del piano di controllo ...... 167 Limiti per i file multimediali e le API dei file multimediali archiviati ...... 168 Quote framment-metadata e fragment-media ...... 170 Risoluzione dei problemi ...... 173 Risoluzione dei problemi generali ...... 173 Latenza troppo elevata ...... 173 Risoluzione dei problemi correlati alla configurazione API ...... 173 Errore: "Opzioni sconosciute" ...... 174 Errore: "Unable to determine service/operation name to be authorized" (Impossibile determinare il nome del servizio/operazione da autorizzare) ...... 174 Errore: "Failed to put a frame in the stream" (Impossibile inserire un fotogramma nel flusso) ...... 174 Errore: "Service closed connection before final AckEvent was received" (Connessione chiusa dal servizio prima della ricezione dell'oggetto AckEvent finale) ...... 175 Errore "STATUS_STORE_OUT_OF_MEMORY" ...... 175 Risoluzione dei problemi correlati alla configurazione HLS ...... 175 Il recupero dell'URL della sessione di streaming HLS riesce, ma si verifica un problema di riproduzione nel lettore video ...... 176 Latenza troppo elevata tra il producer e il lettore ...... 176
v Amazon Kinesis Video Streams Guida per gli sviluppatori
Risoluzione dei problemi con Java ...... 177 Abilitazione dei log di Java ...... 177 Risoluzione dei problemi con la libreria del producer ...... 178 Impossibile compilare l'SDK producer ...... 178 Il flusso video non viene visualizzato nella console ...... 179 Errore "Security token included in the request is invalid" durante lo streaming dei dati con l'applicazione demo GStreamer ...... 179 Errore "Failed to submit frame to Kinesis Video client" ...... 179 L'applicazione GStreamer viene arrestata con il messaggio "streaming stopped, reason not- negotiated" su OS X ...... 180 Errore "Failed to allocate heap" durante la creazione del client Kinesis Video nella demo GStreamer su Raspberry Pi ...... 180 Errore "Illegal Instruction" durante l'esecuzione della demo GStreamer su Raspberry Pi ...... 180 La videocamera non viene caricata su Raspberry Pi ...... 180 Impossibile trovare la videocamera su macOS High Sierra ...... 181 File jni.h non trovato durante la compilazione su macOS High Sierra ...... 181 Errori di curl durante l'esecuzione dell'applicazione demo GStreamer ...... 181 Asserzione timestamp/intervallo in fase di runtime su Raspberry Pi ...... 181 Asserzione su gst_value_set_fraction_range_full su Raspberry Pi ...... 182 STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATA (0x3200000d) error on Android ..... 182 Errore di durata massima del frammento raggiunta ...... 182 Errore "Invalid thing name passed (Passato nome di cosa non valido)" quando si utilizza l'autorizzazione IoT ...... 183 Risoluzione dei problemi con la libreria parser del flusso ...... 183 Impossibile accedere a un singolo fotogramma del flusso ...... 183 Errore di decodifica frammento ...... 183 Cronologia dei documenti ...... 185 Riferimento alle API ...... 188 Actions ...... 188 Amazon Kinesis Video Streams ...... 188 Amazon Kinesis Video Streams Media ...... 245 Amazon Kinesis Video Streams Archived Media ...... 257 Data Types ...... 284 Amazon Kinesis Video Streams ...... 285 Amazon Kinesis Video Streams Media ...... 295 Amazon Kinesis Video Streams Archived Media ...... 297 Common Errors ...... 306 Common Parameters ...... 308 ...... cccx
vi Amazon Kinesis Video Streams Guida per gli sviluppatori
Che cos'è Amazon Kinesis Video Streams?
Amazon Kinesis Video Streams è un servizio AWS completamente gestito che è possibile utilizzare per lo streaming live di video dai dispositivi al cloud AWS oppure per creare applicazioni per l'elaborazione di video in tempo reale o eseguire analisi dei video in batch.
Kinesis Video Streams non serve solo ad archiviare dati video, ma anche a visualizzare i flussi video in tempo reale nel momento stesso in cui vengono ricevuti nel cloud. Consente di monitorare i flussi in tempo reale nella Console di gestione AWS oppure di sviluppare applicazioni personali per il monitoraggio che sfruttano la libreria di API di Kinesis Video Streams per mostrare video in tempo reale.
È possibile utilizzare Kinesis Video Streams per acquisire in tempo reale grandi volumi di dati video provenienti da milioni di sorgenti, compresi smartphone, telecamere di sicurezza, webcam, telecamere integrate nelle automobili, droni e altre origini, ma anche inviare dati non video serializzati nel tempo, ad esempio dati audio, immagini termiche, dati RADAR o sulla profondità e molto altro. Quando il video live viene inviato in streaming da queste origini a un flusso video Kinesis, è possibile creare applicazioni che possono accedere ai dati, fotogramma per fotogramma, in tempo reale per l'elaborazione a bassa latenza. Kinesis Video Streams è indipendente dall'origine. È possibile inviare video in streaming dalla webcam di un computer utilizzando la libreria GStreamer (p. 129) o da una videocamera in rete utilizzando RTSP.
È anche possibile configurare il flusso video Kinesis per archiviare contenuti multimediali in modo persistente per il periodo di conservazione specificato. Kinesis Video Streams archivia automaticamente questi dati e li crittografa quando sono inattivi. Inoltre, Kinesis Video Streams indicizza nel tempo i dati archiviati in base ai timestamp producer e di inserimento. È possibile creare applicazioni che elaborano periodicamente in batch i dati video o che richiedono l'accesso ad hoc ai dati storici per diversi casi d'uso.
Le applicazioni personalizzate, orientate al batch o in tempo reale, possono essere eseguite sulle istanze Amazon EC2. Queste applicazioni possono elaborare i dati utilizzando algoritmi deep-learning open source o applicazioni di terze parti integrate con Kinesis Video Streams.
Alcuni dei vantaggi derivanti dall'uso di Kinesis Video Streams sono:
• Connessione e streaming da milioni di dispositivi – Kinesis Video Streams Consente di connettersi ed eseguire lo streaming di video, audio e altri dati provenienti da milioni di dispositivi quali smartphone, droni consumer, dash cam e molto altro. È possibile usare le librerie del producer Kinesis Video Streams per configurare i propri dispositivi ed eseguire lo streaming in tempo reale e in modo affidabile oppure per caricare i contenuti multimediali in un secondo momento. • Archiviare, crittografare e indicizzare i dati in modo persistente – È possibile configurare il flusso video Kinesis in modo da memorizzare i dati multimediali in modo persistente nel periodo di conservazione richiesto dal cliente. Kinesis Video Streams genera inoltre un indice mediante i dati archiviati in base ai timestamp generati dal producer o lato server. grazie al quale le applicazioni possono facilmente recuperare i dati specificati in un flusso. • Focus sulla gestione delle applicazioni – Kinesis Video Streams È serverless, perciò non ci sono infrastrutture da configurare o gestire. Non dovrai preoccuparti per la distribuzione, la configurazione o il dimensionamento elastico dell'infrastruttura sottostante quando i flussi di dati e il numero di applicazioni in uso aumenta e diminuisce. Kinesis Video Streams esegue automaticamente tutte le operazioni di gestione e manutenzione di flussi, in modo da concentrarsi sulle applicazioni, non sull'infrastruttura. • Creazione di applicazioni in tempo reale e in batch per i flussi di dati – È possibile utilizzare Kinesis Video Streams per creare applicazioni personalizzate in tempo reale che operano su flussi di dati live e per creare applicazioni in batch o ad hoc che operano su dati permanenti senza rigorosi requisiti di latenza. È possibile creare, distribuire e gestire applicazioni personalizzate con soluzioni open source
1 Amazon Kinesis Video Streams Guida per gli sviluppatori Primo utilizzo di Kinesis Video Streams?
(Apache MXNet, OpenCV), interne o di terze parti tramite AWS Marketplace per l'elaborazione e l'analisi dei flussi. Le API Kinesis Video Streams Get consentono di creare diverse applicazioni simultanee per l'elaborazione di dati orientata ai batch o in tempo reale. • Flussi di dati in modo sicuro – Kinesis Video Streams Crittografa tutti dati inviati al servizio e la loro l'archiviazione. Kinesis Video Streams Implementa la crittografia basata su TLS sullo streaming dei dati dai dispositivi e crittografa tutti i dati inattivi che utilizzano AWS Key Management Service (AWS KMS). Inoltre, è possibile gestire l'accesso ai dati mediante AWS Identity and Access Management (IAM). • Calcolo dei prezzi in base all'uso effettivo – Per ulteriori informazioni, consulta la pagina Prezzi AWS.
Primo utilizzo di Kinesis Video Streams?
Se è la prima volta che utilizzi Kinesis Video Streams, ti consigliamo di leggere le seguenti sezioni in ordine:
1. Amazon Kinesis Video Streams: come funziona (p. 5) – Ulteriori informazioni sui concetti essenziali di Kinesis Video Streams. 2. Nozioni di base su Kinesis Video Streams (p. 24) – Configurazione dell'account e test di Kinesis Video Streams. 3. Kinesis Video Streams Producer Library (p. 46) – Ulteriori informazioni sulla creazione di un'applicazione producer Kinesis Video Streams. 4. Libreria parser del flusso video Kinesis (p. 121) – Ulteriori informazioni sull'elaborazione dei fotogrammi di dati in entrata Kinesis Video Streams nell'applicazione consumer. 5. Amazon Kinesis Video StreamsEsempi di (p. 128) – Per vedere ulteriori esempi delle possibilità Kinesis Video Streams.
2 Amazon Kinesis Video Streams Guida per gli sviluppatori Requisiti della videocamera
Kinesis Video StreamsRequisiti di sistema di
Le seguenti sezioni contengono informazioni sui requisiti hardware, software e di storage per Amazon Kinesis Video Streams.
Argomenti • Requisiti della videocamera (p. 3) • Sistemi operativi testati (p. 3) • Requisiti di storage per l'SDK (p. 4)
Requisiti della videocamera
Le videocamere utilizzate per eseguire l'SDK di Kinesis Video Streams Producer e gli esempi devono soddisfare i seguenti requisiti di memoria:
• La visualizzazione dei contenuti SDK richiede 16 MB di memoria. • La configurazione di default dell'applicazione di esempio è di 512 MB. Si tratta di un valore appropriato per i producer con una buona connettività di rete e senza requisiti di buffering aggiuntivo. Se la connessione di rete è scadente ed è necessario ulteriore buffering, è possibile calcolare la memoria richiesta per ogni secondo di buffering moltiplicando il frame rate al secondo per le dimensioni di memoria del fotogramma. Per ulteriori informazioni sull'allocazione della memoria, consultare StorageInfo (p. 103).
È consigliabile usare videocamere USB o RTSP (Real Time Streaming Protocol) in grado di codificare i dati tramite H.264: così si evita che sia la CPU a dover eseguire la crittografia.
Al momento, l'applicazione demo non supporta il protocollo UDP (User Datagram Protocol) per lo streaming RTSP. Questa funzionalità verrà aggiunta in futuro.
L'SDK producer supporta i seguenti tipi di videocamere:
• Videocamere Web • Videocamere USB • Videocamere con codifica H.264 (preferite) • Videocamere senza codifica H.264 • Modulo telecamera Raspberry Pi. Si tratta dell'opzione preferita per i dispositivi Raspberry Pi perché si connette alla GPU per il trasferimento di dati video senza includere l'elaborazione da parte della CPU. • Videocamere RTSP (di rete). Queste videocamere sono preferibili perché i flussi video sono già codificati con H.264.
Sistemi operativi testati
Le videocamere Web e RTSP sono state testate con i seguenti dispositivi e sistemi operativi:
• Mac mini
3 Amazon Kinesis Video Streams Guida per gli sviluppatori Requisiti di storage per l'SDK
• High Sierra • laptop MacBook Pro • Sierra (10.12) • El Capitan (10.11) • Laptop HP con Ubuntu 16.04 • Ubuntu 17.10 (container Docker) • Raspberry Pi 3
Requisiti di storage per l'SDK
Per l'installazione delle Kinesis Video Streams Producer Library (p. 46) è richiesta una capacità di storage minima di 170 MB e sono raccomandati 512 MB.
4 Amazon Kinesis Video Streams Guida per gli sviluppatori
Amazon Kinesis Video Streams: come funziona
Argomenti • Supporto di API e Producer Library di Kinesis Video Streams (p. 6) • Riproduzione Kinesis Video Streams (p. 9) • Utilizzo dei metadati di streaming con Kinesis Video Streams (p. 15) • Modello di dati Kinesis Video Streams (p. 18)
Amazon Kinesis Video Streams è un servizio AWS completamente gestito che consente di trasmettere in streaming video live da dispositivi al cloud AWS e di archiviarli stabilmente. Puoi quindi creare le tue applicazioni per l'elaborazione di video in tempo reale o eseguire analisi dei video in batch.
Il diagramma seguente fornisce una panoramica sul funzionamento di Kinesis Video Streams.
5 Amazon Kinesis Video Streams Guida per gli sviluppatori Producer Library e API
Il diagramma mostra l'interazione tra i componenti seguenti:
• Producer – Qualsiasi sorgente che inserisce dati in un flusso video di Kinesis. Un producer può essere qualsiasi dispositivo che genera video, come una telecamera di sicurezza, una telecamera da indossare, una telecamera di uno smartphone o una telecamera del pannello di controllo. Un producer può anche inviare dati non video, come feed audio, immagini o dati RADAR.
Un producer singolo può generare uno o più flussi video. Ad esempio, una videocamera può inviare dati video a un flusso video di Kinesis e dati audio a un'altra videocamera. • Kinesis Video Streams Producer libraries – Un set di software di facile utilizzo e librerie che puoi installare e configurare sul tuo dispositivo. Queste librerie consentono di stabilire una connessione sicura e uno streaming video affidabile in diversi modi, tra cui in tempo reale, dopo buffering per alcuni secondi oppure come caricamenti multimediali successivi. • Flusso video di Kinesis – Una risorsa che ti consente di trasportare dati video live, archiviarli facoltativamente e renderli disponibili per il consumo sia in tempo reale e in batch o in forma ad-hoc. In una configurazione tipica, un flusso video di Kinesis dispone solo di un producer che pubblica i dati al suo interno.
Il flusso è in grado di trasportare audio e flussi di dati simili codificati temporalmente, ad esempio feed di rilevamento profondità, feed RADAR e molto altro. Puoi creare un flusso di video di Kinesis utilizzando la AWS Management Console o, mediante programmazione, gli SDK AWS.
Numerose applicazioni indipendenti possono utilizzare un flusso video di Kinesis in parallelo. • Consumer – recupera dati, ad esempio frammenti e frame, da un flusso video di Kinesis per visualizzarlo, elaborarlo o analizzarlo. Di solito questi consumer sono chiamati applicazioni di Kinesis Video Streams. Puoi scrivere applicazioni che consumano ed elaborano dati nei flussi video di Kinesis in tempo reale o dopo che i dati vengono stabilmente archiviati e indicizzati temporalmente quando l'elaborazione a bassa latenza non è richiesta. Puoi creare queste applicazioni consumer da eseguire su istanze di Amazon EC2. • Libreria parser del flusso video Kinesis (p. 121) – Permette alle applicazioni Kinesis Video Streams di ottenere dati multimediali dai flussi video di Kinesis a bassa latenza. Inoltre, analizza i limiti del frame nel contenuto multimediale in modo che le applicazioni possano concentrarsi sull'elaborazione e l'analisi dei frame stesso.
Supporto di API e Producer Library di Kinesis Video Streams
Kinesis Video Streams fornisce API per creare e gestire flussi ed eseguire operazioni di lettura o scrittura di dati multimediali da e verso un flusso. Oltre alle funzionalità di gestione, la console Kinesis Video Streams supporta anche riproduzioni live e video-on-demand. Kinesis Video Streams fornisce inoltre un set di librerie producer che è possibile utilizzare nel codice dell'applicazione per estrarre i dati dalle origini multimediali e caricarli nel flusso video di Kinesis.
Argomenti • API Kinesis Video Streams (p. 6) • Producer Library (p. 8)
API Kinesis Video Streams
Kinesis Video Streams fornisce API per la creazione e la gestione di flussi video Kinesis. Fornisce inoltre API per la lettura e la scrittura di dati multimediali su un flusso, nel modo seguente:
6 Amazon Kinesis Video Streams Guida per gli sviluppatori API Kinesis Video Streams
• API Producer – Kinesis Video Streams Fornisce un'API PutMedia per scrivere i dati multimediali in un flusso video Kinesis. In una richiesta PutMedia, il producer invia un flusso di frammenti multimediali. Per frammento si intende una sequenza autonoma di frame. I frame appartenenti a un frammento non devono avere alcun tipo di dipendenza dai frame di altri frammenti. Per ulteriori informazioni, consulta PutMedia (p. 251).
Quando arrivano i frammenti, Kinesis Video Streams assegna un numero di frammento univoco, in ordine crescente. Memorizza inoltre timestamp lato producer e lato server per ogni frammento, così come metadati specifici per Kinesis Video Streams. • API Consumer – Le seguenti API consentono ai consumer di ottenere i dati da un flusso: • GetMedia: quando si utilizza questa API, i consumer devono identificare il frammento di partenza. L'API restituisce i frammenti nell'ordine in cui sono stati aggiunti nel flusso (in ordine crescente per numero di frammento). I dati multimediali nel frammento vengono compressi in un formato strutturato, ad esempio Matroska (MKV). Per ulteriori informazioni, consulta GetMedia (p. 247). Note
GetMedia sa dove sono i frammenti (archiviati nello datastore o disponibili in tempo reale). Ad esempio, se GetMedia determina che i frammenti di partenza sono archiviati, ne avvia la restituzione dal datastore. Quando è necessario restituire frammenti più recenti non ancora archiviati, GetMedia passa alla lettura di frammenti da un buffer del flusso in memoria.
Questo è un esempio di un consumer continuo, che elabora i frammenti nell'ordine in cui vengono acquisiti dal flusso.
GetMedia permette che le applicazioni di elaborazione video falliscano o accumulino ritardo, recuperando senza alcuno sforzo aggiuntivo. Tramite GetMedia, le applicazioni sono in grado di elaborare i dati archiviati nel datastore e man mano che l'applicazione si aggiorna, GetMedia continua ad aggiornare i dati multimediali in tempo reale al loro arrivo. • GetMediaFromFragmentList (e ListFragments): le applicazioni per l'elaborazione in batch sono considerate consumer offline. I consumatori offline potrebbero scegliere di recuperare in modo esplicito particolari frammenti di file multimediali o intervalli di video combinando le API ListFragments e GetMediaFromFragmentList. ListFragments e GetMediaFromFragmentList consentono a un'applicazione di identificare i segmenti di video per un determinato intervallo di tempo o intervallo di frammenti, quindi di recuperare i frammenti in modo sequenziale o in parallelo per l'elaborazione. Questo approccio è idoneo per suite di applicazioni MapReduce, che devono elaborare rapidamente grandi quantità di dati in parallelo.
Ad esempio, supponiamo che un consumer voglia elaborare i frammenti di video di un intero giorno. Il consumer procederebbe nel modo seguente: 1. Ottenere un elenco di frammenti chiamando l'API ListFragments e specificando un intervallo di tempo per selezionare la raccolta di frammenti desiderata.
L'API restituisce i metadati da tutti i frammenti nell'intervallo di tempo specificato. I metadati forniscono informazioni quali numero di frammento, timestamp lato producer/server e così via. 2. Prendere l'elenco dei metadati dei frammenti e recuperare i frammenti, in qualsiasi ordine. Ad esempio, per elaborare tutti i frammenti per il giorno, il consumer potrebbe scegliere di frazionare l'elenco in sottogruppi, facendo in modo che processi di lavoro (ad esempio, più istanze Amazon EC2) recuperino i frammenti in parallelo utilizzando GetMediaFromFragmentList e li elaborino in parallelo.
Il seguente diagramma mostra il flusso di dati per frammenti e blocchi durante queste chiamate API.
7 Amazon Kinesis Video Streams Guida per gli sviluppatori Producer Library
Quando un producer invia una richiesta PutMedia, invia metadati multimediali nel payload nonché una sequenza di frammenti di dati multimediali. Quando riceve i dati, Kinesis Video Streams memorizza i dati multimediali in entrata come blocchi di Kinesis Video Streams. Ogni blocco è costituito dagli elementi seguenti:
• Una copia dei metadati multimediali • Un frammento • Metadati specifici per Kinesis Video Streams, ad esempio il numero di frammento e il timestamp lato producer e lato server
Quando un consumer richiede metadati multimediali, Kinesis Video Streams restituisce un flusso di blocchi, a partire dal numero di frammento specificato nella richiesta.
Se abiliti la persistenza dei dati per il flusso, dopo aver ricevuto un frammento nel flusso, Kinesis Video Streams salva anche una copia del frammento nel datastore. Producer Library
Dopo aver creato un flusso video Kinesis, è possibile iniziare a inviare dati a esso. Puoi utilizzare queste librerie nel codice dell'applicazione per estrarre i dati dalle tue origini multimediali e caricarli sul tuo flusso video Kinesis. Per ulteriori informazioni sulle librerie di producer disponibili, consulta Kinesis Video Streams Producer Library (p. 46).
8 Amazon Kinesis Video Streams Guida per gli sviluppatori Video Playback (Riproduzione video)
Riproduzione Kinesis Video Streams
È possibile visualizzare una Kinesis video stream utilizzando i seguenti metodi:
• GetMedia: utilizzare l'API GetMedia per creare applicazioni personalizzate per l'elaborazione dei flussi video Kinesis. GetMedia è un'API in tempo reale a bassa latenza. Se desideri creare un lettore che usa GetMedia, devi eseguire l'operazione manualmente. Per informazioni su come sviluppare un'applicazione che visualizza un Kinesis video stream che utilizza GetMedia, consulta Libreria parser del flusso (p. 121). • HLS: HTTP Live Streaming (HLS) è un protocollo di comunicazione di streaming multimediale standard del settore basato su HTTP. È possibile usare HLS per visualizzare un Kinesis video stream di Amazon sia per la riproduzione in tempo reale sia per la visualizzazione di video archiviati.
È possibile usare HLS per la riproduzione in tempo reale. La latenza è in genere compresa tra 3 e 5 secondi, ma può essere compresa tra 1 e 10 secondi, a seconda del caso d'uso, del lettore e delle condizioni di rete. Puoi usare un lettore di terze parti (ad esempio Video.js o Google Shaka Player) per visualizzare il flusso video fornendo l'URL della sessione di streaming HLS, a livello di programmazione o manualmente. Puoi anche riprodurre il video digitando l'URL della sessione di streaming HLS nella barra degli indirizzi del browser Apple Safari o Microsoft Edge. • MPEG-DASH: Streaming adattivo dinamico su HTTP (DASH), noto anche come MPEG-DASH, è un protocollo di streaming adattivo a frequenza di bit che consente lo streaming di qualità elevata di contenuti multimediali su Internet distribuiti dai server Web HTTP convenzionali.
È possibile utilizzare MPEG-DASH per la riproduzione in tempo reale. La latenza è in genere compresa tra 3 e 5 secondi, ma può essere compresa tra 1 e 10 secondi, a seconda del caso d'uso, del lettore e delle condizioni di rete. È possibile usare un lettore di terze parti (ad esempio dash.js o Google Shaka Player) per visualizzare il flusso video fornendo l'URL della sessione di streaming MPEG-DASH, a livello di programmazione o manualmente. • API GetClip: è possibile utilizzare l'API GetClip per scaricare una clip (in un file MP4) contenente i supporti archiviati su richiesta dal flusso video specificato nell'intervallo di tempo specificato. Per ulteriori informazioni, consulta la Documentazione di riferimento delle API di GetClip.
Argomenti • Riproduzione di video con HLS (p. 9) • Riproduzione video con MPEG-DASH (p. 13)
Riproduzione di video con HLS
Per visualizzare un Kinesis video stream usando HLS, devi prima creare una sessione di streaming tramite GetHLSStreamingSessionURL. Questa operazione restituisce un URL (contenente un token di sessione) per l'accesso alla sessione HLS. Puoi quindi usare l'URL in un lettore multimediale o in un'applicazione autonoma per visualizzare il flusso.
Un Amazon Kinesis video stream prevede i seguenti requisiti per la visualizzazione di video tramite HLS:
• La conservazione dei dati deve essere superiore a 0. • La traccia 1 del flusso deve avere un ID codec di V_MPEG/ISO/AVC e contenere la codifica multimediale H.264. Se c'è un brano audio (opzionale), deve essere la traccia numero 2 e disporre di un ID codec A_AAC e contener audio codificato AAC. • I frammenti devono contenere dati privati del codec con codifica AVC (Advanced Video Coding) per il formato H.264 ( specifica MPEG-4 ISO/IEC 14496-15) per il multimedia video. Inoltre, devono contenere i dati di codec privati per ACC ( specifiche AAC ISO/IEC 13818-7) per i contenuti multimediali audio (se
9 Amazon Kinesis Video Streams Guida per gli sviluppatori Riproduzione di video con HLS
presenti). Per informazioni sull'adattamento dei dati dei flussi a un formato specifico, consulta Flag di adattamento del NAL (p. 101).
Esempio: uso di HLS in HTML e JavaScript
L'esempio seguente mostra come recuperare una sessione di streaming HLS per un Kinesis video stream e riprodurla in una pagina Web. L'esempio mostra come riprodurre video con i lettori seguenti:
• Video.js • Google Shaka Player • hls.js
Argomenti • Impostare il client Kinesis Video Streams per la riproduzione HLS (p. 10) • Acquisire l'endpoint dei contenuti archiviati Kinesis Video Streams per la riproduzione HLS (p. 10) • Recupero dell'URL della sessione di streaming HLS (p. 11) • Visualizzare il video in streaming con la riproduzione HLS (p. 11) • Risoluzione dei problemi correlati alla configurazione HLS (p. 12) • Esempio completato per la riproduzione HLS (p. 12)
Impostare il client Kinesis Video Streams per la riproduzione HLS
Per accedere al video in streaming con HLS, prima di tutto crea e configura il client Kinesis Video Streams (per recuperare l'endpoint del servizio) e il client per i contenuti multimediali archiviati (per recuperare la sessione di streaming HLS). L'applicazione recupera i valori necessari dalle caselle di input nella pagina HTML.
... else if (playerName === 'VideoJS') { var playerElement = $('#videojs'); playerElement.show(); var player = videojs('videojs'); console.log('Created VideoJS Player');
11 Amazon Kinesis Video Streams Guida per gli sviluppatori Riproduzione di video con HLS player.src({ src: response.HLSStreamingSessionURL, type: 'application/x-mpegURL' }); console.log('Set player source'); player.play(); console.log('Starting playback');
L'esempio di codice seguente illustra come fornire l'URL della sessione di streaming a un lettore Google Shaka Player:
// Shaka Player elements
... else if (playerName === 'Shaka Player') { var playerElement = $('#shaka'); playerElement.show(); var player = new shaka.Player(playerElement[0]); console.log('Created Shaka Player'); player.load(response.HLSStreamingSessionURL).then(function() { console.log('Starting playback'); }); console.log('Set player source');
L'esempio di codice seguente illustra come fornire l'URL della sessione di streaming a un lettore hls.js:
// HLS.js elements
... var playerName = $('#player').val(); if (playerName == 'HLS.js') { var playerElement = $('#hlsjs'); playerElement.show(); var player = new Hls(); console.log('Created HLS.js Player'); player.loadSource(response.HLSStreamingSessionURL); player.attachMedia(playerElement[0]); console.log('Set player source'); player.on(Hls.Events.MANIFEST_PARSED, function() { video.play(); console.log('Starting playback'); }); }
Risoluzione dei problemi correlati alla configurazione HLS
Se il flusso video non viene riprodotto correttamente, consulta Risoluzione dei problemi correlati alla configurazione HLS (p. 175). Esempio completato per la riproduzione HLS
È possibile scaricare o visualizzare il codice di esempio completo.
12 Amazon Kinesis Video Streams Guida per gli sviluppatori Riproduzione video con MPEG-DASH
Riproduzione video con MPEG-DASH
Per visualizzare un Kinesis video stream utilizzando MPEG-DASH, è necessario innanzitutto creare una sessione di streaming mediante GetDASHStreamingSessionURL. Questa operazione restituisce un URL (contenente un token di sessione) per l'accesso alla sessione MPEG-DASH. Puoi quindi usare l'URL in un lettore multimediale o in un'applicazione autonoma per visualizzare il flusso.
Un Amazon Kinesis video stream prevede i seguenti requisiti per la visualizzazione di video 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.
Esempio: utilizzo di MPEG-DASH in HTML e JavaScript
L'esempio seguente mostra come recuperare una sessione di streaming MPEG-DASH per un Kinesis video stream e riprodurla in una pagina Web. L'esempio mostra come riprodurre video con i lettori seguenti:
• Google Shaka Player • dash.js
Argomenti • Impostazione del client Kinesis Video Streams per la riproduzione MPEG-DASH (p. 13) • Acquisisci l'endpoint dei contenuti Kinesis Video Streams archiviati per la riproduzione MPEG- DASH (p. 14) • Recuperare l'URL della sessione di streaming MPEG-DASH (p. 14) • Visualizza il video di streaming con la riproduzione MPEG-DASH (p. 14) • Esempio completo (p. 15)
Impostazione del client Kinesis Video Streams per la riproduzione MPEG-DASH
Per accedere al video in streaming con MPEG-DASH, prima di tutto crea e configura il client Kinesis Video Streams (per recuperare l'endpoint del servizio) e il client per i contenuti multimediali archiviati (per recuperare la sessione di streaming MPEG-DASH). L'applicazione recupera i valori necessari dalle caselle di input nella pagina HTML.
var streamName = $('#streamName').val();
// Step 1: Configure SDK Clients var options = { accessKeyId: $('#accessKeyId').val(), secretAccessKey: $('#secretAccessKey').val(), sessionToken: $('#sessionToken').val() || undefined,
13 Amazon Kinesis Video Streams Guida per gli sviluppatori Riproduzione video con MPEG-DASH
region: $('#region').val(), endpoint: $('#endpoint').val() || undefined } var kinesisVideo = new AWS.KinesisVideo(options); var kinesisVideoArchivedContent = new AWS.KinesisVideoArchivedMedia(options);
Acquisisci l'endpoint dei contenuti Kinesis Video Streams archiviati per la riproduzione MPEG-DASH
Dopo l'avvio dei client, recuperare gli endpoint dei contenuti Kinesis Video Streams archiviati in modo che sia possibile recuperare l'URL della sessione di streaming MPEG-DASH come segue:
// Step 2: Get a data endpoint for the stream console.log('Fetching data endpoint'); kinesisVideo.getDataEndpoint({ StreamName: streamName, APIName: "GET_DASH_STREAMING_SESSION_URL" }, function(err, response) { if (err) { return console.error(err); } console.log('Data endpoint: ' + response.DataEndpoint); kinesisVideoArchivedContent.endpoint = new AWS.Endpoint(response.DataEndpoint);
Recuperare l'URL della sessione di streaming MPEG-DASH
Quando si dispone dell'endpoint dei contenuti archiviati, richiamare l'API GetDASHStreamingSessionURL per recuperare l'URL della sessione di streaming MPEG-DASH come segue:
// Step 3: Get a Streaming Session URL var consoleInfo = 'Fetching ' + protocol + ' Streaming Session URL'; console.log(consoleInfo); if (protocol === 'DASH') { kinesisVideoArchivedContent.getDASHStreamingSessionURL({ StreamName: streamName, PlaybackMode: $('#playbackMode').val(), DASHFragmentSelector: { FragmentSelectorType: $('#fragmentSelectorType').val(), TimestampRange: $('#playbackMode').val() === "LIVE" ? undefined : { StartTimestamp: new Date($('#startTimestamp').val()), EndTimestamp: new Date($('#endTimestamp').val()) } }, DisplayFragmentTimestamp: $('#displayFragmentTimestamp').val(), DisplayFragmentNumber: $('#displayFragmentNumber').val(), MaxManifestFragmentResults: parseInt($('#maxResults').val()), Expires: parseInt($('#expires').val()) }, function(err, response) { if (err) { return console.error(err); } console.log('DASH Streaming Session URL: ' + response.DASHStreamingSessionURL);
Visualizza il video di streaming con la riproduzione MPEG-DASH
Una volta ottenuto l'URL della sessione di streaming MPEG-DASH, forniscilo al lettore video. Il metodo per fornire l'URL al lettore video dipende dal lettore usato.
L'esempio di codice seguente illustra come fornire l'URL della sessione di streaming a un lettore Google Shaka Player:
14 Amazon Kinesis Video Streams Guida per gli sviluppatori Utilizzo dei metadati di streaming
// Step 4: Give the URL to the video player.
//Shaka Player elements ...
var playerName = $('#player').val();
if (playerName === 'Shaka Player') { var playerElement = $('#shaka'); playerElement.show();
var player = new shaka.Player(playerElement[0]); console.log('Created Shaka Player');
player.load(response.DASHStreamingSessionURL).then(function() { console.log('Starting playback'); }); console.log('Set player source'); }
L'esempio di codice seguente illustra come fornire l'URL della sessione di streaming a un lettore dash.js:
...
var playerElement = $('#dashjs'); playerElement.show();
var player = dashjs.MediaPlayer().create(); console.log('Created DASH.js Player');
player.initialize(document.querySelector('#dashjs'), response.DASHStreamingSessionURL, true); console.log('Starting playback'); console.log('Set player source'); }
Esempio completo
È possibile scaricare o visualizzare il codice di esempio completo su GitHub.
Utilizzo dei metadati di streaming con Kinesis Video Streams
Puoi utilizzare Amazon Kinesis Video Streams Producer SDK per incorporare i metadati a livello di singolo frammento in un Kinesis video stream. I metadati in Kinesis Video Streams costituiscono una coppia chiave-valore modificabile. Puoi utilizzarli per descrivere il contenuto del frammento, incorporare le letture dei sensori associati che devono essere trasferite insieme al frammento effettivo oppure soddisfare altre esigenze particolari. I metadati sono disponibili come parte delle operazioni delle API the section called “
15 Amazon Kinesis Video Streams Guida per gli sviluppatori Aggiunta di metadati a Kinesis Video Stream
GetMedia ” (p. 247) o the section called “ GetMediaForFragmentList ” (p. 277). Sono memorizzati con i frammenti per tutta la durata del periodo di conservazione del flusso. Le tue applicazioni in uso possono leggere, elaborare e agire in base ai metadati usando la Libreria parser del flusso video Kinesis (p. 121).
Esistono due modalità in cui i metadati possono essere incorporati con i frammenti in un flusso:
• Non persistente: puoi applicare i metadati ad hoc ai frammenti in un flusso, in base ai criteri specifici dell'azienda in essere. Un esempio è una fotocamera intelligente che rileva il movimento e aggiunge i metadati ai frammenti corrispondenti che contengono il movimento prima di inviare i frammenti a Kinesis video stream. Puoi applicare i metadati al frammento nel formato seguente: Motion = true. • Persistente: puoi applicare i metadati ai frammenti successivi e consecutivi in un flusso sulla base di una necessità costante. Un esempio è una fotocamera intelligente che invia le coordinate correnti di latitudine e longitudine associate a tutti i frammenti inviate a Kinesis video stream. Puoi applicare i metadati a tutti i frammenti nel formato seguente: Lat = 47.608013N , Long = -122.335167W.
Puoi applicare i metadati in entrambe queste modalità allo stesso frammento contemporaneamente in base alle esigenze dell'applicazione. I metadati incorporati potrebbero includere oggetti rilevati, attività tracciate, coordinate GPS o altri dati personalizzati che vuoi associare ai frammenti nel flusso. I metadati sono codificati come coppie di stringhe chiave-valore.
Argomenti • Aggiunta di metadati a Kinesis Video Stream (p. 16) • Consumo dei metadati incorporati in Kinesis Video Stream (p. 17) • Limitazioni dello streaming di metadati (p. 18)
Aggiunta di metadati a Kinesis Video Stream
I metadati che aggiungi a Kinesis video stream sono modellati come tag MKV che vengono implementati come coppie chiave-valore.
I metadati possono essere transitori, ad esempio per contrassegnare un evento all'interno del flusso, o persistenti, ad esempio per identificare frammenti in cui si verifica un determinato evento. Un elemento metadati persistente rimane e viene applicata a ciascun frammento consecutivo, fino a che non viene annullato. Note
Gli elementi metadati aggiunti utilizzando le Producer Library (p. 46) differiscono dalle API di tag a livello di flusso implementato con the section called “ TagStream ” (p. 229), the section called “ UntagStream ” (p. 234) e the section called “ ListTagsForStream ” (p. 224). API streaming di metadati
Puoi utilizzare le seguenti operazioni in Producer SDK per implementare lo streaming dei metadati. PIC
PUBLIC_API STATUS putKinesisVideoFragmentMetadata(STREAM_HANDLE streamHandle, PCHAR name, PCHAR value, BOOL persistent);
C++ Producer SDK
/**
16 Amazon Kinesis Video Streams Guida per gli sviluppatori Consumo dei metadati incorporati in Kinesis Video Stream
* Appends a "tag" or metadata - a key/value string pair into the stream. */ bool putFragmentMetadata(const std::string& name, const std::string& value, bool persistent = true);
Java Producer SDK
Con Java Producer SDK, puoi aggiungere i metadati a MediaSource tramite MediaSourceSink.onCodecPrivateData: void onFragmentMetadata(final @Nonnull String metadataName, final @Nonnull String metadataValue, final boolean persistent) throws KinesisVideoException;
Metadati persistenti e non persistenti
Per i metadati non persistenti, puoi aggiungere più elementi metadati con lo stesso nome. Producer SDK raccoglie gli elementi metadati nella coda finché non vengono anteposti al successivo frammento. La coda dei metadati viene cancellata quando gli elementi metadati vengono applicati al flusso. Per ripetere i metadati, chiama di nuovo putKinesisVideoFragmentMetadata o putFragmentMetadata.
Per i metadati persistenti, Producer SDK raccoglie gli elementi metadati nella coda come per i metadati non persistenti. Tuttavia, gli elementi metadati non vengono rimossi dalla coda quando vengono anteposti al successivo frammento.
La chiamata putKinesisVideoFragmentMetadata o putFragmentMetadata con persistent impostato su true ha il seguente comportamento:
• La chiamata dell'API inserisce l'elemento metadati nella coda. I metadati vengono aggiunti come tag MKV per ogni frammento mentre l'elemento è in coda. • Se si chiama l'API con lo stesso nome e un valore diverso come elemento metadati aggiunto in precedenza, l'elemento viene sovrascritto. • Se si chiama l'API con un valore vuoto, l'elemento metadati viene rimosso (annullato) dalla coda dei metadati.
Consumo dei metadati incorporati in Kinesis Video Stream
Per consumare i metadati in Kinesis video stream, usa un'implementazione di MkvTagProcessor: public interface MkvTagProcessor { default void process(MkvTag mkvTag, Optional
Questa interfaccia si trova nella classe FragmentMetadataVisitor (p. 123) nella Libreria parser del flusso video Kinesis (p. 121).
17 Amazon Kinesis Video Streams Guida per gli sviluppatori Limitazioni dello streaming di metadati
La classe FragmentMetadataVisitor contiene un'implementazione di MkvTagProcessor:
public static final class BasicMkvTagProcessor implements FragmentMetadataVisitor.MkvTagProcessor { @Getter private List
@Override public void process(MkvTag mkvTag, Optional
@Override public void clear() { tags.clear(); } }
La classe KinesisVideoRendererExample contiene un esempio di come usare un BasicMkvTagProcessor. Nel seguente esempio, un BasicMkvTagProcessor viene aggiunto a MediaProcessingArguments di un'applicazione:
if (renderFragmentMetadata) { getMediaProcessingArguments = KinesisVideoRendererExample.GetMediaProcessingArguments.create( Optional.of(new FragmentMetadataVisitor.BasicMkvTagProcessor()));
Il metodo BasicMkvTagProcessor.process viene chiamato quando arrivano i metadati del frammento. Puoi recuperare i metadati accumulati con GetTags. Per recuperare un singolo elemento metadati, chiama prima clear per cancellare i metadati raccolti e poi recupera nuovamente gli elementi metadati. Limitazioni dello streaming di metadati
Le seguenti limitazioni si applicano all'aggiunta dello streaming di metadati a Kinesis video stream:
• Puoi anteporre a un frammento fino a 10 elementi metadati. • La lunghezza del nome dei metadati del frammento può essere al massimo di 128 byte. • La lunghezza del valore dei metadati del frammento può essere al massimo di 256 byte. • Il nome name dei metadati del frammento non può iniziare con la stringa "AWS". Se un elemento metadati viene aggiunto, il metodo putFragmentMetadata nel PIC restituisce un errore STATUS_INVALID_METADATA_NAME (codice errore 0x52000077). La tua applicazione può ignorare l'errore (il PIC non aggiunge l'elemento metadati) oppure correggere l'errore.
Modello di dati Kinesis Video Streams
Producer Library (p. 46) e Libreria parser del flusso (p. 121) inviano e ricevono dati video in un formato che supporta l'incorporamento di informazioni insieme ai dati video. Questo formato si basa sulla specifica Matroska (MKV).
Il formato MKV è una specifica aperta per i dati multimediali. Tutte le librerie e gli esempi di codice in Guida per lo sviluppatore di Amazon Kinesis Video Streams inviano o ricevono i dati nel formato MKV.
Le Kinesis Video Streams Producer Library (p. 46) usano i tipi StreamDefinition e Frame per produrre intestazioni dei flussi, intestazioni dei frame e dati dei frame MKV.
Per informazioni sulle specifiche complete di MKV, consulta l'articolo sulle specifiche Matroska.
18 Amazon Kinesis Video Streams Guida per gli sviluppatori Elementi di intestazione del flusso
Le seguenti sezioni descrivono i componenti di dati in formato MKV creati da C++ Producer Library (p. 56).
Argomenti • Elementi di intestazione del flusso (p. 19) • Streaming dei dati della traccia (p. 22) • Elementi di intestazione del frame (p. 23) • Dati del frame MKV (p. 23)
Elementi di intestazione del flusso
I seguenti elementi di intestazione MKV vengono utilizzati da StreamDefinition (definiti in StreamDefinition.h).
Elemento Descrizione Valori tipici stream_name Corrisponde al nome del Kinesis my-stream video stream. retention_period La durata di conservazione dei 24 dati di flusso da parte di Kinesis Video Streams. Specifica 0 per un flusso che non conservi alcun dato. tags Una raccolta chiave-valore di dati utente. Questi dati vengono visualizzati nella AWS Management Console e possono essere letti dalle applicazioni client per filtrare o ottenere informazioni su un flusso. kms_key_id Se presente, la chiave master 01234567-89ab- AWS KMS definita dall'utente che cdef-0123-456789ab viene utilizzata per crittografare i dati nel flusso. Se è assente, i dati vengono crittografati dalla chiave master fornita da Kinesis (aws/kinesis-video). streaming_type Attualmente, l'unico tipo STREAMING_TYPE_REALTIME di streaming valido è STREAMING_TYPE_REALTIME. content_type Il tipo di contenuto definito video/h264 dall'utente. Per lo streaming di dati video da riprodurre nella console, il tipo di contenuto deve essere video/h264. max_latency Attualmente questo valore non 0 viene utilizzato e deve essere impostato su 0.
19 Amazon Kinesis Video Streams Guida per gli sviluppatori Elementi di intestazione del flusso
Elemento Descrizione Valori tipici fragment_duration La stima della durata dei 2 tuoi frammenti, utile per l'ottimizzazione. La durata effettiva è determinata dai dati di streaming. timecode_scale Indica la scala utilizzata dai timestamp dei frame. Il valore predefinito è 1 millisecondo. Se si specifica 0, si assegna anche il valore predefinito di 1 millisecondo. Questo valore può essere compreso tra 100 nanosecondi e 1 secondo.
Per ulteriori informazioni, consulta TimecodeScale nella documentazione Matroska. key_frame_fragmentation Se true, il flusso avvia un true nuovo cluster quando riceve un keyframe. frame_timecodes Se true, Kinesis Video Streams true contrassegna i frame quando vengono ricevuti. Se false, Kinesis Video Streams usa il tempo di decodifica dei frame ricevuti. absolute_fragment_time Se true, i timecode del cluster true vengono interpretati come se utilizzassero tempo assoluto (ad esempio, dall'orologio di sistema del producer). Se false, i timecode del cluster sono interpretati come relativi all'ora di inizio del flusso. fragment_acks Se true, vengono inviate true conferme (ACK) quando Kinesis Video Streams riceve i dati. Le ACK possono essere ricevute utilizzando le callback KinesisVideoStreamFragmentAck o KinesisVideoStreamParseFragmentAck. restart_on_error Indica se il flusso deve riprendere true la trasmissione dopo la segnalazione di un errore di flusso.
20 Amazon Kinesis Video Streams Guida per gli sviluppatori Elementi di intestazione del flusso
Elemento Descrizione Valori tipici nal_adaptation_flags Indica se i dati privati del NAL_ADAPTATION_ANNEXB_NALS codec o l'adattamento NAL (Network Abstraction Layer) sono presenti nel contenuto. I flag validi includono NAL_ADAPTATION_ANNEXB_NALS e NAL_ADAPTATION_ANNEXB_CPD_NALS. frame_rate Una stima della frequenza 24 di frame del contenuto. Tale valore viene utilizzato per l'ottimizzazione. La frequenza di frame effettiva è determinata dalla velocità dei dati in entrata. Se si specifica 0, si assegna il valore predefinito di 24. avg_bandwidth_bps Stima della larghezza di banda 5 del contenuto. Tale valore viene utilizzato per l'ottimizzazione. La frequenza effettiva è determinata dalla larghezza di banda dei dati in entrata. Ad esempio, per un flusso video con risoluzione di 720 p in esecuzione a 25 FPS, puoi aspettarti una larghezza di banda media di 5 Mbps. buffer_duration La durata del buffering del contenuto sul producer. In presenza di una bassa latenza di rete, questo valore può essere ridotto; se la latenza di rete è elevata, l'aumento di questo valore impedisce che i frame vengano eliminati prima dell'invio, se l'allocazione non è riuscita a posizionare i frame nel buffer più piccolo. replay_duration Il periodo di tempo durante il quale il flusso di dati video viene "riavvolto" in caso di perdita di connessione. Questo valore può essere zero se la perdita di frame dovuta alla perdita di connessione non rappresenta un problema; il valore può essere maggiore se l'applicazione in uso è in grado di eliminare i frame ridondanti. Il valore in questione deve essere inferiore alla durata del buffer. In caso contrario, si utilizza la durata del buffer.
21 Amazon Kinesis Video Streams Guida per gli sviluppatori Streaming dei dati della traccia
Elemento Descrizione Valori tipici connection_staleness Il periodo durante il quale una connessione viene mantenuta quando non vengono ricevuti dati. codec_id Il codec utilizzato per il V_MPEG2 contenuto. Per ulteriori informazioni, consulta CodecID nelle specifiche Matroska. track_name Il nome definito dall'utente della my_track traccia. codecPrivateData I dati forniti dall'encoder utilizzato per decodificare i dati dei frame, ad esempio la larghezza di banda e l'altezza in pixel degli stessi, un'informazione richiesta da numerosi consumer a valle. In C++ Producer Library (p. 56), la matrice gMkvTrackVideoBits in MkvStatics.cpp include la larghezza e l'altezza in pixel per il frame. codecPrivateDataSize La dimensione dei dati nel parametro codecPrivateData. track_type Il tipo di traccia per il flusso. MKV_TRACK_INFO_TYPE_AUDIO or MKV_TRACK_INFO_TYPE_VIDEO segment_uuid uuid segmento definito dall'utente (16 byte). default_track_id Numero univoco diverso da zero 1 per la traccia.
Streaming dei dati della traccia
I seguenti elementi della traccia MKV vengono utilizzati da StreamDefinition (definiti in StreamDefinition.h).
Elemento Descrizione Valori tipici track_name Nome traccia definito dall'utente. audio Ad esempio, "audio" per la traccia audio. codec_id Id codec della traccia. Ad A_AAC esempio, "A_AAC" per la traccia audio.
22 Amazon Kinesis Video Streams Guida per gli sviluppatori Elementi di intestazione del frame
Elemento Descrizione Valori tipici cpd I dati forniti dall'encoder utilizzato per decodificare i dati del frame. Queste informazioni possono includere larghezza e altezza del frame in pixel, necessarie per numerosi consumatori downstream. In C++ Producer Library, la matrice gMkvTrackVideoBits in MkvStatics.cpp include la larghezza e l'altezza in pixel per il frame. cpd_size La dimensione dei dati nel parametro codecPrivateData track_type Il tipo di traccia. Ad MKV_TRACK_INFO_TYPE_AUDIO esempio, è possibile utilizzare il valore di enum MKV_TRACK_INFO_TYPE_AUDIO per l'audio.
Elementi di intestazione del frame
I seguenti elementi di intestazione MKV vengono utilizzati da Frame (definiti nel pacchetto KinesisVideoPic, in mkvgen/Include.h):
• Frame Index (Indice del frame): un valore a incremento monotono. • Flags (Flag): il tipo di frame. I valori validi includono i seguenti: • FRAME_FLAGS_NONE • FRAME_FLAG_KEY_FRAME: se key_frame_fragmentation è impostato su flusso, i key frame avviano un nuovo frammento. • FRAME_FLAG_DISCARDABLE_FRAME: indica al decoder che è possibile ignorare questo frame se la decodifica è lenta. • FRAME_FLAG_INVISIBLE_FRAME: la durata di questo blocco è 0. • Decoding Timestamp (Timestamp della decodifica): il timestamp del momento in cui questo frame viene decodificato. Se i frame precedenti dipendono da questo frame per la decodifica, questo timestamp potrebbe essere precedente a quello di frame precedenti. Questo valore è relativo all'inizio del frammento. • Presentation Timestamp (Timestamp di presentazione): il timestamp del momento in cui questo frame viene visualizzato. Questo valore è relativo all'inizio del frammento. • Duration (Durata): la durata di riproduzione del frame. • Size (Dimensione): la dimensione dei dati del frame in byte
Dati del frame MKV
I dati in frame.frameData potrebbero contenere solo i dati multimediali per il frame o ulteriori informazioni di intestazione annidate, a seconda dello schema di codifica utilizzato. Per essere visualizzati nella AWS Management Console, i dati devono essere codificati nel codec H.264, ma Kinesis Video Streams può ricevere i flussi di dati serializzati nel tempo in qualsiasi formato.
23 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 1: impostazione di un account
Nozioni di base su Kinesis Video Streams
Questa sezione descrive come eseguire le attività seguenti in Amazon Kinesis Video Streams:
• Configurare l'account AWS e creare un amministratore, se non è già stato fatto. • Creazione di una Kinesis video stream. • Inviare i dati a Kinesis video stream dalla fotocamera e visualizzare i contenuti multimediali nella console.
Se è la prima volta che utilizzi Amazon Kinesis Video Streams, ti consigliamo di leggere prima Amazon Kinesis Video Streams: come funziona (p. 5). Note
Attenendoti alla guida esemplificativa alle operazioni di base, non ti verrà addebitato alcun costo per il tuo account AWS. Consulta Prezzi di Amazon Kinesis Video Streams per i costi dei dati nella tua regione.
Argomenti • Fase 1: impostazione di un account AWS e creazione di un Amministratore (p. 24) • Fase 2: creazione di un flusso video Kinesis (p. 26) • Fase 3: invio dei dati al flusso video Kinesis (p. 27) • Fase 4: consumo di dati multimediali (p. 27) • Fasi successive (p. 28)
Fase 1: impostazione di un account AWS e creazione di un Amministratore
Prima di usare Kinesis Video Streams per la prima volta, è necessario completare le seguenti operazioni:
1. Registrazione ad AWS (p. 24) (a meno che non disponi già di un account) 2. Creazione di un utente IAM amministratore (p. 25) 3. Per creare una chiave account AWS (p. 25)
Registrazione ad AWS
Se disponi già di un account AWS, puoi ignorare questa fase.
Quando effettui la registrazione per Amazon Web Services (AWS), il tuo account AWS viene automaticamente registrato per tutti i servizi AWS, incluso Kinesis Video Streams. Quando usi Kinesis Video Streams, ti viene addebitato un costo in base alla quantità di dati trasferiti, archiviati e utilizzati dal
24 Amazon Kinesis Video Streams Guida per gli sviluppatori Creazione di un utente IAM amministratore servizio. Se sei un nuovo cliente AWS, puoi iniziare a utilizzare Kinesis Video Streams gratuitamente. Per ulteriori informazioni, consulta Piano di utilizzo gratuito di AWS.
Per creare un account AWS
1. Aprire https://portal.aws.amazon.com/billing/signup. 2. Seguire le istruzioni online.
Come parte della procedura di registrazione riceverai una telefonata, durante la quale dovrai inserire un codice di verifica sulla tastiera del telefono.
Annota l'ID del tuo account AWS, perché sarà necessario per l'operazione successiva. Creazione di un utente IAM amministratore
Quando ti registri a AWS fornisci un indirizzo e-mail e una password associati al tuo account AWS. Questo è il tuo utente root dell'account AWS. Le relative credenziali forniscono l'accesso completo a tutte le risorse AWS. Note
Per motivi di sicurezza, consigliamo di utilizzare l'utente root solo per creare un amministratore, ovvero un utente IAM con autorizzazioni complete per il tuo account AWS. Puoi quindi utilizzare questo amministratore per creare altri utenti e ruoli IAM; con autorizzazioni limitate. Per ulteriori informazioni consulta Best practice IAM e l'argomento relativo alla creazione di un gruppo e un utente admin nella Guida per l'utente IAM.
Per creare un amministratore e accedere alla console
1. Crea un amministratore nel tuo account AWS. Per istruzioni, consulta l'articolo relativo alla Creazione del primo utente e gruppo di amministratori IAM nella Guida per l'utente di IAM. 2. In qualità di amministratore, puoi accedere alla console utilizzando un URL speciale. Per ulteriori informazioni, consulta Modalità di accesso degli utenti al tuo account nella Guida per l'utente di IAM.
L'amministratore può creare più utenti nell'account. Per impostazione predefinita, gli utenti IAM non dispongono di autorizzazioni. L'amministratore può creare utenti e gestirne le autorizzazioni. Per ulteriori informazioni, consulta Creazione del primo utente e gruppo di amministratori IAM.
Per ulteriori informazioni su IAM, consulta:
• AWS Identity and Access Management (IAM) • Nozioni di base • Guida per l'utente di IAM
Per creare una chiave account AWS
Per accedere a Kinesis Video Streams in modo programmatico, è necessario disporre di una chiave account AWS.
Per creare una chiave account AWS, eseguire quanto descritto di seguito:
1. Accedi alla AWS Management Console e apri la console IAM all'indirizzo https:// console.aws.amazon.com/iam/. 2. Scegliere Users (Utenti) nella barra di navigazione e scegliere l'utente Amministratore.
25 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase successiva
3. Seleziona la scheda Security credentials (Credenziali di sicurezza), quindi Create access key (Crea chiave di accesso). 4. Registra l'Access key ID (ID chiave di accesso) Scegli Show (Mostra) in Secret access key (Chiave di accesso segreta). Registra la Secret access key (Chiave di accesso segreta).
Fase successiva
Fase 2: creazione di un flusso video Kinesis (p. 26)
Fase 2: creazione di un flusso video Kinesis
Questa sezione descrive come creare un flusso video Kinesis.
Questa sezione contiene le procedure seguenti:
• the section called “Creazione di un flusso video tramite console” (p. 26) • the section called “Creazione di un flusso video tramite AWS CLI” (p. 26)
Creazione di un flusso video tramite console
1. Apri la console all'indirizzo https://console.aws.amazon.com/kinesisvideo/home. 2. Nella pagina Video streams (Flussi video) scegliere Create video stream (Crea flusso video). 3. Nella pagina Create a new video stream (Crea un nuovo flusso video), immettere ExampleStream come nome del flusso. Lasciare selezionato il pulsante di opzione Default configuration (Configurazione predefinita). 4. Scegliere Create video stream (Crea flusso video). 5. Dopo che Kinesis Video Streams crea il flusso, rivedi i dettagli sulla pagina ExampleStream.
Creazione di un flusso video tramite AWS CLI
1. Assicurati di avere installato e configurato la AWS CLI. Per ulteriori informazioni, consulta la documentazione relativa all'interfaccia a riga di comando di AWS. 2. Esegui il Create-Stream comando seguente nella AWS CLI:
$ aws kinesisvideo create-stream --stream-name "MyKVStream" --data-retention-in-hours "24"
La risposta sarà simile alla seguente:
{ "StreamARN": "arn:aws:kinesisvideo:us-west-2:123456789012:stream/ MyKVSStream/123456789012" }
Fase successiva
Fase 3: invio dei dati al flusso video Kinesis (p. 27)
26 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: invio dei dati al flusso video Kinesis
Fase 3: invio dei dati al flusso video Kinesis
Questa sezione descrive come inviare dati multimediali da una fotocamera al Kinesis video stream creato nella fase precedente. Questa sezione usa il C++ Producer Library (p. 56) come GStreamer (p. 129) plugin.
Per inviare facilmente contenuti multimediali da un'ampia gamma di dispositivi su un'ampia gamma di sistemi operativi, questo tutorial utilizza la libreria di produttori Kinesis Video Streams C++ e GStreamer, un framework di supporti open source che standardizza l'accesso alle videocamere e ad altre origini multimediali.
In primo luogo, utilizza le seguenti istruzioni per creare la libreria producer: https://github.com/awslabs/ amazon-kinesis-video-streams-producer-sdk-cpp.
Quindi, scegli il sistema operativo da una delle quattro opzioni riportate di seguito e segui le istruzioni per inviare dati video al flusso .
• Linux • macOS • Microsoft Windows • Sistema operativo Raspberry Pi
Per ulteriori informazioni sull'utilizzo del plugin GStreamer per lo streaming di video da un file o da un flusso RTSP da una fotocamera, vedi Esempio: plugin Kinesis Video Streams dell'SDK del producerGStreamer (p. 129). Fase successiva
Fase 4: consumo di dati multimediali (p. 27)
Fase 4: consumo di dati multimediali
È possibile consumare i dati dai file multimediali visualizzandoli nella console o mediante la creazione di un'applicazione che supporti operazioni di lettura dei dati da un flusso tramite il protocollo HLS. Visualizzazione dei dati multimediali nella console
Per visualizzare i dati multimediali inviati dalla fotocamera nella console Kinesis Video Streams, aprire la console Kinesis Video Streams all'indirizzo https://console.aws.amazon.com/kinesisvideo/home e scegliere il flusso MyKinesisVideoStream sulla pagina Gestisci flussi. Viene avviata la riproduzione del video nel riquadro Video Preview (Anteprima video). Consumo dei dati dei media tramite HLS
È possibile creare un'applicazione client che consuma dati da un Kinesis video stream utilizzando il protocollo Hypertext Live Streaming (HLS). Per ulteriori informazioni su come creare un'applicazione che consuma i dati multimediali utilizzando HLS, consulta the section called “Video Playback (Riproduzione video)” (p. 9). Fase successiva
Fasi successive (p. 28)
27 Amazon Kinesis Video Streams Guida per gli sviluppatori Fasi successive
Fasi successive
Vedere i seguenti argomenti per ulteriori informazioni su Kinesis Video Streams:
• Producer Library (p. 46): descrive le classi e i metodi utilizzati per inviare i dati multimediali al servizio Kinesis Video Streams. • Libreria parser del flusso (p. 121): descrive come creare un'applicazione che legge e mostra i dati multimediali da un Kinesis video stream. • RTSP e Docker (p. 141): descrive come eseguire lo streaming video al servizio Kinesis Video Streams da una fotocamera di rete (RTSP).
28 Amazon Kinesis Video Streams Guida per gli sviluppatori Protezione dei dati
Sicurezza in Amazon Kinesis Video Streams
Per AWS, la sicurezza della cloud ha la massima priorità. In quanto cliente AWS, potrai trarre vantaggio da un'architettura di data center e di rete progettata per soddisfare i requisiti delle aziende più esigenti a livello di sicurezza.
La sicurezza è una responsabilità condivisa tra AWS e l'utente. Il modello di responsabilità condivisa descrive questo come sicurezza del cloud e sicurezza nel cloud:
• Sicurezza del cloud: AWS è responsabile della protezione dell'infrastruttura che esegue i servizi AWS nel cloud AWS. AWS fornisce inoltre i servizi che è possibile utilizzare in modo sicuro. L'efficacia della nostra sicurezza è regolarmente testata e verificata da revisori di terze parti come parte dei programmi di conformità AWS. Per ulteriori informazioni sui programmi di conformità che si applicano a Kinesis Video Streams, consulta Servizi coperti dal programma di conformitàAWS. • Sicurezza nel cloud: la tua responsabilità è determinata dal servizio AWS che utilizzi. L'utente è anche responsabile per altri fattori, tra cui la riservatezza dei dati, i requisiti dell'azienda e leggi e normative applicabili.
Questa documentazione consente di comprendere come applicare il modello di responsabilità condivisa quando si usa Kinesis Video Streams. I seguenti argomenti illustrano come configurare Kinesis Video Streams per soddisfare gli obiettivi di sicurezza e conformità. È inoltre illustrato come utilizzare altri servizi AWS che consentono di monitorare e proteggere le risorse Kinesis Video Streams.
Argomenti • Protezione dei dati in Kinesis Video Streams (p. 29) • Controllo dell'accesso alle risorse Kinesis Video Streams che utilizzano IAM (p. 33) • Controllo dell'accesso alle risorse Kinesis Video Streams utilizzando AWS IoT (p. 37) • Monitoraggio di Amazon Kinesis Video Streams (p. 43) • Convalida della conformità per Amazon Kinesis Video Streams (p. 43) • Resilienza in Amazon Kinesis Video Streams (p. 44) • Sicurezza dell'infrastruttura in Kinesis Video Streams (p. 44) • Best practice relative alla sicurezza per Kinesis Video Streams (p. 44)
Protezione dei dati in Kinesis Video Streams
La crittografia lato server con le chiavi di AWS Key Management Service (AWS KMS) consente di rispettare in modo più agevole i rigidi requisiti di gestione dei dati tramite la crittografia dei dati inattivi in Amazon Kinesis Video Streams.
Argomenti • Cos'è la crittografia lato server per Kinesis Video Streams? (p. 30) • Considerazioni su costi, regioni e prestazioni (p. 30)
29 Amazon Kinesis Video Streams Guida per gli sviluppatori Cos'è la crittografia lato server per Kinesis Video Streams?
• Cosa devo fare per iniziare a utilizzare la crittografia lato server? (p. 31) • Creazione e utilizzo di chiavi master AWS KMS generate dall'utente (p. 31) • Autorizzazioni per l'uso di chiavi master AWS KMS generate dall'utente (p. 32)
Cos'è la crittografia lato server per Kinesis Video Streams?
La crittografia lato server è una funzione di Kinesis Video Streams che crittografa automaticamente i dati prima che diventino inattivi utilizzando una chiave master del cliente (CMK) di AWS KMS da te specificata. I dati vengono crittografati prima di essere scritti sul livello di storage del flusso di Kinesis Video Streams e vengono decrittografati dopo essere stati recuperati dallo storage. Di conseguenza, i dati vengono sempre crittografati mentre sono inattivi all'interno del servizio Kinesis Video Streams.
Grazie alla crittografia lato server, i producer e i consumatori del Kinesis video stream non devono gestire le chiavi master o le operazioni di crittografia. Se la conservazione dei dati è abilitata, i dati vengono automaticamente crittografati quando entrano ed escono da Kinesis Video Streams, in modo che i dati a riposo vengano crittografati. AWS KMS fornisce tutte le chiavi master che vengono utilizzate dalla funzione di crittografia lato server. AWS KMS semplifica l'uso di un CMK per Kinesis Video Streams gestito da AWS, un CMK di AWS KMS specificato dall'utente o una chiave master importata nel servizio AWS KMS. Considerazioni su costi, regioni e prestazioni
Quando applichi la crittografia lato server, vengono applicati dei costi collegati alla chiave e all'uso dell'API di AWS KMS. A differenza delle chiavi master AWS KMS personalizzate, la chiave master del cliente (CMK) (Default) aws/kinesis-video è disponibile gratuitamente. Tuttavia, occorre comunque corrispondere un pagamento per i costi di utilizzo dell'API affrontati da Kinesis Video Streams per tuo conto.
I costi di utilizzo dell'API vengono applicati per ogni CMK, incluse quelle personalizzate. I costi legati a KMS variano in base al numero di credenziali utente utilizzate si producer e consumer dei dati dal momento che ogni credenziale utente richiede una chiamata API univoca a AWS KMS.
Di seguito vengono descritti i costi per risorsa:
Chiavi
• La CMK per Kinesis Video Streams gestito da AWS (alias = aws/kinesis-video) è gratuita. • Le chiavi di AWS KMS generate dall'utente sono soggette ai costi delle chiavi di AWS KMS. Per ulteriori informazioni, consulta la sezione relativa ai prezzi di AWS Key Management Service.
Utilizzo di API AWS KMS
Le richieste dell'API di generare nuove chiavi di crittografia dei dati o di recuperare le chiavi di crittografia esistenti aumentano in modo proporzionale al traffico e sono soggette ai costi di utilizzo di AWS KMS. Per ulteriori informazioni, consulta la sezione relativa ai prezzi legati all'uso di AWS Key Management Service.
Kinesis Video Streams genera le richieste di chiave anche quando la conservazione è impostata su 0 (nessuna conservazione). Disponibilità della crittografia lato server in base alla regione
La crittografia lato server dei Kinesis video stream è disponibile in tutte le regioni AWS in cui si trova Kinesis Video Streams.
30 Amazon Kinesis Video Streams Guida per gli sviluppatori Cosa devo fare per iniziare a utilizzare la crittografia lato server? Cosa devo fare per iniziare a utilizzare la crittografia lato server?
Su Kinesis video stream, la crittografia lato server è sempre abilitata. Se al momento di creare il flusso non si specifica una chiave fornita dall'utente, viene usata quella predefinita (fornita da Kinesis Video Streams).
È necessario assegnare una chiave master di AWS KMS fornita dall'utente a un Kinesis video stream, nel momento in cui viene creato. Non potrai assegnare al flusso una chiave diversa in un secondo momento tramite l'API UpdateStream.
È possibile assegnare una chiave master di AWS KMS fornita dall'utente a un Kinesis video stream in due modi:
• Quando si crea un Kinesis video stream in AWS Management Console, specificare la chiave master AWS KMS nella scheda Encryption (Crittografia) nella pagina Create a new Video stream (Crea nuovo flusso video). • Quando si crea un Kinesis video stream utilizzando l'API CreateStream, specificare l'ID della chiave nel parametro KmsKeyId.
Creazione e utilizzo di chiavi master AWS KMS generate dall'utente
In questa sezione viene descritto come creare e utilizzare le chiavi master AWS KMS proprie piuttosto che utilizzare la chiave master amministrata da Amazon Kinesis Video Streams. Creazione di chiavi master AWS KMS generate dall'utente
Per informazioni su come creare chiavi master personalizzate, consulta la sezione relativa alla creazione di chiavi nella AWS Key Management Service Developer Guide. Dopo aver creato le chiavi per l'account, il servizio Kinesis Video Streams restituisce tali chiavi nell'elenco KMS master key (Chiave master di KMS). Utilizzo di chiavi master KMS di AWS KMS generate dall'utente
Dopo aver applicato le autorizzazioni corrette a consumatori, producer e amministratori, puoi utilizzare le chiavi master di AWS KMS personalizzate nel proprio account AWS o in un altro account AWS. Tutte le chiavi master di AWS KMS del tuo account vengono visualizzate nell'elenco KMS Master Key (Chiave master di KMS) nella console.
Per utilizzare le chiavi master di AWS KMS personalizzate che si trovano in un altro account, è necessario disporre delle relative autorizzazioni. Inoltre, occorre creare il flusso tramite l'API CreateStream. Non puoi utilizzare le chiavi master di AWS KMS da diversi account nei flussi creati nella console. Note
Non puoi accedere alla chiave di AWS KMS finché non esegui le operazioni PutMedia o GetMedia. Tali operazioni producono i risultati seguenti:
• Se la chiave specificata non esiste, l'operazione CreateStream riesce, ma le operazioni PutMedia e GetMedia sul flusso produrranno un errore. • Se utilizzi la chiave master fornita (aws/kinesis-video), quest'ultima non sarà visualizzata nel tuo account fino a quando non viene eseguita la prima operazione PutMedia o GetMedia.
31 Amazon Kinesis Video Streams Guida per gli sviluppatori Autorizzazioni per l'uso di chiavi master AWS KMS generate dall'utente Autorizzazioni per l'uso di chiavi master AWS KMS generate dall'utente
Prima di utilizzare la crittografia lato server con una chiave master AWS KMS generata dall'utente, devi configurare le policy della chiave di AWS KMS per consentire la crittografia dei flussi, nonché la crittografia e la decrittografia dei record di flusso. Per esempi e ulteriori informazioni sulle autorizzazioni di AWS KMS, consulta la sezione relativa alle autorizzazioni dell'API AWS KMS (documentazione di riferimento per operazioni e risorse). Note
L'utilizzo della chiave del servizio predefinita per la crittografia non richiede l'applicazione delle autorizzazioni IAM personalizzate.
Prima di utilizzare le chiavi master di AWS KMS generate dall'utente, assicurati che i producer e i consumatori del Kinesis video stream (entità IAM principali) siano registrati come utenti nella policy della chiave master di AWS KMS. In caso contrario, le operazioni di lettura e scrittura dai flussi non riusciranno, causando perdite di dati, ritardi delle elaborazioni o blocchi delle applicazioni. Puoi gestire le autorizzazioni relative alle chiavi AWS KMS tramite le policy IAM. Per ulteriori informazioni, consulta la sezione relativa all'uso delle policy IAM con AWS KMS. Autorizzazioni dei producer di esempio
I producer del Kinesis video stream devono disporre dell'autorizzazione kms:GenerateDataKey:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:GenerateDataKey" ], "Resource": "arn:aws:kms:us- west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, { "Effect": "Allow", "Action": [ "kinesis-video:PutMedia", ], "Resource": "arn:aws:kinesis-video:*:123456789012:MyStream" } ] }
Autorizzazioni dei consumatori di esempio
I consumatori del Kinesis video stream devono disporre dell'autorizzazione kms:Decrypt:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:Decrypt"
32 Amazon Kinesis Video Streams Guida per gli sviluppatori Controllo dell'accesso alle risorse Kinesis Video Streams che utilizzano IAM
], "Resource": "arn:aws:kms:us- west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab" }, { "Effect": "Allow", "Action": [ "kinesis-video:GetMedia", ], "Resource": "arn:aws:kinesis-video:*:123456789012:MyStream" } ] }
Controllo dell'accesso alle risorse Kinesis Video Streams che utilizzano IAM
Utilizzando AWS Identity and Access Management (IAM) con Amazon Kinesis Video Streams, puoi controllare se gli utenti all'interno dell'organizzazione sono in grado di eseguire un'attività utilizzando specifiche operazioni API Kinesis Video Streams e se possono utilizzare risorse AWS specifiche.
Per ulteriori informazioni su IAM, consulta:
• AWS Identity and Access Management (IAM) • Nozioni di base • Guida per l'utente di IAM
Indice • Sintassi delle policy (p. 33) • Operazioni per Kinesis Video Streams (p. 34) • Amazon Resource Name (ARN) per Kinesis Video Streams (p. 34) • Concessione dell'accesso ad altri account IAM a un flusso di video Kinesis (p. 35) • Esempi di policy per Kinesis Video Streams (p. 35)
Sintassi delle policy
Una policy IAM è un documento JSON costituito da una o più dichiarazioni. Ogni dichiarazione è strutturata come segue:
{ "Statement":[{ "Effect":"effect", "Action":"action", "Resource":"arn", "Condition":{ "condition":{ "key":"value" } } } ]
33 Amazon Kinesis Video Streams Guida per gli sviluppatori Operazioni per Kinesis Video Streams
}
Una dichiarazione è costituita da diversi elementi:
• Effect (Effetto): l'elemento effect può essere Allow o Deny. Per impostazione predefinita, gli utenti IAM non dispongono dell'autorizzazione per l'utilizzo di risorse e operazioni API, pertanto tutte le richieste vengono rifiutate. Un permesso esplicito sostituisce l'impostazione predefinita. Un rifiuto esplicito sovrascrive tutti i consensi. • Action (Operazione): l'elemento action corrisponde all'operazione API specifica per la quale si concede o si nega l'autorizzazione. • Resource (Risorsa): la risorsa che viene modificata dall'operazione. Per specificare una risorsa nella dichiarazione, devi utilizzare il relativo Amazon Resource Name (ARN). • Condition: le condizioni sono facoltative. Possono essere utilizzate per controllare quando è in vigore una policy.
Quando crei e gestisci policy IAM, puoi utilizzare gli strumenti IAM Policy Generator e IAM Policy Simulator. Operazioni per Kinesis Video Streams
In una dichiarazione di policy IAM, è possibile specificare qualsiasi operazione API per qualsiasi servizio che supporta IAM. Per Kinesis Video Streams, utilizza il seguente prefisso con il nome dell'operazione API: kinesisvideo:. For example: kinesisvideo:CreateStream, kinesisvideo:ListStreams e kinesisvideo:DescribeStream.
Per specificare più operazioni in una sola dichiarazione, separa ciascuna di esse con una virgola come mostrato di seguito:
"Action": ["kinesisvideo:action1", "kinesisvideo:action2"]
Puoi anche specificare più operazioni tramite caratteri jolly. Ad esempio, puoi specificare tutte le operazioni il cui nome inizia con la parola "Get" come segue:
"Action": "kinesisvideo:Get*"
Per specificare tutte le operazioni di Kinesis Video Streams, utilizza il carattere jolly asterisco (*) come mostrato di seguito:
"Action": "kinesisvideo:*"
Per l'elenco completo delle operazioni API Kinesis Video Streams, consulta il Riferimento per le API Kinesis Video Streams. Amazon Resource Name (ARN) per Kinesis Video Streams
Ogni dichiarazione di policy IAM si applica alle risorse specificate utilizzando i relativi ARN.
Usa il seguente formato di risorsa ARN per Kinesis Video Streams: arn:aws:kinesisvideo:region:account-id:stream/stream-name/code
34 Amazon Kinesis Video Streams Guida per gli sviluppatori Concessione dell'accesso ad altri account IAM a un flusso di video Kinesis
Ad esempio:
"Resource": arn:aws:kinesisvideo::*:111122223333:stream/my-stream/0123456789012
Puoi ottenere l'ARN di un flusso utilizzando DescribeStream. Concessione dell'accesso ad altri account IAM a un flusso di video Kinesis
Potrebbe essere necessario concedere autorizzazioni per altri IAM account per eseguire operazioni su Kinesis video stream. La seguente panoramica descrive i passi per concedere l'accesso ai flussi video su tutti gli account:
1. Scarica l'ID account a 12 cifre dell'account a cui vuoi concedere le autorizzazioni per eseguire operazioni sul flusso (per esempio, 111111111111). 2. Crea una policy gestita per l'account che possiede il flusso che consenta il livello di accesso che vuoi concedere. Per esempi di policy per le risorse Kinesis Video Streams, consulta Policy di esempio (p. 35) nella sezione successiva. 3. Crea un ruolo, specificando l'account a cui vuoi concedere le autorizzazioni e collega la policy creata nella fase precedente. 4. Crea una policy gestita che consenta l'azione AssumeRole sul ruolo creato nella fase precedente. Ad esempio, il ruolo potrebbe apparire come segue:
{ "Version": "2012-10-17", "Statement": { "Effect": "Allow", "Action": "sts:AssumeRole", "Resource": "arn:aws:iam::123456789012:role/CustomRole" } }
Per istruzioni dettagliate su come concedere l'accesso a più account, consulta Come delegare l'accesso su più account AWS utilizzando i ruoli IAM. Esempi di policy per Kinesis Video Streams
Le policy di esempio seguenti dimostrano in che modo puoi controllare l'accesso degli utenti ai Kinesis video stream.
Example 1: Consenti agli utenti di ottenere i dati da un Kinesis video stream
Questa policy consente a un utente o a un gruppo di eseguire le operazioni DescribeStream, GetDataEndpoint, GetMedia, ListStreams e ListTagsForStream su qualsiasi Kinesis video stream. Questa policy è appropriata per gli utenti che possono ottenere i dati da qualsiasi flusso di video.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kinesisvideo:Describe*",
35 Amazon Kinesis Video Streams Guida per gli sviluppatori Policy di esempio
"kinesisvideo:Get*", "kinesisvideo:List*" ], "Resource": "*" } ] }
Example 2: Consenti a un utente di creare un Kinesis video stream e di scrivervi dati
Questa policy consente a un utente o a un gruppo di eseguire le operazioni CreateStream e PutMedia. Questa policy è appropriata per una fotocamera di sicurezza su cui è possibile creare un flusso di video e inviare dati.
{ "Statement": [ { "Effect": "Allow", "Action": [ "kinesisvideo:CreateStream", "kinesisvideo:PutMedia" ], "Resource": "*" } ] }
Example 3: Concedi a un utente l'accesso completo a tutte le risorse Kinesis Video Streams
Questa policy consente a un utente o a un gruppo di eseguire qualsiasi operazione Kinesis Video Streams su qualsiasi risorsa. Questa policy è appropriata per gli amministratori.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "kinesisvideo:*", "Resource": "*" } ] }
Example 4: Consenti a un utente di scrivere dati su un determinato Kinesis video stream
Questa policy consente a un utente o a un gruppo di scrivere dati su un determinato flusso di video. Questa policy è appropriata per un dispositivo in grado di inviare dati a un solo flusso.
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": "kinesisvideo:PutMedia", "Resource": "arn:aws:kinesisvideo:us-west-2:123456789012:stream/ your_stream/0123456789012" } ] }
36 Amazon Kinesis Video Streams Guida per gli sviluppatori Controllo dell'accesso alle risorse Kinesis Video Streams utilizzando AWS IoT Controllo dell'accesso alle risorse Kinesis Video Streams utilizzando AWS IoT
Questa sezione descrive come abilitare un dispositivo (ad esempio, una videocamera) per inviare dati audio/video solo a un determinato flusso video Kinesis. A tale scopo, è possibile utilizzare il provider di credenziali AWS IoT e un ruolo AWS Identity and Access Management (IAM).
I dispositivi possono usare certificati X.509 per connettersi ad AWS IoT tramite protocolli di autenticazione reciproca TLS. Altri servizi AWS (ad esempio, Kinesis Video Streams) non supportano l'autenticazione basata su certificati, ma possono essere chiamati tramite credenziali AWS in formato AWS Signature Version 4. L'algoritmo Signature Version 4 normalmente richiede all'intermediario di disporre di un ID chiave di accesso e di una chiave di accesso segreta. AWS IoT dispone di un provider di credenziali che consente di utilizzare il certificato X.509 integrato come identità univoca del dispositivo per autenticare le richieste AWS (ad esempio, le richieste a Kinesis Video Streams). Ciò elimina la necessità di archiviare un ID chiave di accesso e la chiave di accesso segreta sul dispositivo.
Il provider di credenziali autentica un client (in questo caso, un SDK Kinesis Video Streams in esecuzione sulla videocamera da cui si desidera inviare dati a un flusso video) utilizzando un certificato X.509 ed emette un token di sicurezza temporaneo con privilegi limitati. Il token può essere utilizzato per firmare e autenticare qualsiasi richiesta AWS (in questo caso, una chiamata a Kinesis Video Streams). Per ulteriori informazioni, consulta Autorizzazione di chiamate dirette ai servizi AWS.
Questa modalità di autenticazione delle richieste della fotocamera a Kinesis Video Streams necessita della configurazione di un ruolo IAM e di collegarvi policy IAM appropriate, in modo che il fornitore di credenziali IoT possa assumere il ruolo per conto dell'utente.
Per ulteriori informazioni su AWS IoT, consulta la documentazione di AWS IoT Core. Per ulteriori informazioni su IAM, consulta AWS Identity and Access ManagementIAM.
Argomenti • IoT ThingName come nome del flusso (p. 37) • IoT CertificateID come nome del flusso (p. 42)
IoT ThingName come nome del flusso
Argomenti • Fase 1: creazione di un tipo di oggetto IoT e un oggetto IoT (p. 37) • Fase 2: creazione di un ruolo IAM che deve essere assunto da IoT (p. 38) • Fase 3: creazione e configurazione del certificato X.509 (p. 40) • Fase 4: test delle credenziali IoT con Kinesis Video Stream (p. 41) • Fase 5: distribuzione di certificati e credenziali IoT sul file system della fotocamera e streaming di dati nel flusso video (p. 41)
Fase 1: creazione di un tipo di oggetto IoT e un oggetto IoT
Un oggetto è una rappresentazione di un'entità logica o un di dispositivo specifico. In questo caso, un oggetto IoT rappresenta il flusso video Kinesis per il quale desideri configurare il controllo degli accessi a livello di risorsa. Per creare un oggetto, devi prima creare un tipo di oggetto IoT. I tipi di oggetti permettono di archiviare la descrizione e le informazioni di configurazione comuni a tutti gli oggetti associati allo stesso tipo.
1. Il comando di esempio seguente crea un tipo di oggetto kvs_example_camera:
37 Amazon Kinesis Video Streams Guida per gli sviluppatori IoT ThingName come nome del flusso
aws --profile default iot create-thing-type --thing-type-name kvs_example_camera > iot-thing-type.json
2. Questo comando di esempio crea l'oggetto kvs_example_camera_stream del tipo di oggetto kvs_example_camera:
aws --profile default iot create-thing --thing-name kvs_example_camera_stream --thing- type-name kvs_example_camera > iot-thing.json
Fase 2: creazione di un ruolo IAM che deve essere assunto da IoT
I ruoli IAM sono simili agli utenti IAM, in quanto un ruolo è un'identità AWS con policy di autorizzazioni che determinano ciò che l'identità può e non può fare in AWS. Un ruolo può essere assunto da chiunque ne abbia bisogno. Tuttavia, quando assumi un ruolo, vengono fornite le credenziali di sicurezza provvisorie per la sessione del ruolo.
Il ruolo creato in questa fase può essere assunto da IoT per ottenere credenziali temporanee dal servizio token di sicurezza (STS) durante l'esecuzione di richieste di autorizzazione delle credenziali dal client. In questo caso, il client è l'SDK Kinesis Video Streams in esecuzione sulla fotocamera.
Eseguire la procedura seguente per creare e configurare questo ruolo IAM:
1. Creare un ruolo IAM.
Il comando di esempio seguente crea un ruolo IAM denominato KVSCameraCertificateBasedIAMRole:
aws --profile default iam create-role --role-name KVSCameraCertificateBasedIAMRole -- assume-role-policy-document 'file://iam-policy-document.json' > iam-role.json
Puoi utilizzare il seguente JSON della policy di attendibilità per iam-policy-document.json:
{ "Version":"2012-10-17", "Statement":[ { "Effect":"Allow", "Principal":{ "Service":"credentials.iot.amazonaws.com" }, "Action":"sts:AssumeRole" } ] }
2. Quindi, devi collegare una policy di autorizzazione al ruolo IAM creato in precedenza. Questa policy di autorizzazione consente il controllo selettivo degli accessi (un sottoinsieme di operazioni supportate) per una risorsa AWS. In questo caso, la risorsa AWS è il flusso video a cui desideri che la fotocamera
38 Amazon Kinesis Video Streams Guida per gli sviluppatori IoT ThingName come nome del flusso
invii i dati. In altre parole, una volta completate tutte le fasi di configurazione, questa telecamera sarà in grado di inviare dati solo a questo flusso video.
aws --profile default iam put-role-policy --role-name KVSCameraCertificateBasedIAMRole --policy-name KVSCameraIAMPolicy --policy-document 'file://iam-permission- document.json'
Puoi utilizzare la seguente policy JSON IAM per iam-permission-document.json:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kinesisvideo:DescribeStream", "kinesisvideo:PutMedia", "kinesisvideo:TagStream", "kinesisvideo:GetDataEndpoint" ], "Resource": "arn:aws:kinesisvideo:*:*:stream/${credentials-iot:ThingName}/ *" } ] }
Questa policy autorizza le operazioni specificate solo su un flusso video (risorsa AWS) specificato dal segnaposto (${credentials-iot:ThingName}). Questo segnaposto assume il valore dell'attributo dell'oggetto IoT ThingName quando il provider di credenziali IoT invia il nome del flusso video nella richiesta. 3. Quindi, crea un alias ruolo per il ruolo IAM. L'alias del ruolo è un modello di dati alternativo che punta al ruolo IAM. Una richiesta di provider di credenziali IoT deve includere un alias-ruolo per indicare quale ruolo IAM assumere per ottenere le credenziali temporanee da STS.
Il comando di esempio seguente crea un alias del ruolo denominato KvsCameraIoTRoleAlias.
aws --profile default iot create-role-alias --role-alias KvsCameraIoTRoleAlias --role- arn $(jq --raw-output '.Role.Arn' iam-role.json) --credential-duration-seconds 3600 > iot-role-alias.json
4. Ora puoi creare la policy che consentirà a IoT di assumere il ruolo con il certificato (una volta collegato) utilizzando l'alias del ruolo.
Il comando di esempio seguente crea una policy per IoT denominata KvsCameraIoTPolicy.
aws --profile default iot create-policy --policy-name KvsCameraIoTPolicy --policy- document 'file://iot-policy-document.json'
Puoi utilizzare il comando seguente per creare il JSON del documento iot-policy-document.json:
cat > iot-policy-document.json < 39 Amazon Kinesis Video Streams Guida per gli sviluppatori IoT ThingName come nome del flusso { "Effect":"Allow", "Action":[ "iot:Connect" ], "Resource":"$(jq --raw-output '.roleAliasArn' iot-role-alias.json)" }, { "Effect":"Allow", "Action":[ "iot:AssumeRoleWithCertificate" ], "Resource":"$(jq --raw-output '.roleAliasArn' iot-role-alias.json)" } ] } EOF Fase 3: creazione e configurazione del certificato X.509 La comunicazione tra un dispositivo (il flusso video) e AWS IoT è protetta tramite l'uso di certificati X.509. 1. Crea il certificato a cui devi collegare la policy per IoT creata in precedenza. aws --profile default iot create-keys-and-certificate --set-as-active --certificate- pem-outfile certificate.pem --public-key-outfile public.pem.key --private-key-outfile private.pem.key > certificate 2. Collegare la policy per IoT (KvsCameraIoTPolicy creata in precedenza) a questo certificato. aws --profile default iot attach-policy --policy-name KvsCameraIoTPolicy --target $(jq --raw-output '.certificateArn' certificate) 3. Collegare l'oggetto IoT (kvs_example_camera_stream) al certificato appena creato: aws --profile default iot attach-thing-principal --thing-name kvs_example_camera_stream --principal $(jq --raw-output '.certificateArn' certificate) 4. Per autorizzare le richieste tramite il provider di credenziali IoT, è necessario l'endpoint delle credenziali IoT univoco per l'ID dell'account AWS. Puoi utilizzare il comando seguente per ottenere l'endpoint delle credenziali IoT. aws --profile default iot describe-endpoint --endpoint-type iot:CredentialProvider -- output text > iot-credential-provider.txt 5. Oltre al certificato X.509 creato sopra, è necessario disporre anche di un certificato CA per stabilire l'attendibilità con il servizio di back-end tramite TLS. Puoi ottenere il certificato CA utilizzando il comando seguente: 40 Amazon Kinesis Video Streams Guida per gli sviluppatori IoT ThingName come nome del flusso curl --silent 'https://www.amazontrust.com/repository/SFSRootCAG2.pem' --output cacert.pem Fase 4: test delle credenziali IoT con Kinesis Video Stream Ora puoi testare le credenziali IoT che hai configurato fino a questo momento. 1. In primo luogo, creare un Kinesis Video Stream con cui testare questa configurazione. Important Crea un flusso video con un nome identico al nome dell'oggetto IoT creato nella fase precedente (kvs_example_camera_stream). aws kinesisvideo create-stream --data-retention-in-hours 24 --stream-name kvs_example_camera_stream 2. Quindi, chiamare il provider di credenziali IoT per ottenere le credenziali temporanee: curl --silent -H "x-amzn-iot-thingname:kvs_example_camera_stream" --cert certificate.pem --key private.pem.key https://IOT_GET_CREDENTIAL_ENDPOINT/role- aliases/KvsCameraIoTRoleAlias/credentials --cacert ./cacert.pem > token.json Note È possibile utilizzare il comando seguente per ottenere IOT_GET_CRENDETIAL_ENDPOINT: IOT_GET_CREDENTIAL_ENDPOINT=`cat iot-credential-provider.txt` L'output JSON contiene accessKey, secretKey e sessionToken che è possibile utilizzare per accedere a Kinesis Video Streams. 3. Ora, per il test, puoi utilizzare queste credenziali per richiamare l'API DescribeStream di Kinesis Video Streams per il flusso video kvs_example_camera_stream di esempio. AWS_ACCESS_KEY_ID=$(jq --raw-output '.credentials.accessKeyId' token.json) AWS_SECRET_ACCESS_KEY=$(jq --raw-output '.credentials.secretAccessKey' token.json) AWS_SESSION_TOKEN=$(jq --raw-output '.credentials.sessionToken' token.json) aws kinesisvideo describe-stream --stream-name kvs_example_camera_stream Fase 5: distribuzione di certificati e credenziali IoT sul file system della fotocamera e streaming di dati nel flusso video Note Le fasi illustrate in questa sezione descrivono l'invio di contenuti multimediali a un flusso video Kinesis da una videocamera che utilizza C++ Producer Library. 41 Amazon Kinesis Video Streams Guida per gli sviluppatori IoT CertificateID come nome del flusso 1. Copiare il certificato X.509, la chiave privata e il certificato CA generato nelle fasi precedenti nel file system della telecamera. È necessario specificare i percorsi in cui vengono archiviati questi file, il nome alias del ruolo e l'endpoint delle credenziali IOT per eseguire il comando gst-launch-1.0 o l'applicazione di esempio. 2. Il comando di esempio seguente utilizza l'autorizzazione del certificato IoT per inviare video a Kinesis Video Streams: $ gst-launch-1.0 rtspsrc location=rtsp://YourCameraRtspUrl short-header=TRUE ! rtph264depay ! video/x-h264, format=avc,alignment=au ! h264parse ! kvssink stream-name="kvs_example_camera_stream" iot-certificate="iot- certificate,endpoint=iot-credential-endpoint-host-name,cert-path=/path/to/ certificate.pem,key-path=/path/to/private.pem.key,ca-path=/path/to/cacert.pem,role- aliases=KvsCameraIoTRoleAlias" IoT CertificateID come nome del flusso Se si desidera rappresentare il dispositivo (ad esempio la fotocamera) tramite un oggetto IoT ma autorizzare un nome di flusso diverso, è possibile utilizzare l'attributo IoT certifiacateId come nome del flusso e fornire a Kinesis Video Streams le autorizzazioni per il flusso che utilizza IoT. Le fasi per eseguire questa operazione sono simili a quelle descritte in precedenza, con alcune modifiche. • Modificare le policy di autorizzazioni nel ruolo IAM (iam-permission-document.json) come segue: { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kinesisvideo:DescribeStream", "kinesisvideo:PutMedia", "kinesisvideo:TagStream", "kinesisvideo:GetDataEndpoint" ], "Resource": "arn:aws:kinesisvideo:*:*:stream/${credentials- iot:AwsCertificateId}/*" } ] } Note L'ARN risorsa utilizza l'ID certificato come segnaposto per il nome del flusso. L'autorizzazione IAM funzionerà quando si utilizza l'ID certificato come nome del flusso. Ottenere l'ID dal certificato in modo che si possa utilizzarlo come nome del flusso nella seguente chiamata API di descrizione del flusso. export CERTIFICATE_ID=`cat certificate | jq --raw-output '.certificateId'jq -- raw-output '.certificateId'` • Verificare questa modifica utilizzando il comando CLI describe-stream di Kinesis Video Streams: 42 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio AWS_ACCESS_KEY_ID=$(jq --raw-output '.credentials.accessKeyId' token.json) AWS_SECRET_ACCESS_KEY=$(jq --raw-output '.credentials.secretAccessKey' token.json) AWS_SESSION_TOKEN=$(jq --raw-output '.credentials.sessionToken' token.json) aws kinesisvideo describe-stream --stream-name ${CERTIFICATE_ID} • Inviare certificatId al provider di credenziali IoT nell'applicazione di esempio nell'SDK C++ di Kinesis Video Streams: credential_provider = make_unique Note Si noti che si sta inviando thingname al provider di credenziali IoT. È possibile utilizzare getenv per passare thingname all'applicazione demo in modo simile all'invio degli altri attributi IoT. Utilizzare l'ID certificato come nome del flusso nei parametri della riga di comando quando si esegue l'applicazione di esempio. Monitoraggio di Amazon Kinesis Video Streams Kinesis Video Streams fornisce funzionalità di monitoraggio per i flussi di distribuzione. Per ulteriori informazioni, consulta Monitoraggio (p. 151). Convalida della conformità per Amazon Kinesis Video Streams Revisori di terze parti valutano la sicurezza e la conformità di Amazon Kinesis Video Streams come parte di più programmi di conformità di AWS. Sono inclusi SOC, PCI e HIPAA. Per un elenco di servizi AWS nell'ambito di programmi di conformità specifici, consulta Servizi AWS coperti dal programma di conformità. Per informazioni generali, consulta Programmi per la conformità di AWS. Puoi scaricare i report di audit di terze parti utilizzando AWS Artifact. Per ulteriori informazioni, consulta Download dei rapporti in AWS Artifact. La tua responsabilità di conformità durante l'utilizzo di Kinesis Video Streams è determinata dalla riservatezza dei dati, dagli obiettivi dell'azienda e dalle leggi e normative applicabili. Se l'utilizzo di Kinesis Video Streams è soggetto a conformità con standard quali HIPAA o PCI, AWS fornisce risorse utili: • Guide Quick Start Sicurezza e compliance: queste guide alla distribuzione illustrano considerazioni relative all'architettura e forniscono procedure per la distribuzione di ambienti di base incentrati sulla sicurezza e sulla conformità su AWS. • Architecting for HIPAA Security and Compliance Whitepaper : questo whitepaper descrive in che modo le aziende possono utilizzare AWS per creare applicazioni conformi ai requisiti HIPAA. 43 Amazon Kinesis Video Streams Guida per gli sviluppatori Flessibilità • Risorse AWS per la conformità: questa raccolta di cartelle di lavoro e guide potrebbe essere utile per l'industria e la posizione. • AWS Config: questo servizio AWS valuta il livello di conformità delle configurazioni delle risorse con procedure interne, linee guida e regolamenti di settore. • AWS Security Hub: questo servizio AWS fornisce una visione completa dello stato di sicurezza all'interno di AWS che consente di verificare la conformità con standard industriali di sicurezza e best practice. Resilienza in Amazon Kinesis Video Streams L'infrastruttura globale di AWS è basata su regioni e zone di disponibilità AWS. Le regioni AWS forniscono più zone di disponibilità fisicamente separate e isolate che sono connesse tramite reti altamente ridondanti, a bassa latenza e throughput elevato. Con le zone di disponibilità, è possibile progettare e gestire le applicazioni e database che eseguono il failover automatico tra zone di disponibilità senza interruzioni. Le zone di disponibilità sono più disponibili, tolleranti ai guasti e scalabili rispetto alle infrastrutture a data center singolo o multiplo. Per ulteriori informazioni sulle regioni e le zone di disponibilità AWS, consulta Infrastruttura globale di AWS. Sicurezza dell'infrastruttura in Kinesis Video Streams Come servizio gestito, Amazon Kinesis Video Streams è protetto da AWS procedure globali di sicurezza della rete descritte nel Amazon Web Services: : panoramica dei processi di sicurezza (whitepaper) Utilizza le chiamate all'API pubblicate di AWS per accedere a Kinesis Video Streams tramite la rete. I client devono supportare Transport Layer Security (TLS) 1.2 o versioni successive. I client devono inoltre supportare le suite di cifratura con PFS (Perfect Forward Secrecy), ad esempio Ephemeral Diffie-Hellman (DHE) o Elliptic Curve Ephemeral Diffie-Hellman (ECDHE). La maggior parte dei sistemi moderni, come Java 7 e versioni successive, supporta tali modalità. Inoltre, le richieste devono essere firmate utilizzando un ID chiave di accesso e una chiave di accesso segreta che è associata a un'entità IAM. In alternativa, puoi utilizzare AWS Security Token Service (AWS STS) per generare le credenziali di sicurezza temporanee per firmare le richieste. Best practice relative alla sicurezza per Kinesis Video Streams Amazon Kinesis Video Streams fornisce una serie di funzionalità di sicurezza da considerare quando sviluppi e implementi le tue policy di sicurezza. Le seguenti best practice sono linee guida generali e non rappresentano una soluzione di sicurezza completa. Poiché queste best practice potrebbero non essere appropriate o sufficienti per l'ambiente, trattale come utili considerazioni piuttosto che come istruzioni. Per le best practice di sicurezza per i tuoi dispositivi remoti, consulta Best practice per la sicurezza degli agenti dei dispositivi. Implementazione dell'accesso ai privilegi minimi Nel concedere le autorizzazioni, decidi chi ottiene le autorizzazioni a livello di risorse Kinesis Video Streams. Puoi abilitare operazioni specifiche che desideri consentire su tali risorse. Pertanto è necessario 44 Amazon Kinesis Video Streams Guida per gli sviluppatori Uso di ruoli IAM concedere solo le autorizzazioni necessarie per eseguire un'attività. L'implementazione dell'accesso ai privilegi minimi è fondamentale per ridurre i rischi per la sicurezza e l'impatto che potrebbe derivare da errori o intenzioni dannose. Ad esempio, un producer che invia a Kinesis Video Streams richiede solo PutMedia, GetStreamingEndpoint e DescribeStream. Non concedere autorizzazioni delle applicazioni del producer per tutte le operazioni (*) o per altre operazioni, ad esempio GetMedia. Per ulteriori informazioni, consulta l'argomento che descrive qual è il privilegio minimo e perché è necessario. Uso di ruoli IAM Le applicazioni producer e client devono avere credenziali valide per accedere ai flussi video Kinesis. Non memorizzare le credenziali AWS direttamente in un'applicazione client o in un bucket Amazon S3. Si tratta di credenziali a lungo termine che non vengono automaticamente ruotate e potrebbero avere un impatto aziendale significativo se vengono compromesse. Al contrario, è consigliabile utilizzare un ruolo IAM per gestire le credenziali temporanee per le applicazioni producer e client per accedere ai flussi video Kinesis. Quando utilizzi un ruolo, non devi necessariamente usare credenziali a lungo termine (come, ad esempio, nome utente e password oppure chiavi di accesso) per accedere ad altre risorse. Per ulteriori informazioni, consulta gli argomenti seguenti nella Guida per l'utente di IAM: • Ruoli IAM • Scenari comuni per ruoli: utenti, applicazioni e servizi Uso di CloudTrail per il monitoraggio delle chiamate API Kinesis Video Streams è integrato con AWS CloudTrail, un servizio che offre un record delle operazioni eseguite da un utente, un ruolo o un servizio AWS in Kinesis Video Streams. Le informazioni raccolte da CloudTrail consentono di determinare la richiesta effettuata a Kinesis Video Streams, l'indirizzo IP di origine da cui è stata eseguita la richiesta, l'autore della richiesta, il momento in cui è stata eseguita e altri dettagli. Per ulteriori informazioni, consulta the section called “Registrazione delle chiamate API con CloudTrail” (p. 162). 45 Amazon Kinesis Video Streams Guida per gli sviluppatori Client Kinesis Video Streams Producer Kinesis Video Streams Producer Library Le Amazon Kinesis Video Streams Producer Library sono un insieme di librerie di semplice utilizzo che fanno parte dell'SDK di Kinesis Video Streams Producer. Il client utilizza librerie e SDK per sviluppare un'applicazione su dispositivo che consenta di connettersi in modo sicuro a Kinesis Video Streams e trasmettere in streaming video e altri dati multimediali che possono essere visualizzati nella console o nelle applicazioni client in tempo reale. I dati multimediali possono essere diffusi nei seguenti modi: • Streaming di dati multimediali in tempo reale • Streaming di dati multimediali dopo il buffering per alcuni secondi • Streaming di caricamenti multimediali successivi Dopo aver creato un flusso Kinesis Video Streams, è possibile iniziare a inviare dati a esso. È possibile usare l'SDK per creare il codice dell'applicazione che consente di estrarre i dati video (frame) dall'origine multimediale e di caricarli su Kinesis Video Streams. Queste applicazioni vengono anche definite applicazioni producer. Le Producer Library contengono i seguenti componenti: • Client Kinesis Video Streams Producer (p. 46) • Kinesis Video Streams Producer Library (p. 47) Client Kinesis Video Streams Producer Il client Kinesis Video Streams Producer include una singola classe KinesisVideoClient. Questa classe gestisce le origini multimediali, ne riceve i dati e gestisce il ciclo di vita dei flussi di dati da un'origine multimediale a Kinesis Video Streams. Inoltre, offre un'interfaccia MediaSource per definire l'interazione tra Kinesis Video Streams e l'hardware e il software proprietari. Un'origine multimediale può essere costituita da pressoché qualsiasi elemento. Ad esempio, è possibile utilizzare un'origine multimediale sotto forma di fotocamera o microfono. Le origini multimediali sorgenti non si limitano a sorgenti audio e video. Ad esempio, i log dei dati potrebbero essere file di testo, che tuttavia possono sempre essere inviati come flusso di dati. Puoi inoltre disporre di più telecamere sul tuo telefono che trasmettono in streaming i dati simultaneamente. Per ottenere i dati da qualsiasi di queste origini, puoi implementare l'interfaccia MediaSource. Questa interfaccia consente ulteriori scenari per cui non forniamo il supporto integrato. Ad esempio, puoi scegliere di inviare gli elementi seguenti a Kinesis Video Streams: • Un flusso di dati diagnostici (ad esempio, i log dell'applicazione e gli eventi) • I dati provenienti da telecamere a infrarossi, RADAR o telecamere di profondità Kinesis Video Streams non fornisce implementazioni integrate per i dispositivi di produzione multimediale, come le videocamere. Per estrarre i dati provenienti da questi dispositivi, è necessario implementare il codice, creando la tua implementazione di origine multimediale personalizzate. Potrai quindi registrare le origini multimediali personalizzate in modo esplicito con KinesisVideoClient, che carica i dati su Kinesis Video Streams. 46 Amazon Kinesis Video Streams Guida per gli sviluppatori Kinesis Video Streams Producer Library Il client di Kinesis Video Streams Producer è disponibile per le applicazioni Java e Android. Per ulteriori informazioni, consulta Utilizzo di Java Producer Library (p. 47) e Utilizzo di Android Producer Library (p. 51). Kinesis Video Streams Producer Library La Kinesis Video Streams Producer Library è contenuta all'interno del client Kinesis Video Streams Producer. La libreria è disponibile anche per l'uso diretto da parte di chi desidera un'integrazione completa con Kinesis Video Streams. Ciò consente l'integrazione da dispositivi con sistemi operativi proprietari, stack di rete oppure risorse sul dispositivo limitate. La Kinesis Video Streams Producer Library implementa la macchina a stati per lo streaming al Kinesis Video Streams. Offre hook di callback, che ti richiedono di fornire la tua implementazione di trasporto e di gestire in modo esplicito ogni messaggio da e verso il servizio. Puoi scegliere di utilizzare la Kinesis Video Streams Producer Library direttamente per i motivi seguenti: • Il dispositivo in cui vuoi eseguire l'applicazione non ha una macchina virtuale Java. • Vuoi scrivere il codice dell'applicazione in altri linguaggi diversi da Java. • Potresti disporre di Java sul dispositivo, ma vuoi ridurre il sovraccarico nel codice e limitare al minimo il livello di astrazione, a causa di limitazioni quali memoria e potenza di elaborazione. Attualmente, Kinesis Video Streams Producer Library è disponibile per le applicazioni C++. Per ulteriori informazioni, consulta Utilizzo di C++ Producer Library (p. 56). Argomenti correlati Utilizzo di Java Producer Library (p. 47) Utilizzo di Android Producer Library (p. 51) Utilizzo di C++ Producer Library (p. 56) ??? (p. 65) Utilizzo di Java Producer Library Amazon Kinesis Video Streams fornisce Java Producer Library, che puoi utilizzare per scrivere il codice dell'applicazione, con una configurazione minima, per inviare dati multimediali da un dispositivo a un Kinesis video stream. È necessario attenersi alla procedura seguente per integrare il codice con Kinesis Video Streams, in modo che l'applicazione possa inviare i dati in streaming al Kinesis video stream: 1. Crea un'istanza dell'oggetto KinesisVideoClient. 2. Crea un oggetto MediaSource fornendo informazioni sull'origine multimediale. Ad esempio, durante la creazione di un'origine multimediale fotocamera, devi fornire informazioni quali l'identificazione della fotocamera e specificare la codifica utilizzata dalla fotocamera. Quando vuoi avviare lo streaming, devi creare un'origine multimediale personalizzata. 3. Registra l'origine multimediale con KinesisVideoClient. 47 Amazon Kinesis Video Streams Guida per gli sviluppatori Procedura: utilizzo dell'SDK Java Producer Dopo che hai registrano l'origine multimediale con KinesisVideoClient, ogni volta che i dati diventano disponibili con tale origine, viene chiamato KinesisVideoClient con i dati. Procedura: utilizzo dell'SDK Java Producer Questa procedura illustra come utilizzare il client Kinesis Video Streams Java Producer nell'applicazione Java per inviare i dati al Kinesis video stream. Per questa procedura non è necessario disporre di un'origine multimediale, come una videocamera o un microfono. Al contrario, a scopo di test, il codice genera frame di esempio composti da una serie di byte. Puoi utilizzare lo stesso modello di codifica quando invii dati multimediali da origini reali, come videocamere e microfoni. La procedura include le seguenti fasi: • Download e configurazione del codice • Scrittura e analisi del codice • Esecuzione e verifica del codice Prerequisiti • Nel codice di esempio, fornisci le credenziali specificando un profilo configurato nel file del profilo delle credenziali AWS. Se non lo hai già fatto, configura prima il profilo delle credenziali. Per ulteriori informazioni, consulta la sezione Configurazione della regione e delle credenziali per lo sviluppo di AWS nella AWS SDK for Java. Note Per ottenere le credenziali AWS, l'esempio Java utilizza un oggetto SystemPropertiesCredentialsProvider. Il provider recupera queste credenziali dalle proprietà del sistema Java aws.accessKeyId e aws.secretKey. Puoi impostare queste proprietà nel tuo ambiente di sviluppo Java. Per informazioni su come impostare le proprietà del sistema Java, consulta la documentazione per il tuo ambiente di sviluppo integrato (IDE) specifico. • L'elemento NativeLibraryPath deve contenere il file KinesisVideoProducerJNI, disponibile all'indirizzo https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp. L'estensione del nome di questo file varia a seconda del sistema operativo: • KinesisVideoProducerJNI.so per Linux • KinesisVideoProducerJNI.dylib per macOS • KinesisVideoProducerJNI.dll per Windows Note Librerie predefinite per macOS, Ubuntu, Windows e Raspbian sono disponibili in src/main/ resources/lib alla pagina https://github.com/awslabs/amazon-kinesis-video-streams- producer-sdk-java. Per altri ambienti, compila C++ Producer Library (p. 56). Fase 1: download e configurazione del codice di Java Producer Library In questa sezione della procedura per Java Producer Library puoi scaricare il codice di esempio Java, importare il progetto nell'IDE Java e configurare i percorsi della libreria. 48 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice Per i prerequisiti e altri dettagli su questo esempio, consulta l'articolo sull'utilizzo di Java Producer Library. 1. Crea una directory, quindi clona il codice di origine di esempio dal repository GitHub. $ git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java 2. Apri l'ambiente di sviluppo integrato (IDE) Java in uso (ad esempio Eclipse o JetBrains IntelliJ IDEA) e importa il progetto Apache Maven scaricato: • In IntelliJ IDEA: scegli Import (Importa). Vai al file pom.xml nella root del pacchetto scaricato. • In Eclipse: scegliere File, Import (Importa), Maven, Existing Maven Projects (Progetti Maven esistenti). Passa quindi alla directory kinesis-video-java-demo. Per ulteriori informazioni, consulta la documentazione relativa al tuo IDE. 3. Il codice di esempio Java utilizza le credenziali AWS correnti. Per usare un profilo di credenziali differenti, individua il seguente codice in DemoAppMain.java: final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory .createKinesisVideoClient( Regions.US_WEST_2, AuthHelper.getSystemPropertiesCredentialsProvider()); Modifica il codice come indicato di seguito: final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory .createKinesisVideoClient( Regions.US_WEST_2, new ProfileCredentialsProvider("credentials-profile-name")); Per ulteriori informazioni, consulta ProfileCredentialsProvider nel riferimento AWS SDK for Java. Fase successiva the section called “Fase 2: scrittura e analisi del codice” (p. 49) Fase 2: scrittura e analisi del codice In questa sezione della procedura per Java Producer Library, è possibile scrivere e analizzare il codice di esempio scaricato nella sezione precedente. L'applicazione per i test di Java (DemoAppMain) mostra il seguente modello di codifica: • Creare un'istanza di KinesisVideoClient. • Creare un'istanza di MediaSource. • Registra MediaSource con il client. • Avvia lo streaming. Ciò significa avviare MediaSource, che inizia a inviare dati al client. Nelle seguenti sezioni sono fornite maggiori informazioni. Creazione di un'istanza di KinesisVideoClient Per creare l'oggetto KinesisVideoClient, richiama l'operazione createKinesisVideoClient. 49 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: esecuzione e verifica del codice final KinesisVideoClient kinesisVideoClient = KinesisVideoJavaClientFactory .createKinesisVideoClient( Regions.US_WEST_2, AuthHelper.getSystemPropertiesCredentialsProvider()); Per eseguire chiamate alla rete, KinesisVideoClient ha bisogno di credenziali da autenticare. Puoi trasferire un'istanza di SystemPropertiesCredentialsProvider, che legge AWSCredentials per il profilo predefinito nel file di credenziali: [default] aws_access_key_id = ABCDEFGHIJKLMOPQRSTU aws_secret_access_key = AbCd1234EfGh5678IjKl9012MnOp3456QrSt7890 Creazione di un'istanza di MediaSource Per inviare byte a Kinesis video stream, è necessario produrre i dati. Amazon Kinesis Video Streams fornisce l'interfaccia MediaSource, che rappresenta l'origine dati. Ad esempio, la libreria per Java di Kinesis Video Streams offre l'implementazione di ImageFileMediaSource dell'interfaccia MediaSource. Questa classe legge i dati solo da una serie di file multimediali invece che da un Kinesis video stream, ma puoi utilizzarla per verificare il codice. final MediaSource bytesMediaSource = createImageFileMediaSource(); Registrazione di MediaSource con il client Registra l'origine multimediale creata con KinesisVideoClient in modo che sia a conoscenza dell'esistenza del client e possa quindi inviargli i dati. kinesisVideoClient.registerMediaSource(STREAM_NAME, bytesMediaSource); Avvio dell'origine multimediale Avvia l'origine multimediale in modo che inizi a generare dati e a inviarli al client. bytesMediaSource.start(); Fase successiva the section called “Fase 3: esecuzione e verifica del codice” (p. 50) Fase 3: esecuzione e verifica del codice Per eseguire il test harness Java per Java Producer Library, effettua le operazioni descritte di seguito. 1. Scegli DemoAppMain. 2. Scegli Run (Esegui), Run "DemoAppMain" (Esegui "DemoAppMain"). 3. Aggiungi le tue credenziali per gli argomenti JVM per l'applicazione: • Per credenziali AWS non temporanee: "-Daws.accessKeyId={YourAwsAccessKey} - Daws.secretKey={YourAwsSecretKey} -Djava.library.path={NativeLibraryPath}" 50 Amazon Kinesis Video Streams Guida per gli sviluppatori Android Producer Library • Per credenziali AWS temporanee: "-Daws.accessKeyId={YourAwsAccessKey} - Daws.secretKey={YourAwsSecretKey} -Daws.sessionToken={YourAwsSessionToken} -Djava.library.path={NativeLibraryPath}" 4. Accedere a AWS Management Console e aprire la console Kinesis Video Streams. Nella pagina Manage Streams (Gestisci flussi), scegli il tuo flusso. 5. Il video di esempio viene riprodotto nel lettore integrato. La visualizzazione del video potrebbe richiedere una breve attesa (fino a 10 secondi con la larghezza di banda e le condizioni del processore abituali) affinché vengano caricati i fotogrammi. L'esempio di codice crea un flusso. Appena MediaSource nel codice si avvia, inizia a inviare frame di esempio a KinesisVideoClient. Il client, quindi, invia i dati al tuo Kinesis video stream. Utilizzo di Android Producer Library In Amazon Kinesis Video Streams è disponibile Android Producer Library, che è possibile utilizzare per scrivere codice dell'applicazione, con una configurazione minima, per inviare dati multimediali da un dispositivo Android a un Kinesis video stream. È necessario attenersi alla procedura seguente per integrare il codice con Kinesis Video Streams in modo che l'applicazione possa iniziare lo streaming dei dati al Kinesis video stream: 1. Crea un'istanza dell'oggetto KinesisVideoClient. 2. Crea un oggetto MediaSource fornendo informazioni sull'origine multimediale. Ad esempio, durante la creazione di un'origine multimediale fotocamera, devi fornire informazioni quali l'identificazione della fotocamera e specificare la codifica utilizzata dalla fotocamera. Quando vuoi avviare lo streaming, devi creare un'origine multimediale personalizzata. Procedura: utilizzo dell'SDK del producer Android Questa procedura illustra come utilizzare il client del producer Android Kinesis Video Streams nell'applicazione Android per inviare dati al Kinesis video stream. La procedura include le seguenti fasi: • Download e configurazione del codice • Analisi del codice • Esecuzione e verifica del codice Prerequisiti • Ti consigliamo di utilizzare Android Studio per esaminare, modificare ed eseguire il codice dell'applicazione. Ti consigliamo di utilizzare almeno la versione 3.0.0, rilasciata a ottobre 2017. • Nel codice di esempio, fornisci le credenziali Amazon Cognito. Segui queste procedure per configurare un pool di identità e un pool di utenti Amazon Cognito: Per configurare un pool di utenti 1. Accedere alla console Amazon Cognito. 2. Scegli Manage your User Pools (Gestisci i pool di utenti). 3. Scegli Create a User Pool (Crea un pool di utenti). 51 Amazon Kinesis Video Streams Guida per gli sviluppatori Procedura: utilizzo dell'SDK del producer Android 4. Inserire un nome per Pool name (Nome pool); ad esempio, Per configurare un pool di identità 1. Aprire la console Amazon Cognito. 2. Scegliere Manage Identity Pools (Gestisci pool di identità). 3. Scegliere Create new identity pool (Crea un nuovo pool di identità). 4. Inserire un nome per Identity Pool name (Nome pool identità); ad esempio, { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cognito-identity:*", "kinesisvideo:*" ], "Resource": [ "*" ] } ] } 10. Scegli Allow (Permetti). 11. Nella pagina successiva, copia e salva il valore di Identity pool ID (ID pool identità) dal frammento di codice Get AWS Credentials (Ottieni credenziali AWS). Questo valore sarà necessario per configurare l'applicazione di esempio. 52 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 1: download e configurazione del codice Fase 1: download e configurazione del codice di Android Producer Library In questa sezione della procedura per Android Producer Library, puoi scaricare il codice di esempio per Android e aprire il progetto in Android Studio. Per i prerequisiti e altri dettagli su questo esempio, consulta Utilizzo di Android Producer Library. 1. Crea una directory, quindi clona l'SDK Android AWS dal repository GitHub. $ git clone https://github.com/awslabs/aws-sdk-android-samples 2. Apri Android Studio. 3. Nella schermata iniziale, scegli Apri un progetto di Android Studio esistente. 4. Passa alla directory aws-sdk-android-samples/AmazonKinesisVideoDemoApp e scegli OK. 5. Apri il file AmazonKinesisVideoDemoApp/src/main/res/raw/awsconfiguration.json. Nel nodo CredentialsProvider, specificare l'ID del pool di identità indicato nella procedura Per configurare un pool di identità nella sezione Prerequisiti e fornire la regione AWS (ad esempio, us- west-2). Nel nodo CognitoUserPool, specificare il segreto client dell'app, l'ID client dell'app e l'ID pool indicati nella procedura Per configurare un pool di utenti nella sezione Prerequisiti e fornire la regione AWS (ad esempio, us-west-2). 6. Il file awsconfiguration.json sarà simile a quanto riportato di seguito: { "Version": "1.0", "CredentialsProvider": { "CognitoIdentity": { "Default": { "PoolId": "us-west-2:01234567-89ab-cdef-0123-456789abcdef", "Region": "us-west-2" } } }, "IdentityManager": { "Default": {} }, "CognitoUserPool": { "Default": { "AppClientSecret": "abcdefghijklmnopqrstuvwxyz0123456789abcdefghijklmno", "AppClientId": "0123456789abcdefghijklmnop", "PoolId": "us-west-2_qRsTuVwXy", "Region": "us-west-2" } } } 7. Aggiorna AmazonKinesisVideoDemoApp/src/main/java/com/amazonaws/kinesisvideo/ demoapp/KinesisVideoDemoApp.java con la tua regione (nell'esempio seguente, è impostato su US_WEST_2): public class KinesisVideoDemoApp extends Application { public static final String TAG = KinesisVideoDemoApp.class.getSimpleName(); 53 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: analisi del codice public static Regions KINESIS_VIDEO_REGION = Regions.US_WEST_2; Per le costanti della regione AWS, consulta Regioni. Fase successiva the section called “Fase 2: analisi del codice” (p. 54) Fase 2: analisi del codice In questa sezione della procedura per Android Producer Library, puoi esaminare il codice di esempio. L'applicazione per i test di Android (AmazonKinesisVideoDemoApp) mostra il seguente modello di codifica: • Creare un'istanza di KinesisVideoClient. • Creare un'istanza di MediaSource. • Avvia lo streaming—ossia avvia MediaSource, che inizia a inviare dati al client. Nelle seguenti sezioni sono fornite maggiori informazioni. Creazione di un'istanza di KinesisVideoClient Per creare l'oggetto KinesisVideoClient, richiama l'operazione createKinesisVideoClient. mKinesisVideoClient = KinesisVideoAndroidClientFactory.createKinesisVideoClient( getActivity(), KinesisVideoDemoApp.KINESIS_VIDEO_REGION, KinesisVideoDemoApp.getCredentialsProvider()); Per eseguire chiamate alla rete, KinesisVideoClient ha bisogno di credenziali da autenticare. Passa un'istanza di AWSCredentialsProvider, che legge le credenziali Amazon Cognito dal file awsconfiguration.json modificato nella sezione precedente. Creazione di un'istanza di MediaSource Per inviare byte a Kinesis video stream, è necessario produrre i dati. Amazon Kinesis Video Streams fornisce l'interfaccia MediaSource, che rappresenta l'origine dati. Ad esempio, la libreria per Android di Kinesis Video Streams fornisce l'implementazione AndroidCameraMediaSource dell'interfaccia MediaSource. Questa classe legge i dati da una delle fotocamere del dispositivo. Nel seguente esempio di codice (dal file fragment/StreamConfigurationFragment.java), viene creata la configurazione per l'origine multimediale: private AndroidCameraMediaSourceConfiguration getCurrentConfiguration() { return new AndroidCameraMediaSourceConfiguration( AndroidCameraMediaSourceConfiguration.builder() .withCameraId(mCamerasDropdown.getSelectedItem().getCameraId()) .withEncodingMimeType(mMimeTypeDropdown.getSelectedItem().getMimeType()) 54 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: esecuzione e verifica del codice .withHorizontalResolution(mResolutionDropdown.getSelectedItem().getWidth()) .withVerticalResolution(mResolutionDropdown.getSelectedItem().getHeight()) .withCameraFacing(mCamerasDropdown.getSelectedItem().getCameraFacing()) .withIsEncoderHardwareAccelerated( mCamerasDropdown.getSelectedItem().isEndcoderHardwareAccelerated()) .withFrameRate(FRAMERATE_20) .withRetentionPeriodInHours(RETENTION_PERIOD_48_HOURS) .withEncodingBitRate(BITRATE_384_KBPS) .withCameraOrientation(- mCamerasDropdown.getSelectedItem().getCameraOrientation()) .withNalAdaptationFlags(StreamInfo.NalAdaptationFlags.NAL_ADAPTATION_ANNEXB_CPD_AND_FRAME_NALS) .withIsAbsoluteTimecode(false)); } Nel seguente esempio di codice (dal file fragment/StreamingFragment.java), viene creata la configurazione per l'origine multimediale: mCameraMediaSource = (AndroidCameraMediaSource) mKinesisVideoClient .createMediaSource(mStreamName, mConfiguration); Avvio dell'origine multimediale Avvia l'origine multimediale in modo che inizi a generare dati e a inviarli al client. I seguenti esempi di codice sono tratti dal file fragment/StreamingFragment.java: mCameraMediaSource.start(); Fase successiva the section called “Fase 3: esecuzione e verifica del codice” (p. 55) Fase 3: esecuzione e verifica del codice Per eseguire l'applicazione di esempio Android per Android Producer Library, esegui le operazioni descritte di seguito. 1. Esegui la connessione a un dispositivo Android. 2. Scegli Run (Esegui), Run... (Esegui...), quindi scegli Edit configurations... (Modifica configurazioni...). 3. Scegli +, Android App (App Android). Nel campo Name (Nome), inserire AmazonKinesisVideoDemoApp. Nell'elenco a discesa Module (Modulo) scegli AmazonKinesisVideoDemoApp. Seleziona OK. 4. Scegli Run (Esegui), Run (Esegui). 5. Nella schermata Select Deployment Target (Seleziona destinazione distribuzione) scegli il dispositivo connesso, quindi scegli OK. 6. Nell'applicazione AWSKinesisVideoDemoApp sul dispositivo, scegli Create new account (Crea nuovo account). 7. Inserisci i valori per USERNAME (NOME UTENTE), Password, Given name (Nome specificato), Email address (Indirizzo e-mail) e Phone number (Numero di telefono), quindi scegli Sign up (Iscrizione). Note Questi valori hanno le seguenti limitazioni: 55 Amazon Kinesis Video Streams Guida per gli sviluppatori C++ Producer Library • Password: deve contenere lettere maiuscole e minuscole, numeri e caratteri speciali. È possibile modificare queste restrizioni nella pagina del pool di utenti nella console Amazon Cognito. • Email address (Indirizzo e-mail): deve essere un indirizzo valido a cui ricevere un codice di conferma. • Phone number (Numero di telefono): deve avere il seguente formato: + Nella pagina Manage Streams (Gestisci flussi), scegli demo-stream. 11. Il video streaming viene riprodotto nel lettore integrato. La visualizzazione del video potrebbe richiedere una breve attesa (fino a 10 secondi con la larghezza di banda e le condizioni del processore abituali) affinché vengano caricati i fotogrammi. Note Se lo schermo del dispositivo ruota (ad esempio, da verticale a orizzontale), l'applicazione interrompe lo streaming del video. L'esempio di codice crea un flusso. Appena MediaSource nel codice viene avviato, inizia a inviare fotogrammi dalla fotocamera a KinesisVideoClient. Il client invia quindi i dati a un Kinesis video stream denominato demo-stream. Utilizzo di C++ Producer Library Amazon Kinesis Video Streams In è disponibile C++ Producer Library, che è possibile utilizzare per scrivere codice dell'applicazione per inviare dati multimediali da un dispositivo a un Kinesis video stream. Modello di oggetto La libreria C++ fornisce i seguenti oggetti per gestire l'invio di dati a un Kinesis video stream: • KinesisVideoProducer: contiene informazioni sull'origine multimediale e sulle credenziali AWS e gestisce i callback per segnalare gli eventi di Kinesis Video Streams. • KinesisVideoStream: rappresenta il Kinesis video stream. Contiene informazioni sui parametri del flusso di video, ad esempio il nome, il periodo di retention dei dati, il tipo di contenuti multimediali e così via. Inserimento di dati multimediali nel flusso La libreria C++ fornisce metodi (per esempio, PutFrame) che consentono di inserire dati nell'oggetto KinesisVideoStream. La libreria gestisce quindi lo stato interno dei dati, che può includere le seguenti attività: • Esecuzione dell'autenticazione. • Controllo della latenza di rete. Se la latenza è troppo elevata, la libreria potrebbe scegliere di eliminare i fotogrammi. 56 Amazon Kinesis Video Streams Guida per gli sviluppatori Interfacce di richiamata • Monitoraggio dello stato dello streaming in corso. Interfacce di richiamata Questo livello mostra un set di interfacce di richiamata, che consentono la comunicazione con il livello dell'applicazione. Queste interfacce di richiamata includono: • Interfaccia di richiamata del servizio (CallbackProvider): la libreria richiama gli eventi ottenuti mediante questa interfaccia quando crea un flusso, ottiene la descrizione di un flusso, elimina un flusso e così via. • Interfaccia con stato client pronto o eventi di storage ridotto (ClientCallbackProvider): la libreria richiama gli eventi su questa interfaccia quando il client è pronto oppure quando rileva che potrebbe esaurire lo storage o la memoria disponibile. • Interfaccia di richiamata degli eventi del flusso (StreamCallbackProvider): la libreria richiama gli eventi su questa interfaccia quando si verificano eventi del flusso, ad esempio quando lo stato del flusso diventa pronto, quando i fotogrammi vengono saltati o in caso di errori del flusso. Kinesis Video Streams fornisce implementazioni predefinite per queste interfacce. Puoi anche fornire un'implementazione personalizzata, ad esempio se hai bisogno di una logica di rete personalizzata o se vuoi esporre una condizione di storage ridotto sull'interfaccia utente. — Per ulteriori informazioni sui callback in Producer Library, consulta Callback dell'SDK Producer (p. 115). Procedura: utilizzo dell'SDK del producer C++ Questa procedura illustra come utilizzare origini multimediali e client Kinesis Video Streams in un'applicazione C++ per inviare dati al Kinesis video stream. La procedura include le seguenti fasi: • Fase 1: download e configurazione del codice • Fase 2: scrittura e analisi del codice • Fase 3: esecuzione e verifica del codice Prerequisites • Credenziali: nel codice di esempio, fornisci le credenziali specificando un profilo configurato nel file del profilo delle credenziali AWS. Se non lo hai già fatto, configura prima il profilo delle credenziali. Per ulteriori informazioni, consulta la sezione Configurazione della regione e delle credenziali AWS per lo sviluppo. • Integrazione dello store dei certificati: Kinesis Video Streams Producer Library deve stabilire relazioni di attendibilità con il servizio che chiama. Ciò è possibile mediante la convalida delle autorità di certificazione (CA) nello store dei certificati pubblico. Sui modelli basati su Linux, questo store si trova nella directory /etc/ssl/. Scarica il certificato dal percorso seguente per lo store dei certificati: https://www.amazontrust.com/repository/SFSRootCAG2.pem • Installa le seguenti dipendenze di build per macOS: • Autoconf 2.69 (Licenza GPLv3+/Autoconf: GNU GPL versione 3 o successive) • CMake 3.7 o 3.8 57 Amazon Kinesis Video Streams Guida per gli sviluppatori Procedura: utilizzo dell'SDK del producer C++ • Pkg-Config • Flex 2.5.35 Apple (flex-31) o versioni successive • Bison 2.4 (licenza GNU) • Automake 1.15.1 (licenza GNU) • GNU Libtool (Apple Inc. versione cctools-898) • xCode (macOS) / clang / gcc (xcode-select versione 2347) • Java Development Kit (JDK) (per la compilazione di Java JNI) • Lib-Pkg • Installa le seguenti dipendenze di build per Ubuntu (le risposte ai comandi delle versioni sono troncate): • Installa Git: sudo apt-get install git $ git --version git version 2.14.1 • Installa CMake: sudo apt-get install cmake $ cmake --version cmake version 3.9.1 • Installa Libtool: sudo apt-get install libtool 2.4.6-2 • Installa libtool-bin: sudo apt-get install libtool-bin $ libtool --version libtool (GNU libtool) 2.4.6 Written by Gordon Matzigkeit, 1996 • Installa GNU Automake: sudo apt-get install automake $ automake --version automake (GNU automake) 1.15 • Installa GNU Bison: sudo apt-get install bison $ bison -V bison (GNU Bison) 3.0.4 • Installa G++: sudo apt-get install g++ g++ --version g++ (Ubuntu 7.2.0-8ubuntu3) 7.2.0 • Installa curl: sudo apt-get install curl $ curl --version curl 7.55.1 (x86_64-pc-linux-gnu) libcurl/7.55.1 OpenSSL/1.0.2g zlib/1.2.11 libidn2/2.0.2 libpsl/0.18.0 (+libidn2/2.0.2) librtmp/2.3 • Installa pkg-config: sudo apt-get install pkg-config $ pkg-config --version 0.29.1 • Installa Flex: sudo apt-get install flex 58 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 1: download e configurazione del codice $ flex --version flex 2.6.1 • Installa OpenJDK: sudo apt-get install openjdk-8-jdk $ java -version openjdk version "1.8.0_171" • Imposta la variabile JAVA_HOME di ambiente : export JAVA_HOME=/usr/lib/jvm/java-8- openjdk-amd64/ • Esegui lo script di creazione: ./install-script Fase successiva Fase 1: download e configurazione del codice di C++ Producer Library Fase 1: download e configurazione del codice di C++ Producer Library Per informazioni su come scaricare e configurare la libreria di produttori C++, consulta Amazon Kinesis Video Streams CPP Producer, GStreamer Plugin e JNI. Per i prerequisiti e altri dettagli su questo esempio, consulta Utilizzo di C++ Producer Library. Fase successiva Fase 2: scrittura e analisi del codice (p. 59) Fase 2: scrittura e analisi del codice In questa sezione della procedura per C++ Producer Library, potrai esaminare il codice nel test harness C+ + (tst/ProducerTestFixture.h e altri file). Hai scaricato questo codice nella sezione precedente. L'esempio di C++ indipendente dalla piattaforma mostra i seguenti modelli di codifica: • Crea un'istanza di KinesisVideoProducer per accedere a Kinesis Video Streams. • Creare un'istanza di KinesisVideoStream. Se non esiste già un flusso con lo stesso nome, nel tuo account AWS viene creato un Kinesis video stream. • Chiama putFrame in KinesisVideoStream per ogni fotogramma di dati, non appena diventa disponibile, per inviarlo al flusso. Nelle seguenti sezioni sono fornite maggiori informazioni: Creazione di un'istanza di KinesisVideoProducer Per creare l'oggetto KinesisVideoProducer, richiama il metodo KinesisVideoProducer::createSync. L'esempio seguente crea KinesisVideoProducer nel ProducerTestFixture.h file : kinesis_video_producer_ = KinesisVideoProducer::createSync(move(device_provider_), move(client_callback_provider_), 59 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice move(stream_callback_provider_), move(credential_provider_), defaultRegion_); Il metodo createSync accetta i parametri seguenti: • Un oggetto DeviceInfoProvider, che restituisce un oggetto DeviceInfo contenente informazioni sul dispositivo o sulla configurazione dello storage. Note Puoi configurare la dimensione dello store dei contenuti utilizzando il parametro deviceInfo.storageInfo.storageSize. I flussi di contenuti condividono lo store dei contenuti. Per determinare i requisiti delle dimensioni di storage, moltiplica la dimensione media dei fotogrammi per il numero di fotogrammi archiviati per la durata massima di tutti i flussi. Quindi moltiplica per 1,2 per prendere in considerazione la deframmentazione. Supponi, ad esempio, che la tua applicazione abbia la seguente configurazione: • Tre flussi • 3 minuti di durata massima • Ogni flusso è di 30 fotogrammi al secondo (FPS) • Ogni fotogramma ha una dimensione di 10.000 KB I requisiti di storage dei contenuti per questa applicazione sono 3 (flussi) * 3 (minuti) * 60 (secondi in un minuto) * 10.000 (KB) * 1,2 (quota di deframmentazione) = 194,4 Mb ~ 200 MB. • Un oggetto ClientCallbackProvider, che restituisce puntatori delle funzioni che segnalano eventi specifici del client. • Un oggetto StreamCallbackProvider, che restituisce puntatori delle funzioni richiamati quando si verificano eventi specifici del flusso. • Un oggetto CredentialProvider, che fornisce l'accesso alle variabili di ambiente delle credenziali AWS. • La regione AWS ("us-west-2"). L'endpoint del servizio è determinato dalla regione. Creazione di un'istanza di KinesisVideoStream Per creare l'oggetto KinesisVideoStream, richiama il metodo KinesisVideoProducer::CreateStream con un parametro StreamDefinition. L'esempio crea KinesisVideoStream nel file ProducerTestFixture.h con il tipo di traccia video e con id traccia pari a 1: auto stream_definition = make_unique L'oggetto StreamDefinition dispone dei campi seguenti: • Nome del flusso. • Periodo di retention dei dati. 60 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice • Tag per il flusso. Questi tag possono essere utilizzati dalle applicazioni dei consumatori per trovare il flusso corretto o per avere maggiori informazioni sul flusso. I tag possono anche essere visualizzati in AWS Management Console. • AWS KMSChiave di crittografia per il flusso. Per ulteriori informazioni, consulta Uso della crittografia lato server con Kinesis Video Streams. • Tipo di streaming. Attualmente, l'unico valore valido è STREAMING_TYPE_REALTIME. • Tipo di contenuti multimediali. • Latenza file multimediali. Attualmente questo valore non viene utilizzato e deve essere impostato su 0. • Durata della riproduzione di ogni frammento. • Scala del timecode dei file multimediali. • Se i file multimediali usano la frammentazione del fotogramma chiave. • Se i file multimediali utilizzano i timecode. • Se i file multimediali usano i tempi assoluti del frammento. Aggiungere una traccia audio a Kinesis Video Stream È possibile aggiungere dettagli della traccia audio a una definizione del flusso della traccia video utilizzando il metodo addTrack di StreamDefinition: stream_definition->addTrack(DEFAULT_AUDIO_TRACKID, DEFAULT_AUDIO_TRACK_NAME, DEFAULT_AUDIO_CODEC_ID, MKV_TRACK_INFO_TYPE_AUDIO); Il metodo addTrack richiede i parametri seguenti: • Id traccia (1 per audio). Questo deve essere unico e un valore diverso da zero. • Nome traccia definito dall'utente (ad es., "audio" per la traccia audio). • Id codec per questa traccia (ad es., per la traccia audio "A_AAC"). • Tipo di traccia (ad es., utilizzare il valore enum di MKV_TRACK_INFO_TYPE_AUDIO per l'audio). Se si dispone di dati provati codec per la traccia audio, è possibile passarli quando si chiama la funzione addTrack. È anche possibile inviare i dati privati del codec dopo aver creato l'oggetto KinesisVideoStream mentre si chiama il metodo di avvio in KinesisVideoStream. Inserimento di un fotogramma nel flusso di video Kinesis Per inserire i file multimediali nel Kinesis video stream con KinesisVideoStream::putFrame, passando un oggetto Frame contenente l'intestazione e i dati dei file multimediali. L'esempio chiama putFrame nel ProducerApiTest.cpp file : frame.duration = FRAME_DURATION_IN_MICROS * HUNDREDS_OF_NANOS_IN_A_MICROSECOND; frame.size = SIZEOF(frameBuffer_); frame.frameData = frameBuffer_; MEMSET(frame.frameData, 0x55, frame.size); while (!stop_producer_) { // Produce frames timestamp = std::chrono::duration_cast 61 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice // Key frame every 50th frame.flags = (frame.index % 50 == 0) ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE; ... EXPECT_TRUE(kinesis_video_stream->putFrame(frame)); Note L'esempio di producer C++ precedente invia un buffer di dati di prova. In un'applicazione reale, è consigliabile ottenere il buffer e la dimensione del fotogramma dai dati del fotogramma da un'origine multimediale (ad esempio una fotocamera). L'oggetto Frame dispone dei campi seguenti: • Indice dei fotogrammi. Deve essere un valore a incremento monotono. • Flag associati al fotogramma. Ad esempio, se il codificatore è stato configurato per ottenere un fotogramma chiave, a questo fotogramma verrà assegnato il contrassegno FRAME_FLAG_KEY_FRAME. • Timestamp decodifica. • Timestamp presentazione. • Durata del fotogramma (in unità di 100 ns). • Dimensione del fotogramma in byte. • Dati del fotogramma. Per ulteriori informazioni sul formato del fotogramma, consulta Modello di dati Kinesis Video Streams. Inserire un KinesisVideoFrame in una traccia specifica di KinesisVideoStream È possibile utilizzare la classe PutFrameHelper per inserire i dati del frame in una traccia specifica. In primo luogo, chiamare getFrameDataBuffer per ottenere un puntatore a uno dei buffer preallocati per l'inserimento dei dati KinesisVideoFrame. Quindi, è possibile chiamare putFrameMultiTrack per inviare KinesisVideoFrame insieme al valore per indicare il tipo di dati del frame. Utilizza "true" se si tratta di dati video o "false" se il frame contiene dati audio. Il metodo putFrameMultiTrack utilizza un meccanismo di accodamento per assicurarsi che i frammenti MKV aumentino aumentare in maniera monotona i timestamp dei frame senza che due frammenti si sovrappongano. Ad esempio, il timestamp MKV del primo frame di un frammento deve essere sempre maggiore del timestamp MKV dell'ultimo frame del frammento precedente. L'oggetto PutFrameHelper dispone dei campi seguenti: • Numero massimo di frame audio in coda • Numero massimo di frame video in coda • Dimensioni per allocare un singolo frame audio • Dimensioni per allocare un singolo frame video Parametri e registrazione dei parametri L'SDK del producer C++ include funzionalità per i parametri e la registrazione dei parametri. Puoi utilizzare le operazioni API getKinesisVideoMetrics e getKinesisVideoStreamMetrics per richiamare le informazioni su Kinesis Video Streams e sui flussi attivi. Il seguente codice è tratto dal file kinesis-video-pic/src/client/include/com/amazonaws/ kinesis/video/client/Include.h. 62 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice /** * Gets information about the storage availability. * * @param 1 CLIENT_HANDLE - the client object handle. * @param 2 PKinesisVideoMetrics - OUT - Kinesis Video metrics to be filled. * * @return Status of the function call. */ PUBLIC_API STATUS getKinesisVideoMetrics(CLIENT_HANDLE, PKinesisVideoMetrics); /** * Gets information about the stream content view. * * @param 1 STREAM_HANDLE - the stream object handle. * @param 2 PStreamMetrics - Stream metrics to fill. * * @return Status of the function call. */ PUBLIC_API STATUS getKinesisVideoStreamMetrics(STREAM_HANDLE, PStreamMetrics); L'oggetto PClientMetrics compilato da getKinesisVideoMetrics contiene le seguenti informazioni: • contentStoreSize: le dimensioni generali in byte dello store dei contenuti (la memoria utilizzata per archiviare i dati del flusso). • contentStoreAvailableSize: la memoria libera nello store dei contenuti, in byte. • contentStoreAllocatedSize: la memoria allocata nello store dei contenuti. • totalContentViewsSize: il totale della memoria utilizzata per la visualizzazione dei contenuti. La vista dei contenuti è una serie di indici di informazioni nello store dei contenuti. • totalFrameRate: il numero totale di fotogrammi al secondo in tutti i flussi attivi. • totalTransferRate: bit totali al secondo (bps) inviati in tutti i flussi. L'oggetto PStreamMetrics compilato da getKinesisVideoStreamMetrics contiene le seguenti informazioni: • currentViewDuration: la differenza in unità di 100 ns tra l'inizio della vista dei contenuti (quando i fotogrammi vengono codificati) e la posizione corrente (quando i dati dei fotogrammi vengono inviati a Kinesis Video Streams). • overallViewDuration: la differenza in unità di 100 ns tra l'inizio della vista dei contenuti (quando i fotogrammi vengono codificati) e la fine (quando i fotogrammi vengono eliminati dalla memoria, perché lo spazio totale allocato per la vista dei contenuti è stato superato oppure perché è stato ricevuto un messaggio PersistedAck da Kinesis Video Streams e i fotogrammi notoriamente persistenti vengono eliminati). • currentViewSize: le dimensioni in byte della vista dei contenuti dall'inizio (quando i fotogrammi vengono codificati) alla posizione corrente (quando i fotogrammi vengono inviati a Kinesis Video Streams). • overallViewSize: la dimensione totale in byte della vista dei contenuti. • currentFrameRate: l'ultima velocità del flusso misurata, in fotogrammi al secondo. • currentTransferRate: l'ultima velocità del flusso misurata, in byte al secondo. Teardown Se desideri inviare i byte rimanenti in un buffer e attendere il ACK, puoi utilizzare stopSync: kinesis_video_stream->stopSync(); 63 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: esecuzione e verifica del codice In alternativa, puoi chiamare stop per terminare lo streaming: kinesis_video_stream->stop(); Dopo aver arrestato il flusso, puoi liberarlo richiamando la seguente API: kinesis_video_producer_->freeStream(kinesis_video_stream); Fase successiva the section called “Fase 3: esecuzione e verifica del codice” (p. 64) Fase 3: esecuzione e verifica del codice Per eseguire e verificare il codice per la procedura di C++ Producer Library, consulta le seguenti istruzioni specifiche del sistema operativo: • Linux • macOS • Windows • Sistema operativo Raspberry Pi Puoi monitorare il traffico sul flusso osservando i parametri associati al flusso nella Amazon CloudWatch console , ad esempio PutMedia.IncomingBytes. Utilizzo di C++ Producer SDK come GStreamer Plugin GStreamer è un framework multimediale diffuso utilizzato da numerose videocamere e fonti video per creare pipeline multimediali personalizzate attraverso l'abbinamento di plugin modulari. Il plugin Kinesis Video Streams GStreamer semplifica ampiamente l'integrazione di pipeline multimediali GStreamer esistenti con Kinesis Video Streams. Per informazioni sull'uso dell'SDK di C++ Producer come plugin GStreamer, consulta Esempio: plugin Kinesis Video Streams dell'SDK del producerGStreamer (p. 129). Utilizzo dell'SDK C++ Producer come plugin GStreamer in un container Docker GStreamer è un framework multimediale diffuso utilizzato da numerose videocamere e fonti video per creare pipeline multimediali personalizzate attraverso l'abbinamento di plugin modulari. Il plugin Kinesis Video Streams GStreamer semplifica ampiamente l'integrazione di pipeline multimediali GStreamer esistenti con Kinesis Video Streams. Inoltre, l'utilizzo di Docker per creare la pipeline GStreamer standardizza l'ambiente operativo per Kinesis Video Streams, che semplifica ampiamente la creazione e l'esecuzione dell'applicazione. Per informazioni sull'uso dell'SDK di C++ Producer come plugin GStreamer in un container Docker, consulta Esecuzione dell'elemento GStreamer in un container Docker (p. 132). 64 Amazon Kinesis Video Streams Guida per gli sviluppatori Uso del logging Uso del logging con l'SDK di C++ Producer Puoi configurare il logging per le applicazioni dell'SDK di C++ Producer SDK nel file kvs_log_configuration nella cartella kinesis-video-native-build. L'esempio seguente mostra la prima riga del file di configurazione predefinito, che configura l'applicazione per scrivere voci di livello DEBUG nella AWS Management Console: log4cplus.rootLogger=DEBUG, KvsConsoleAppender È possibile impostare il livello di logging su INFO per ottenere un log meno dettagliato. Per configurare l'applicazione per scrivere anche le voci di log in un file di log, aggiorna la prima riga del file come segue: log4cplus.rootLogger=DEBUG, KvsConsoleAppender, KvsFileAppender Ciò consente di configurare l'applicazione per scrivere voci di log nel file kvs.log nella cartella kinesis- video-native-build/log. Per modificare la posizione del file di log, aggiorna la riga seguente con il nuovo percorso: log4cplus.appender.KvsFileAppender.File=./log/kvs.log Note Se il logging di livello DEBUG viene scritto in un file, il file di log può occupare rapidamente tutto lo spazio di storage disponibile nel dispositivo. Utilizzo di C Producer Library In Amazon Kinesis Video Streams è disponibile C++ Producer Library, che è possibile utilizzare per scrivere codice dell'applicazione per inviare dati multimediali da un dispositivo a un Kinesis video stream. Modello di oggetto La libreria produttori C Kinesis Video Streams si basa su un componente comune chiamato Platform Independent Codebase (PIC), che è disponibile su GitHub all'indirizzo https://github.com/awslabs/amazon- kinesis-video-streams-pic/. Il PIC contiene la logica di business indipendente dalla piattaforma per i livelli bassi. La libreria di produttori C Kinesis Video Streams include PIC con un ulteriore livello di API che abilita callback ed eventi specifici di scenario e piattaforma. La libreria di produttori C Kinesis Video Streams dispone dei seguenti componenti basati su PIC: • Provider di informazioni sui dispositivi – Espone la struttura DeviceInfo che può essere fornita direttamente all'API PIC. Esiste un set di provider facili da configurare, inclusi quelli a scenario ottimizzato per l'applicazione, che possono ottimizzare lo store dei contenuti in base al tipo e al numero di flussi gestiti dall'applicazione e alla quantità di buffer richiesto configurata in base alla quantità di RAM disponibile. • Provider di informazioni sullo streaming – Espone la struttura StreamInfo che può essere fornita direttamente all'API PIC. Esiste un set di provider facili da configurare specifici per i tipi di applicazione e i tipi comuni di scenari di streaming. Questi includono provider quali video, audio, multitraccia audio/video ecc. Ognuno di questi scenari dispone di impostazioni predefinite che è possibile personalizzare in base ai requisiti dell'applicazione. • Provider di callback – Espone la struttura ClientCallbacks che può essere fornita direttamente all'API PIC. È incluso un set di provider facili da configurare per il networking (callback di APIbasati su CURL), 65 Amazon Kinesis Video Streams Guida per gli sviluppatori Inserimento di dati multimediali nel flusso autorizzazioni (API di credenziali AWS), ripetizione dello streaming su callback degli errori, ecc. L'API del provider di callback configura una serie di argomenti, ad esempio la regione AWS e le informazioni di autorizzazione (tramite certificati IoT o tramiteAccessKeyId, SecretKey e SessionToken di AWS). È possibile potenziare i provider di callback con callback personalizzati se l'applicazione ha bisogno di ulteriori elaborazioni di un determinato callback per raggiungere la logica specifica dell'applicazione. • FrameOrderCoordinator – Aiuta a gestire la sincronizzazione audio e video per gli scenari multitraccia. Ha un comportamento predefinito che è possibile personalizzare per gestire la logica specifica dell'applicazione. Inoltre, semplifica la creazione di pacchetti dei metadati del frame nella struttura PIC Frame prima di inviarli all'API PIC di basso livello. Per gli scenari non multitraccia, questo componente è un punto di passaggio all'API putFrame PIC. La libreria C fornisce i seguenti oggetti per gestire l'invio di dati a un flusso video di Kinesis: • KinesisVideoClient – Contiene informazioni sul dispositivo e mantiene i callback per riportare sugli eventi Kinesis Video Streams. • KinesisVideoStream – Contiene informazioni sui parametri del flusso di video, ad esempio il nome, il periodo di retention dei dati, il tipo di contenuti multimediali e così via. Inserimento di dati multimediali nel flusso La libreria C fornisce metodi (per esempio, PutKinesisVideoFrame) che consentono di inserire dati nell'oggetto KinesisVideoStream. La libreria gestisce quindi lo stato interno dei dati, che può includere le seguenti attività: • Esecuzione dell'autenticazione. • Controllo della latenza di rete. Se la latenza è troppo elevata, la libreria potrebbe scegliere di eliminare i fotogrammi. • Monitoraggio dello stato dello streaming in corso. Procedura: utilizzo dell'SDK del producer C Questa procedura illustra come utilizzare origini multimediali e client Kinesis Video Streams in un'applicazione C per inviare frame video con codifica H.264 a Kinesis video stream. La procedura include le seguenti fasi: • Fase 1: download del codice C Producer Library (p. 68) • Fase 2: scrittura e analisi del codice (p. 68) • Fase 3: esecuzione e verifica del codice (p. 70) Prerequisiti • Credenziali – nel codice di esempio, fornisci le credenziali specificando un profilo configurato nel file del profilo delle credenziali AWS. Se non lo hai già fatto, configura prima il profilo delle credenziali. Per ulteriori informazioni, consulta la sezione Configurazione della regione e delle credenziali per lo sviluppo di AWS. • Integrazione dello store dei certificati – Kinesis Video Streams Producer Library deve stabilire relazioni di attendibilità con il servizio che chiama. Ciò è possibile mediante la convalida delle autorità di certificazione (CA) nello store dei certificati pubblico. Sui modelli basati su Linux, questo store si trova nella directory /etc/ssl/. 66 Amazon Kinesis Video Streams Guida per gli sviluppatori Procedura: utilizzo dell'SDK del producer C Scarica il certificato dal percorso seguente per lo store dei certificati: https://www.amazontrust.com/repository/SFSRootCAG2.pem • Installa le seguenti dipendenze di build per macOS: • Autoconf 2.69 (Licenza GPLv3+/Autoconf: GNU GPL versione 3 o successive) • CMake 3.7 o 3.8 • Pkg-Config • Flex 2.5.35 Apple (flex-31) o versioni successive • Bison 2.4 (licenza GNU) • Automake 1.15.1 (licenza GNU) • GNU Libtool (Apple Inc. versione cctools-898) • xCode (macOS) / clang / gcc (xcode-select versione 2347) • Java Development Kit (JDK) (per la compilazione di Java JNI) • Lib-Pkg • Installa le seguenti dipendenze di build per Ubuntu (le risposte ai comandi delle versioni sono troncate): • Installa Git: sudo apt-get install git $ git --version git version 2.14.1 • Installa CMake: sudo apt-get install cmake $ cmake --version cmake version 3.9.1 • Installa Libtool: sudo apt-get install libtool 2.4.6-2 • Installa libtool-bin: sudo apt-get install libtool-bin $ libtool --version libtool (GNU libtool) 2.4.6 Written by Gordon Matzigkeit, 1996 • Installa GNU Automake: sudo apt-get install automake $ automake --version automake (GNU automake) 1.15 • Installa GNU Bison: sudo apt-get install bison $ bison -V bison (GNU Bison) 3.0.4 • Installa G++: sudo apt-get install g++ g++ --version g++ (Ubuntu 7.2.0-8ubuntu3) 7.2.0 • Installa curl: sudo apt-get install curl $ curl --version 67 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 1: Download del codice curl 7.55.1 (x86_64-pc-linux-gnu) libcurl/7.55.1 OpenSSL/1.0.2g zlib/1.2.11 libidn2/2.0.2 libpsl/0.18.0 (+libidn2/2.0.2) librtmp/2.3 • Installa pkg-config: sudo apt-get install pkg-config $ pkg-config --version 0.29.1 • Installa Flex: sudo apt-get install flex $ flex --version flex 2.6.1 • Installa OpenJDK: sudo apt-get install openjdk-8-jdk $ java -version openjdk version "1.8.0_171" • Imposta la variabile di ambiente JAVA_HOME: export JAVA_HOME=/usr/lib/jvm/java-8- openjdk-amd64/ • Esegui lo script di creazione: ./install-script Approfondimenti Fase 1: download del codice C Producer Library (p. 68) Fase 1: download del codice C Producer Library In questa sezione sarà possibile scaricare le librerie di basso livello. Per i prerequisiti e altri dettagli su questo esempio, consulta Utilizzo di C Producer Library. 1. Crea una directory, quindi clona il codice di origine di esempio dal repository GitHub. git clone --recursive https://github.com/awslabs/amazon-kinesis-video-streams-producer- c.git Note Se non si esegue Git clone con --recursive, eseguire git submodule update --init nella directory amazon-kinesis-video-streams-producer-c/open-source. È inoltre necessario installare pkg-config, automake, CMake e un ambiente di compilazione. Per ulteriori informazioni, consulta il README.md in https://github.com/awslabs/amazon- kinesis-video-streams-producer-c.git. 2. Apri il codice nell'ambiente di sviluppo integrato (IDE) di tua scelta (ad esempio, Eclipse). Approfondimenti Fase 2: scrittura e analisi del codice (p. 68) Fase 2: scrittura e analisi del codice In questa sezione sarà possibile esaminare il codice dell'applicazione di esempio KvsVideoOnlyStreamingSample.c nella cartella samples del repository https://github.com/awslabs/ 68 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice amazon-kinesis-video-streams-producer-c su GitHub. Hai scaricato questo codice nella fase precedente. In questo esempio viene illustrato come utilizzare la C Producer Library per l'invio del frame video con codifica H.264 all'interno della cartella samples/h264SampleFrames per la tua Kinesis video stream. Questa applicazione di esempio ha tre sezioni: • Inizializzazione e configurazione: • Inizializzazione e configurazione della pipeline dei supporti specifici della piattaforma. • Inizializzazione e configurazione di KinesisVideoClient e KinesisVideoStream per la pipeline, impostazione dei callback, integrazione dell'autenticazione specifica dello scenario, estrazione e invio di dati codec privati e ottenimento dello stato READY per il flusso. • Loop principale: • Ottenere il frame dalla pipeline dei supporti con timestamp e flag. • Inoltro del frame al KinesisVideoStream. • Teardown: • Interruzione di (sync) KinesisVideoStream, abilitazione di KinesisVideoStream, abilitazione di KinesisVideoClient. Questa applicazione di esempio completa le attività seguenti: • Chiama l'API createDefaultDeviceInfo per creare l'oggetto deviceInfo che contiene informazioni sul dispositivo o sulla configurazione dello storage. // default storage size is 128MB. Use setDeviceInfoStorageSize after create to change storage size. CHK_STATUS(createDefaultDeviceInfo(&pDeviceInfo)); // adjust members of pDeviceInfo here if needed pDeviceInfo->clientInfo.loggerLogLevel = LOG_LEVEL_DEBUG; • Chiama l'API createRealtimeVideoStreamInfoProvider per creare l'oggetto StreamInfo. CHK_STATUS(createRealtimeVideoStreamInfoProvider(streamName, DEFAULT_RETENTION_PERIOD, DEFAULT_BUFFER_DURATION, &pStreamInfo)); // adjust members of pStreamInfo here if needed • Chiama l'API createDefaultCallbacksProviderWithAwsCredentials per creare il provider di callback predefinito in base alle credenziali AWS statiche. CHK_STATUS(createDefaultCallbacksProviderWithAwsCredentials(accessKey, secretKey, sessionToken, MAX_UINT64, region, cacertPath, NULL, NULL, FALSE, &pClientCallbacks)); • Chiama l'API createKinesisVideoClient per creare l'oggetto KinesisVideoClient che contiene informazioni sul dispositivo di storage e gestisce i callback per riportare sugli eventi Kinesis Video Streams. 69 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: esecuzione e verifica del codice CHK_STATUS(createKinesisVideoClient(pDeviceInfo, pClientCallbacks, &clientHandle)); • Chiama l'API createKinesisVideoStreamSync per creare l' oggetto KinesisVideoStream. CHK_STATUS(createKinesisVideoStreamSync(clientHandle, pStreamInfo, &streamHandle)); • Configura un frame di esempio e chiama l'API PutKinesisVideoFrame per l'invio di frame all'oggetto KinesisVideoStream. // setup sample frame MEMSET(frameBuffer, 0x00, frameSize); frame.frameData = frameBuffer; frame.version = FRAME_CURRENT_VERSION; frame.trackId = DEFAULT_VIDEO_TRACK_ID; frame.duration = HUNDREDS_OF_NANOS_IN_A_SECOND / DEFAULT_FPS_VALUE; frame.decodingTs = defaultGetTime(); // current time frame.presentationTs = frame.decodingTs; while(defaultGetTime() > streamStopTime) { frame.index = frameIndex; frame.flags = fileIndex % DEFAULT_KEY_FRAME_INTERVAL == 0 ? FRAME_FLAG_KEY_FRAME : FRAME_FLAG_NONE; frame.size = SIZEOF(frameBuffer); CHK_STATUS(readFrameData(&frame, frameFilePath)); CHK_STATUS(putKinesisVideoFrame(streamHandle, &frame)); defaultThreadSleep(frame.duration); frame.decodingTs += frame.duration; frame.presentationTs = frame.decodingTs; frameIndex++; fileIndex++; fileIndex = fileIndex % NUMBER_OF_FRAME_FILES; } • Teardown: CHK_STATUS(stopKinesisVideoStreamSync(streamHandle)); CHK_STATUS(freeKinesisVideoStream(&streamHandle)); CHK_STATUS(freeKinesisVideoClient(&clientHandle)); Approfondimenti Fase 3: esecuzione e verifica del codice (p. 70) Fase 3: esecuzione e verifica del codice Per eseguire e verificare il codice per la procedura per C Producer Library, esegui le operazioni descritte di seguito: 70 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: esecuzione e verifica del codice 1. Eseguire i seguenti comandi per creare una directory build nell'SDK C scaricato ed eseguire cmake da esso: mkdir -p amazon-kinesis-video-streams-producer-c/build; cd amazon-kinesis-video-streams-producer-c/build; cmake .. È possibile inviare le seguenti opzioni a cmake .. • -DBUILD_DEPENDENCIES: se creare o meno librerie dipendenti dall'origine • -DBUILD_TEST=TRUE: creare test di integrazione/unità, può essere utile per confermare il supporto per il dispositivo. ./tst/webrtc_client_test • -DCODE_COVERAGE: abilitare la segnalazione della copertura • -DCOMPILER_WARNINGS: abilitare tutti gli avvisi del compilatore • -DADDRESS_SANITIZER: compilazione con AddressSanitizer • -DMEMORY_SANITIZER: compilazione con MemorySanitizer • -DTHREAD_SANITIZER: compilazione con ThreadSanitizer • -DUNDEFINED_BEHAVIOR_SANITIZER: compilazione con UnDefinedBehaviorSanitizer • -DALIGNED_MEMORY_MODEL: compilazione per dispositivi solo con modello di memoria allineato Il valore predefinito è OFF. 2. Passare alla directory build appena creata con la fase precedente ed eseguire make per compilare l'SDK WebRTC C e i relativi esempi forniti. make 3. L'applicazione di esempio kinesis_video_cproducer_video_only_sample invia i frame video con codifica h.264 all'interno della cartella samples/h264SampleFrames su Kinesis Video Streams. Il comando seguente invia i frame video in un loop per dieci secondi in Kinesis Video Streams: ./kinesis_video_cproducer_video_only_sample YourStreamName 10 Se si desidera inviare i frame con codifica H.264 da un'altra cartella (ad esempio MyH264FramesFolder), è possibile eseguire il campione con i seguenti argomenti: ./kinesis_video_cproducer_video_only_sample YourStreamName 10 MyH264FramesFolder 4. Per abilitare i log verbose, crea le definizioni C HEAP_DEBUG e LOG_STREAMING rimuovendo i commenti dalla righe appropriate in CMakeList.txt. Puoi monitorare l'avanzamento della suite di test nell'output di debug nell'IDE. Puoi anche monitorare il traffico sul flusso osservando i parametri associati al flusso nella console Amazon CloudWatch, ad esempio PutMedia.IncomingBytes. 71 Amazon Kinesis Video Streams Guida per gli sviluppatori Riferimento Note Poiché il test harness invia solo fotogrammi di byte vuoti, la console non visualizza i dati come un flusso di video. Documentazione di riferimento per l'SDK producer Questa sezione contiene informazioni su limiti, codici di errore e altri riferimenti relativi alle Kinesis Video Streams Producer Library (p. 46). Argomenti • Limiti dell'SDK producer (p. 72) • Documentazione di riferimento per il codice di errore (p. 74) • Documentazione di riferimento per i flag di adattamento del Network Abstraction Layer (NAL) (p. 101) • Strutture dell'SDK producer (p. 102) • KinesisStrutture di flussi video di (p. 104) • Callback dell'SDK Producer (p. 115) Limiti dell'SDK producer La tabella riportata di seguito contiene i limiti attuali dei valori delle Producer Library (p. 46). Note Prima di impostare questi valori, è necessario convalidare gli input. L'SDK non convalida questi limiti e si verifica un errore di runtime se vengono superati i limiti. Valore Limite Note Numero massimo di flussi 128 Il numero massimo di flussi che un oggetto producer può creare. Si tratta di un limite flessibile, per il quale puoi richiedere un aumento. Consente di accertarsi che il producer non crei i flussi in modo ricorsivo. Lunghezza massima del nome 128 caratteri del dispositivo Numero massimo di tag 50 per flusso Lunghezza massima del nome 256 caratteri del flusso Dimensione minima di storage 10 MiB = 10 * 1024 * 1024 byte Dimensione massima di storage 10 GiB = 10 * 1024 * 1024 * 1024 byte Lunghezza massima del 4,096 caratteri percorso della directory root Lunghezza massima delle 10,000 byte informazioni di autorizzazione 72 Amazon Kinesis Video Streams Guida per gli sviluppatori Limiti dell'SDK producer Valore Limite Note Lunghezza massima della stringa 10,000 caratteri URI Lunghezza massima del nome 128 caratteri del tag Lunghezza massima del valore 1,024 caratteri del tag Periodo minimo del token di 30 secondi sicurezza Periodo di tolleranza del token di 40 minuti Se la durata specificata è sicurezza superiore a tale periodo, sarà limitato a questo valore. Periodo di conservazione 0 o superiore a un'ora Il valore 0 indica nessuna conservazione. Durata minima del cluster 1 secondo Il valore è specificato in unità di 100 ns, ovvero lo standard dell'SDK. Durata massima del cluster 30 secondi Il valore è specificato in unità di 100 ns, ovvero lo standard dell'SDK. L'API di back-end può applicare una durata più breve del cluster. Dimensione massima del 50 MB Per ulteriori informazioni, frammento consulta Kinesis Video StreamsLimiti per (p. 167). Durata massima del frammento 10 secondi Per ulteriori informazioni, consulta Kinesis Video StreamsLimiti per (p. 167). Durata massima della 45 minuti Il back-end chiude la connessione connessione dopo questo intervallo di tempo. L'SDK ruota il token e stabilisce una nuova connessione entro questo intervallo di tempo. Lunghezza massima del 1,024 caratteri Lunghezza massima del segmento ACK segmento di conferma inviato alla funzione del parser di ACK. Lunghezza massima della stringa 128 caratteri del tipo di contenuto Lunghezza massima della stringa 32 caratteri dell'ID codec Lunghezza massima della stringa 32 caratteri del nome della traccia 73 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Valore Limite Note Lunghezza massima dei dati 1 MiB = 1 * 1024 * 1024 byte privati del codec Lunghezza minima del valore di 100 ns Il valore di scala minimo del scala del timecode timecode per rappresentare i timestamp del fotogramma nel cluster MKV risultante. Il valore è specificato in incrementi di 100 ns, ovvero lo standard dell'SDK. Lunghezza massima del valore di 1 secondo Il valore di scala massimo del scala del timecode timecode per rappresentare i timestamp del fotogramma nel cluster MKV risultante. Il valore è specificato in incrementi di 100 ns, ovvero lo standard dell'SDK. Numero minimo degli elementi di 10 visualizzazione dei contenuti Durata minima del buffer 20 secondi Il valore è specificato in incrementi di 100 ns, ovvero lo standard dell'SDK. Lunghezza massima della 128 caratteri versione di aggiornamento Lunghezza massima dell'ARN 1024 caratteri Lunghezza massima della 128 caratteri sequenza dei frammenti Periodo massimo di 10 anni conservazione Documentazione di riferimento per il codice di errore Questa sezione contiene informazioni sui codici di errore e stato delle Producer Library (p. 46). Per informazioni sulle soluzioni ai problemi comuni, consulta Risoluzione dei problemi di Kinesis Video Streams (p. 173). Argomenti • Errori e codici di stato restituiti dai callback PutFrame – Platform Independent Code (PIT) (p. 74) • Errori e codici di stato resituiti dai callback PutFrame – C Producer Library (p. 99) Errori e codici di stato restituiti dai callback PutFrame – Platform Independent Code (PIT) Le sezioni seguenti contengono informazioni sugli errori e sugli stati restituiti dai callback per l'operazione PutFrame in Platform Independent Codebase (PIT). Argomenti 74 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore • Codici di errore e stato restituiti dalla libreria Client (p. 75) • Codici di errore e stato restituiti dalla libreria Duration (p. 90) • Codici di errore e stato restituiti dalla libreria Common (p. 91) • Codici di errore e stato restituiti dalla libreria Heap (p. 92) • Codici di errore e stato restituiti dalla libreria MKVGen (p. 93) • Codici di errore e stato restituiti dalla libreria Trace (p. 97) • Codici di errore e stato restituiti dalla libreria Utils (p. 97) • Codici di errore e stato restituiti dalla libreria View (p. 98) Codici di errore e stato restituiti dalla libreria Client La tabella seguente contiene informazioni sugli errori e sugli stati restituiti dai metodi nella libreria Kinesis Video Streams Client. Codice Message Descrizione Operazione consigliata 0x52000001 STATUS_MAX_STREAM_COUNTÈ stato raggiunto il Specificare un numero numero massimo di massimo di flussi più elevato flussi. in DeviceInfo come specificato in Limiti dell'SDK producer (p. 72). 0x52000002 STATUS_MIN_STREAM_COUNTErrore numero minimo Specificare un numero di flussi. massimo di flussi maggiore di 0 in DeviceInfo. 0x52000003 STATUS_INVALID_DEVICE_NAME_LENGTHLunghezza del nome Fare riferimento alla del dispositivo non lunghezza massima in valida. caratteri del nome del dispositivo specificata in Limiti dell'SDK producer (p. 72). 0x52000004 STATUS_INVALID_DEVICE_INFO_VERSIONVersione della Specificare la versione struttura DeviceInfo corrente corretta della non valida. struttura. 0x52000005 STATUS_MAX_TAG_COUNT È stato raggiunto il Fare riferimento al numero numero massimo di massimo di tag corrente tag. specificato in Limiti dell'SDK producer (p. 72). 0x52000006 STATUS_DEVICE_FINGERPRINT_LENGTH 0x52000007 STATUS_INVALID_CALLBACKS_VERSIONVersione della Specificare la versione struttura Callbacks corrente corretta della non valida. struttura. 0x52000008 STATUS_INVALID_STREAM_INFO_VERSIONVersione della Specificare la versione struttura StreamInfo corrente corretta della non valida. struttura. 0x52000009 STATUS_INVALID_STREAM_NAME_LENGTHLunghezza del nome Fare riferimento alla del flusso non valida. lunghezza massima in caratteri del nome del flusso 75 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata specificata in Limiti dell'SDK producer (p. 72). 0x5200000a STATUS_INVALID_STORAGE_SIZEÈ stata specificata La dimensione di storage una dimensione di in byte non deve superare storage non valida. i limiti specificati in Limiti dell'SDK producer (p. 72). 0x5200000b STATUS_INVALID_ROOT_DIRECTORY_LENGTHLunghezza della Fare riferimento alla stringa della directory lunghezza massima del root non valida. percorso della directory root specificata in Limiti dell'SDK producer (p. 72). 0x5200000c STATUS_INVALID_SPILL_RATIORapporto di spill non Esprimere il rapporto di spill valido. come percentuale da 0 a 100. 0x5200000d STATUS_INVALID_STORAGE_INFO_VERSIONVersione Specificare la versione della struttura corrente corretta della StorageInfo non struttura. valida. 0x5200000e STATUS_INVALID_STREAM_STATELo stato attuale del Nella maggior parte dei flusso non consente casi, questo errore si l'operazione corrente. verifica quando l'SDK non riesce a raggiungere lo stato necessario per l'esecuzione dell'operazione richiesta. Ad esempio, si verifica se la chiamata API GetStreamingEndpoint non riesce e se l'applicazione client la ignora e continua a inserire i fotogrammi nel flusso. 0x5200000f STATUS_SERVICE_CALL_CALLBACKS_MISSINGNella struttura Assicurarsi che i Callbacks non callback obbligatori sono presenti dei siano implementati punti di accesso della nell'applicazione client. funzione di alcune Questo errore è esposto funzioni obbligatorie. soltanto ai client PIC (Platform Independent Code). C++ e altri wrapper di livello più elevato sono in grado di soddisfare queste chiamate. 76 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000010 STATUS_SERVICE_CALL_NOT_AUTHORIZED_ERRORNon autorizzato. Verificare l'integrazione e la scadenza del token di sicurezza e del certificato. Verificare che al token siano stati associati i diritti corretti. Per le applicazioni di esempio di Kinesis Video Streams, accertarsi che la variabile di ambiente sia impostata correttamente. 0x52000011 STATUS_DESCRIBE_STREAM_CALL_FAILEDDescribeStreamErroreQuesto errore viene restituito dell'API . dopo che il nuovo tentativo dell'API DescribeStream ha restituito un errore. Il client PIC restituisce questo errore dopo aver smesso di effettuare nuovi tentativi. 0x52000012 STATUS_INVALID_DESCRIBE_STREAM_RESPONSEStruttura La struttura inviata al DescribeStreamResponseDescribeStreamResultEvent non valida. è nulla o contiene elementi non validi, come un Amazon Resource Name (ARN) nullo. 0x52000013 STATUS_STREAM_IS_BEING_DELETED_ERRORIl flusso è in fase di Il flusso in fase di eliminazione. eliminazione ha causato un errore dell'API. Verificare che nessun altro processo stia tentando di eliminare il flusso mentre quest'ultimo è in uso. 0x52000014 STATUS_SERVICE_CALL_INVALID_ARG_ERRORSono stati specificati Il back-end restituisce questo degli argomenti non errore quando un argomento validi per la chiamata della chiamata di servizio di servizio. non è valido o quando l'SDK rileva un errore che non è in grado di interpretare. 0x52000015 STATUS_SERVICE_CALL_DEVICE_NOT_FOUND_ERRORIl dispositivo non è Verificare che il dispositivo stato trovato. non venga eliminato mentre è in uso. 0x52000016 STATUS_SERVICE_CALL_DEVICE_NOT_PROVISIONED_ERRORNon è stato effettuato Verificare che sia stato il provisioning del effettuato il provisioning del dispositivo. dispositivo. 77 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000017 STATUS_SERVICE_CALL_RESOURCE_NOT_FOUND_ERRORRisorsa generica non Questo errore si verifica trovata restituita dal quando il servizio non è servizio. in grado di individuare la risorsa (ad esempio, un flusso). Tale errore potrebbe avere più significati in contesti diversi, ma la sua causa più probabile è l'utilizzo delle API prima della creazione del flusso. Utilizzare l'SDK per assicurarsi che venga creato innanzitutto il flusso. 0x52000018 STATUS_INVALID_AUTH_LENLunghezza delle Fare riferimento ai valori informazioni di correnti specificati in Limiti autorizzazione non dell'SDK producer (p. 72). valida. 0x52000019 STATUS_CREATE_STREAM_CALL_FAILEDLa chiamata dell'API Fare riferimento alla stringa CreateStream non è di errore per ulteriori riuscita. informazioni dettagliate sul motivo della mancata riuscita dell'operazione. 0x5200002a STATUS_GET_STREAMING_TOKEN_CALL_FAILEDLa chiamata Fare riferimento alla stringa GetStreamingToken di errore per ulteriori non è riuscita. informazioni dettagliate sul motivo della mancata riuscita dell'operazione. 0x5200002b STATUS_GET_STREAMING_ENDPOINT_CALL_FAILEDLa chiamata dell'API Fare riferimento alla stringa GetStreamingEndpointdi errore per ulteriori non è riuscita. informazioni dettagliate sul motivo della mancata riuscita dell'operazione. 0x5200002c STATUS_INVALID_URI_LEN L'API Fare riferimento ai GetStreamingEndpointvalori massimi correnti ha restituito una specificati in Limiti dell'SDK lunghezza della producer (p. 72). stringa URI non valida. 0x5200002d STATUS_PUT_STREAM_CALL_FAILEDLa chiamata dell'API Fare riferimento alla stringa PutMedia non è di errore per ulteriori riuscita. informazioni dettagliate sul motivo della mancata riuscita dell'operazione. 78 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x5200002e STATUS_STORE_OUT_OF_MEMORYLa memoria dello Lo store dei contenuti store dei contenuti è viene condiviso tra i flussi esaurita. e deve disporre di capacità sufficiente per l'archiviazione della durata massima di tutti i flussi più di un altro 20% circa di spazio (per la deframmentazione). È importante non superare la capacità di storage. Scegliere i valori di durata massima per flusso corrispondenti alla dimensione di storage cumulativa e alle tolleranze di latenza. È consigliabile eliminare i fotogrammi mentre escono dalla finestra della visualizzazione dei contenuti piuttosto che in seguito al loro inserimento nella finestra (utilizzo di memoria dello store dei contenuti). Ciò perché l'eliminazione dei fotogrammi attiva i callback di notifica sull'utilizzo dei flussi. L'applicazione è in grado di regolare i componenti multimediali di upstream (come il codificatore) per comprimere il bitrate, eliminare i fotogrammi o adottare le misure necessarie. 0x5200002f STATUS_NO_MORE_DATA_AVAILABLEAl momento non sono Si tratta di un risultato disponibili altri dati per potenziale valido quando un flusso. la pipeline multimediale produce i fotogrammi da inviare al servizio più lentamente rispetto a quanto il thread di networking ne consuma. I client di livello superiore (ad esempio C++, Java o Android) non visualizzano questo avviso perché viene gestito internamente. 0x52000030 STATUS_INVALID_TAG_VERSIONVersione della Specificare la versione struttura Tag non corrente corretta della valida. struttura. 79 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000031 STATUS_SERVICE_CALL_UNKNOWN_ERRORÈ stato restituito un Consultare i log per ulteriori errore sconosciuto o informazioni dettagliate. generico dallo stack di rete. 0x52000032 STATUS_SERVICE_CALL_RESOURCE_IN_USE_ERRORRisorsa in uso. Restituito dal servizio. Per ulteriori informazioni, consulta la documentazione di riferimento delle API Kinesis Video Streams. 0x52000033 STATUS_SERVICE_CALL_CLIENT_LIMIT_ERRORLimite del client. Restituito dal servizio. Per ulteriori informazioni, consulta la documentazione di riferimento delle API Kinesis Video Streams. 0x52000034 STATUS_SERVICE_CALL_DEVICE_LIMIT_ERRORLimite del dispositivo. Restituito dal servizio. Per ulteriori informazioni, consulta la documentazione di riferimento delle API Kinesis Video Streams. 0x52000035 STATUS_SERVICE_CALL_STREAM_LIMIT_ERRORLimite del flusso. Restituito dal servizio. Per ulteriori informazioni, consulta la documentazione di riferimento delle API Kinesis Video Streams. 0x52000036 STATUS_SERVICE_CALL_RESOURCE_DELETED_ERRORLa risorsa è stata Restituito dal servizio. eliminata o è in fase di Per ulteriori informazioni, eliminazione. consulta la documentazione di riferimento delle API Kinesis Video Streams. 0x52000037 STATUS_SERVICE_CALL_TIMEOUT_ERRORLa chiamata di La chiamata a una servizio è scaduta. determinata API del servizio è risultata in un timeout. Verificare che la connessione di rete sia attiva. Il PIC ritenterà l'operazione automaticamente. 0x52000038 STATUS_STREAM_READY_CALLBACK_FAILEDNotifica di flusso Questa notifica viene inviata pronto all'uso. dal PIC al client per indicare che il flusso asincrono è stato creato. 0x52000039 STATUS_DEVICE_TAGS_COUNT_NON_ZERO_TAGS_NULLSono stati specificati Il numero di tag non è dei tag non validi. zero, ma i tag sono vuoti. Assicurarsi che i tag siano stati specificati o che il loro numero sia zero. 80 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x5200003a STATUS_INVALID_STREAM_DESCRIPTION_VERSIONVersione Specificare la versione della struttura corrente corretta della StreamDescription struttura. non valida. 0x5200003b STATUS_INVALID_TAG_NAME_LENLunghezza del nome Fare riferimento ai limiti del tag non valida. relativi al nome del tag specificati in Limiti dell'SDK producer (p. 72). 0x5200003c STATUS_INVALID_TAG_VALUE_LENLunghezza del valore Fare riferimento ai limiti del tag non valida. relativi al valore del tag specificati in Limiti dell'SDK producer (p. 72). 0x5200003d STATUS_TAG_STREAM_CALL_FAILEDErrore dell'API La chiamata dell'API TagResource. TagResource non è riuscita. Controllare che la connessione di rete sia attiva. Consultare i log per ulteriori informazioni sull'errore. 0x5200003e STATUS_INVALID_CUSTOM_DATADati personalizzati Sono stati specificati dei non validi durante la dati personalizzati non validi chiamata alle API del in una chiamata alle API PIC. del PIC. Questo errore può verificarsi soltanto per i client che utilizzano direttamente il PIC. 0x5200003f STATUS_INVALID_CREATE_STREAM_RESPONSEStruttura La struttura o i relativi CreateStreamResponsecampi dei membri non non valida. sono validi (ovvero, l'ARN è nullo o di dimensioni superiori rispetto a quelle specificate in Limiti dell'SDK producer (p. 72)). 0x52000040 STATUS_CLIENT_AUTH_CALL_FAILEDAutenticazione del Il PIC non è riuscito a client non riuscita. ottenere le informazioni di autenticazione corrette (ovvero AccessKeyId o SecretAccessKey) dopo un determinato numero di tentativi. Verificare l'integrazione dell'autenticazione. Le applicazioni di esempio utilizzano le variabili di ambiente per inviare le informazioni sulle credenziali alla libreria del producer C+ +. 81 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000041 STATUS_GET_CLIENT_TOKEN_CALL_FAILEDErrore di ricezione Questa situazione può della chiamata al verificarsi per i client che token di sicurezza. utilizzano direttamente il PIC. Dopo un determinato numero di tentativi, la chiamata non riesce con questo errore. 0x52000042 STATUS_CLIENT_PROVISION_CALL_FAILEDErrore di provisioning. Il provisioning non viene implementato. 0x52000043 STATUS_CREATE_CLIENT_CALL_FAILEDImpossibile creare il Un errore generico restituito client del producer. dal PIC dopo un determinato numero di tentativi quando la creazione del client non riesce. 0x52000044 STATUS_CLIENT_READY_CALLBACK_FAILEDNon è stato possibile Restituito dal computer di impostare il client del stato PIC se il PIC non riesce producer sullo stato a passare allo stato READY. READY. Consultare i log per ulteriori informazioni sulla causa principale. 0x52000045 STATUS_TAG_CLIENT_CALL_FAILEDErrore di Errore della chiamata API TagResource per il TagResource per il client client del producer. del producer. Consultare i log per ulteriori informazioni sulla causa principale. 0x52000046 STATUS_INVALID_CREATE_DEVICE_RESPONSECreazione del Gli SDK di livello più elevato dispositivo/producer (ad esempio C++ o Java) non riuscita. non implementano ancora l'API di creazione del dispositivo/producer. I client che utilizzano direttamente il PIC possono indicare un errore tramite la notifica sui risultati. 0x52000047 STATUS_ACK_TIMESTAMP_NOT_IN_VIEW_WINDOWIl timestamp dell'ACK Questo errore si verifica se il di ricezione non fotogramma corrispondente si trova nella all'ACK di ricezione visualizzazione. esce dalla finestra della visualizzazione dei contenuti. In genere, ciò si verifica se la consegna dell'ACK è lenta. Può essere interpretato come un avviso e un'indicazione delle prestazioni lente del downlink. 0x52000048 STATUS_INVALID_FRAGMENT_ACK_VERSIONVersione Specificare la versione della struttura corrente corretta della FragmentAck non struttura FragmentAck. valida. 82 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000049 STATUS_INVALID_TOKEN_EXPIRATIONScadenza del token di La scadenza del token di sicurezza non valida. sicurezza deve disporre di un timestamp assoluto nel futuro superiore al timestamp attuale, con un periodo di tolleranza. Per i limiti relativi al periodo di tolleranza, consulta Limiti dell'SDK producer (p. 72). 0x5200004a STATUS_END_OF_STREAM Indicatore di fine del Nel chiamata dell'API flusso (EOS). GetStreamData, indica che la sessione di gestione dell'upload attuale è terminata. Ciò si verifica se la sessione termina o produce degli errori oppure se il token della sessione è scaduto e la sessione viene ruotata. 0x5200004b STATUS_DUPLICATE_STREAM_NAMENome di flusso Più flussi non possono avere duplicato. lo stesso nome. Scegliere un nome univoco per il flusso. 0x5200004c STATUS_INVALID_RETENTION_PERIODPeriodo di Un periodo di conservazione conservazione non non valido è stato valido. specificato nella struttura StreamInfo. Per informazioni sull'intervallo valido di valori per il periodo di conservazione, consulta Limiti dell'SDK producer (p. 72). 0x5200004d STATUS_INVALID_ACK_KEY_STARTSintassi non valida Impossibile analizzare la FragmentAck. stringa ACK del frammento. Indicatore di inizio della chiave non valido. La stringa ACK del frammento potrebbe essere danneggiata. Può correggersi autonomamente e questo errore può essere trattato come un avviso. 0x5200004e STATUS_INVALID_ACK_DUPLICATE_KEY_NAMESintassi non valida Impossibile analizzare la FragmentAck. stringa ACK del frammento. Più chiavi hanno lo stesso nome. La stringa ACK del frammento potrebbe essere danneggiata. Può correggersi autonomamente e questo errore può essere trattato come un avviso. 83 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x5200004f STATUS_INVALID_ACK_INVALID_VALUE_STARTSintassi non valida Impossibile analizzare la FragmentAck. stringa ACK del frammento a causa di un indicatore di inizio del valore di chiave non valido. La stringa ACK del frammento potrebbe essere danneggiata. Può correggersi autonomamente e questo errore può essere trattato come un avviso. 0x52000050 STATUS_INVALID_ACK_INVALID_VALUE_ENDSintassi non valida Impossibile analizzare la FragmentAck. stringa ACK del frammento a causa di un indicatore di fine del valore di chiave non valido. La stringa ACK del frammento potrebbe essere danneggiata. Può correggersi autonomamente e questo errore può essere trattato come un avviso. 0x52000051 STATUS_INVALID_PARSED_ACK_TYPESintassi non valida Impossibile analizzare la FragmentAck. stringa ACK del frammento perché è stato specificato un tipo di ACK non valido. 0x52000052 STATUS_STREAM_HAS_BEEN_STOPPEDIl flusso è stato Il flusso è stato interrotto, interrotto. ma un fotogramma viene comunque inserito nel flusso. 0x52000053 STATUS_INVALID_STREAM_METRICS_VERSIONVersione Specificare la versione della struttura corrente corretta della StreamMetrics non struttura StreamMetrics. valida. 0x52000054 STATUS_INVALID_CLIENT_METRICS_VERSIONVersione Specificare la versione della struttura corrente corretta della ClientMetrics non struttura ClientMetrics. valida. 0x52000055 STATUS_INVALID_CLIENT_READY_STATEL'inizializzazione Impossibile raggiungere del producer non ha lo stato READY durante raggiunto uno stato l'inizializzazione del client del READY. producer. Consultare i log per ulteriori informazioni. 0x52000056 STATUS_STATE_MACHINE_STATE_NOT_FOUNDErrore interno del Non è un errore visibile computer di stato. pubblicamente. 0x52000057 STATUS_INVALID_FRAGMENT_ACK_TYPEUn tipo di ACK La struttura FragmentAck non valido è deve contenere i tipi di ACK stato specificato definiti nell'intestazione nella struttura pubblica. FragmentAck. 84 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000058 STATUS_INVALID_STREAM_READY_STATEErrore di transizione Non è un errore visibile interno del computer pubblicamente. di stato. 0x52000059 STATUS_CLIENT_FREED_BEFORE_STREAML'oggetto di flusso Si è tentato di liberare un è stato liberato oggetto di flusso dopo la in seguito alla liberazione dell'oggetto del liberazione del producer. Ciò può verificarsi producer. soltanto nei client che utilizzano direttamente il PIC. 0x5200005a STATUS_ALLOCATION_SIZE_SMALLER_THAN_REQUESTEDErrore interno di Un errore interno che storage. indica che la dimensione di allocazione effettiva dello store dei contenuti è inferiore alla dimensione del frammento/fotogramma inserito nel pacchetto. 0x5200005b STATUS_VIEW_ITEM_SIZE_GREATER_THAN_ALLOCATIONErrore interno di La dimensione archiviata storage. dell'allocazione nella vista dei contenuti è superiore alla dimensione di allocazione nello store dei contenuti. 0x5200005c STATUS_ACK_ERR_STREAM_READ_ERRORACK di errore di Un errore restituito dall'ACK lettura del flusso. dal back-end per indicare un errore di lettura/analisi del flusso. Ciò in genere si verifica quando il back-end non è in grado di recuperare il flusso. In genere è possibile correggere questo errore tramite il ripristino automatico dello streaming. 85 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x5200005d STATUS_ACK_ERR_FRAGMENT_SIZE_REACHEDLa dimensione La dimensione massima massima del del frammento in byte è frammento è stata definita in Limiti dell'SDK raggiunta. producer (p. 72). Questo errore indica che sono presenti fotogrammi di dimensioni molto grandi o che non è presente nessun fotogramma chiave per la creazione di frammenti di dimensione gestibile. Controllare le impostazioni del codificatore e assicurarsi che i fotogrammi chiave vengano creati correttamente. Per i flussi con densità molto elevata, configurare il codificatore sulla creazione di frammenti in durate più ridotte per gestire la dimensione massima. 0x5200005e STATUS_ACK_ERR_FRAGMENT_DURATION_REACHEDLa durata massima La durata massima del frammento è stata del frammento viene raggiunta. definita in Limiti dell'SDK producer (p. 72). Questo errore indica che sono presenti fotogrammi molto lenti al secondo o che non è presente nessun fotogramma chiave per la creazione di frammenti di durata gestibile. Controllare le impostazioni del codificatore e assicurarsi che i fotogrammi chiave vengano creati correttamente a intervalli regolari. 0x5200005f STATUS_ACK_ERR_CONNECTION_DURATION_REACHEDLa durata massima Kinesis Video Streams della connessione è applica la durata massima stata raggiunta. della connessione come specificato in Limiti dell'SDK producer (p. 72). L'SDK producer ruota automaticamente il flusso/ token prima che venga raggiunto il valore massimo per fare in modo che i client che utilizzano l'SDK non ricevano questo errore. 86 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000060 STATUS_ACK_ERR_FRAGMENT_TIMECODE_NOT_MONOTONICI timecode non L'SDK producer applica i aumentano in maniera timestamp per fare in modo monotona. che i client che utilizzano l'SDK non ricevano questo errore. 0x52000061 STATUS_ACK_ERR_MULTI_TRACK_MKVTracce multiple in L'SDK producer applica i MKV. flussi di traccia singoli per fare in modo che i client che utilizzano l'SDK non ricevano questo errore. 0x52000062 STATUS_ACK_ERR_INVALID_MKV_DATADati MKV non validi. Il parser MKV di back- end ha rilevato un errore durante l'analisi del flusso. I client che utilizzano l'SDK possono rilevare questo errore se il flusso è danneggiato nella transizione o se l'utilizzo del buffer forza l'SDK all'eliminazione dei fotogrammi di coda parzialmente trasmessi. Nell'ultimo caso, consigliamo di ridurre l'FPS/la risoluzione, aumentare il rapporto di compressione oppure (nel caso di una rete con flusso intermittente) consentire store dei contenuti e durata del buffer di dimensioni maggiori per gestire gli utilizzi elevati temporanei. 0x52000063 STATUS_ACK_ERR_INVALID_PRODUCER_TIMESTAMPTimestamp del Il servizio restituisce questo producer non valido. ACK di errore se nell'orologio del producer è presente un elevato scostamento nel futuro. Gli SDK di livello più elevato (come Java o C++) utilizzano alcune versioni dell'orologio di sistema per soddisfare il callback dell'ora corrente dal PIC. Verificare che l'orologio di sistema sia impostato correttamente. I client che utilizzano direttamente il PIC devono assicurarsi che le funzioni di callback restituiscano il timestamp corretto. 87 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000064 STATUS_ACK_ERR_STREAM_NOT_ACTIVEFlusso non attivo. È stata effettuata una chiamata all'API di back- end mentre il flusso non era in stato "Attivo". Ciò si verifica quando il client crea il flusso e continua immediatamente a inserirvi i fotogrammi. L'SDK gestisce questo scenario attraverso il computer di stato e il meccanismo di recupero. 0x52000065 STATUS_ACK_ERR_KMS_KEY_ACCESS_DENIEDAWS KMSErrore di Restituito quando l'account accesso a negato. non dispone dell'accesso alla chiave specificata. 0x52000066 STATUS_ACK_ERR_KMS_KEY_DISABLEDAWS KMSLa chiave La chiave specificata è stata di è disabilitata disabilitata. 0x52000067 STATUS_ACK_ERR_KMS_KEY_VALIDATION_ERRORAWS KMSErrore di Errore di convalida generico. convalida della chiave Per ulteriori informazioni, di . consulta AWS Key Management Service API Reference. 0x52000068 STATUS_ACK_ERR_KMS_KEY_UNAVAILABLEAWS KMSChiave di La chiave non è disponibile. non disponibile. Per ulteriori informazioni, consulta AWS Key Management Service API Reference. 0x52000069 STATUS_ACK_ERR_KMS_KEY_INVALID_USAGEUtilizzo non valido La chiave di AWS KMS non della chiave di AWS è configurata per l'uso in KMS. questo contesto. Per ulteriori informazioni, consulta AWS Key Management Service API Reference. 0x5200006a STATUS_ACK_ERR_KMS_KEY_INVALID_STATEAWS KMSStato di Per ulteriori informazioni, non valido. consulta AWS Key Management Service API Reference. 0x5200006b STATUS_ACK_ERR_KMS_KEY_NOT_FOUNDAWS KMSChiave di La chiave non è stata non trovata. trovata. Per ulteriori informazioni, consulta AWS Key Management Service API Reference. 0x5200006c STATUS_ACK_ERR_STREAM_DELETEDIl flusso è stato Il flusso è in fase di eliminato o è in fase di eliminazione da un'altra eliminazione. applicazione o tramite AWS Management Console. 0x5200006d STATUS_ACK_ERR_ACK_INTERNAL_ERRORErrore interno. Errore interno generico del servizio. 88 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x5200006e STATUS_ACK_ERR_FRAGMENT_ARCHIVAL_ERRORErrore di archiviazione Restituito quando il servizio del frammento. non riesce a mantenere in modo durevole e indicizzare il frammento. Anche se è raro, questo errore può verificarsi per diversi motivi. Per impostazione predefinita, l'SDK riprova a inviare il frammento. 0x5200006f STATUS_ACK_ERR_UNKNOWN_ACK_ERRORErrore sconosciuto. Il servizio ha restituito un errore sconosciuto. 0x52000070 STATUS_MISSING_ERR_ACK_IDInformazioni ACK Il parser ACK ha completato mancanti. l'analisi, ma l'informazione FragmentAck è mancante. 0x52000071 STATUS_INVALID_ACK_SEGMENT_LENLunghezza del Nel parser ACK è stata segmento ACK non specificata una stringa valida. di segmento ACK con lunghezza non valida. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x52000074 STATUS_MAX_FRAGMENT_METADATA_COUNTIl numero massimo Kinesis video stream di elementi metadati può aggiungere fino a 10 è stato aggiunto a un elementi metadati a un frammento. frammento, aggiungendo un elemento non persistente a un frammento oppure aggiungendo un elemento persistente alla coda dei metadati. Per ulteriori informazioni, consulta Utilizzo dei metadati di streaming con Kinesis Video Streams (p. 15). 0x52000075 STATUS_ACK_ERR_FRAGMENT_METADATA_LIMIT_REACHEDÈ stato raggiunto Producer SDK limita il un limite (numero numero e la dimensione massimo di metadati, degli elementi metadati. lunghezza del nome Questo errore non si verifica o del valore dei se i limiti del codice Producer metadati). SDK non vengono cambiati. Per ulteriori informazioni, consulta Utilizzo dei metadati di streaming con Kinesis Video Streams (p. 15). 0x52000076 STATUS_BLOCKING_PUT_INTERRUPTED_STREAM_TERMINATEDNon ancora disponibile. 89 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata 0x52000077 STATUS_INVALID_METADATA_NAMEIl nome dei metadati Il nome dei metadati non può non è valido. iniziare con la stringa "AWS". Se si verifica questo errore, l'elemento metadati non viene aggiunto al frammento o alla coda dei metadati. Per ulteriori informazioni, consulta Utilizzo dei metadati di streaming con Kinesis Video Streams (p. 15). 0x52000078 STATUS_END_OF_FRAGMENT_FRAME_INVALID_STATEIl termine di un Il termine del frammento non frammento frame è in deve essere inviato in un uno stato non valido. flusso frammentato chiave- flusso. 0x52000079 STATUS_TRACK_INFO_MISSINGLe informazioni sulle Il numero della traccia deve tracce sono mancanti. essere maggiore di 0 e deve corrispondere all'id del brano. 0x5200007a STATUS_MAX_TRACK_COUNT_EXCEEDEDÈ stato superato il Puoi definire un massimo di conteggio massimo di 3 tracce per flusso. trcce. 0x5200007b STATUS_OFFLINE_MODE_WITH_ZERO_RETENTIONIl tempo di Il tempo di conservazione conservazione della della modalità di streaming modalità di streaming offline non dovrebbe essere offline è impostato su impostato su zero. zero. 0x5200007c STATUS_ACK_ERR_TRACK_NUMBER_MISMATCHIl numero di traccia dell'errore ACK non corrisponde. 0x5200007d STATUS_ACK_ERR_FRAMES_MISSING_FOR_TRACKFrame mancanti per una traccia. 0x5200007e STATUS_ACK_ERR_MORE_THAN_ALLOWED_TRACKS_FOUNDIl numero massimo di tracce consentito è stato superato. 0x5200007f STATUS_UPLOAD_HANDLE_ABORTEDL'handle di caricamento è stata interrotta. 0x52000080 STATUS_INVALID_CERT_PATH_LENGTHLunghezza percorso certificato non valida. 0x52000081 STATUS_DUPLICATE_TRACK_ID_FOUNDTrovato ID traccia duplicato. Codici di errore e stato restituiti dalla libreria Duration La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria Duration. 90 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message 0xFFFFFFFFFFFFFFFF INVALID_DURATION_VALUE Codici di errore e stato restituiti dalla libreria Common La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria Common. Note Le informazioni sui codici di errore e di stato sono comuni a molte API. Codice Message Descrizione 0x00000001 STATUS_NULL_ARG Valore NULL inviato per un argomento obbligatorio. 0x00000002 STATUS_INVALID_ARG È stato specificato un valore non valido per un argomento. 0x00000003 STATUS_INVALID_ARG_LEN È stata specificata una lunghezza di argomento non valida. 0x00000004 STATUS_NOT_ENOUGH_MEMORY Non è stato possibile allocare memoria sufficiente. 0x00000005 STATUS_BUFFER_TOO_SMALL La dimensione specificata del buffer è troppo piccola. 0x00000006 STATUS_UNEXPECTED_EOF È stata raggiunta una fine imprevista del file. 0x00000007 STATUS_FORMAT_ERROR È stato rilevato un formato non valido. 0x00000008 STATUS_INVALID_HANDLE_ERRORValore di gestione non valido. 0x00000009 STATUS_OPEN_FILE_FAILED Impossibile aprire un file. 0x0000000a STATUS_READ_FILE_FAILED Impossibile leggere da un file. 0x0000000b STATUS_WRITE_TO_FILE_FAILEDImpossibile scrivere su un file. 0x0000000c STATUS_INTERNAL_ERROR Un errore interno che in genere non si verifica e che può indicare un bug dell'SDK o dell'API del servizio. 0x0000000d STATUS_INVALID_OPERATION Si è verificata un'operazione non valida o l'operazione non è consentita. 0x0000000e STATUS_NOT_IMPLEMENTED La funzione non viene implementata. 0x0000000f STATUS_OPERATION_TIMED_OUT Timeout dell'operazione. 0x00000010 STATUS_NOT_FOUND Una risorsa obbligatoria non è stata trovata. 91 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codici di errore e stato restituiti dalla libreria Heap La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria Heap. Codice Message Descrizione 0x01000001 STATUS_HEAP_FLAGS_ERROR È stata specificata una combinazione di flag non valida. 0x01000002 STATUS_HEAP_NOT_INITIALIZEDÈ stata tentata un'operazione prima dell'inizializzazione dell'heap. 0x01000003 STATUS_HEAP_CORRUPTED L'heap era danneggiato o la banda di guardia (in modalità debug) è stata sovrascritta. Il danneggiamento dell'heap potrebbe essere causato da un overflow del buffer nel codice del client. 0x01000004 STATUS_HEAP_VRAM_LIB_MISSINGL'utente della VRAM (RAM video) o la libreria della modalità kernel non possono essere caricati o sono mancanti. Verificare che la piattaforma sottostante supporti le allocazioni della VRAM. 0x01000005 STATUS_HEAP_VRAM_LIB_REOPENImpossibile aprire la libreria della VRAM. 0x01000006 STATUS_HEAP_VRAM_INIT_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione INIT. 0x01000007 STATUS_HEAP_VRAM_ALLOC_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione ALLOC. 0x01000008 STATUS_HEAP_VRAM_FREE_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione FREE. 0x01000009 STATUS_HEAP_VRAM_LOCK_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione LOCK. 0x0100000a STATUS_HEAP_VRAM_UNLOCK_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione UNLOCK. 0x0100000b STATUS_HEAP_VRAM_UNINIT_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione UNINIT. 0x0100000c STATUS_HEAP_VRAM_GETMAX_FUNC_SYMBOLImpossibile caricare l'esportazione della funzione GETMAX. 92 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione 0x0100000d STATUS_HEAP_DIRECT_MEM_INITImpossibile inizializzare il pool di heap principale nell'heap ibrido. 0x0100000e STATUS_HEAP_VRAM_INIT_FAILEDL'inizializzazione dinamica della VRAM non è riuscita. 0x0100000f STATUS_HEAP_LIBRARY_FREE_FAILEDImpossibile annullare l'allocazione e liberare la libreria della VRAM. 0x01000010 STATUS_HEAP_VRAM_ALLOC_FAILEDL'allocazione della VRAM non è riuscita. 0x01000011 STATUS_HEAP_VRAM_FREE_FAILEDLa liberazione della VRAM non è riuscita. 0x01000012 STATUS_HEAP_VRAM_MAP_FAILEDLa mappatura della VRAM non è riuscita. 0x01000013 STATUS_HEAP_VRAM_UNMAP_FAILEDL'annullamento della mappatura della VRAM non è riuscito. 0x01000014 STATUS_HEAP_VRAM_UNINIT_FAILEDLa deinizializzazione della VRAM non è riuscita. Codici di errore e stato restituiti dalla libreria MKVGen La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria MKVGen. Codice Message Descrizione/Operazione consigliata 0x32000001 STATUS_MKV_INVALID_FRAME_DATAMembri della struttura di dati Frame non validi. Verificare che la durata, la dimensione e i dati del fotogramma siano validi ed entro i limiti specificati in Limiti dell'SDK producer (p. 72). 0x32000002 STATUS_MKV_INVALID_FRAME_TIMESTAMPTimestamp del fotogramma non valido. I valori del timestamp di presentazione (PTS) e del timestamp di decodifica (DTS) calcolati sono maggiori o uguali al timestamp del fotogramma iniziale del frammento. Ciò indica un potenziale riavvio della pipeline multimediale o un problema di stabilità del codificatore. Per informazioni sulla risoluzione dei problemi, consulta Errore "Failed to submit frame to Kinesis Video client" (p. 179) 93 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione/Operazione consigliata 0x32000003 STATUS_MKV_INVALID_CLUSTER_DURATIONÈ stata specificata una durata non valida del frammento. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x32000004 STATUS_MKV_INVALID_CONTENT_TYPE_LENGTHLunghezza della stringa del tipo di contenuto non valida. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x32000005 STATUS_MKV_NUMBER_TOO_BIG Si è verificato un tentativo di codifica di un numero troppo grande per essere rappresentato nel formato EBML (Extensible Binary Meta Language). Questo errore non dovrebbe essere esposto ai client dell'SDK. 0x32000006 STATUS_MKV_INVALID_CODEC_ID_LENGTHLunghezza della stringa dell'ID codec non valida. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x32000007 STATUS_MKV_INVALID_TRACK_NAME_LENGTHLunghezza della stringa del nome della traccia non valida. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x32000008 STATUS_MKV_INVALID_CODEC_PRIVATE_LENGTHLunghezza dei dati privati del codec non valida. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x32000009 STATUS_MKV_CODEC_PRIVATE_NULLI dati privati del codec (CPD) sono NULL, mentre la loro dimensione è maggiore di 0. 0x3200000a STATUS_MKV_INVALID_TIMECODE_SCALEValore di scala del timecode non valido. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x3200000b STATUS_MKV_MAX_FRAME_TIMECODEIl timecode del fotogramma è superiore al valore massimo. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 94 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione/Operazione consigliata 0x3200000c STATUS_MKV_LARGE_FRAME_TIMECODEIl valore massimo del timecode del fotogramma è stato raggiunto. Il formato MKV utilizza 16-bit con firma per rappresentare il timecode relativo del fotogramma all'inizio del cluster. L'errore viene generato se il timecode del fotogramma non può essere rappresentato. Questo errore indica una selezione di scala del timecode non valida o che la durata del cluster è troppo lunga. Di conseguenza, il timecode del fotogramma supera lo spazio di 16-bit con firma. 0x3200000d STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATAÈ stato rilevato un codice di avvio Annex-B non valido. Ad esempio, il flag di adattamento Annex-B è stato specificato e il codice ha rilevato una sequenza di avvio non valida composta da più di tre zeri. Un formato Annex-B valido deve avere una sequenza di "prevenzione di emulazione" per evitare una sequenza di tre o più zeri nel bytestream. Per ulteriori informazioni, consulta la specifica MPEG. Per ulteriori informazioni su questo errore su Android, consulta STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATA (0x3200000d) error on Android (p. 182). 0x3200000e STATUS_MKV_INVALID_AVCC_NALU_IN_FRAME_DATACreazione di un pacchetto AVCC NALu non valida durante la specifica del flag di adattamento AVCC. Assicurarsi che il bytestream sia in un formato AVCC valido. Per ulteriori informazioni, consulta la specifica MPEG. 0x3200000f STATUS_MKV_BOTH_ANNEXB_AND_AVCC_SPECIFIEDSono state specificate dei NAL AVCC e Annex-B di adattamento. Specificare soltanto un formato o nessuno dei due. 95 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione/Operazione consigliata 0x32000010 STATUS_MKV_INVALID_ANNEXB_NALU_IN_CPDFormato Annex-B non valido dei CPD durante la specifica del flag Annex-B di adattamento. Assicurarsi che i CPD siano in un formato Annex-B valido. In caso contrario, rimuovere il flag di adattamento Annex-B dei CPD. 0x32000011 STATUS_MKV_PTS_DTS_ARE_NOT_SAMEKinesis Video Streams applica il timestamp di presentazione (PTS) e il timestamp di decodifica (DTS) per fare in modo che siano uguali ai fotogrammi di inizio del frammento. Si tratta dei fotogrammi chiave che avviano il frammento. 0x32000012 STATUS_MKV_INVALID_H264_H265_CPDImpossibile analizzare i dati privati del codec H264/H265. 0x32000013 STATUS_MKV_INVALID_H264_H265_SPS_WIDTHImpossibile estrarre la larghezza dai dati privati del codec. 0x32000014 STATUS_MKV_INVALID_H264_H265_SPS_HEIGHTImpossibile estrarre l'altezza dai dati privati del codec. 0x32000015 STATUS_MKV_INVALID_H264_H265_SPS_NALUNALu SPS H264/H265 non valida. 0x32000016 STATUS_MKV_INVALID_BIH_CPD Formato di intestazione delle informazioni bitmap non valido nei dati privati del codec. 0x32000017 STATUS_MKV_INVALID_HEVC_NALU_COUNTConteggio unità High Efficiency Video Coding (HEVC) Network Abstraction Layer (NALU) non valido. 0x32000018 STATUS_MKV_INVALID_HEVC_FORMATFormato HEVC non valido. 0x32000019 STATUS_MKV_HEVC_SPS_NALU_MISSINGHEVC NALUs mancanti in Sequence Parameter Set (SPS). 0x3200001a STATUS_MKV_INVALID_HEVC_SPS_NALU_SIZEDimensione HEVC SPS NALU non valida. 0x3200001b STATUS_MKV_INVALID_HEVC_SPS_CHROMA_FORMAT_IDCIDC formato Chroma non valido. 0x3200001c STATUS_MKV_INVALID_HEVC_SPS_RESERVEDHEVC SPS riservato non valido. 0x3200001d STATUS_MKV_MIN_ANNEX_B_CPD_SIZEDimensione minima valore beta privato codec Annex-b. Per H264, questo valore deve essere maggiore o uguale a 11. Per H265, questo valore deve essere maggiore o uguale a 15. 96 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione/Operazione consigliata 0x3200001e STATUS_MKV_ANNEXB_CPD_MISSING_NALUSDati codec privato mancanti in Annex-B NALUs. 0x3200001f STATUS_MKV_INVALID_ANNEXB_CPD_NALUSBeta codec privato non valido in Annex-B NALUs. 0x32000020 STATUS_MKV_INVALID_TAG_NAME_LENGTHLunghezza del nome del tag non valida. Il valore valido è maggiore di zero e inferiore a 128. 0x32000021 STATUS_MKV_INVALID_TAG_VALUE_LENGTHLunghezza valore tag non valido. Il valore valido è maggiore di zero e inferiore a 256. 0x32000022 STATUS_MKV_INVALID_GENERATOR_STATE_TAGSTag stato generatore non validi. 0x32000023 STATUS_MKV_INVALID_AAC_CPD_SAMPLING_FREQUENCY_INDEXIndice non valido di frequenza di campionamento dati privati codec AAC. 0x32000024 STATUS_MKV_INVALID_AAC_CPD_CHANNEL_CONFIGConfigurazione canale dati privati codec AAC non valida. 0x32000025 STATUS_MKV_INVALID_AAC_CPD Dati privati codec AAC non validi. 0x32000026 STATUS_MKV_TRACK_INFO_NOT_FOUNDInformazioni sulle tracce non trovate. 0x32000027 STATUS_MKV_INVALID_SEGMENT_UUIDUUID segmento non valido. 0x32000028 STATUS_MKV_INVALID_TRACK_UIDUID traccia non valido. Codici di errore e stato restituiti dalla libreria Trace La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria Trace. Codice Message 0x10100001 STATUS_MIN_PROFILER_BUFFER Codici di errore e stato restituiti dalla libreria Utils La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria Utils. Codice Message 0x40000001 STATUS_INVALID_BASE64_ENCODE 0x40000002 STATUS_INVALID_BASE 0x40000003 STATUS_INVALID_DIGIT 0x40000004 STATUS_INT_OVERFLOW 97 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message 0x40000005 STATUS_EMPTY_STRING 0x40000006 STATUS_DIRECTORY_OPEN_FAILED 0x40000007 STATUS_PATH_TOO_LONG 0x40000008 STATUS_UNKNOWN_DIR_ENTRY_TYPE 0x40000009 STATUS_REMOVE_DIRECTORY_FAILED 0x4000000a STATUS_REMOVE_FILE_FAILED 0x4000000b STATUS_REMOVE_LINK_FAILED 0x4000000c STATUS_DIRECTORY_ACCESS_DENIED 0x4000000d STATUS_DIRECTORY_MISSING_PATH 0x4000000e STATUS_DIRECTORY_ENTRY_STAT_ERROR Codici di errore e stato restituiti dalla libreria View La tabella seguente contiene informazioni sugli errori e gli stati restituiti dai metodi nella libreria View. Codice Message Descrizione 0x30000001 STATUS_MIN_CONTENT_VIEW_ITEMSÈ stato specificato un numero di elementi di visualizzazione dei contenuti non valido. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x30000002 STATUS_INVALID_CONTENT_VIEW_DURATIONÈ stata specificata una durata di visualizzazione dei contenuti non valida. Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). 0x30000003 STATUS_CONTENT_VIEW_NO_MORE_ITEMSSi è tentato di superare la posizione principale. 0x30000004 STATUS_CONTENT_VIEW_INVALID_INDEXÈ stato specificato un indice non valido. 0x30000005 STATUS_CONTENT_VIEW_INVALID_TIMESTAMPTimestamp non valido o sovrapposto. Il timestamp di decodifica del fotogramma deve essere maggiore o uguale al timestamp del fotogramma precedente, più la durata del fotogramma precedente: `DTS(n) >= DTS(n-1) + Duration(n-1)`. Questo errore spesso indica un codificatore "instabile". Il codificatore produce un 98 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione incremento dei fotogrammi codificati e i relativi timestamp sono inferiori rispetto alle durate intra-frame. Oppure, il flusso è configurato sull'uso dei timestamp dell'SDK e i fotogrammi vengono inviati più velocemente rispetto alla loro durata. Per ovviare a possibili instabilità del codificatore, specificare una durata del fotogramma inferiore nella struttura StreamInfo.StreamCaps. Ad esempio, se il flusso è pari a 25 FPS, la durata di ogni fotogramma è di 40 ms. Tuttavia, per gestire l'instabilità del codificatore, consigliamo di utilizzare la metà della durata di tale fotogramma (20 ms). Alcuni flussi richiedono un controllo più preciso sul tempo per il rilevamento degli errori. 0x30000006 STATUS_INVALID_CONTENT_VIEW_LENGTHÈ stata specificata una lunghezza dei dati degli elementi di visualizzazione dei contenuti non valida. Errori e codici di stato resituiti dai callback PutFrame – C Producer Library La sezione seguente contiene informazioni sugli errori e sullo stato restituiti dai callback per l'operazione PutFrame all'interno della libreria di produttori C. Codice Message Descrizione Operazione consigliata 0x15000001 STATUS_STOP_CALLBACK_CHAINLa catena di callback è stata interrotta. 0x15000002 STATUS_MAX_CALLBACK_CHAINIl limite massimo della catena callback è stato raggiunto. 0x15000003 STATUS_INVALID_PLATFORM_CALLBACKS_VERSIONVersione Specificare la versione della struttura corrente corretta della PlatformCallbacks struttura. non valida. 0x15000004 STATUS_INVALID_PRODUCER_CALLBACKS_VERSIONVersione Specificare la versione della struttura corrente corretta della struttura. 99 Amazon Kinesis Video Streams Guida per gli sviluppatori Documentazione di riferimento per il codice di errore Codice Message Descrizione Operazione consigliata ProducerCallbacks non valida. 0x15000005 STATUS_INVALID_STREAM_CALLBACKS_VERSIONVersione Specificare la versione della struttura corrente corretta della StreamCallbacks struttura. non valida. 0x15000006 STATUS_INVALID_AUTH_CALLBACKS_VERSIONVersione Specificare la versione della struttura corrente corretta della AuthCallbacks non struttura. valida. 0x15000007 STATUS_INVALID_API_CALLBACKS_VERSIONVersione Specificare la versione della struttura corrente corretta della ApiCallbacks non struttura. valida. 0x15000008 STATUS_INVALID_AWS_CREDENTIALS_VERSIONVersione Specificare la versione della struttura corrente corretta della AwsCredentials struttura. non valida. 0x15000009 STATUS_MAX_REQUEST_HEADER_COUNTIl numero massimo dei conteggi dell'intestazione della richiesta è stato raggiunto. 0x1500000a STATUS_MAX_REQUEST_HEADER_NAME_LENLa lunghezza massima del nome dell'intestazione della richiesta è stata raggiunta. 0x1500000b STATUS_MAX_REQUEST_HEADER_VALUE_LENLa lunghezza massima del valore dell'intestazione della richiesta è stata raggiunta. 0x1500000c STATUS_INVALID_API_CALL_RETURN_JSONRestituzione JSON non valida per una chiamata API. 0x1500000d STATUS_CURL_INIT_FAILEDInizializzazione curl non riuscita. 0x1500000e STATUS_CURL_LIBRARY_INIT_FAILEDInizializzazione lib curl non riuscita. 0x1500000f STATUS_INVALID_DESCRIBE_STREAM_RETURN_JSONRestituzione JSON non valida per DescribeStream. 0x150000010 STATUS_HMAC_GENERATION_ERRORErrore di generazione HMAC. 100 Amazon Kinesis Video Streams Guida per gli sviluppatori Flag di adattamento del NAL Codice Message Descrizione Operazione consigliata 0x150000011 STATUS_IOT_FAILED Autorizzazione IOT non riuscita. 0x150000012 STATUS_MAX_ROLE_ALIAS_LEN_EXCEEDEDLa lunghezza Specificare una lunghezza massima dell'alias dell'alias minore. del ruolo è stata raggiunta. 0x150000013 STATUS_MAX_USER_AGENT_NAME_POSTFIX_LEN_EXCEEDEDLa lunghezza massima del suffisso del nome agente è stata raggiunta. 0x150000014 STATUS_MAX_CUSTOM_USER_AGENT_LEN_EXCEEDEDLa lunghezza massima dell'agente utente cliente è stata raggiunta. 0x150000015 STATUS_INVALID_USER_AGENT_LENGTHLunghezza agente utente non valida. 0x150000016 STATUS_INVALID_ENDPOINT_CACHING_PERIODPeriodo di caching Specificare un periodo di dell'endpoint non caching inferiore a 24 ore. valido. 0x150000017 STATUS_IOT_EXPIRATION_OCCURS_IN_PASTIl timestamp di scadenza IOT si verifica nel passato. 0x150000018 STATUS_IOT_EXPIRATION_PARSING_FAILEDL'analisi della scadenza IOT non è andata a buon fine. Documentazione di riferimento per i flag di adattamento del Network Abstraction Layer (NAL) Questa sezione contiene informazioni sui flag disponibili per l'enumerazione StreamInfo.NalAdaptationFlags. Il flusso semplice in un'applicazione può essere nel formato Annex-B o AVCC : • Il formato Annex-B delimita NALUs (Network Abstraction Layer unit) con due byte di zero, seguiti da uno o tre byte di zero, seguito dal numero 1 (denominato codice di avvio, ad esempio 00000001 • Anche il formato AVCC esegue il wrapping delle NALU, ma ogni NALU è preceduta da un valore che ne indica la dimensione (di solito quattro byte). Molti codificatori producono il formato Annex-B di bitstream. Alcuni processori bitstream di livello più elevato (come il motore di riproduzione o il lettore Media Source Extensions (MSE) nella AWS Management Console) utilizzano il formato AVCC per i propri fotogrammi. Anche i dati privati del codec (CPD), che corrispondono agli SPS/PPS (Sequence Parameter Set/Picture Parameter Set) per il codec H.264, possono essere nel formato Annex-B o AVCC. Tuttavia, per i CPD, i formati sono diversi da quelli descritti in precedenza. 101 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture del producer I flag informano l'SDK di adattare le NALU al formato AVCC o Annex-B per i dati del fotogramma e i CPD come segue: Flag Adattamento NAL_ADAPTATION_FLAG_NONE Nessun adattamento NAL_ADAPTATION_ANNEXB_NALS Adatta NALU Annex-B a NALU AVCC NAL_ADAPTATION_AVCC_NALS Adatta NALU AVCC a NALU Annex-B NAL_ADAPTATION_ANNEXB_CPD_NALSAdatta NALU Annex-B dei dati privati del codec alle NALU in formato AVCC NAL_ADAPTATION_ANNEXB_CPD_AND_FRAME_NALSAdatta NALU Annex-B dei dati privati del codec e del fotogramma alle NALU in formato AVCC Per ulteriori informazioni sui tipi di NALU, consulta la sezione 1.3 relativa ai tipi di Network Abstraction Layer Unit in RFC 3984. Strutture dell'SDK producer Questa sezione include informazioni sulle strutture utilizzabili per fornire i dati all'oggetto di Kinesis Video StreamsProducer. Argomenti • DeviceInfo/DefaultDeviceInfoProvider (p. 102) • StorageInfo (p. 103) DeviceInfo/DefaultDeviceInfoProvider Gli oggetti DeviceInfo e DefaultDeviceInfoProvider controllano il comportamento dell'oggetto di Kinesis Video Streams Producer. Campi dei membri • version (versione): un valore intero utilizzato per verificare che la versione corretta della struttura venga utilizzata con la versione corrente del codebase. La versione corrente viene specificata con la macro DEVICE_INFO_CURRENT_VERSION. • name: il nome leggibile del dispositivo. • tagCount/tags: attualmente non utilizzato. • streamCount: il numero massimo di flussi che il dispositivo è in grado di gestire. Questo campo effettua inizialmente la pre-allocazione dello storage per i puntatori verso gli oggetti di flusso, ma gli oggetti di flusso effettivi vengono creati in un secondo momento. Il valore predefinito è 16 flussi, ma questo valore può essere modificato nel file DefaultDeviceInfoProvider.cpp. • storageInfo: un oggetto che descrive la configurazione principale dello storage. Per ulteriori informazioni, consulta StorageInfo (p. 103). 102 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture del producer StorageInfo Specifica la configurazione dello storage principale per Kinesis Video Streams. L'implementazione predefinita si basa su un'implementazione di heap rapida a bassa frammentazione, ottimizzata per lo streaming. Utilizza l'allocatore MEMALLOC, che è possibile sovrascrivere su determinate piattaforme. Alcune piattaforme dispongono di un'allocazione di memoria virtuale senza il supporto dell'allocazione con pagine fisiche. Man mano che la memoria viene utilizzata, le pagine virtuali vengono supportate dalle pagine fisiche. Di conseguenza, quando lo storage è sottoutilizzato, la memoria viene utilizzata in modo ridotto in tutto il sistema. Calcolare la dimensione predefinita dello storage in base alla seguente formula. DefragmentationFactor deve essere impostato su 1.2 (20%). Size = NumberOfStreams * AverageFrameSize * FramesPerSecond * BufferDurationInSeconds * DefragmentationFactor Nell'esempio seguente, un dispositivo dispone di flussi video e audio. Il flusso audio contiene 512 campioni al secondo, con una media di campionamento di 100 byte. Il flusso video è composto da 25 fotogrammi al secondo, con una media di campionamento di 10.000 byte. Ogni flusso ha 3 minuti di durata di buffer. Size = (512 * 100 * (3 * 60) + 25 * 10000 * (3 * 60)) * 1.2 = (9216000 + 45000000) * 1.2 = 65059200 = ~ 66MB. Se sul dispositivo è disponibile una quantità più elevata di memoria, è consigliabile aggiungere ulteriore memoria allo storage, per evitare una grave frammentazione. Assicurarsi che la dimensione di storage sia sufficiente per contenere i buffer completi di tutti i flussi a elevata complessità di codifica (quando la dimensione dei fotogrammi è più elevata a causa di un elevato movimento) o nei momenti in cui la larghezza di banda è ridotta. Se il producer causa un utilizzo elevato della memoria, emetterà dei callback di utilizzo di overflow dello storage (StorageOverflowPressureFunc). Tuttavia, se la memoria disponibile nello store dei contenuti è insufficiente, l'invio del fotogramma a Kinesis Video Streams genererà un errore (STATUS_STORE_OUT_OF_MEMORY = 0x5200002e). Per ulteriori informazioni, consulta Codici di errore e stato restituiti dalla libreria Client (p. 75). Ciò può verificarsi anche se le ACK dell'applicazione non sono disponibili o se le ACK persistenti vengono ritardate. In questo caso i buffer raggiungeranno la capacità di "durata del buffer" prima che i fotogrammi meno recenti inizino a essere eliminati. Campi dei membri • version (versione): un valore intero utilizzato per verificare che la versione corretta della struttura venga utilizzata con la versione corrente del codebase. • storageType: un'enumerazione DEVICE_STORAGE_TYPE che specifica il supporto/l'implementazione sottostante dello storage. Attualmente, l'unico valore supportato è DEVICE_STORAGE_TYPE_IN_MEM. DEVICE_STORAGE_TYPE_HYBRID_FILE sarà supportato in un'implementazione futura per indicare che lo storage utilizza lo store dei contenuti supportato da file. • storageSize: la dimensione in byte dello storage da pre-allocare. L'allocazione minima è 10 MB, mentre quella massima è 10 GB (questo valore cambierà nell'implementazione futura dello store dei contenuti supportato da file). • spillRatio: un valore intero che rappresenta la percentuale di storage da allocare dal tipo di storage di memoria diretto (RAM), rispetto allo storage di overflow secondario (storage di file). Attualmente non utilizzato. • rootDirectory: il percorso alla directory in cui è si trova lo store dei contenuti supportato da file. Attualmente non utilizzato. 103 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi KinesisStrutture di flussi video di È possibile utilizzare le seguenti strutture per fornire i dati a un'istanza di un Kinesis video stream. Argomenti • StreamDefinition/StreamInfo (p. 104) • ClientMetrics (p. 113) • StreamMetrics (p. 114) StreamDefinition/StreamInfo L'oggetto StreamDefinition nel livello C++ racchiude l'oggetto StreamInfo nel Platform Independent Code (PIC) e fornisce alcuni valori predefiniti nel costruttore. Campi dei membri Campo Tipo di dati Descrizione Valore predefinito stream_name string Nome di flusso Se non viene specificato facoltativo. Consulta alcun nome, ne per ulteriori informazioni verrà generato uno sulla lunghezza casualmente. del nome del flus Limiti dell'SDK producer (p. 72) . Ogni flusso deve avere un nome univoco. retention_period duration 104 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito content_type string Il formato del contenuto video/h264 del flusso. La console Kinesis Video Streams è in grado di riprodurre i contenuti nel formato video/h264. max_latency duration 105 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito timecode_scale duration 106 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito frame_timecodes bool Per scegliere se true utilizzare i timecode del fotogramma o generare timestamp tramite il callback dell'ora corrente. Molti codificatori non creano timestamp con i fotogrammi. L'indicazione di false per questo parametro assicura che i fotogrammi dispongano di un timestamp quando vengono inseriti in Kinesis Video Streams. absolute_fragment_times bool Kinesis Video Streams true utilizza MKV come meccanismo di creazione di pacchetti sottostante. La specifica MKV è rigorosa per quanto riguarda l'impostazione dei timecode del fotogramma come relativi all'inizio del cluster (frammento), ma i timecode del cluster possono essere assoluti o relativi all'ora di inizio del flusso. Se i timestamp sono relativi, la chiamata API del servizio PutMedia utilizza il timestamp di inizio facoltativo del flusso e modifica i timestamp del cluster. Il servizio archivia sempre i frammenti con i relativi timestamp assoluti. fragment_acks bool Per scegliere se true, per indicare che ricevere o meno ACK l'SDK riceverà le ACK e (conferme) per il agirà di conseguenza. frammento a livello di applicazione. restart_on_error bool Per scegliere se true, per indicare che riavviare in seguito a l'SDK tenta di riavviare errori specifici. lo streaming in caso di errori. 107 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito recalculate_metrics bool Per scegliere se true calcolare nuovamente i parametri. Ogni chiamata effettuata per recuperare i parametri è in grado di ricalcolarli per ottenere il valore "in esecuzione" più recente (ciò potrebbe avere un leggero impatto sulla CPU). Sui dispositivi layout componente/con potenza estremamente ridotta, potrebbe essere necessario configurare questa impostazione su false per risparmiare cicli della CPU. Negli altri casi, non è consigliato impostare questo valore su false. 108 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito nal_adaptation_flags uint32_t Specifica i flag di L'impostazione adattamento dell'unità predefinita consiste Network Abstraction nell'adattare il formato Layer (NALU). Se il Annex-B al formato bitstream dispone AVCC per i dati dei della codifica H.264, fotogrammi e per i dati può essere elaborato privati del codec. come raw o inserito in pacchetti nelle NALU, in formato Annex-B o AVCC. La maggior parte dei producer/ consumatori di flussi semplici (codificatori/ decodificatori di lettura) utilizza il formato Annex- B, poiché presenta alcuni vantaggi, come il recupero dagli errori. I sistemi di livello superiore utilizzano il formato AVCC che è il formato di default per MPEG, HLS, DASH e così via. La funzione di riproduzione della console utilizza le estensioni di sorgente multimediali (MSE) del browser per decodificare e riprodurre i flussi in formato AVCC. Per H.264 (e per M-JPEG e H.265), nell'SDK sono presenti funzionalità di adattamento. Molti flussi semplici sono nel formato seguente. In questo esempio, Ab è il codice di avvio Annex-B (001 o 0001). Ab(Sps)Ab(Pps)Ab(I- frame)Ab(P/B-frame) Ab(P/B-frame)…. Ab(Sps)Ab(Pps)Ab(I- frame)Ab(P/B-frame) Ab(P/B-frame) I dati privati del codec (CPD), nel caso della codifica H.264, sono impostati sui 109 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito parametri SPS e PPS e possono essere adattati al formato AVCC. A meno che la pipeline multimediale non fornisca i CPD separatamente, l'applicazione è in grado di estrarli dal fotogramma cercando il primo fotogramma IDR (che dovrebbe contenere i parametri SPS/PPS), estraendo le due NALU (che sono Ab(Sps)Ab(Pps)) e impostandolo nei CPD in StreamDefinition. Per ulteriori informazioni, consulta Flag di adattamento del NAL (p. 101). frame_rate uint32_t La frequenza 25 fotogrammi prevista. Tale valore viene utilizzato per calcolare meglio le esigenze di buffering. avg_bandwidth_bps uint32_t La larghezza di banda 4 * 1024 * 1024 media prevista del flusso. Tale valore viene utilizzato per calcolare meglio le esigenze di buffering. 110 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito buffer_duration duration 111 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito replay_duration duration 112 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione Valore predefinito codecPrivateData unsigned char* Il buffer dei dati privati null del codec (CPD). Se sulla pipeline multimediale sono presenti informazioni sui CPD prima dell'inizio del flusso, sarà possibile impostarlo su StreamDefinition.codecPrivateData. I bit vengono copiati e il buffer può essere riutilizzato o liberato in seguito alla chiamata per la creazione del flusso. Se, tuttavia, i dati non sono disponibili al momento della creazione del flusso, il buffer può essere impostato in uno dei sovraccarichi della funzione KinesisVideoStream.start(cpd). codecPrivateDataSize uint32_t La dimensione del 0 buffer dei dati privati del codec. ClientMetrics L'oggetto ClientMetrics viene compilato richiamando getKinesisVideoMetrics. Campi dei membri Campo Tipo di dati Descrizione versione UINT32 La versione della struttura, definita nella macro CLIENT_METRICS_CURRENT_VERSION. contentStoreSize UINT64 La dimensione totale dello store dei contenuti in byte. Si tratta del valore specificato in DeviceInfo.StorageInfo.storageSize. contentStoreAvailableSize UINT64 La dimensione di storage attualmente disponibile in byte. contentStoreAllocatedSize UINT64 La dimensione attualmente allocata. La dimensione allocata e quella disponibile devono essere leggermente inferiori alla dimensione totale di storage, per via della contabilità interna e 113 Amazon Kinesis Video Streams Guida per gli sviluppatori Strutture di flussi Campo Tipo di dati Descrizione dell'implementazione dello store dei contenuti. totalContentViewsSize UINT64 La dimensione della memoria allocata per tutte le visualizzazioni dei contenuti per tutti i flussi. Non viene conteggiata nella dimensione di storage. Questa memoria viene allocata tramite la macro MEMALLOC, che è possibile sovrascrivere per fornire un allocatore personalizzato. totalFrameRate UINT64 La frequenza fotogrammi totale osservata su tutti i flussi. totalTransferRate UINT64 La velocità di streaming totale osservata in byte al secondo su tutti i flussi. StreamMetrics L'oggetto StreamMetrics viene compilato richiamando getKinesisVideoMetrics. Campi dei membri Campo Tipo di dati Descrizione versione UINT32 La versione della struttura, definita nella macro STREAM_METRICS_CURRENT_VERSION. currentViewDuration UINT64 La durata dei fotogrammi accumulati. Nei casi con configurazione rapida della rete, questa durata è pari a 0 o alla durata del fotogramma (durante la trasmissione del fotogramma). Se la durata supera il valore max_latency specificato in StreamDefinition, il callback di latenza del flusso viene richiamato se è stato specificato. La durata viene specificata in unità di 100ns, ovvero l'unità di tempo predefinita del livello PIC. overallViewDuration UINT64 La durata di visualizzazione generale. Se il flusso viene configurato senza ACK o persistenza, questo valore aumenta man mano che i fotogrammi vengono inseriti in Kinesis video stream e 114 Amazon Kinesis Video Streams Guida per gli sviluppatori Callback Campo Tipo di dati Descrizione diventa uguale al valore buffer_duration in StreamDefinition. Se le ACK sono abilitate e l'ACK persistente viene ricevuta, il buffer viene tagliato sul fotogramma chiave successivo, dal momento che il timestamp dell'ACK indica l'inizio dell'intero frammento. La durata viene specificata in unità di 100 ns, ovvero l'unità di tempo predefinita del livello PIC. currentViewSize UINT64 La dimensione in byte del buffer corrente. overallViewSize UINT64 La dimensione totale della visualizzazione in byte. currentFrameRate UINT64 La frequenza fotogramma osservata del flusso corrente. currentTransferRate UINT64 La velocità di trasferimento osservata in byte al secondo del flusso corrente. Callback dell'SDK Producer I corsi di formazione e i metodi nell'SDK di Amazon Kinesis Video Streams Producer non mantengono i propri processi. Vengono, invece, utilizzate le chiamate di funzione in ingresso e gli eventi per programmare callback e comunicare con l'applicazione. Sono disponibili due modelli di callback che l'applicazione può utilizzare per interagire con l'SDK: • CallbackProvider: questo oggetto espone ogni callback dal componente di codice indipendente dalla piattaforma (PIC) all'applicazione. Questo modello consente di eseguire questa funzionalità, ma anche significa che l'implementazione deve gestire tutti i metodi API pubblici e le firme nel livello C++. • StreamCallbackProvider (p. 116) e ClientCallbackProvider (p. 116): questi oggetti espongono i callback specifici di client e flusso, mentre il livello C++ dell'SDK espone il resto dei callback. Questo è il modello di callback preferito per interagire con l'SDK Producer. Il seguente diagramma mostra il modello di oggetti callback: 115 Amazon Kinesis Video Streams Guida per gli sviluppatori Callback Nel diagramma precedente, DefaultCallbackProvider deriva da CallbackProvider (che espone tutti i callback nel PIC) e contiene StreamCallbackProvider e ClientCallbackProvider. Questo argomento contiene le sezioni seguenti: • ClientCallbackProvider (p. 116) • StreamCallbackProvider (p. 116) • Struttura ClientCallbacks (p. 116) • Implementazioni di callback per riprovare lo streaming (p. 120) ClientCallbackProvider L'oggetto ClientCallbackProvider espone le funzioni di callback a livello di client. I dettagli delle funzioni sono descritti nella sezione ClientCallbacks (p. 116). Metodi di callback: • getClientReadyCallback: segnala lo stato pronto per il client. • getStorageOverflowPressureCallback: segnala l'overflow di storage o di pressione. Questo callback viene chiamato quando l'utilizzo dello storage è inferiore al valore STORAGE_PRESSURE_NOTIFICATION_THRESHOLD, pari al 5% delle dimensioni dello spazio di archiviazione generale. Per ulteriori informazioni, consulta StorageInfo (p. 103). StreamCallbackProvider L'oggetto StreamCallbackProvider espone le funzioni di callback a livello di flusso. Metodi di callback: • getDroppedFragmentReportCallback: segnala un frammento interrotto. • getDroppedFrameReportCallback: segnala un fotogramma interrotto. • getFragmentAckReceivedCallback: segnala un frammento ACK ricevuto per il flusso. • getStreamClosedCallback: segnala una condizione flusso chiusa. • getStreamConnectionStaleCallback: segnala una condizione di connessione obsoleta. In questa condizione, il produttore invia dati al servizio, ma non riceve conferme. • getStreamDataAvailableCallback: segnala che i dati sono disponibili nel flusso. • getStreamErrorReportCallback: segnala una condizione di errore del flusso. • getStreamLatencyPressureCallback: segnala una condizione di latenza del flusso, quando la dimensione del buffer accumulata è superiore al valore max_latency. Per ulteriori informazioni, consulta StreamDefinition/StreamInfo (p. 104). • getStreamReadyCallback: segnala una condizione di idoneità del flusso. • getStreamUnderflowReportCallback: segnala una condizione di underflow del flusso. Questa funzione non è attualmente utilizzata ed è riservata a un uso futuro. Per il codice sorgente per StreamCallbackProvider, consulta StreamCallbackProvider.h. Struttura ClientCallbacks La struttura ClientCallbacks contiene i punti di accesso della funzione di callback che il PIC chiama quando si verificano determinati eventi. La struttura, inoltre, contiene le informazioni sulla versione nel campo CALLBACKS_CURRENT_VERSION e un campo customData per i dati definiti dall'utente che vengono restituiti con le singole funzioni di callback. 116 Amazon Kinesis Video Streams Guida per gli sviluppatori Callback L'applicazione client può utilizzare un puntatore this per il campo custom_data per mappare le funzioni membro per le funzioni statiche ClientCallback in fase di runtime, come mostra il seguente codice di esempio: STATUS TestStreamCallbackProvider::streamClosedHandler(UINT64 custom_data, STREAM_HANDLE stream_handle, UINT64 stream_upload_handle) { LOG_INFO("Reporting stream stopped."); TestStreamCallbackProvider* streamCallbackProvider = reinterpret_cast Events Funzione Descrizione Type (Tipo) CreateDeviceFunc Non attualmente implementato API di back-end nel back-end. Questa chiamata ha esito negativo quando viene effettuata da Java o C++. Altri client eseguono l'inizializzazione specifica per piattaforma. CreateStreamFunc Chiamata al momento della API di back-end creazione del flusso DescribeStreamFunc Chiamata con API di back-end DescribeStream. GetStreamingEndpointFunc Chiamata con API di back-end GetStreamingEndpoint. GetStreamingTokenFunc Chiamata con API di back-end GetStreamingToken. PutStreamFunc Chiamata con PutStream. API di back-end TagResourceFunc Chiamata con TagResource. API di back-end CreateMutexFunc Crea un mutex per la Sincronizzazione sincronizzazione. FreeMutexFunc Libera il mutex. Sincronizzazione LockMutexFunc Blocca il mutex di Sincronizzazione sincronizzazione. TryLockMutexFunc Tenta di bloccare il mutex. Non Sincronizzazione attualmente implementato. UnlockMutexFunc Sblocca il mutex. Sincronizzazione ClientReadyFunc Viene chiamato quando il client Notification entra nello stato pronto. DroppedFrameReportFunc Segnala quando un fotogramma Notification viene interrotto. 117 Amazon Kinesis Video Streams Guida per gli sviluppatori Callback Funzione Descrizione Type (Tipo) DroppedFragmentReportFunc Segnala quando un frammento Notification viene interrotto. Questa funzione non è attualmente utilizzata ed è riservata a un uso futuro. FragmentAckReceivedFunc Viene chiamato quando viene Notification ricevuto un frammento ACK (buffering, ricevuto, persistente e di errore). StorageOverflowPressureFuncChiamato quando l'utilizzo dello Notification storage è al di sotto del valore STORAGE_PRESSURE_NOTIFICATION_THRESHOLD, pari al 5% delle dimensioni dello spazio di archiviazione generale. StreamClosedFunc Chiamato quando vengono Notification trasmessi gli ultimi bit dei fotogrammi rimanenti. StreamConnectionStaleFunc Chiamato quando il flusso entra Notification in uno stato di connessione obsoleto. In questa condizione, il produttore invia dati al servizio, ma non riceve conferme. StreamDataAvailableFunc Chiamato quando sono Notification disponibili i dati di flusso. StreamErrorReportFunc Chiamato quando si verifica un Notification errore di flusso. Il PIC chiude automaticamente il flusso in questa condizione. StreamLatencyPressureFunc Chiamato quando il flusso entra Notification in una condizione di latenza, quando la dimensione del buffer accumulata è superiore al valore max_latency. Per ulteriori informazioni, consulta StreamDefinition/ StreamInfo (p. 104). StreamReadyFunc Viene chiamato quando il flusso Notification entra nello stato pronto. StreamUnderflowReportFunc Questa funzione non è Notification attualmente utilizzata ed è riservata a un uso futuro. DeviceCertToTokenFunc Restituisce il certificato di Integrazione con la piattaforma connessione come token. GetCurrentTimeFunc Restituisce l'orario attuale. Integrazione con la piattaforma 118 Amazon Kinesis Video Streams Guida per gli sviluppatori Callback Funzione Descrizione Type (Tipo) GetDeviceCertificateFunc Restituisce il certificato del Integrazione con la piattaforma dispositivo. Questa funzione non è attualmente utilizzata ed è riservata a un uso futuro. GetDeviceFingerprintFunc Restituisce l'impronta del Integrazione con la piattaforma dispositivo. Questa funzione non è attualmente utilizzata ed è riservata a un uso futuro. GetRandomNumberFunc Restituisce un numero casuale Integrazione con la piattaforma compreso tra 0 e RAND_MAX. GetSecurityTokenFunc Restituisce il token di sicurezza Integrazione con la piattaforma passato alle funzioni che comunicano con le API di back-end. L'implementazione è in grado di specificare i AccessKeyId e SecretKeyId serializzati e il token della sessione. LogPrintFunc Registra una riga di testo con Integrazione con la piattaforma il tag e il livello di log. Per ulteriori informazioni, consulta PlatformUtils.h. Per le funzioni di integrazione della piattaforma nella tabella precedente, l'ultimo parametro è una struttura ServiceCallContext, che include i campi riportati di seguito: • version: la versione della strut. • callAfter: un tempo assoluto dopo il quale per chiamare la funzione. • timeout: il timeout dell'operazione in unità di 100 nanosecondi. • customData: un valore definito dall'utente da passare al client. • pAuthInfo: le credenziali per la chiamata. Per maggiori informazioni, consultare la seguente struttura (__AuthInfo). Le informazioni di autorizzazione vengono fornite utilizzando la struttura __AuthInfo che può essere credenziali serializzate o un token di autenticazione specifico del provider. Questa struttura include i campi riportati di seguito: • version: la versione della __AuthInfo struttura. • type: un valore AUTH_INFO_TYPE che definisce il tipo di credenziale (certificato o token di sicurezza). • data: un array di byte contenente le informazioni di autenticazione. • size: la dimensione del data parametro. • expiration: la scadenza delle credenziali in unità di 100 nanosecondi. 119 Amazon Kinesis Video Streams Guida per gli sviluppatori Callback Implementazioni di callback per riprovare lo streaming Kinesis Video Producer SDK fornisce lo stato dello streaming tramite le funzioni di callback. È consigliabile implementare i seguenti meccanismi di callback per il ripristino da eventuali problemi di rete momentanei riscontrati durante lo streaming. • Callback di utilizzo della latenza del flusso: questo meccanismo di callback viene attivato quando l'SDK rileva una condizione di latenza del flusso. Ciò accade quando la dimensione del buffer accumulato è maggiore del valore MAX_LATENCY. Quando il flusso viene creato, l'applicazione di streaming imposta MAX_LATENCY sul valore predefinito di 60 secondi. L'implementazione tipica per questo callback è il ripristino della connessione. Puoi usare l'implementazione di esempio all'indirizzo https://github.com/ awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/blob/master/kinesis-video-c-producer/src/ source/StreamLatencyStateMachine.c in base alle esigenze. Tieni presente che non esiste alcuna opzione per archiviare i frame non consegnati a causa di un'interruzione della rete in uno storage secondario per il back-fill. • Callback di obsolescenza del flusso: questo callback viene attivato quando il produttore può inviare dati al servizio AWS KVS (uplink) ma non è in grado di recuperare le conferme (ACK con buffer) nel tempo (l'impostazione predefinita è di 60 secondi). A seconda delle impostazioni di rete, può essere attivato il callback di utilizzo della latenza del flusso o il callback di obsolescenza del flusso o entrambi. Analogamente all'implementazione del nuovo tentativo di callback di utilizzo della latenza del flusso, l'implementazione tipica consiste nel ripristinare la connessione e avviare una nuova connessione per lo streaming. Puoi usare l'implementazione di esempio all'indirizzo https://github.com/awslabs/amazon- kinesis-video-streams-producer-c/blob/master/src/source/ConnectionStaleStateMachine.c in base alle esigenze. • Callback errore di flusso: questo callback viene attivato quando l'SDK rileva un timeout sulla connessione di rete o altri errori durante la chiamata alle chiamate del servizio API KVS. • Callback del frame interrotto: questo callback viene attivato quando la dimensione di storage è piena a causa di una velocità di rete lenta o di un errore di flusso. Se la velocità della rete determina l'interruzione dei frame, puoi aumentare la dimensione dello storage, ridurre la dimensione o la frequenza dei frame video in modo che corrisponda alla velocità della rete. 120 Amazon Kinesis Video Streams Guida per gli sviluppatori Procedura: utilizzo della libreria parser del flusso video Kinesis Libreria parser del flusso video Kinesis La libreria parser del flusso video Kinesis comprende una serie di strumenti intuitivi che puoi utilizzare nelle applicazioni Java per utilizzare i dati MKV in un Kinesis video stream. La libreria include gli strumenti seguenti: • StreamingMkvReader (p. 122): questa classe legge gli elementi MKV specificati da un flusso video. • FragmentMetadataVisitor (p. 123): questa classe recupera i metadati relativi ai frammenti (elementi multimediali) e alle tracce (singoli flussi di dati che contengono informazioni multimediali, ad esempio audio o sottotitoli). • OutputSegmentMerger (p. 124): questa classe unisce frammenti consecutivi o blocchi in un flusso video. • KinesisVideoExample (p. 125): questa è un'applicazione di esempio che illustra come utilizzare la libreria parser del flusso video Kinesis. La libreria include inoltre dei test che illustrano come vengono utilizzati gli strumenti. Procedura: utilizzo della libreria parser del flusso video Kinesis Questa procedura include le fasi seguenti: • the section called “Fase 1: download e configurazione del codice” (p. 122) • the section called “Fase 2: scrittura e analisi del codice” (p. 122) • the section called “Fase 3: esecuzione e verifica del codice” (p. 127) Prerequisiti Occorre disporre degli elementi seguenti per esaminare e utilizzare la libreria parser del flusso video Kinesis: • Un account Amazon Web Services (AWS). Se non hai ancora un account AWS, procedi come segue: • Aprire https://aws.amazon.com/, quindi scegliere Create an AWS Account (Crea un account AWS). Note Tale opzione potrebbe non essere disponibile nel browser se in precedenza è stato effettuato l'accesso alla AWS Management Console. In tal caso, scegliere Sign in to the Console (Accedi alla console) e Create a new AWS account (Crea un nuovo account AWS). • Seguire le istruzioni online. Come parte della procedura di registrazione si riceverà una telefonata, durante la quale si dovrà inserire un PIN usando la tastiera del telefono. 121 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 1: download e configurazione del codice Annotare l'ID dell'account AWS perché sarà necessario per configurare l'accesso programmatico ai Kinesis video stream. • Un ambiente di sviluppo integrato (IDE) Java, come Eclipse Java Neon o JetBrains IntelliJ Idea. Fase 1: download e configurazione del codice In questa sezione, potrai scaricare la libreria Java, testare il codice e importare il progetto nell'IDE Java. Per i prerequisiti e altri dettagli su questa procedura, consulta Libreria parser del flusso (p. 121). 1. Crea una directory e clona il codice sorgente della libreria dal repository di GitHub (https://github.com/ aws/amazon-kinesis-video-streams-parser-library). $ git clone https://github.com/aws/amazon-kinesis-video-streams-parser-library 2. Aprire l'IDE Java in uso (ad esempio Eclipse o IntelliJ IDEA) e importare il progetto Apache Maven scaricato: • In Eclipse: scegliere File, Import (Importa), Maven, Existing Maven Projects (Progetti Maven esistenti) e accedere alla cartella kinesis-video-streams-parser-lib. • In IntelliJ Idea: scegliere Import (Importa). Andare al file pom.xml nella radice del pacchetto scaricato. Per ulteriori informazioni, consulta la documentazione IDE correlata. Fase successiva the section called “Fase 2: scrittura e analisi del codice” (p. 122) Fase 2: scrittura e analisi del codice In questa sezione, puoi esaminare la libreria Java, testare il codice e scoprire come utilizzare gli strumenti della libreria nel codice. La libreria parser del flusso video Kinesis contiene i seguenti strumenti: • StreamingMkvReader (p. 122) • FragmentMetadataVisitor (p. 123) • OutputSegmentMerger (p. 124) • KinesisVideoExample (p. 125) StreamingMkvReader Questa classe legge gli elementi MKV specificati da un flusso in modalità senza blocchi. L'esempio di codice seguente (da FragmentMetadataVisitorTest) mostra come creare e utilizzare un Streaming MkvReader per recuperare gli oggetti MkvElement da un flusso di input chiamato inputStream: 122 Amazon Kinesis Video Streams Guida per gli sviluppatori FragmentMetadataVisitor StreamingMkvReader mkvStreamReader = StreamingMkvReader.createDefault(new InputStreamParserByteSource(inputStream)); while (mkvStreamReader.mightHaveNext()) { Optional FragmentMetadataVisitor Questa classe recupera i metadati relativi ai frammenti (elementi multimediali) e alle tracce (singoli flussi di dati che contengono informazioni multimediali, ad esempio dati privati del codec, larghezza o altezza dei pixel). L'esempio di codice seguente (dal file FragmentMetadataVisitorTest) illustra come utilizzare FragmentMetadataVisitor per recuperare i dati da un oggetto MkvElement: FragmentMetadataVisitor fragmentVisitor = FragmentMetadataVisitor.create(); StreamingMkvReader mkvStreamReader = StreamingMkvReader.createDefault(new InputStreamParserByteSource(in)); int segmentCount = 0; while(mkvStreamReader.mightHaveNext()) { Optional } L'esempio precedente mostra i seguenti modelli di codifica: • Creare un FragmentMetadataVisitor per analizzare i dati e un StreamingMkvReader (p. 122) per inserire i dati. • Per ogni MkvElement nel flusso, verificare se i relativi metadati sono di tipo SIMPLEBLOCK. • Se sì, recuperare il MkvDataElement dal MkvElement. 123 Amazon Kinesis Video Streams Guida per gli sviluppatori OutputSegmentMerger • Recuperate il Frame (dati multimediali) dal MkvDataElement. • Recuperare il MkvTrackMetadata relativo al Frame dal FragmentMetadataVisitor. • Recuperare e verificare i dati seguenti dagli oggetti Frame e MkvTrackMetadata: • Il numero di traccia. • L'altezza dei pixel del fotogramma. • La larghezza dei pixel del fotogramma. • L'ID codec relativo al codec utilizzato per la codifica del fotogramma. • L'arrivo del fotogramma nell'ordine corretto. Ovvero, verificare che il numero di traccia del fotogramma precedente, se presente, sia inferiore a quello del fotogramma corrente. Per utilizzare FragmentMetadataVisitor nel progetto, inviare gli oggetti MkvElement al visitatore tramite il relativo metodo accept: mkvElement.get().accept(fragmentVisitor); OutputSegmentMerger Questa classe unisce i metadati di diverse tracce del flusso in un flusso con un singolo segmento. L'esempio di codice seguente (dal file FragmentMetadataVisitorTest) illustra come utilizzare OutputSegmentMerger per unire i metadati della traccia da un array di byte chiamato inputBytes: FragmentMetadataVisitor fragmentVisitor = FragmentMetadataVisitor.create(); ByteArrayOutputStream outputStream = new ByteArrayOutputStream(); OutputSegmentMerger outputSegmentMerger = OutputSegmentMerger.createDefault(outputStream); CompositeMkvElementVisitor compositeVisitor = new TestCompositeVisitor(fragmentVisitor, outputSegmentMerger); final InputStream in = TestResourceUtil.getTestInputStream("output_get_media.mkv"); StreamingMkvReader mkvStreamReader = StreamingMkvReader.createDefault(new InputStreamParserByteSource(in)); while (mkvStreamReader.mightHaveNext()) { Optional L'esempio precedente mostra i seguenti modelli di codifica: • Creare un FragmentMetadataVisitor (p. 123)per recuperare i metadati dal flusso. • Creare un flusso di output per ricevere i metadati uniti. 124 Amazon Kinesis Video Streams Guida per gli sviluppatori KinesisVideoExample • Creare un OutputSegmentMerger, tramite l'invio del ByteArrayOutputStream. • Creare un CompositeMkvElementVisitor contenente i due visitatori. • Creare un InputStream che punti al file specificato. • Unire ciascun elemento nei dati di input nel flusso di output. KinesisVideoExample Questa è un'applicazione di esempio che illustra come utilizzare la libreria parser del flusso video Kinesis. Questa classe effettua le seguenti operazioni: • Crea un Kinesis video stream. Se un flusso con il nome specificato è già esistente, tale flusso verrà eliminato e ricreato. • Richiama PutMedia per effettuare lo streaming dei frammenti video sul Kinesis video stream. • Richiama GetMedia per effettuare lo streaming dei frammenti video al di fuori del Kinesis video stream. • Utilizza un StreamingMkvReader (p. 122) per analizzare i frammenti restituiti sul flusso e un FragmentMetadataVisitor (p. 123) per registrare i frammenti. Eliminazione e nuova creazione del flusso L'esempio di codice seguente (dal file StreamOps.java) elimina un determinato Kinesis video stream: //Delete the stream amazonKinesisVideo.deleteStream(new DeleteStreamRequest().withStreamARN(streamInfo.get().getStreamARN())); L'esempio di codice seguente (dal file StreamOps.java) crea un Kinesis video stream con il nome specificato: amazonKinesisVideo.createStream(new CreateStreamRequest().withStreamName(streamName) .withDataRetentionInHours(DATA_RETENTION_IN_HOURS) .withMediaType("video/h264")); Chiamate a PutMedia L'esempio di codice seguente (dal file PutMediaWorker.java) richiama PutMedia sul flusso: putMedia.putMedia(new PutMediaRequest().withStreamName(streamName) .withFragmentTimecodeType(FragmentTimecodeType.RELATIVE) .withProducerStartTimestamp(new Date()) .withPayload(inputStream), new PutMediaAckResponseHandler() { ... }); Chiamate a GetMedia L'esempio di codice seguente (dal file GetMediaWorker.java) richiama GetMedia sul flusso: GetMediaResult result = videoMedia.getMedia(new GetMediaRequest().withStreamName(streamName).withStartSelector(startSelector)); 125 Amazon Kinesis Video Streams Guida per gli sviluppatori KinesisVideoExample Analisi dei risultati GetMedia In questa sezione viene descritto come utilizzare StreamingMkvReader (p. 122), FragmentMetadataVisitor (p. 123) e CompositeMkvElementVisitor per analizzare, salvare sul file e registrare i dati restituiti da GetMedia. Lettura dell'output di GetMedia con StreamingMkvReader L'esempio di codice seguente (dal file GetMediaWorker.java) crea un StreamingMkvReader (p. 122) e lo utilizza per analizzare i risultati dell'operazione GetMedia: StreamingMkvReader mkvStreamReader = StreamingMkvReader.createDefault(new InputStreamParserByteSource(result.getPayload())); log.info("StreamingMkvReader created for stream {} ", streamName); try { mkvStreamReader.apply(this.elementVisitor); } catch (MkvElementVisitException e) { log.error("Exception while accepting visitor {}", e); } Nell'esempio di codice precedente, il StreamingMkvReader (p. 122) recupera gli oggetti MKVElement dal payload dei risultati GetMedia. Nella sezione successiva, gli elementi vengono inviati a un FragmentMetadataVisitor (p. 123). Recupero dei frammenti con FragmentMetadataVisitor Gli esempi di codice seguenti (dai file KinesisVideoExample.java e StreamingMkvReader.java) creano un FragmentMetadataVisitor (p. 123). Gli oggetti MkvElement iterati dal StreamingMkvReader (p. 122) vengono quindi inviati al visitatore tramite il metodo accept. da KinesisVideoExample.java: FragmentMetadataVisitor fragmentMetadataVisitor = FragmentMetadataVisitor.create(); da StreamingMkvReader.java: if (mkvElementOptional.isPresent()) { //Apply the MkvElement to the visitor mkvElementOptional.get().accept(elementVisitor); } Registrazione degli elementi e scrittura in un file L'esempio di codice seguente (dal file KinesisVideoExample.java) crea gli oggetti seguenti e li restituisce come parte del valore restituito della funzione GetMediaProcessingArguments: • Un LogVisitor (un'estensione di MkvElementVisitor) che effettua la scrittura nel log di sistema. • Un OutputStream che scrive i dati in entrata su un file MKV. • Un BufferedOutputStream che effettua il buffer dei dati associati all'OutputStream. • Un the section called “OutputSegmentMerger” (p. 124) che unisce gli elementi consecutivi nel risultato GetMedia con la stessa traccia e gli stessi dati EBML. • Un CompositeMkvElementVisitor che compone il FragmentMetadataVisitor (p. 123), l'the section called “OutputSegmentMerger” (p. 124)e il LogVisitor in un singolo visitatore di elemento 126 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase successiva //A visitor used to log as the GetMedia stream is processed. LogVisitor logVisitor = new LogVisitor(fragmentMetadataVisitor); //An OutputSegmentMerger to combine multiple segments that share track and ebml metadata into one //mkv segment. OutputStream fileOutputStream = Files.newOutputStream(Paths.get("kinesis_video_example_merged_output2.mkv"), StandardOpenOption.WRITE, StandardOpenOption.CREATE); BufferedOutputStream outputStream = new BufferedOutputStream(fileOutputStream); OutputSegmentMerger outputSegmentMerger = OutputSegmentMerger.createDefault(outputStream); //A composite visitor to encapsulate the three visitors. CompositeMkvElementVisitor mkvElementVisitor = new CompositeMkvElementVisitor(fragmentMetadataVisitor, outputSegmentMerger, logVisitor); return new GetMediaProcessingArguments(outputStream, logVisitor, mkvElementVisitor); Gli argomenti di elaborazione degli elementi multimediali vengono quindi inviati al GetMediaWorker, che viene a sua volta inviato all'ExecutorService che esegue il lavoratore su un thread separato: GetMediaWorker getMediaWorker = GetMediaWorker.create(getRegion(), getCredentialsProvider(), getStreamName(), new StartSelector().withStartSelectorType(StartSelectorType.EARLIEST), amazonKinesisVideo, getMediaProcessingArgumentsLocal.getMkvElementVisitor()); executorService.submit(getMediaWorker); Fase successiva the section called “Fase 3: esecuzione e verifica del codice” (p. 127) Fase 3: esecuzione e verifica del codice La libreria parser del flusso video Kinesis contiene strumenti concepiti per l'uso nei propri progetti. Il progetto contiene test di unità degli strumenti che puoi eseguire per verificare l'installazione. Nella libreria sono inclusi i seguenti test di unità: • mkv • ElementSizeAndOffsetVisitorTest • MkvValueTest • StreamingMkvReaderTest • utilities • FragmentMetadataVisitorTest • OutputSegmentMergerTest 127 Amazon Kinesis Video Streams Guida per gli sviluppatori Esempi: invio di dati a Kinesis Video Streams Amazon Kinesis Video StreamsEsempi di I seguenti esempi di codice illustrano come lavorare con le API Kinesis Video Streams Esempi: invio di dati a Kinesis Video Streams • Esempio: plugin Kinesis Video Streams dell'SDK del producerGStreamer (p. 129): mostra come creare l'SDK di Kinesis Video Streams Producer da utilizzare come destinazione GStreamer. • Esecuzione dell'elemento GStreamer in un container Docker (p. 132): mostra come usare un'immagine Docker preconfigurata e inviare un video RTSP da una videocamera IP a Kinesis Video Streams. • Esempio streaming da un'origine RTSP (p. 141): mostra come creare un'immagine Docker propria e inviare un video RTSP da una videocamera IP a Kinesis Video Streams. • Esempio: invio di dati a Kinesis Video Streams tramite l'APIPutMedia (p. 138) : mostra come utilizzare Utilizzo di Java Producer Library (p. 47) per inviare dati a Kinesis Video Streams che è già in un formato container (MKV) utilizzando l'API PutMedia. Esempi: recupero dei dati da Kinesis Video Streams • KinesisVideoExample (p. 125): viene illustrato come analizzare e registrare frammenti video utilizzando Kinesis Video Streams Parser Library. • Esempio: analisi e rendering dei frammenti Kinesis Video Streams (p. 142) : mostra come analizzare ed eseguire il rendering dei frammenti Kinesis video stream utilizzando JCodec e JFrame. • the section called “SageMaker” (p. 144): illustra una soluzione che utilizza SageMaker per determinare quando determinati oggetti appaiono in un flusso video. Esempi: riproduzione di dati video • Esempio: uso di HLS in HTML e JavaScript (p. 10): mostra come recuperare una sessione di streaming HLS per un Kinesis video stream e riprodurlo in una pagina Web. Prerequisites • Nel codice di esempio, è necessario fornire le credenziali specificando un profilo impostato nel file del profilo delle credenziali AWS oppure le credenziali riportate nelle proprietà del sistema Java dell'ambiente di sviluppo integrato (IDE). Se non lo hai già fatto, configura prima le credenziali. Per ulteriori informazioni, consulta la sezione Configurazione della regione e delle credenziali AWS per lo sviluppo. • Per visualizzare ed eseguire il codice, ti consigliamo di utilizzare un IDE Java, come uno dei seguenti: • Eclipse Java Neon 128 Amazon Kinesis Video Streams Guida per gli sviluppatori GStreamer • JetBrains IntelliJ IDE Esempio: plugin Kinesis Video Streams dell'SDK del producerGStreamer Questo argomento mostra come creare l'SDK di Amazon Kinesis Video Streams Producer da utilizzare come plugin GStreamer. Argomenti • Scaricare, creare e configurare l'elementoGStreamer (p. 130) • Esecuzione dell'elementoGStreamer (p. 130) • Comandi di avvio GStreamer di esempio (p. 130) • Esecuzione dell'elemento GStreamer in un container Docker (p. 132) • Riferimento ai parametri degli elementiGStreamer (p. 135) GStreamer è un framework multimediale diffuso utilizzato da numerose videocamere e origini video per creare pipeline multimediali personalizzate mediante la combinazione di plugin modulari. Il plugin Kinesis Video Streams GStreamer semplifica notevolmente l'integrazione della pipeline multimediale GStreamer esistente con Kinesis Video Streams. Dopo l'integrazione di GStreamer, puoi iniziare a utilizzare lo streaming di video da una webcam o da una videocamera RTSP (Real Time Streaming Protocol) a Kinesis Video Streams per la riproduzione in tempo reale o successiva, lo storage e ulteriori analisi. Il plugin GStreamer gestisce automaticamente il trasferimento del flusso video a Kinesis Video Streams incapsulando la funzionalità fornita dall'SDK di Kinesis Video Streams Producer in un elemento sink GStreamer, kvssink. Il framework GStreamer fornisce un ambiente gestito standard per la costruzione di flussi multimediali da un dispositivo, ad esempio una videocamera o altre origini video per ulteriori elaborazioni, rendering o storage. La pipeline GStreamer in genere è costituita dal collegamento tra un'origine (videocamera) e l'elemento sink (un lettore per il rendering del video o lo storage per il recupero offline). In questo esempio, si utilizza l'elemento SDK Producer come sink o destinazione multimediale per l'origine video (webcam o videocamera IP). L'elemento plugin che incapsula l'SDK gestisce quindi l'invio del flusso video a Kinesis Video Streams. Questo argomento mostra come creare una pipeline multimediale GStreamer in grado di eseguire lo streaming video da una sorgente video, ad esempio una webcam o un flusso RTSP, in genere connessa tramite fasi di codifica intermedi (usando la codifica H.264) a Kinesis Video Streams. Quando il flusso video è disponibile come Kinesis video stream, è possibile utilizzare la Kinesis Video Stream Parser Library per ulteriori elaborazioni, per la riproduzione, lo storage o l'analisi del flusso video. 129 Amazon Kinesis Video Streams Guida per gli sviluppatori Scaricare, creare e configurare l'elementoGStreamer Scaricare, creare e configurare l'elementoGStreamer Il plugin di esempio GStreamer è incluso in C++ Producer SDK Kinesis Video Streams. Per informazioni sui prerequisiti e il download di SDK consulta Fase 1: download e configurazione del codice di C++ Producer Library (p. 59). È possibile creare il sink GStreamer dell'SDK Producer come libreria dinamica su macOS, Ubuntu, Raspberry Pi o Windows. Il plugin GStreamer si trova nella directory build. Per caricare questo plugin, deve trovarsi nel tuo GST_PLUGIN_PATH. Eseguire il comando seguente: export GST_PLUGIN_PATH=`pwd`/build Esecuzione dell'elementoGStreamer Per eseguire GStreamer con l'elemento Kinesis Video Streams Producer SDK come sink, eseguire il comando gst-launch-1.0. Utilizza le impostazioni appropriate per il plugin GStreamer da utilizzare. Ad esempio, v4l2src per dispositivi v4l2 su sistemi Linux o rtspsrc per dispositivi RTSP. Specificare kvssink come sink (destinazione finale della pipeline) per inviare video all'SDK Producer. L'elemento kvssink richiede i seguenti parametri: • stream-name: il nome della destinazione Kinesis video stream. • storage-size: la dimensione dello storage del dispositivo in kilobyte. Per informazioni sulla configurazione dello storage del dispositivo, consulta StorageInfo (p. 103). • access-key: la chiave di accesso AWS utilizzata per accedere a Kinesis Video Streams. È necessario fornire questo parametro o credential-path. • secret-key: la chiave segreta AWS utilizzata per accedere a Kinesis Video Streams. È necessario fornire questo parametro o credential-path. • credential-path: il percorso a un file contenente le credenziali di accesso a Kinesis Video Streams. Per ulteriori informazioni sulle credenziali in rotazione, consulta Gestione delle chiavi di accesso per gli utenti IAM. È necessario fornire questo parametro o access-key e secret-key. Per informazioni sui kvssink parametri opzionali consulta Riferimento ai parametri degli elementiGStreamer (p. 135). Per le informazioni più recenti su plugin e parametri GStreamer, consulta GStreamerPlugin oppure esegui il comando seguente per elencare le opzioni: gst-inspect-1.0 kvssink Se la compilazione non è riuscita o GST_PLUGIN_PATH non è impostato correttamente, l'output è simile a quanto segue: No such element or plugin 'kvssink' Comandi di avvio GStreamer di esempio Questi esempi illustrano come utilizzare un plugin GStreamer per lo streaming di video da diversi tipi di dispositivi. 130 Amazon Kinesis Video Streams Guida per gli sviluppatori Comandi di avvio Esempio 1: flussi video da una videocamera RTSP su Ubuntu Il comando seguente crea una pipeline GStreamer su Ubuntu che esegue lo streaming da una videocamera RTSP di rete, utilizzando il plugin rtspsrc GStreamer: $ gst-launch-1.0 rtspsrc location="rtsp://YourCameraRtspUrl" short-header=TRUE ! rtph264depay ! video/x-h264, format=avc,alignment=au ! kvssink stream- name="YourStreamName" storage-size=512 access-key="YourAccessKey" secret- key="YourSecretKey" aws-region="YourAWSRegion" Esempio 2: eseguire la codifica e i flussi video da una videocamera USB su Ubuntu Il comando seguente crea una pipeline GStreamer su Ubuntu che codifica il flusso da una videocamera USB in formato H.264 e lo trasmette a Kinesis Video Streams. Questo esempio utilizza il plugin v4l2src.GStreamer $ gst-launch-1.0 v4l2src do-timestamp=TRUE device=/dev/video0 ! videoconvert ! video/ x-raw,format=I420,width=640,height=480,framerate=30/1 ! x264enc bframes=0 key-int- max=45 bitrate=500 ! video/x-h264,stream-format=avc,alignment=au,profile=baseline ! kvssink stream-name="YourStreamName" storage-size=512 access-key="YourAccessKey" secret- key="YourSecretKey" aws-region="YourAWSRegion" Esempio 3: eseguire la precodifica video da una videocamera USB su Ubuntu Il comando seguente crea una pipeline GStreamer su Ubuntu che esegue lo streaming del video già codificato dalla fotocamera in formato H.264 su Kinesis Video Streams. Questo esempio utilizza il plugin v4l2src.GStreamer $ gst-launch-1.0 v4l2src do-timestamp=TRUE device=/dev/video0 ! h264parse ! video/x- h264,stream-format=avc,alignment=au ! kvssink stream-name="plugin" storage-size=512 access- key="YourAccessKey" secret-key="YourSecretKey" aws-region="YourAWSRegion" Esempio 4: video in streaming da una videocamera di rete sumacOS Il comando seguente crea una pipeline GStreamer su macOS che esegue lo streaming video su Kinesis Video Streams da una videocamera di rete. Questo esempio utilizza il plugin rtspsrc.GStreamer $ gst-launch-1.0 rtspsrc location="rtsp://YourCameraRtspUrl" short-header=TRUE ! rtph264depay ! video/x-h264, format=avc,alignment=au ! kvssink stream- name="YourStreamName" storage-size=512 access-key="YourAccessKey" secret- key="YourSecretKey" aws-region="YourAWSRegion" Esempio 5: video in streaming da una videocamera di rete su Windows Il comando seguente crea una pipeline GStreamer su Windows che esegue lo streaming video su Kinesis Video Streams da una videocamera di rete. Questo esempio utilizza il plugin rtspsrc.GStreamer $ gst-launch-1.0 rtspsrc location="rtsp://YourCameraRtspUrl" short-header=TRUE ! rtph264depay ! video/x-h264, format=avc,alignment=au ! kvssink stream- 131 Amazon Kinesis Video Streams Guida per gli sviluppatori Esecuzione dell'elemento GStreamer in un container Docker name="YourStreamName" storage-size=512 access-key="YourAccessKey" secret- key="YourSecretKey" aws-region="YourAWSRegion" Esempio 6: video in streaming da una videocamera su Raspberry Pi Il comando seguente crea una pipeline GStreamer su Raspberry Pi che esegue lo streaming video su Kinesis Video Streams. Questo esempio utilizza il plugin v4l2src.GStreamer $ gst-launch-1.0 v4l2src do-timestamp=TRUE device=/dev/video0 ! videoconvert ! video/x- raw,format=I420,width=640,height=480,framerate=30/1 ! omxh264enc control-rate=1 target- bitrate=5120000 periodicity-idr=45 inline-header=FALSE ! h264parse ! video/x-h264,stream- format=avc,alignment=au,width=640,height=480,framerate=30/1,profile=baseline ! kvssink stream-name="YourStreamName" frame-timestamp=dts-only access-key="YourAccessKey" secret- key="YourSecretKey" aws-region="YourAWSRegion" Esempio 7: streaming di video da una videocamera su Raspberry Pi e regione specifica Il comando seguente crea una pipeline GStreamer su Raspberry Pi che esegue lo streaming video su Kinesis Video Streams nella regione US East (N. Virginia). Questo esempio utilizza il plugin v4l2src.GStreamer $ gst-launch-1.0 v4l2src do-timestamp=TRUE device=/dev/video0 ! videoconvert ! video/x- raw,format=I420,width=640,height=480,framerate=30/1 ! omxh264enc control-rate=1 target- bitrate=5120000 periodicity-idr=45 inline-header=FALSE ! h264parse ! video/x-h264,stream- format=avc,alignment=au,width=640,height=480,framerate=30/1,profile=baseline ! kvssink stream-name="YourStreamName" frame-timestamp=dts-only access-key="YourAccessKey" secret- key="YourSecretKey" aws-region="YourAWSRegion" Esempio 8: flussi audio e video in Raspberry-PI e Ubuntu Scopri come eseguire il comando gst-launch-1.0 per avviare lo streaming audio e video in Raspberry-PI e Ubuntu. Esempio 9: flussi audio e video in MacOS Scopri come eseguire il comando gst-launch-1.0 per avviare lo streaming audio e video in MacOS. Esempio 10: caricamento del file MKV che contiene sia audio che video Scopri come eseguire il comando gst-launch-1.0 per caricare il file MKV che contiene sia audio che video. Esecuzione dell'elemento GStreamer in un container Docker Docker è una piattaforma per sviluppare, distribuire ed eseguire le applicazioni utilizzando i contenitori. L'utilizzo di Docker per creare la pipeline GStreamer standardizza l'ambiente operativo per Kinesis Video Streams, semplificando notevolmente la creazione e l'esecuzione dell'applicazione. Per installare e configurare Docker, consulta le seguenti informazioni: 132 Amazon Kinesis Video Streams Guida per gli sviluppatori Esecuzione dell'elemento GStreamer in un container Docker • Istruzioni di download di Docker • Nozioni di base su Docker Dopo aver installato Docker, è possibile scaricare l'SDK di Kinesis Video Streams C++ Producer (e il plugin GStreamer) da Amazon Elastic Container Registry utilizzando il comando docker pull. Per eseguire GStreamer con l'elemento SDK di Kinesis Video Streams Producer come sink in un container Docker, procedere nel seguente modo: Argomenti • Autenticare il Client Docker (p. 133) • Scaricare l'immagine Docker per Ubuntu, macOS, Windows o Raspberry Pi (p. 133) • Eseguire l'immagine Docker (p. 134) Autenticare il Client Docker Autentica il tuo client Docker nel registro Amazon ECR dal quale desideri estrarre la tua immagine. Devi ottenere i token di autenticazione per ciascun registro utilizzato. I token hanno una validità di 12 ore. Per ulteriori informazioni, consulta l'argomento relativo all'autenticazione del registro nella Guida per l'utente di Amazon Elastic Container Registry. Example : autenticazione con Amazon ECR aws ecr get-login --no-include-email --region us-west-2 --registry-ids 546150905175 Il comando precedente genera un output simile al seguente: docker login -u AWS -p L'output risultante è un comando di login del Docker che serve per autenticare il client Docker nel registro Amazon ECR Scaricare l'immagine Docker per Ubuntu, macOS, Windows o Raspberry Pi Scaricare l'immagine Docker per l'ambiente Docker utilizzando uno dei comandi riportati di seguito, a seconda del sistema operativo in uso: Scaricare l'immagine Docker per Ubuntu sudo docker pull 546150905175.dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk- cpp-amazon-linux:latest Scaricare l'immagine Docker permacOS sudo docker pull 546150905175.dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk- cpp-amazon-linux:latest Scaricare l'immagine Docker per Windows docker pull 546150905175.dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk-cpp- amazon-windows:latest 133 Amazon Kinesis Video Streams Guida per gli sviluppatori Esecuzione dell'elemento GStreamer in un container Docker Scaricare l'immagine Docker per Raspberry Pi sudo docker pull 546150905175.dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk- cpp-raspberry-pi:latest Per verificare che l'immagine sia stata aggiunta, eseguire il comando riportato di seguito: docker images Eseguire l'immagine Docker Utilizzare uno dei seguenti comandi per eseguire l'immagine Docker, a seconda del sistema operativo in uso: Eseguire l'immagine Docker su Ubuntu sudo docker run -it --network="host" --device=/dev/video0 546150905175 .dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk-cpp-amazon-linux /bin/bash Eseguire l'immagine Docker su macOS. sudo docker run -it --network="host" 546150905175.dkr.ecr.us-west-2.amazonaws.com/kinesis- video-producer-sdk-cpp-amazon-linux /bin/bash Eseguire l'immagine Docker su Windows docker run -it 546150905175.dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk-cpp- windows Eseguire l'immagine Docker su Raspberry Pi sudo docker run -it --device=/dev/video0 --device=/dev/vchiq -v /opt/vc:/opt/vc 546150905175 .dkr.ecr.us-west-2.amazonaws.com/kinesis-video-producer-sdk-cpp-raspberry-pi /bin/bash Docker lancia il container e presenta un prompt dei comandi per eseguire i comandi all'interno del contenitore. Nel container, impostare le variabili di ambiente utilizzando il comando seguente: export LD_LIBRARY_PATH=/opt/awssdk/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis- video-native-build/downloads/local/lib:$LD_LIBRARY_PATH export PATH=/opt/awssdk/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis-video-native- build/downloads/local/bin:$PATH export GST_PLUGIN_PATH=/opt/awssdk/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis- video-native-build/downloads/local/lib:$GST_PLUGIN_PATH Avviare lo streaming dalla videocamera utilizzando il comando gst-launch-1.0 appropriato per il dispositivo. Note Su macOS, puoi eseguire lo streaming di video solo da una videocamera di rete quando esegui GStreamer in un container Docker. Lo streaming video da una videocamera USB su macOS in un container Docker non è supportato. 134 Amazon Kinesis Video Streams Guida per gli sviluppatori Parametri del server Per esempi sull'utilizzo del comando gst-launch-1.0 per connettersi a una videocamera Web locale o una videocamera RTSP di rete, consulta Comandi di avvio (p. 130). Riferimento ai parametri degli elementiGStreamer Per inviare video all'SDK di Amazon Kinesis Video Streams Producer, è necessario specificare kvssink come sink o destinazione finale della pipeline. La documentazione di riferimento fornisce informazioni sui parametri kvssink obbligatori e facoltativi. Per ulteriori informazioni, consulta the section called “GStreamer” (p. 129). L'elemento kvssink richiede i seguenti parametri: • stream-name: il nome della destinazione Kinesis video stream. Note Quando si utilizza l'autorizzazione IoT, il valore di stream-name deve essere identico al valore di iot-thingname (in IoT provisioning). Per ulteriori informazioni, consulta Errore "Invalid thing name passed (Passato nome di cosa non valido)" quando si utilizza l'autorizzazione IoT (p. 183). • storage-size: la dimensione di storage del dispositivo in megabyte. Per informazioni sulla configurazione dello storage del dispositivo, consulta StorageInfo (p. 103). • access-key: la chiave di accesso AWS utilizzata per accedere a Kinesis Video Streams. È necessario fornire questo parametro o credential-path. • secret-key: la chiave segreta AWS utilizzata per accedere a Kinesis Video Streams. È necessario fornire questo parametro o credential-path. • credential-path: il percorso a un file contenente le credenziali di accesso a Kinesis Video Streams. È necessario fornire questo parametro o access-key e secret-key. L'elemento kvssink ha i seguenti parametri opzionali. Per ulteriori informazioni su questi parametri, consultare KinesisStrutture di flussi video di (p. 104). Parametro Descrizione Unità/Tipo Impostazione predefinita absolute-fragment- Per scegliere se usare Booleano true times i tempi assoluti del frammento. avg-bandwidth-bps La larghezza di banda Byte al secondo 4194304 media prevista del flusso. aws-region Regione AWS da usare. String us-west-2 buffer-duration Durata del buffer del Secondi 180 flusso. codec-id L'ID del codec del String "V_MPEG4/ISO/AVC" flusso. connection- L'intervallo di tempo Secondi 60 staleness dopo il quale verrà richiamato il callback di obsolescenza del flusso. content-type Il tipo di contenuto del String "video/h264" flusso. 135 Amazon Kinesis Video Streams Guida per gli sviluppatori Parametri del server Parametro Descrizione Unità/Tipo Impostazione predefinita fragment-acks Indica se utilizzare il Booleano true frammento ACKs. fragment-duration La durata del frammento Millisecondi 2000 desiderata. framerate La frequenza Fotogrammi al secondo 25 fotogrammi prevista. frame-timecodes Per scegliere se Booleano true utilizzare i timecode del fotogramma o generare timestamp tramite il callback dell'ora corrente. frame-timestamp • (0): solo pts: Enum default-timestamp per impostare GstKvsSinkFrameTimestampType il timestamp di decodifica (DTS) uguale al timestamp di presentazione (PTS) per ogni fotogramma inviato a Kinesis Video Streams. • (1): solo dts: per impostare il PTS uguale al DTS per ogni fotogramma inviato a Kinesis Video Streams. • (2): default- timestamp: per provare a utilizzare PTS e DTS. Se uno non è disponibile, utilizzare l'altro. key-frame- Per scegliere se Booleano true fragmentation creare frammenti su un fotogramma chiave. log-config Percorso di String "./ configurazione del log. kvs_log_configuration" max-latency La latenza massima del Secondi 60 flusso. recalculate- Per scegliere se Booleano true metrics calcolare nuovamente i parametri. 136 Amazon Kinesis Video Streams Guida per gli sviluppatori Parametri del server Parametro Descrizione Unità/Tipo Impostazione predefinita replay-duration La durata per spostare Secondi 40 all'indietro il lettore corrente per la riproduzione quando si verifica un errore se il riavvio è abilitato. restart-on-error Per scegliere se Booleano true riavviare quando si verifica un errore. retention-period Il periodo di tempo Hours (Ore) 2 in cui il flusso viene conservato. rotation-period Il periodo di rotazione Secondi 2400 delle chiavi. Per ulteriori informazioni, consulta Rotazione delle chiavi master del cliente. streaming-type Tipo di streaming. I Enum 0: tempo reale valori validi includono: GstKvsSinkStreamingType • 0: tempo reale • 1: quasi in tempo reale (non attualmente supportato) • 2: offline (attualmente non supportato) timecode-scale La dimensione del Millisecondi 1 timecode MKV. track-name Il nome della traccia String "kinesis_video" MKV. iot-certificate Credenziali IoT da String Nessuna utilizzare nell'elemento kvssink. Accetta le seguenti chiavi e valori: • endpoint=iotcredentialsproviderendpoint • cert-path=/ localdirectorypath /to/ certificate • key-path=/ localdirectorypath /to/ private/key • ca-path=/ localdirectorypath/to/ ca-cert • role-aliases=role- aliases 137 Amazon Kinesis Video Streams Guida per gli sviluppatori APIPutMedia Esempio: invio di dati a Kinesis Video Streams tramite l'APIPutMedia Questo esempio illustra come utilizzare l'API PutMedia. Viene illustrato come inviare i dati che si trovano già nel formato container (MKV). Se i dati devono essere assemblati in un formato container prima dell'invio (ad esempio, se stai assemblando i dati della videocamera in fotogrammi), consulta Kinesis Video Streams Producer Library (p. 46). Note L'operazione PutMedia è disponibile solo in C++ e Java SDKs, a causa della gestione full-duplex di connessioni, flusso di dati e conferme. Non è supportata in altri linguaggi. Questo esempio include le fasi seguenti: • Fase 1: download e configurazione del codice (p. 138) • Fase 2: scrittura e analisi del codice (p. 139) • Fase 3: esecuzione e verifica del codice (p. 140) Fase 1: download e configurazione del codice In questa sezione, potrai scaricare il codice di esempio Java, importare il progetto nell'IDE Java, configurare i percorsi della libreria e configurare il codice per utilizzare le credenziali AWS. 1. Creare una directory e clonare il codice di origine di esempio dal repository GitHub. L'esempio PutMedia è parte della Java Producer Library (p. 47). $ git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java 2. Aprire l'IDE Java in uso (ad esempio, Eclipse o IntelliJ IDEA) e importare il progetto Apache Maven scaricato: • In Eclipse: scegliere File, Import (Importa), Maven, Existing Maven Projects (Progetti Maven esistenti) e andare alla radice del pacchetto scaricato. Selezionare il file pom.xml • In IntelliJ Idea: scegliere Import (Importa). Andare al file pom.xml nella radice del pacchetto scaricato. Per ulteriori informazioni, consulta la documentazione IDE correlata. 3. Aggiornare il progetto per fare in modo che l'IDE possa individuare le librerie importate. • Per IntelliJ IDEA, procedere come segue: a. Facendo clic con il pulsante destro del mouse, aprire il menu contestuale della directory lib del progetto e scegliere Add as library (Aggiungi come libreria). b. Scegliere File, Project Structure (Struttura progetto). c. In Project Settings (Impostazioni progetto), scegliere Modules (Moduli). d. Nella scheda Sources (Origini), impostare Language Level (Livello linguaggio) su 7 o superiore. • Per Eclipse, procedere come segue: a. Facendo clic con il pulsante destro del mouse, aprire il menu contestuale del progetto e scegliere Proprerties (Proprietà), Java Build Path (Percorso di compilazione Java), Source (Origine). Quindi, esegui queste operazioni: 138 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 2: scrittura e analisi del codice 1. Nella scheda Source (Origine), fare doppio clic su Native library location (Percorso libreria nativa). 2. Nella procedura guidata Native Library Folder Configuration (Configurazione cartella libreria nativa), scegliere Workspace (Area di lavoro). 3. Nella selezione Native Library Folder (Cartella libreria nativa), scegliere la directory lib nel progetto. b. Facendo clic con il pulsante destro del mouse, aprire il menu contestuale del progetto e scegliere Properties (Proprietà). Quindi, esegui queste operazioni: 1. Nella scheda Libraries (Librerie), scegliere Add Jars (Aggiungi Jar). 2. Nella procedura guidata JAR selection (Selezione JAR), scegliere tutti i file .jar nella directory lib del progetto. Fase 2: scrittura e analisi del codice L'esempio dell'API PutMedia (PutMediaDemo) mostra i seguenti modelli di codifica: Argomenti • Creazione diPutMediaClient (p. 139) • Streaming di file multimediali e sospensione del thread (p. 140) Gli esempi di codice riportati in questa sezione sono presi dalla classe PutMediaDemo Creazione diPutMediaClient Per la creazione dell'oggetto PutMediaClient sono richiesti i parametri seguenti: • L'URI dell'endpoint PutMedia • Un InputStream diretto al file MKV di cui effettuare lo streaming. • Il nome del flusso. In questo esempio viene utilizzato il flusso creato in Utilizzo di Java Producer Library (p. 47) (my-stream). Per utilizzare un flusso diverso, modificare il parametro seguente: private static final String STREAM_NAME="my-stream"; Note L'esempio dell'API PutMedia non crea nessun flusso. È necessario creare un flusso utilizzando l'applicazione di test per Utilizzo di Java Producer Library (p. 47), utilizzando la console Kinesis Video Streams o AWS CLI. • Il timestamp corrente. • Il tipo di timecode. L'esempio utilizza il codice RELATIVE, che indica che il timestamp è relativo all'inizio del container. • Un oggetto AWSKinesisVideoV4Signer che verifica che i pacchetti ricevuti siano stati inviati da un mittente autorizzato. • La larghezza di banda di upstream massima in Kbps. • Un oggetto AckConsumer per la ricezione delle conferme di ricezione dei pacchetti. Il codice seguente crea l'oggetto PutMediaClient /* actually URI to send PutMedia request */ 139 Amazon Kinesis Video Streams Guida per gli sviluppatori Fase 3: esecuzione e verifica del codice final URI uri = URI.create(KINESIS_VIDEO_DATA_ENDPOINT + PUT_MEDIA_API); /* input stream for sample MKV file */ final InputStream inputStream = new FileInputStream(MKV_FILE_PATH); /* use a latch for main thread to wait for response to complete */ final CountDownLatch latch = new CountDownLatch(1); /* a consumer for PutMedia ACK events */ final AckConsumer ackConsumer = new AckConsumer(latch); /* client configuration used for AWS SigV4 signer */ final ClientConfiguration configuration = getClientConfiguration(uri); /* PutMedia client */ final PutMediaClient client = PutMediaClient.builder() .putMediaDestinationUri(uri) .mkvStream(inputStream) .streamName(STREAM_NAME) .timestamp(System.currentTimeMillis()) .fragmentTimeCodeType("RELATIVE") .signWith(getKinesisVideoSigner(configuration)) .upstreamKbps(MAX_BANDWIDTH_KBPS) .receiveAcks(ackConsumer) .build(); Streaming di file multimediali e sospensione del thread Dopo aver creato il client, il campione avvia lo streaming asincrono con putMediaInBackground. Il thread principale viene quindi messo in pausa con latch.await fino a quando non viene restituito AckConsumer e a quel punto il client viene chiuso. /* start streaming video in a background thread */ client.putMediaInBackground(); /* wait for request/response to complete */ latch.await(); /* close the client */ client.close(); Fase 3: esecuzione e verifica del codice Per eseguire l'esempio dell'API PutMedia, procedere come segue: 1. Creare un flusso denominato my-stream nella console Kinesis Video Streams o utilizzando AWS CLI. 2. Per modificare la directory di lavoro nella directory SDK del producer Java: $ cd / 3. Per compilare l'SDK Java e l'applicazione di demo: mvn package 4. Creare un filename temporaneo nella directory /tmp $ jar_files=$(mktemp) 140 Amazon Kinesis Video Streams Guida per gli sviluppatori RTSP e Docker 5. Creare una stringa di classpath di dipendenze dall'archivio locale a un file: $ mvn -Dmdep.outputFile=$jar_files dependency:build-classpath 6. Impostare il valore della variabile di ambiente LD_LIBRARY_PATH come segue: $ export LD_LIBRARY_PATH=/ 7. Eseguire la demo dalla riga di comando come segue, fornendo le proprie credenziali AWS: $ java -classpath target/kinesisvideo-java-demo-1.0-SNAPSHOT.jar:$classpath_values -Daws.accessKeyId=${ACCESS_KEY} -Daws.secretKey=${SECRET_KEY} -Djava.library.path=/ opt/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis-video-native-build com.amazonaws.kinesisvideo.demoapp.DemoAppMain 8. Aprire la console Kinesis Video Streams all'indirizzo https://console.aws.amazon.com/kinesisvideo/ e scegliere il flusso nella pagina Manage Streams (Gestisci flussi). Viene riprodotta la riproduzione del video nel riquadro Video Preview (Anteprima video). Esempio streaming da un'origine RTSP contiene una definizione per un container C++ Producer Library (p. 56)Docker che si connette a una videocamera di rete RTSP (Real Time Streaming Protocol). Utilizzando Docker è possibile standardizzare l'ambiente operativo per Kinesis Video Streams, semplificando notevolmente la creazione e l'esecuzione dell'applicazione. Per utilizzare l'applicazione demo RTSP, installare e creare C++ Producer Library (p. 56). La procedura seguente illustra come configurare e utilizzare l'applicazione demo di RTSP. Argomenti • Prerequisites (p. 141) • Creazione dell'immagine Docker (p. 141) • Eseguire l'applicazione di esempio RTSP (p. 142) Prerequisites Per eseguire l'applicazione di esempio RTSP di Kinesis Video Streams è necessario disporre di quanto elencato di seguito: • Docker: per informazioni sull'installazione e l'utilizzo di Docker, consulta i seguenti collegamenti: • Istruzioni di download di Docker • Nozioni di base su Docker • Origine videocamera di rete RTSP: per informazioni sulle videocamere consigliate consulta Requisiti di sistema (p. 3). Creazione dell'immagine Docker In primo luogo, è possibile generare l'immagine Docker che sarà eseguita all'interno dell'applicazione di demo. 141 Amazon Kinesis Video Streams Guida per gli sviluppatori Eseguire l'applicazione di esempio RTSP 1. Creare una nuova directory e copiare i file seguenti dalla directory docker_native_scripts alla nuova directory: • Dockerfile • start_rtsp_in_docker.sh 2. Passare alla directory creata nella fase precedente. 3. Creare l'immagine Docker utilizzando il comando seguente. Questo comando crea l'immagine e i tag come rtspdockertest. docker build -t rtspdockertest . 4. Registrare l'ID immagine restituito nella fase precedente (ad esempio, 54f0d65f69b2). Eseguire l'applicazione di esempio RTSP Avviare il container Docker di Kinesis Video Streams mediante il seguente comando. Fornire l'ID immagine dalla fase precedente, le credenziali di AWS, l'URL della videocamera RTSP di rete e il nome di Kinesis video stream per inviare i dati. $ docker run - it Per personalizzare l'applicazione, commentare o rimuovere il comando ENTRYPOINT in Dockerfilee avviare il container utilizzando il comando seguente: docker run -it Verrà richiesto all'interno del container Docker di personalizzare l'applicazione di esempio e avviare lo streaming. Esempio: analisi e rendering dei frammenti Kinesis Video Streams Libreria parser del flusso (p. 121) contiene un'applicazione demo denominata KinesisVideoRendererExample in cui viene illustrato come effettuare l'analisi e il rendering dei frammenti Amazon Kinesis video stream L'esempio utilizza JCodec per decodificare i fotogrammi con codifica H.264 acquisiti tramite l'applicazione Esempio: plugin Kinesis Video Streams dell'SDK del producerGStreamer (p. 129). Dopo aver decodificato il fotogramma utilizzando JCodec, viene eseguito il rendering dell'immagine visibile utilizzando JFrame. In questo esempio viene mostrato come effettuare le operazioni seguenti: • Recuperare i fotogrammi da un Kinesis video stream utilizzando l'API GetMedia ed effettuare il rendering del flusso per la visualizzazione. • Visualizzare il contenuto video dei flussi in un'applicazione personalizzata anziché nella console Kinesis Video Streams Puoi inoltre utilizzare le classi riportate in questo esempio per visualizzare i contenuti di Kinesis video stream che non dispongono della codifica H.264, ad esempio un flusso di file JPEG che non richiede la decodifica prima di essere visualizzato. 142 Amazon Kinesis Video Streams Guida per gli sviluppatori Prerequisites La procedura seguente illustra come configurare e utilizzare l'applicazione demo di Renderer. Prerequisites Per esaminare e utilizzare la libreria di esempio di Renderer, occorre quanto segue: • Un account Amazon Web ServicesAWS Se non disponi già di un account AWS, consulta Nozioni di base su Kinesis Video Streams. • Un ambiente di sviluppo integrato (IDE) Java, ad esempio Eclipse Java Neon o JetBrains IntelliJ Idea. Esecuzione dell'esempio di Renderer 1. Crea una directory, quindi clona il codice sorgente di esempio dal repository GitHub. $ git clone https://github.com/aws/amazon-kinesis-video-streams-parser-library 2. Aprire l'IDE Java in uso (ad esempio, Eclipse o IntelliJ IDEA) e importare il progetto Apache Maven scaricato: • In Eclipse: scegliere File, Import (Importa), Maven, Existing Maven Projects (Progetti Maven esistenti). Passa alla directory kinesis-video-streams-parser-lib • In IntelliJ Idea: scegliere Import (Importa). Andare al file pom.xml nella radice del pacchetto scaricato. Note Se IntelliJ non è in grado di trovare le dipendenze, potrebbe essere necessario eseguire le seguenti operazioni: • Build clean: scegliere File (File), Settings (Impostazioni), Build, Execution, Deployment (Creazione, esecuzione, distribuzione), Compiler (Compilatore). Verificare che Clear output directory on rebuild (Cancella directory di output alla ricompilazione) sia selezionato, quindi scegliere Build (Crea), Build Project (Crea progetto). • Reimport the project (Reimporta il progetto): aprire il menu di scelta rapida (fare clic con il pulsante destro del mouse) del progetto e scegliere Maven, Reimport (Reimporta). Per ulteriori informazioni, consulta la documentazione IDE correlata. 3. Dall'IDE Java, aprire src/test/java/com.amazonaws.kinesisvideo.parser/examples/ KinesisVideoRendererExampleTest. 4. Rimuovere la direttiva @Ignore dal file. 5. Aggiornare il parametro .stream con il nome del Kinesis video stream. 6. Eseguire il test KinesisVideoRendererExample Come funziona L'applicazione di esempio dimostra quanto segue: • Invio dei dati MKV (p. 144) • Analisi dei frammenti MKV in fotogrammi (p. 144) • Decodifica e visualizzazione del fotogramma (p. 144) 143 Amazon Kinesis Video Streams Guida per gli sviluppatori SageMaker Invio dei dati MKV L'esempio invia i dati MKV di esempio dal file rendering_example_video.mkv, tramite PutMedia, per inviare i dati video a un flusso denominato render-example-stream. L'applicazione crea un PutMediaWorker: PutMediaWorker putMediaWorker = PutMediaWorker.create(getRegion(), getCredentialsProvider(), getStreamName(), inputStream, streamOps.amazonKinesisVideo); executorService.submit(putMediaWorker); Per informazioni sulle classi PutMediaWorker, consulta Chiamate a PutMedia (p. 125) nella documentazione della Libreria parser del flusso (p. 121) Analisi dei frammenti MKV in fotogrammi L'esempio quindi recupera e analizza i frammenti MKV dal flusso tramite un GetMediaWorker: GetMediaWorker getMediaWorker = GetMediaWorker.create(getRegion(), getCredentialsProvider(), getStreamName(), new StartSelector().withStartSelectorType(StartSelectorType.EARLIEST), streamOps.amazonKinesisVideo, getMediaProcessingArgumentsLocal.getFrameVisitor()); executorService.submit(getMediaWorker); Per ulteriori informazioni sulle classi GetMediaWorker, consulta Chiamate a GetMedia (p. 125) nella documentazione della Libreria parser del flusso (p. 121) Decodifica e visualizzazione del fotogramma L'esempio quindi decodifica e visualizza il fotogramma utilizzando JFrame. Il seguente esempio di codice è tratto dalla classe KinesisVideoFrameViewer, che estende JFrame: public void setImage(BufferedImage bufferedImage) { image = bufferedImage; repaint(); } L'immagine viene visualizzata come istanza di java.awt.image.BufferedImage. Per esempi che illustrano come lavorare con BufferedImage, consulta la sezione relativa alla lettura/al caricamento di un'immagine. Esempio: identificazione degli oggetti nei flussi video con SageMaker Questo esempio illustra come creare una soluzione che utilizza SageMaker per identificare quando determinati oggetti appaiono in un flusso video Amazon Kinesis. SageMaker è la piattaforma gestita per 144 Amazon Kinesis Video Streams Guida per gli sviluppatori Prerequisites sviluppatori e data scientist per creare, addestrare e distribuire modelli di Machine Learning in modo rapido e semplice. L'esempio è costituito da un container Docker che include la funzionalità dell'applicazione e un modello AWS CloudFormation che automatizza la distribuzione delle risorse AWS dell'applicazione. Il modello AWS CloudFormation crea le seguenti risorse: • Un cluster Amazon Elastic Container Service (Amazon ECS) che utilizza il motore di elaborazione AWS Fargate che esegue il software della libreria. • Una tabella Amazon DynamoDB che gestisce i checkpoint e lo stato correlato tra i lavoratori in esecuzione nei task Fargate. • Un flusso di dati Kinesis che acquisisce gli output delle inferenze generate da SageMaker. • Una funzione AWS Lambda che analizza l'output di SageMaker. • Risorse AWS Identity and Access Management (IAM) per consentire l'accesso tra i servizi. • Amazon CloudWatchRisorse per il monitoraggio dell'applicazione. L'applicazione è compatibile con qualsiasi endpoint SageMaker di elaborazione dei dati. Questo esempio contiene istruzioni per la creazione di un endpoint SageMaker che utilizza un modello di algoritmo di identificazione degli oggetti di esempio. Puoi modificare o sostituire l'algoritmo in base ai casi d'uso e ai requisiti dell'applicazione. Argomenti • Prerequisites (p. 145) • Creazione dell'applicazione (p. 146) • Monitoraggio dell'applicazione (p. 147) • Ampliamento dell'applicazione (p. 149) • Pulizia dell'applicazione (p. 149) Prerequisites L'applicazione di esempio include i seguenti prerequisiti: • SageMaker (p. 145) • KinesisFlusso video (p. 146) • Ruolo collegato ai servizi (p. 146) SageMaker Questo esempio richiede un notebook SageMaker. Per informazioni sulla creazione di un notebook, consulta Creazione di un'istanza notebook nella Guida per gli sviluppatori di Amazon SageMaker. Durante la creazione del notebook, prendi nota di quanto segue: • Aggiungi l'esempio object_detection_image_json_format.ipynb (dalla sezione Introduction to Amazon Algorithms (Introduzione agli algoritmi Amazon) nella scheda SageMaker Examples (Esempi) della console Jupyter) al notebook. • Creare un bucket Amazon Simple Storage Service (Amazon S3) e specificarne il nome nella fase Prerequisites (Prerequisiti) quando si aggiunge l'esempio. • Dopo avere creato il notebook, scegliere Endpoint configuration (Configurazione endpoint) nella console SageMaker e annotare l'Endpoint name (Nome endpoint). 145 Amazon Kinesis Video Streams Guida per gli sviluppatori Creazione dell'applicazione KinesisFlusso video Questo esempio richiede uno o più flussi video Kinesis con dati video in tempo reale. Per informazioni sulla creazione di un Kinesis video stream e l'invio di dati da una videocamera, consulta GStreamer (p. 129). Annotare il nome del Kinesis video stream Ruolo collegato ai servizi Questo esempio richiede che l'account disponga di un ruolo collegato ai servizi per l'operazione di AWS Fargate. Nei nuovi account AWS questo ruolo è abilitato per impostazione predefinita. Se viene visualizzato il seguente errore al momento della creazione dell'applicazione, è necessario abilitare il ruolo collegato ai servizi: Unable to assume the service linked role. Please verify that the ECS service linked role exists Per abilitare il ruolo collegato ai servizi, eseguire il seguente comando: aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com Creazione dell'applicazione Per creare l'applicazione di esempio, si utilizza AWS CloudFormation e i modelli forniti. Per utilizzare AWS CloudFormation per creare l'applicazione 1. Accedere a AWS Management Console e aprire la console AWS CloudFormation utilizzando uno dei seguenti collegamenti delle regioni AWS Il collegamento avvia lo stack corretto per la regione: • Avvia nella regione Asia Pacifico (Sydney) (ap-southeast-2) • Avvia nella regione Asia Pacifico (Tokyo) (ap-northeast-1) • Avvio nella regione Regione Europa (Francoforte) (eu-central-1) • Avvia nella regione Regione Europa (Irlanda) (eu-west-1) • Avvia nella regione US East (N. Virginia) (us-east-1) • Avvia nella regione Stati Uniti occidentali (Oregon) (us-west-2) 2. Nella pagina Create Stack (Crea stack), fornire i seguenti valori: • Assegnare allo stack un nome univoco (ad esempio, username-KVS-SageMaker. • Specificare il nome dell'endpoint SageMaker (non l'ARN dell'endpoint) creato nella sezione precedente. • Specificare il nome del Kinesis video stream. Se si dispone di più di un Kinesis video stream, specificare i nomi dei flussi tra virgolette, separandoli con virgole. • Lasciare inalterate le altre impostazioni. Selezionare Successivo. 3. Nella pagina Options (Opzioni), non modificare le impostazioni. 4. Selezionare la casella di controllo I acknowledge that AWS CloudFormation might create IAM resources (Acconsento alla creazione di risorse IAM da parte di AWS). Selezionare Successivo. AWS CloudFormation crea l'applicazione. 146 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dell'applicazione La tabella seguente elenca i diversi parametri utilizzati dal container Docker al momento della creazione di uno stack con questo modello AWS CloudFormation I valori sono predefiniti nella risorsa SSM del modello, ma è possibile personalizzarli in base alle esigenze. Nome risorsa Valore predefinito Descrizione inferenceInterval 6 The sampling ratio for video frames that are sent to the SageMaker endpoint. Currently, we only support inferencing on I-Frames. The default value of 6 means that 1 out of every 6 I-Frames is sent to the SageMaker endpoint. sageMakerTaskQueueSize 5000 The size of the queue that maintains the pending requests to the SageMaker endpoint. The size of the queue is affected by ‘inferenceInternval’ and ‘sageMakerTaskTimeoutInMilli’. If SageMaker inference takes longer, requests are buffered in this queue. sageMakerTaskThreadPoolSize 20 Number of threads that is used to concurrently execute SageMaker requests. sageMakerTaskTimeoutInMilli 20000 The maximum duration allowed for a single request (or a retry request) that is sent to the SageMaker endpoint. sageMakerTaskThreadPoolName SageMakerThreadPool- The name of the threadpool that is sending requests to the SageMaker endpoint. %d Per personalizzare i valori di questi parametri, scaricare il modello AWS CloudFormation scegliendo l'URL del modello nella pagina Create stack (Crea stack) e quindi individuare questi parametri nella sezione Params del modello simile alla seguente: Params: Type: AWS::SSM::Parameter Properties: Name: Ref: AppName Description: "Configuration for SageMaker app" Type: String Value: Fn::Sub: | {"streamNames":[${StreamNames}], "tagFilters": [${TagFilters}],"sageMakerEndpoint":"${SageMakerEndpoint}", "endPointAcceptContentType": "${EndPointAcceptContentType}", "kdsStreamName":"${Kds}","inferenceInterval":6,"sageMakerTaskQueueSize":5000, "sageMakerTaskThreadPoolSize":20,"sageMakerTaskTimeoutInMilli":20000, "sageMakerTaskThreadPoolName":"SageMakerThreadPool-%d"} Monitoraggio dell'applicazione L'applicazione creata con il modello AWS CloudFormation include un pannello di controllo Amazon CloudWatch e un flusso di log CloudWatch per monitorare i parametri e gli eventi dell'applicazione. Pannello di controllo dell'applicazione L'applicazione include un pannello di controllo CloudWatch per monitorare i relativi parametri. Per visualizzare il pannello di controllo dell'applicazione, apri la console CloudWatch in https:// console.aws.amazon.com/cloudwatch/ e scegli Dashboards (Pannelli di controllo) nella barra di navigazione a sinistra. Scegliere KVS-SageMaker-Driver-KvsSageMakerIntegration-aws-region Pannello di controllo di . Il pannello di controllo mostra le seguenti informazioni: 147 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dell'applicazione • Parametri dei fotogrammi: parametri per l'elaborazione del flusso di video, l'invio di fotogrammi all'endpoint SageMaker e la scrittura nel flusso di dati Kinesis che connette il notebook SageMaker alla funzione di AWS Lambda di elaborazione dei risultati degli output delle inferenze di SageMaker • IngestToProcessLatency: la differenza di tempo tra l'inserimento di un fotogramma video nel servizio Kinesis Video Streams e la ricezione del fotogramma da parte dell'applicazione. • Totale lease corrente: all'applicazione vengono concesse le autorizzazioni in lettura dal Kinesis video stream tramite un lease. Questo parametro mostra il numero di lease attivi. L'applicazione utilizza un lease per il Kinesis video stream e uno per la sincronizzazione fra i flussi. • Parametri di sincronizzazione lease: la frequenza e la durata della sincronizzazione dei lease di autorizzazione. • LeaseCount per lavoratore: la distribuzione di lease tra i thread dei lavoratori SageMaker. • Numero di lavoratori: il numero di lavoratori SageMaker che elaborano i flussi. Ogni attività di un cluster Amazon ECS prevede un lavoratore. Un lavoratore può elaborare più flussi. • Utilizzo servizio ECS: i parametri di utilizzo del cluster Amazon ECS • KinesisDataStream: parametri di utilizzo del flusso di dati Kinesis. • SageMaker: operazioni eseguite dal notebook SageMaker. • Lambda: il numero e la durata della funzione Lambda che elabora l'output dal notebook SageMaker Se una qualsiasi delle informazioni di questi grafici indica un problema operativo (ad esempio un valore costantemente in aumento anziché stabile), consulta la sezione seguente per informazioni su come leggere i log delle applicazioni per determinare il problema. CloudWatchLog di L'applicazione include due log CloudWatch Argomenti • Log dell'applicazione (p. 148) • Log della funzione Lambda (p. 148) Log dell'applicazione Puoi utilizzare il log dell'applicazione per monitorare gli eventi e le condizioni di errore dell'applicazione. Questo log è utile se devi contattare il supporto del prodotto relativamente a un problema. Per leggere il log dell'applicazione 1. Aprire la console Amazon ECS all'indirizzo https://console.aws.amazon.com/ecs. 2. Scegliere il cluster KVS-Sagemaker-Driver. 3. Seleziona stack-name-SageMakerDriverService nella scheda Services (Servizi). 4. Scegliere la scheda Logs (Log). Il log dell'applicazione mostra eventi quali l'inizializzazione, la configurazione e le attività dei lease. Log della funzione Lambda Puoi utilizzare il log della funzione Lambda per tenere traccia delle identificazioni degli oggetti andate a buon fine. Per leggere il log Lambda 1. Aprire la console AWS Lambda all'indirizzo https://console.aws.amazon.com/lambda. 148 Amazon Kinesis Video Streams Guida per gli sviluppatori Ampliamento dell'applicazione 2. Scegliere la funzione Lambda per l'applicazione. Il nome della funzione Lambda ha il seguente formato: stack-name-LambdaFunction-A1B2C3D4E5F6G 3. Scegliere il riquadro Monitoring (Monitoraggio). 4. Scegliere View logs in CloudWatch (Visualizza log in ). Il log CloudWatch dell'applicazione mostra le identificazioni di oggetti andate a buon fine nel Kinesis video stream e in altri eventi dell'applicazione. Ampliamento dell'applicazione Puoi aggiungere funzionalità personalizzate all'applicazione modificando i valori forniti nella finestra del modello AWS CloudFormation, come indicato di seguito: • EndPointAcceptContentType: puoi modificare questo valore se il tuo endpoint SageMaker non accetta frame in formato JPG. Sono supportati i formati seguenti: • image/jpeg • image/png • image/bmp • image/gif • application/x-image • LambdaFunctionBucket, LambdaFunctionKey: le impostazioni fornite utilizzano una funzione AWS Lambda che elabora l'output SageMaker e lo scrive in CloudWatch Logs. Se desideri inviare l'output SageMaker altrove, puoi specificare una funzione Lambda personale. • Filtri tag: se disponi di flussi contrassegnati da tag mediante l'operazione the section called “ TagStream ” (p. 229), puoi specificare i tag dei flussi da elaborare. Ad esempio, se disponi di due flussi con la chiave Location con i valori Front e Parking, potresti applicare filtri per utilizzare solo quei flussi immettendo quanto segue: {"key":"Location","values":["Front","Parking"]} Pulizia dell'applicazione Al termine dell'utilizzo dell'applicazione creata per questo tutorial, ti consigliamo di eliminare le risorse che non desideri conservare per evitare l'addebito di spese aggiuntive. 1. Endpoint SageMaker: se hai creato l'endpoint SageMaker per questo tutorial anziché utilizzarne uno esistente, elimina l'endpoint. Nel pannello di controllo SageMaker, scegliere Endpoint configurations (Configurazioni endpoint). Scegliere l'endpoint creato, quindi Actions (Operazioni), Delete (Elimina). Confermare l'eliminazione. 2. Notebook SageMaker: nella console SageMaker, scegliere Notebook instances (Istanze notebook). Scegliere il notebook creato, quindi Actions (Operazioni), Stop (Arresta). Se lo Status (Stato) del notebook è Stopped (Arrestato), scegliere Actions (Operazioni), Delete (Elimina). Confermare l'eliminazione. Note Per ulteriori informazioni sulla pulizia delle risorse SageMaker, consulta Pulizia nella Guida per gli sviluppatori SageMaker. 149 Amazon Kinesis Video Streams Guida per gli sviluppatori Pulizia dell'applicazione 3. Policy di esecuzione SageMaker: nel riquadro di navigazione della console IAM, scegliere Policies (Policy). Scegliere la policy creata per questo tutorial. Il nome della policy è simile al seguente: AmazonSageMaker-ExecutionPolicy-timestamp Scegliere Policy actions (Operazioni policy), Delete (Elimina) Confermare l'eliminazione. 4. Ruolo di esecuzione SageMaker: nel riquadro di navigazione della console IAM, scegliere Roles (Ruoli). Scegliere il ruolo creato per questo tutorial. Il nome del ruolo è simile al seguente: AmazonSageMaker-ExecutionRole-timestamp Scegliere Delete role (Elimina ruolo). Confermare l'eliminazione. 5. Stack AWS CloudFormation: nella console AWS CloudFormation, scegliere lo stack creato per questo tutorial. Scegli Actions (Operazioni), quindi Delete Stack (Elimina stack). Confermare l'eliminazione. 6. Bucket Amazon S3: nella console Amazon S3, scegliere il bucket creato per archiviare gli asset SageMaker Seleziona Delete (Elimina). Immettere il nome del bucket e scegliere Confirm (Conferma) per confermare l'eliminazione. 7. Kinesis video stream: nella console Kinesis Video Streams, scegliere il flusso video creato per l'applicazione. Seleziona Delete (Elimina). Confermare l'eliminazione. 150 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Monitoraggio di Kinesis Video Streams Il monitoraggio è importante per mantenere l'affidabilità, la disponibilità e le prestazioni di Kinesis Video Streams e delle soluzioni AWS. È necessario raccogliere i dati sul monitoraggio da tutte le parti della soluzione AWS per consentire un debug più facile di eventuali guasti in più punti. Prima di iniziare il monitoraggio di Kinesis Video Streams è tuttavia opportuno creare un piano di monitoraggio che includa le risposte alle seguenti domande: • Quali sono gli obiettivi del monitoraggio? • Di quali risorse intendi eseguire il monitoraggio? • Con quale frequenza eseguirai il monitoraggio di queste risorse? • Quali strumenti di monitoraggio utilizzerai? • Chi eseguirà le attività di monitoraggio? • Chi deve ricevere una notifica quando si verifica un problema? Dopo aver definito gli obiettivi del monitoraggio e aver creato il tuo piano di monitoraggio, la fase successiva consiste in stabilire una baseline per le normali prestazioni Kinesis Video Streams nel tuo ambiente. È necessario misurare le prestazioni Kinesis Video Streams in diversi orari e in diverse condizioni di carico. Durante il monitoraggio di Kinesis Video Streams, è necessario archiviare una cronologia dei dati di monitoraggio raccolti. Comparare le attuali prestazioni Kinesis Video Streams con questi dati storici è utile per identificare i modelli di prestazioni normali e le anomalie di prestazioni, oltre che per ideare metodi per gestire eventuali problemi. Argomenti • Monitoraggio dei parametri di Kinesis Video Streams con CloudWatch (p. 151) • Registrazione di chiamate dell'API di Kinesis Video Streams con AWS CloudTrail (p. 162) Monitoraggio dei parametri di Kinesis Video Streams con CloudWatch Puoi monitorare un Kinesis video stream usando Amazon CloudWatch, che raccoglie i dati non elaborati da Kinesis Video Streams e li elabora trasformandoli in parametri leggibili quasi in tempo reale. Queste statistiche vengono registrate per un periodo di 15 mesi, per permettere l'accesso alle informazioni storiche e offrire una prospettiva migliore sulle prestazioni del servizio o dell'applicazione Web. Nella console di gestione Kinesis Video Streams, è possibile visualizzare i parametri CloudWatch per un Kinesis video stream in due modi: • Nella pagina Dashboard (Pannello di controllo) scegliere la scheda Video streams (Flussi video) nella sezione Account-level metrics for Current Region (Parametri a livello di account per la regione corrente). • Scegliere la scheda Monitoring (Monitoraggio) nella pagina dei dettagli del flusso video. Kinesis Video Streams fornisce i seguenti parametri: 151 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione ArchivedFragmentsConsumed.Media Numero di punti di quota dei supporti di frammento utilizzati da tutte le APIs. Per una spiegazione del concetto di punti di quota, consulta the section called “Quote framment-metadata e fragment-media” (p. 170). Unità: numero ArchivedFragmentsConsumed.Metadata Numero di punti di quota dei metadati dei frammenti utilizzati da tutte le APIs. Per una spiegazione del concetto di punti di quota, consulta the section called “Quote framment-metadata e fragment-media” (p. 170). Unità: numero PutMedia.Requests Numero di richieste API PutMedia per un determinato flusso. Unità: numero PutMedia.IncomingBytes Numero di byte ricevuti come parte di PutMedia per il flusso. Unità: byte PutMedia.IncomingFragments Numero di frammenti completi ricevuti come parte di PutMedia per il flusso. Unità: numero PutMedia.IncomingFrames Numero di fotogrammi completi ricevuti come parte di PutMedia per il flusso. Unità: numero PutMedia.ActiveConnections Il numero totale di connessioni al service host. Unità: numero PutMedia.ConnectionErrors Errori durante il tentativo di stabilire la connessione PutMedia per il flusso. Unità: numero PutMedia.FragmentIngestionLatency Intervallo di tempo fra la ricezione del primo e dell'ultimo byte di un frammento da parte di Kinesis Video Streams. Unità: millisecondi PutMedia.FragmentPersistLatency Il tempo impiegato dalla ricezione e l'archiviazione dei dati del frammento. Unità: numero PutMedia.Latency Intervallo di tempo fra la richiesta e la risposta HTTP da InletService durante il tentativo di stabilire la connessione. Unità: numero 152 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione PutMedia.BufferingAckLatency Intervallo di tempo fra la ricezione del primo byte di un nuovo frammento da parte di Kinesis Video Streams e l'invio dell'ACK di buffering del frammento. Unità: millisecondi PutMedia.ReceivedAckLatency Intervallo di tempo fra la ricezione dell'ultimo byte di un nuovo frammento da parte di Kinesis Video Streams e l'invio dell'ACK di ricezione del frammento. Unità: millisecondi PutMedia.PersistedAckLatency Intervallo di tempo fra la ricezione dell'ultimo byte di un nuovo frammento da parte di Kinesis Video Streams e l'invio dell'ACK di persistenza del frammento. Unità: millisecondi PutMedia.ErrorAckCount Numero di ACK di errore inviati durante l'esecuzione di PutMedia per il flusso. Unità: numero PutMedia.Success 1 per ogni frammento scritto senza errori; 0 per ogni frammento con errori. Il valore medio di questo parametro indica il numero di frammenti completi e validi inviati. Unità: numero GetMedia.Requests Numero di richieste API GetMedia per un determinato flusso. Unità: numero GetMedia.OutgoingBytes Numero totale di byte inviati dal servizio come parte dell'API GetMedia per un determinato flusso. Unità: byte GetMedia.OutgoingFragments Numero di frammenti inviati durante l'esecuzione di GetMedia per il flusso. Unità: numero GetMedia.OutgoingFrames Numero di fotogrammi inviati durante l'esecuzione di GetMedia nel flusso specificato. Unità: numero GetMedia.MillisBehindNow Intervallo di tempo fra il timestamp corrente del server e quello dell'ultimo frammento inviato. Unità: millisecondi GetMedia.ConnectionErrors Il numero di connessioni che non sono state stabilite con successo. Unità: numero 153 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione GetMedia.Success 1 per ogni frammento inviato senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetMediaForFragmentList.OutgoingBytesNumero totale di byte inviati dal servizio come parte dell'API GetMediaForFragmentList per un determinato flusso. Unità: byte GetMediaForFragmentList.OutgoingFragmentsNumero totale di frammenti inviati dal servizio come parte dell'API GetMediaForFragmentList per un determinato flusso. Unità: numero GetMediaForFragmentList.OutgoingFramesNumero totale di fotogrammi inviati dal servizio come parte dell'API GetMediaForFragmentList per un determinato flusso. Unità: numero GetMediaForFragmentList.Requests Numero di richieste API GetMediaForFragmentList per un determinato flusso. Unità: numero GetMediaForFragmentList.Success 1 per ogni frammento inviato senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero ListFragments.Latency Latenza delle chiamate API ListFragments per il nome del flusso specificato. Unità: millisecondi 154 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione ListFragments.Requests Numero di richieste API ListFragments per un determinato flusso. Unità: numero ListFragments.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetHLSStreamingSessionURL.Latency Latenza delle chiamate API GetHLSStreamingSessionURL per il nome del flusso specificato. Unità: millisecondi GetHLSStreamingSessionURL.Requests Numero di richieste API GetHLSStreamingSessionURL per un determinato flusso. Unità: numero GetHLSStreamingSessionURL.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetHLSMasterPlaylist.Latency Latenza delle chiamate API GetHLSMasterPlaylist per il nome del flusso specificato. Unità: millisecondi GetHLSMasterPlaylist.Requests Numero di richieste API GetHLSMasterPlaylist per un determinato flusso. Unità: numero 155 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione GetHLSMasterPlaylist.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetHLSMediaPlaylist.Latency Latenza delle chiamate API GetHLSMediaPlaylist per il nome del flusso specificato. Unità: millisecondi GetHLSMediaPlaylist.Requests Numero di richieste API GetHLSMediaPlaylist per un determinato flusso. Unità: numero GetHLSMediaPlaylist.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetMP4InitFragment.Latency Latenza delle chiamate API GetMP4InitFragment per il nome del flusso specificato. Unità: millisecondi GetMP4InitFragment.Requests Numero di richieste API GetMP4InitFragment per un determinato flusso. Unità: numero 156 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione GetMP4InitFragment.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetMP4MediaFragment.Latency Latenza delle chiamate API GetMP4MediaFragment per il nome del flusso specificato. Unità: millisecondi GetMP4MediaFragment.Requests Numero di richieste API GetMP4MediaFragment per un determinato flusso. Unità: numero GetMP4MediaFragment.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetMP4MediaFragment.OutgoingBytes Numero totale di byte inviati dal servizio come parte dell'API GetMP4MediaFragment per un determinato flusso. Unità: byte GetTSFragment.Latency Latenza delle chiamate API GetTSFragment per il nome del flusso specificato. Unità: millisecondi GetTSFragment.Requests Numero di richieste API GetTSFragment per un determinato flusso. Unità: numero 157 Amazon Kinesis Video Streams Guida per gli sviluppatori Monitoraggio dei parametri di con CloudWatch Parametro Descrizione GetTSFragment.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetTSFragment.OutgoingBytes Numero totale di byte inviati dal servizio come parte dell'API GetTSFragment per un determinato flusso. Unità: byte GetDASHStreamingSessionURL.Latency Latenza delle chiamate API GetDASHStreamingSessionURL per il nome del flusso specificato. Unità: millisecondi GetDASHStreamingSessionURL.Requests Numero di richieste API GetDASHStreamingSessionURL per un determinato flusso. Unità: numero GetDASHStreamingSessionURL.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetDASHManifest.Latency Latenza delle chiamate API GetDASHManifest per il nome del flusso specificato. Unità: millisecondi GetDASHManifest.Requests Numero di richieste API GetDASHManifest per un determinato flusso. Unità: numero 158 Amazon Kinesis Video Streams Guida per gli sviluppatori CloudWatchGuida ai parametri di Parametro Descrizione GetDASHManifest.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetClip.Latency Latenza delle chiamate API GetClip per il nome del flusso video specificato. Unità: milisecondi GetClip.Requests Numero di richieste API GetClip per un determinato flusso video. Unità: numero GetClip.Success 1 per ogni richiesta senza errori; 0 per ogni errore. Il valore medio indica la percentuale di successo. Note Gli errori includono errori 400 (utente) e 500 (sistema). Per ulteriori informazioni sull'abilitazione di un riepilogo delle richieste e delle risposte, inclusi gli ID delle richieste AWS, consulta Registrazione del riepilogo delle richieste/risposte. Unità: numero GetClip.OutgoingBytes Numero totale di byte inviati dal servizio come parte dell'API GetClip per un determinato flusso video. Unità: byte CloudWatchGuida ai parametri di CloudWatchI parametri di possono dare risposte alle seguenti domande: Argomenti • I dati arrivano al servizio Kinesis Video Streams? (p. 160) • Perché i dati non vengono acquisiti correttamente dal servizio Kinesis Video Streams? (p. 160) • Perché non è possibile leggere i dati dal servizio Kinesis Video Streams alla stessa velocità con cui vengono inviati dal producer? (p. 160) • Perché non c'è video nella console oppure perché il video viene riprodotto in ritardo? (p. 161) • Con quanto ritardo vengono letti i dati in tempo reale e perché il client è in ritardo rispetto all'inizio del flusso? (p. 161) 159 Amazon Kinesis Video Streams Guida per gli sviluppatori CloudWatchGuida ai parametri di • Il client legge i dal Kinesis video stream e con quale velocità? (p. 161) • Perché il client non riesce a leggere i dati dal Kinesis video stream? (p. 162) I dati arrivano al servizio Kinesis Video Streams? Parametri pertinenti: • PutMedia.IncomingBytes • PutMedia.IncomingFragments • PutMedia.IncomingFrames Cosa fare: • Se questi parametri evidenziano un calo, controllare se l'applicazione sta ancora inviando dati al servizio. • Verificare la larghezza di banda della rete. Se è insufficiente, potrebbe rallentare la velocità con cui il servizio riceve i dati. Perché i dati non vengono acquisiti correttamente dal servizio Kinesis Video Streams? Parametri pertinenti: • PutMedia.Requests • PutMedia.ConnectionErrors • PutMedia.Success • PutMedia.ErrorAckCount Cosa fare: • Se è presente un aumento in PutMedia.ConnectionErrors, controllare i codici di risposta/errore HTTP ricevuti dal client del producer per scoprire quali errori si verificano quando si stabilisce la connessione. • Se è presente un calo in PutMedia.Success o un aumento in PutMedia.ErrorAckCount, controllare il codice errore ack nelle risposte ack inviate dal servizio per scoprire perché l'acquisizione di dati non riesce. Per ulteriori informazioni, vedere AckErrorCode.Values. Perché non è possibile leggere i dati dal servizio Kinesis Video Streams alla stessa velocità con cui vengono inviati dal producer? Parametri pertinenti: • PutMedia.FragmentIngestionLatency • PutMedia.IncomingBytes Cosa fare: • Se questi parametri evidenziano un calo, controllare la larghezza di banda della rete per le connessioni. Una connessione con larghezza di banda ridotta potrebbe causare un trasferimento lento dei dati al servizio. 160 Amazon Kinesis Video Streams Guida per gli sviluppatori CloudWatchGuida ai parametri di Perché non c'è video nella console oppure perché il video viene riprodotto in ritardo? Parametri pertinenti: • PutMedia.FragmentIngestionLatency • PutMedia.FragmentPersistLatency • PutMedia.Success • ListFragments.Latency • PutMedia.IncomingFragments Cosa fare: • Se è presente un aumento in PutMedia.FragmentIngestionLatency o un calo in PutMedia.IncomingFragments, controllare la larghezza di banda della rete e se i dati vengono ancora inviati. • Se è presente un calo in PutMedia.Success, controllare i codici di errore ack. Per ulteriori informazioni, vedere AckErrorCode.Values. • Se è presente un aumento in PutMedia.FragmentPersistLatency o ListFragments.Latency, con ogni probabilità si tratta di un problema del servizio. Se la situazione si protrae per un periodo di tempo esteso, contattare l'assistenza clienti per controllare se il servizio presenta un problema. Con quanto ritardo vengono letti i dati in tempo reale e perché il client è in ritardo rispetto all'inizio del flusso? Parametri pertinenti: • GetMedia.MillisBehindNow • GetMedia.ConnectionErrors • GetMedia.Success Cosa fare: • Se è presente un aumento in GetMedia.ConnectionErrors, il consumer potrebbe trovarsi in svantaggio nella lettura del flusso a causa di frequenti tentativi di riconnettersi al flusso. Controllare i codici di risposta/errore HTTP restituiti per la richiesta GetMedia. • Se è presente un calo in GetMedia.Success, la probabile causa è l'impossibilità da parte del servizio di inviare i dati al consumer. Di conseguenza, la connessione cade e il consumer ritenta di connettersi, restando così indietro rispetto all'inizio del flusso. • Se è presente un aumento in GetMedia.MillisBehindNow, verificare i limiti della larghezza di banda per vedere se il rallentamento nella ricezione dei dati può essere dovuto a una ridotta larghezza di banda. Il client legge i dal Kinesis video stream e con quale velocità? Parametri pertinenti: • GetMedia.OutgoingBytes • GetMedia.OutgoingFragments • GetMedia.OutgoingFrames 161 Amazon Kinesis Video Streams Guida per gli sviluppatori Registrazione delle chiamate API con CloudTrail • GetMediaForFragmentList.OutgoingBytes • GetMediaForFragmentList.OutgoingFragments • GetMediaForFragmentList.OutgoingFrames Cosa fare: • Questi parametri indicano la velocità di lettura dei dati in tempo reale e archiviati. Perché il client non riesce a leggere i dati dal Kinesis video stream? Parametri pertinenti: • GetMedia.ConnectionErrors • GetMedia.Success • GetMediaForFragmentList.Success • PutMedia.IncomingBytes Cosa fare: • Se è presente un aumento in GetMedia.ConnectionErrors, verificare i codici di errore/ risposta HTTP restituiti dalla richiesta GetMedia. Per ulteriori informazioni, vedere AckErrorCode.Values. • Se si sta tentando di leggere dati molto recenti/in diretta, controllare PutMedia.IncomingBytes per verificare se vi sono dati in arrivo nel flusso per l'invio ai consumer da parte del servizio. • Se è presente un calo in GetMedia.Success o GetMediaForFragmentList.Success, è probabile che il servizio non sia in grado di inviare i dati ai consumer. Se la situazione si protrae per un periodo di tempo esteso, contattare l'assistenza clienti per controllare se il servizio presenta un problema. Registrazione di chiamate dell'API di Kinesis Video Streams con AWS CloudTrail Amazon Kinesis Video Streams è integrato con AWS CloudTrail, un servizio che offre un record delle operazioni eseguite da un utente, ruolo o servizio AWS in Amazon Kinesis Video Streams. CloudTrail acquisisce tutte le chiamate API per Amazon Kinesis Video Streams come eventi. Le chiamate acquisite includono le chiamate dalla console Amazon Kinesis Video Streams e le chiamate di codice alle operazioni API di Amazon Kinesis Video Streams. Se crei un trail, puoi abilitare la distribuzione continua di eventi CloudTrail in un bucket Amazon S3 includendo eventi per Amazon Kinesis Video Streams. Se non configuri un trail, è comunque possibile visualizzare gli eventi più recenti nella console di CloudTrail in Event history (Cronologia eventi). Le informazioni raccolte da CloudTrail permettono di determinare la richiesta effettuata a Amazon Kinesis Video Streams, l'indirizzo IP da cui è stata effettuata la richiesta, l'autore della richiesta, il momento in cui è stata effettuata e altri dettagli. Per ulteriori informazioni su CloudTrail, incluse le modalità di configurazione e abilitazione, consulta la AWS CloudTrail User Guide. Kinesis Video Streams e CloudTrail CloudTrail è abilitato sull'account AWS al momento della sua creazione. Quando si verifica un'attività di eventi supportata in Amazon Kinesis Video Streams, l'attività viene registrata in un evento CloudTrail 162 Amazon Kinesis Video Streams Guida per gli sviluppatori Esempio: Voci di file di log Amazon Kinesis Video Streams insieme ad altri eventi del servizio AWS in Event history (Cronologia eventi). È possibile visualizzare, cercare e scaricare gli eventi recenti nell'account AWS. Per ulteriori informazioni, consulta Visualizzazione di eventi mediante la cronologia eventi di CloudTrail . Per una registrazione continua degli eventi nell'account AWS che includa eventi per Amazon Kinesis Video Streams, crea un trail. Un trail consente a CloudTrail di fornire i file di log in un bucket Amazon S3. Per impostazione predefinita, quando crei un trail nella console, il trail si applica a tutte le regioni AWS. Il trail registra gli eventi di tutte le regioni nella partizione AWS e distribuisce i file di log nel bucket Amazon S3 specificato. Inoltre, puoi configurare altri servizi AWS per analizzare con maggiore dettaglio e usare i dati raccolti nei log CloudTrail. Per ulteriori informazioni, consulta gli argomenti seguenti: • Panoramica della creazione di un trail • CloudTrail Servizi e integrazioni supportati • Configurazione delle notifiche Amazon SNS per CloudTrail • Ricezione di file di log CloudTrail da più regioni e Ricezione di file di log CloudTrail da più account Amazon Kinesis Video Streams supporta la registrazione delle seguenti operazioni come eventi nei file di log di CloudTrail: • CreateStream • DeleteStream • DescribeStream • GetDataEndpoint • ListStreams • ListTagsForStream • TagStream • UntagStream • UpdateDataRetention • UpdateStream Ogni evento o voce di log contiene informazioni sull'utente che ha generato la richiesta. Le informazioni di identità consentono di determinare quanto segue: • Se la richiesta è stata effettuata con le credenziali utente AWS Identity and Access Management (IAM) o root. • Se la richiesta è stata effettuata con le credenziali di sicurezza temporanee per un ruolo o un utente federato. • Se la richiesta è stata effettuata da un altro servizio AWS. Per ulteriori informazioni, consulta Elemento CloudTrail userIdentity. Esempio: Voci di file di log Amazon Kinesis Video Streams Un trail è una configurazione che consente la distribuzione di eventi come file di log in un bucket Amazon S3 specificato. I file di log di CloudTrail contengono una o più voci di log. Un evento rappresenta una singola richiesta da qualsiasi sorgente e include informazioni sull'operazione richiesta, la data e l'ora dell'operazione, i parametri della richiesta e così via. I file di log di CloudTrail non sono una traccia di stack ordinata delle chiamate API pubbliche, pertanto non vengono visualizzati in un ordine specifico. L'esempio seguente mostra una voce di log di CloudTrail relativa all'operazione CreateStream. 163 Amazon Kinesis Video Streams Guida per gli sviluppatori Esempio: Voci di file di log Amazon Kinesis Video Streams { "Records": [ { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::123456789012:user/Alice", "accountId": "123456789012", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2018-05-25T00:16:31Z", "eventSource": " kinesisvideo.amazonaws.com", "eventName": "CreateStream", "awsRegion": "us-east-1", "sourceIPAddress": "127.0.0.1", "userAgent": "aws-sdk-java/unknown-version Linux/x.xx", "requestParameters": { "streamName": "VideoStream", "dataRetentionInHours": 2, "mediaType": "mediaType", "kmsKeyId": "arn:aws:kms::us-east-1:123456789012:alias", "deviceName": "my-device" }, "responseElements": { "streamARN":arn:aws:kinesisvideo:us-east-1:123456789012:stream/VideoStream/12345" }, "requestID": "db6c59f8-c757-11e3-bc3b-57923b443c1c", "eventID": "b7acfcd0-6ca9-4ee1-a3d7-c4e8d420d99b" }, { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::123456789012:user/Alice", "accountId": "123456789012", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2018-05-25:17:06Z", "eventSource": " kinesisvideo.amazonaws.com", "eventName": "DeleteStream", "awsRegion": "us-east-1", "sourceIPAddress": "127.0.0.1", "userAgent": "aws-sdk-java/unknown-version Linux/x.xx", "requestParameters": { "streamARN": "arn:aws:kinesisvideo:us-east-1:012345678910:stream/ VideoStream/12345", "currentVersion": "keqrjeqkj9" }, "responseElements": null, "requestID": "f0944d86-c757-11e3-b4ae-25654b1d3136", "eventID": "0b2f1396-88af-4561-b16f-398f8eaea596" }, { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::123456789012:user/Alice", "accountId": "123456789012", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" 164 Amazon Kinesis Video Streams Guida per gli sviluppatori Esempio: Voci di file di log Amazon Kinesis Video Streams }, "eventTime": "2014-04-19T00:15:02Z", "eventSource": " kinesisvideo.amazonaws.com", "eventName": "DescribeStream", "awsRegion": "us-east-1", "sourceIPAddress": "127.0.0.1", "userAgent": "aws-sdk-java/unknown-version Linux/x.xx", "requestParameters": { "streamName": "VideoStream" }, "responseElements": null, "requestID": "a68541ca-c757-11e3-901b-cbcfe5b3677a", "eventID": "22a5fb8f-4e61-4bee-a8ad-3b72046b4c4d" }, { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::123456789012:user/Alice", "accountId": "123456789012", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2014-04-19T00:15:03Z", "eventSource": "kinesisvideo.amazonaws.com", "eventName": "GetDataEndpoint", "awsRegion": "us-east-1", "sourceIPAddress": "127.0.0.1", "userAgent": "aws-sdk-java/unknown-version Linux/x.xx", "requestParameters": { "streamName": "VideoStream", "aPIName": "LIST_FRAGMENTS" " }, "responseElements": null, "requestID": "a6e6e9cd-c757-11e3-901b-cbcfe5b3677a", "eventID": "dcd2126f-c8d2-4186-b32a-192dd48d7e33" }, { "eventVersion": "1.05", "userIdentity": { "type": "IAMUser", "principalId": "EX_PRINCIPAL_ID", "arn": "arn:aws:iam::123456789012:user/Alice", "accountId": "123456789012", "accessKeyId": "EXAMPLE_KEY_ID", "userName": "Alice" }, "eventTime": "2018-05-25T00:16:56Z", "eventSource": "kinesisvideo.amazonaws.com", "eventName": "ListStreams", "awsRegion": "us-east-1", "sourceIPAddress": "127.0.0.1", "userAgent": "aws-sdk-java/unknown-version Linux/x.xx", "requestParameters": { "maxResults": 100, "streamNameCondition": {"comparisonValue":"MyVideoStream" comparisonOperator":"BEGINS_WITH"}} }, "responseElements": null, "requestID": "e9f9c8eb-c757-11e3-bf1d-6948db3cd570", "eventID": "77cf0d06-ce90-42da-9576-71986fec411f" } ] } 165 Amazon Kinesis Video Streams Guida per gli sviluppatori Esempio: Voci di file di log Amazon Kinesis Video Streams 166 Amazon Kinesis Video Streams Guida per gli sviluppatori Limiti API del piano di controllo Kinesis Video StreamsLimiti per Kinesis Video Streams presenta i seguenti limiti: I limiti indicati di seguito sono flessibili [f], che possono essere modificati inviando un ticket di supporto, oppure rigidi [r], che non possono essere aumentati. Limiti API del piano di controllo Nella sezione seguente sono indicati i limiti per le API control-plane. TPS sta per transazioni al secondo. Quando viene raggiunto un limite di richieste a livello di account o a livello di risorsa, ClientLimitExceededException viene generata un'eccezione . Limiti per l'API Control Plane API Limite account: Limite account: Limite a livello Eccezioni pertinenti e note richieste flussi di flusso CreateStream 50 TPS 2500 flussi per Questa API può essere invocata account nelle da dispositivi, CLI, accessi basati regioni Stati su SDK e dalla console. Se il Uniti orientali flusso non è già esistente, va a (Virginia buon fine una sola chiamata API. settentrionale) e Stati Uniti occidentali (Oregon). 1000 flussi per account in tutte le altre regioni supportate. Note Questo limite può essere aumentato fino a 100.000 (o più) flussi per account. Accedi alla AWS Management Console all'indirizzo 167 Amazon Kinesis Video Streams Guida per gli sviluppatori Limiti per i file multimediali e le API dei file multimediali archiviati API Limite account: Limite account: Limite a livello Eccezioni pertinenti e note richieste flussi di flusso https:// console.aws.amazon.com/ e invia un caso di aumento dei limiti del servizio per Kinesis Video Streams per richiedere un aumento di questo limite. DescribeStream 300 TPS [r] N/D 5 TPS [r] UpdateStream 50 TPS [r] N/D 5 TPS [r] ListStreams 50 TPS [r] N/D DeleteStream 50 TPS [r] N/D 5 TPS [r] GetDataEndpoint 300 TPS [r] N/D 5 TPS [r] Viene chiamato ogni 45 minuti per aggiornare il token di streaming per la maggior parte dei casi d'uso PutMedia/GetMedia. Il caching dei dati dell'endpoint è un'operazione sicura se l'applicazione ricarica i dati in caso di errore. UpdateDataRetention50 TPS [r] N/D 5 TPS [r] TagStream 50 TPS [r] N/D 5 TPS [r] UntagStream 50 TPS [r] N/D 5 TPS [r] ListTagsForStream50 TPS [r] N/D 5 TPS [r] Limiti per i file multimediali e le API dei file multimediali archiviati La sezione seguente descrive i limiti delle API per dati multimediali e dati multimediali archiviati. 168 Amazon Kinesis Video Streams Guida per gli sviluppatori Limiti per i file multimediali e le API dei file multimediali archiviati Quando viene raggiunto un limite di richieste a livello di account o a livello di risorsa, ClientLimitExceededException viene generata un'eccezione . Quando viene raggiunto un limite a livello di connessione, viene generata un'eccezione ConnectionLimitExceededException. Quando viene raggiunto un limite a livello di frammento, vengono generati i seguenti errori o messaggi ACK: • Se un frammento è inferiore alla durata minima, viene restituito il messaggio ACK MIN_FRAGMENT_DURATION_REACHED. • Se un frammento è superiore alla durata massima, viene restituito il messaggio ACK MAX_FRAGMENT_DURATION_REACHED. • Se un frammento supera le dimensioni massime dei dati, viene restituito il messaggio ACK MAX_FRAGMENT_SIZE. • Viene generata un'eccezione FragmentLimitExceeded se viene raggiunto un limite a livello di frammento in un'operazione GetMediaForFragmentList. Limiti per l'API Data Plane API Limite a Limite a Limite Limite a Eccezioni pertinenti e note livello di livello di larghezza di livello di flusso connessione banda frammento PutMedia 5 TPS [r] 1 [f] 12,5 MB/sec. • Durata Una tipica richiesta o 100 Mbps minima PutMedia conterrà i [f] frammento: dati per alcuni secondi, 1 secondo generando un TPS minore [r] per flusso. In caso di più • Durata connessioni contemporanee massima che superano i limiti, frammento: viene accettata l'ultima 20 secondi connessione. [r] • Dimensione massima frammento: 50 MB [r] • Numero massimo di brani: 3 [s] GetHLSStreamingSessionURL25 TPS [r] N/D N/D N/D GetDASHStreamingSessionURL25 TPS [r] N/D N/D N/D GetMedia 5 TPS [r] 3 [f] 25 MB/sec. o N/D In qualsiasi momento, solo 200 Mbps [f] tre client possono ricevere simultaneamente contenuti dal flusso di file multimediali. Eventuali altre connessioni client vengono rifiutate. A un unico client in uso non servono più di 2 o 3 TPS perché, una volta stabilita la 169 Amazon Kinesis Video Streams Guida per gli sviluppatori Quote framment-metadata e fragment-media API Limite a Limite a Limite Limite a Eccezioni pertinenti e note livello di livello di larghezza di livello di flusso connessione banda frammento connessione, prevediamo che l'applicazione leggerà in modo continuo. Se un frammento tipico è di circa 5 MB, questo limite significherà circa 75 MB/ sec per flusso video Kinesis. Un tale flusso avrebbe un bitrate in uscita doppio rispetto al massimo bitrate in entrata per i flussi. GetMediaForFragmentListN/D 5 [s] 25 MB/sec. o Numero Cinque applicazioni in 200 Mbps [s] massimo di uso basate su frammenti frammenti: possono ricevere 1.000 [h] contemporaneamente elementi multimediali. Eventuali altre connessioni vengono rifiutate. GetClip N/D N/D Limite di Numero dimensione massimo di 100 MB [h] frammenti: 200 [h] Limiti dell'API del protocollo di riproduzione video API Limite a livello di sessione Limite a livello di frammento GetDASHManifestPlaylist 5 TPS [r] Numero massimo di frammenti per playlist: 5000 [r] GetHLSMasterPlaylist 5 TPS [r] N/D GetHLSMediaPlaylist 5 TPS [r] Numero massimo di frammenti per playlist: 5000 [r] GetMP4InitFragment 5 TPS [r] N/D GetMP4MediaFragment 20 TPS [r] N/D GetTSFragment 20 TPS [r] N/D Quote framment-metadata e fragment-media Kinesis Video Streams APIs per l'accesso ai supporti archiviati sono sottoposte a throttling in base al numero di frammenti richiesti anziché al numero di chiamate API. APIs sono limitate dalla frequenza sia in base al numero di metadati dei frammenti sia in base al numero di supporti dei frammenti richiesti. I metadati del frammento e le quote dei supporti del frammento vengono applicati per flusso. In altre parole, le richieste di metadati di frammento o file multimediali in un flusso non si applicano alle quote di un altro flusso. Tuttavia, all'interno di un determinato flusso, ogni quota è condivisa tra più APIs. Ciò significa che, 170 Amazon Kinesis Video Streams Guida per gli sviluppatori Quote framment-metadata e fragment-media per un determinato flusso, le richieste di frammenti tra APIs diverse utilizzano dalla stessa quota. Quando vengono superati i metadati del frammento o la quota dei file multimediali del frammento per un flusso, l'API restituisce un ClientLimitExceededExceptionvalore . Le tabelle seguenti mostrano come le APIs utilizzano ciascuno dei due tipi di quota. Per la seconda colonna in queste tabelle, supponiamo che se un flusso ha una quota di N, ciò significa che le APIs hanno N punti da consumare da quel tipo di quota per quel flusso. GetClip L'API viene visualizzata in entrambe le tabelle. Utilizzo delle quote dei metadati dei frammenti API Numero di punti di quota utilizzati per richiesta ListFragments Valore del parametro MaxResults GetClip Numero di frammenti nella clip risultante GetHLSMediaPlaylist Valore del parametro MaxMediaPlaylistFragmentResults GetDASHManifest Valore del parametro MaxManifestFragmentResults Consumo della quota media dei frammenti API Numero di punti di quota utilizzati per richiesta GetMediaForFragmentList Numero di frammenti nel parametro Fragments GetClip Numero di frammenti nella clip risultante GetMP4MediaFragment 1 GetTSFragment 1 Ad esempio, con una quota di 500 file multimediali di frammento al secondo, sono supportati i seguenti modelli di chiamata per un determinato flusso: • 5 richieste al secondo a GetClip con 100 frammenti in ogni clip. • 100 richieste al secondo a GetClip con 5 frammenti in ogni clip. • 2 richieste al secondo a GetClip con 100 frammenti in ogni clip e 3 richieste al secondo a GetMediaForFragmentList in ogni clip. • 400 richieste al secondo a GetMP4MediaFragment e 100 richieste al secondo a GetTSFragment. Queste quote hanno un impatto importante sul numero di sessioni HLS e MPEG-DASH che possono essere supportate per flusso. Non vi è alcun limite al numero di sessioni HLS e DASH che possono essere utilizzate dai lettori multimediali in un determinato momento. Pertanto, è importante che l'applicazione di riproduzione non consenta l'utilizzo simultaneo di troppe sessioni. Di seguito sono riportati due esempi di come determinare il numero di sessioni di riproduzione simultanee che possono essere supportate: Esempio 1: streaming in tempo reale In uno scenario di streaming live con HLS con frammenti di durata di 1 secondo, una traccia audio e video e MaxMediaPlaylistFragmentResults impostato su 5, un lettore multimediale in genere effettua 2 chiamate a GetHLSMediaPlaylist al secondo: una chiamata per i metadati video più recenti e un'altra per i metadati audio corrispondenti. Le due chiamate consumano 5 punti di quota di metadati di frammento ciascuna. Inoltre, effettua 2 chiamate a GetMP4MediaFragment al secondo: una chiamata per il video più recente e un'altra per l'audio corrispondente. Queste due chiamate consumano un totale di 2 punti di quota 171 Amazon Kinesis Video Streams Guida per gli sviluppatori Quote framment-metadata e fragment-media dei file multimediali di frammento. In questo scenario, possono essere supportate fino a 125 sessioni di riproduzione simultanee. Con 250 sessioni, questo scenario utilizza 2.500 punti di quota di metadati dei frammenti al secondo (sotto la quota 10.000) e 500 punti di quota dei supporti dei frammenti al secondo. Esempio 2: riproduzione on demand In uno scenario di riproduzione on demand di un evento passato con MPEG-DASH, una traccia audio e video e MaxManifestFragmentResults impostata su 1.000, un lettore multimediale in genere chiama GetDASHManifest una volta all'inizio della sessione (utilizzando 1.000 punti di quota dei metadati dei frammenti) e chiama GetMP4MediaFragment a una velocità di massimo 5 volte al secondo (utilizzando 5 punti di quota dei file multimediali dei frammenti) fino a quando tutti i frammenti non vengono caricati. In questo scenario, possono essere avviate fino a 10 nuove sessioni al secondo (a destra della quota di 10.000 metadati del frammento al secondo) e fino a 100 sessioni possono caricare attivamente i file multimediali del frammento a una velocità di 5 al secondo (a destra della quota di 500 file multimediali del frammento al secondo). È possibile utilizzare ArchivedFragmentsConsumed.Metadata e ArchivedFragmentsConsumed.Media per monitorare il consumo di metadati dei frammenti e punti di quota dei supporti dei frammenti, rispettivamente. Per informazioni sul monitoraggio, consulta Monitoraggio (p. 151). 172 Amazon Kinesis Video Streams Guida per gli sviluppatori Risoluzione dei problemi generali Risoluzione dei problemi di Kinesis Video Streams Utilizzare le informazioni riportate di seguito per risolvere i problemi più comuni riscontrati con Amazon Kinesis Video Streams. Argomenti • Risoluzione dei problemi generali (p. 173) • Risoluzione dei problemi correlati alla configurazione API (p. 173) • Risoluzione dei problemi correlati alla configurazione HLS (p. 175) • Risoluzione dei problemi con Java (p. 177) • Risoluzione dei problemi con la libreria del producer (p. 178) • Risoluzione dei problemi con la libreria parser del flusso (p. 183) Risoluzione dei problemi generali Questa sezione descrive i problemi generali che possono verificarsi durante l'utilizzo di Kinesis Video Streams. Problemi • Latenza troppo elevata (p. 173) Latenza troppo elevata La latenza potrebbe essere causata dalla durata dei frammenti inviati al servizio Kinesis Video Streams. Uno dei modi per ridurre la latenza tra producer e servizio è configurare la pipeline dei file multimediali per ottenere frammenti di più breve durata. Per ridurre il numero di fotogrammi inviati in ciascun frammento, e quindi diminuire la quantità di tempo per ogni frammento, ridurre il valore seguente in kinesis_video_gstreamer_sample_app.cpp: g_object_set(G_OBJECT (data.encoder), "bframes", 0, "key-int-max", 45, "bitrate", 512, NULL); Note Le latenze sono più elevate nel browser Mozilla Firefox a causa dell'implementazione interna del rendering video. Risoluzione dei problemi correlati alla configurazione API Questa sezione descrive i problemi con le API che possono verificarsi durante l'utilizzo di Kinesis Video Streams. 173 Amazon Kinesis Video Streams Guida per gli sviluppatori Errore: "Opzioni sconosciute" Problemi • Errore: "Opzioni sconosciute" (p. 174) • Errore: "Unable to determine service/operation name to be authorized" (Impossibile determinare il nome del servizio/operazione da autorizzare) (p. 174) • Errore: "Failed to put a frame in the stream" (Impossibile inserire un fotogramma nel flusso) (p. 174) • Errore: "Service closed connection before final AckEvent was received" (Connessione chiusa dal servizio prima della ricezione dell'oggetto AckEvent finale) (p. 175) • Errore "STATUS_STORE_OUT_OF_MEMORY" (p. 175) Errore: "Opzioni sconosciute" Se le richieste GetMedia eGetMediaForFragmentList non riescono, può essere generato questo errore: Unknown options: Questo errore si verifica se hai configurato AWS CLI con un tipo output di json. Riconfigurare AWS CLI con il tipo di output predefinito (none). Per ulteriori informazioni sulla configurazione di AWS CLI, consulta configure nella AWS CLI Command Reference. Errore: "Unable to determine service/operation name to be authorized" (Impossibile determinare il nome del servizio/operazione da autorizzare) Se la richiesta GetMedia non riesce, può essere generato questo errore: Unable to determine service/operation name to be authorized Questo errore può verificarsi se l'endpoint non è specificato correttamente. Nella richiesta dell'endpoint, assicurarsi di includere il seguente parametro nella chiamata GetDataEndpoint (a seconda dell'API da chiamare): --api-name GET_MEDIA --api-name PUT_MEDIA --api-name GET_MEDIA_FOR_FRAGMENT_LIST --api-name LIST_FRAGMENTS Errore: "Failed to put a frame in the stream" (Impossibile inserire un fotogramma nel flusso) Se la richiesta PutMedia non riesce, può essere generato questo errore: Failed to put a frame in the stream Questo errore può verificarsi se la connettività o le autorizzazioni non sono disponibili per il servizio. Eseguire quanto riportato più avanti nella AWS CLI e verificare che sia possibile recuperare le informazioni sul flusso: 174 Amazon Kinesis Video Streams Guida per gli sviluppatori Errore: "Service closed connection before final AckEvent was received" (Connessione chiusa dal servizio prima della ricezione dell'oggetto AckEvent finale) aws kinesisvideo describe-stream --stream-name StreamName --endpoint https:// ServiceEndpoint.kinesisvideo.region.amazonaws.com Se la chiamata ha esito negativo, consultare la sezione relativa alla risoluzione degli errori dell'AWS CLI per ulteriori informazioni. Errore: "Service closed connection before final AckEvent was received" (Connessione chiusa dal servizio prima della ricezione dell'oggetto AckEvent finale) Se la richiesta PutMedia non riesce, può essere generato questo errore: com.amazonaws.SdkClientException: Service closed connection before final AckEvent was received Questo errore può verificarsi se l'elemento PushbackInputStream non è implementato correttamente. Verificare che i metodi unread() siano implementati correttamente. Errore "STATUS_STORE_OUT_OF_MEMORY" Se la richiesta PutMedia non riesce, può essere generato questo errore: The content store is out of memory. Questo errore si verifica quando allo store dei contenuti non è allocato spazio a sufficienza. Per ovviare, aumentare il valore di StorageInfo.storageSize. Per ulteriori informazioni, consulta StorageInfo (p. 103). Risoluzione dei problemi correlati alla configurazione HLS In questa sezione vengono descritti i problemi che potresti riscontrare usando HTTP Live Streaming (HLS) con Kinesis Video Streams. Problemi • Il recupero dell'URL della sessione di streaming HLS riesce, ma si verifica un problema di riproduzione nel lettore video (p. 176) • Latenza troppo elevata tra il producer e il lettore (p. 176) 175 Amazon Kinesis Video Streams Guida per gli sviluppatori Il recupero dell'URL della sessione di streaming HLS riesce, ma si verifica un problema di riproduzione nel lettore video Il recupero dell'URL della sessione di streaming HLS riesce, ma si verifica un problema di riproduzione nel lettore video Questa situazione si verifica quando è possibile recuperare correttamente l'URL di una sessione di streaming HLS usando GetHLSStreamingSessionURL, ma non è possibile riprodurre il video fornendo l'URL a un lettore video. Per risolvere questo problema, prova le soluzioni seguenti: • Determina se il flusso video si può riprodurre nella console Kinesis Video Streams. Esamina gli errori visualizzati nella console. • Se la durata del frammento è meno di un secondo, aumentala a un secondo. Se la durata del frammento è troppo breve, il servizio potrebbe limitare il lettore a causa della frequenza troppo elevata delle richieste di frammenti video. • Verificare che ogni URL di una sessione di streaming HLS venga usato da un solo lettore. Se più di un lettore usa un singolo URL di una sessione di streaming HLS, il servizio potrebbe ricevere troppe richieste e limitarle. • Verifica che il lettore supporti tutte le opzioni specificate per la sessione di streaming HLS. Prova combinazioni diverse di valori per i parametri seguenti: • ContainerFormat • PlaybackMode • FragmentSelectorType • DiscontinuityMode • MaxMediaPlaylistFragmentResults Alcuni lettori multimediali (ad esempio HTML5 e lettori mobile) in genere supportano solo HLS con il formato container fMP4. Altri lettori multimediali (ad esempio Flash e lettori personalizzati) supportano solo HLS con il formato container MPEG TS. Eseguire esperimenti con il parametro ContainerFormat è un buon modo per iniziare a risolvere i problemi. • Verificare che ogni frammento abbia un numero consistente di tracce. Verificare che i frammenti nel flusso non cambino tra avere sia un brano audio e video e solo una traccia video. Verificare inoltre che le impostazioni dell'encoder (risoluzione, frequenza dei frame e così via) non siano mutevoli tra frammenti in ogni traccia. Latenza troppo elevata tra il producer e il lettore Questa situazione si verifica quando vi è una latenza troppo elevata dal momento dell'acquisizione del video alla sua riproduzione nel lettore. Il video viene riprodotto tramite HLS frammento per frammento. Pertanto, la latenza non può essere inferiore alla durata dei frammenti. La latenza include anche il tempo necessario per il buffering e il trasferimento dei dati. Se la soluzione richiede una latenza inferiore a un secondo, usa l'API GetMedia. È possibile modificare i parametri seguenti per ridurre la latenza complessiva, ma la modifica di questi parametri potrebbe comportare anche la riduzione della qualità video o l'aumento della frequenza di ripetizione del buffering. • Durata dei frammenti: la durata di un frammento è la quantità di video tra divisioni nel flusso controllata dalla frequenza dei fotogrammi chiave generati dal codificatore video. Il valore consigliato è di un secondo. Una durata inferiore dei frammenti significa meno tempo di attesa per il completamento del 176 Amazon Kinesis Video Streams Guida per gli sviluppatori Risoluzione dei problemi con Java frammento prima della trasmissione dei dati video al servizio. I frammenti più brevi vengono anche elaborati più velocemente dal servizio. Tuttavia, se la durata di frammento è troppo breve, aumentano le probabilità che il lettore esaurisca i contenuti e debba arrestarsi ed eseguire il buffering di altri contenuti. Se la durata del frammento è meno di 500 millisecondi, il producer potrebbe creare troppe richieste, che potrebbero pertanto essere limitate dal servizio. • Velocità in bit: un flusso video con una velocità in bit inferiore richiede meno tempo per la lettura, la scrittura e la trasmissione. Tuttavia, un flusso video con una velocità in bit inferiore ha in genere una qualità video inferiore. • Numero di frammenti nelle playlist multimediali: un lettore sensibile alla latenza deve caricare solo i frammenti più recenti in una playlist multimediale. La maggior parte dei lettori, tuttavia, inizia dai frammenti meno recenti. Riducendo il numero di frammenti nella playlist, è possibile ridurre la separazione temporale tra frammenti meno recenti e più recenti. Con una playlist di dimensioni più piccole, un frammento può venire ignorato durante la riproduzione se si verifica un ritardo nell'aggiunta di nuovi frammenti alla playlist oppure un ritardo del lettore nel recupero di una playlist aggiornata. È consigliabile usare 3–5 frammenti e un lettore configurato per caricare solo i frammenti più recenti di una playlist. • Dimensioni del buffer del lettore: la maggior parte dei lettori video prevede una durata del buffer minima configurabile, in genere con un valore predefinito di 10 secondi. Per ottenere la latenza più bassa, è possibile impostare questo valore su 0 secondi. Tuttavia, in questo caso il lettore ripeterà il buffering in caso di ritardo nella produzione dei frammenti, perché non ha un buffer per assorbire il ritardo. • "Recupero" del lettore: i lettori video in genere non recuperano la riproduzione fino a raggiungere la parte inziale del buffer video se il buffer si riempie, ad esempio quando un frammento ritardato genera un backlog di frammenti da riprodurre. Un lettore personalizzato consente di evitare questa situazione, eliminando i fotogrammi o aumentando la velocità di riproduzione (ad esempio a 1,1x) per raggiungere la parte iniziale del buffer. Ciò causa una riproduzione irregolare o un aumento della velocità mentre il lettore recupera e la ripetizione del buffering potrebbe avvenire con maggiore frequenza se le dimensioni del buffer sono contenute. Risoluzione dei problemi con Java Questa sezione descrive come risolvere i problemi più comuni riscontrati con Java nell'utilizzo di Kinesis Video Streams. Problemi • Abilitazione dei log di Java (p. 177) Abilitazione dei log di Java Per risolvere i problemi con gli esempi e le librerie di Java, è utile abilitare ed esaminare i log di debug. Per abilitarli, procedere come segue: 1. Aggiungere log4j al file pom.xml nel nodo dependencies: 2. Nella directory target/classes, creare un file denominato log4j.properties con il seguente contenuto: # Root logger option 177 Amazon Kinesis Video Streams Guida per gli sviluppatori Risoluzione dei problemi con la libreria del producer log4j.rootLogger=DEBUG, stdout # Redirect log messages to console log4j.appender.stdout=org.apache.log4j.ConsoleAppender log4j.appender.stdout.Target=System.out log4j.appender.stdout.layout=org.apache.log4j.PatternLayout log4j.appender.stdout.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n log4j.logger.org.apache.http.wire=DEBUG I log di debug vengono quindi stampati nella console IDE. Risoluzione dei problemi con la libreria del producer Questa sezione descrive i problemi che possono verificarsi durante l'utilizzo della Producer Library (p. 46). Problemi • Impossibile compilare l'SDK producer (p. 178) • Il flusso video non viene visualizzato nella console (p. 179) • Errore "Security token included in the request is invalid" durante lo streaming dei dati con l'applicazione demo GStreamer (p. 179) • Errore "Failed to submit frame to Kinesis Video client" (p. 179) • L'applicazione GStreamer viene arrestata con il messaggio "streaming stopped, reason not-negotiated" su OS X (p. 180) • Errore "Failed to allocate heap" durante la creazione del client Kinesis Video nella demo GStreamer su Raspberry Pi (p. 180) • Errore "Illegal Instruction" durante l'esecuzione della demo GStreamer su Raspberry Pi (p. 180) • La videocamera non viene caricata su Raspberry Pi (p. 180) • Impossibile trovare la videocamera su macOS High Sierra (p. 181) • File jni.h non trovato durante la compilazione su macOS High Sierra (p. 181) • Errori di curl durante l'esecuzione dell'applicazione demo GStreamer (p. 181) • Asserzione timestamp/intervallo in fase di runtime su Raspberry Pi (p. 181) • Asserzione su gst_value_set_fraction_range_full su Raspberry Pi (p. 182) • STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATA (0x3200000d) error on Android (p. 182) • Errore di durata massima del frammento raggiunta (p. 182) • Errore "Invalid thing name passed (Passato nome di cosa non valido)" quando si utilizza l'autorizzazione IoT (p. 183) Impossibile compilare l'SDK producer Controllare che le librerie richieste siano presenti nel percorso. Per eseguire una verifica, utilizzare il comando seguente: $ env | grep LD_LIBRARY_PATH LD_LIBRARY_PATH=/home/local/awslabs/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis- video-native-build/downloads/local/lib 178 Amazon Kinesis Video Streams Guida per gli sviluppatori Il flusso video non viene visualizzato nella console Il flusso video non viene visualizzato nella console Perché sia visualizzato nella console, il flusso video deve essere codificato con H.264 nel formato AvCC. Se il flusso non viene visualizzato, verificare quanto segue: • I Flag di adattamento del NAL (p. 101) sono impostati su NAL_ADAPTATION_ANNEXB_NALS | NAL_ADAPTATION_ANNEXB_CPD_NALS se il flusso originale è in formato Annex-B. Questo è il valore di default nel costruttore StreamDefinition. • I dati privati del codec sono forniti correttamente. Per H.264, si tratta del set di parametri di sequenza (SPS) e del set di parametri delle immagini (PPS). A seconda dell'origine del contenuto multimediale, questi dati potrebbero essere recuperati dall'origine separatamente o codificati nel fotogramma. Molti flussi elementari sono nel formato seguente, dove Ab è il codice di inizio (001 o 0001) Annex-B: Ab(Sps)Ab(Pps)Ab(I-frame)Ab(P/B-frame) Ab(P/B-frame)…. Ab(Sps)Ab(Pps)Ab(I-frame)Ab(P/B- frame) Ab(P/B-frame) I dati privati del codec (CPD) che, nel caso della codifica H.264, sono impostati nel flusso come SPS e PPS, possono essere adattati al formato AvCC. A meno che la pipeline multimediale non fornisca i CPD separatamente, l'applicazione è in grado di estrarli dal fotogramma cercando il primo fotogramma Idr (che dovrebbe contenere i parametri SPS/PPS), estraendo le due NALU (che saranno Ab(Sps)Ab(Pps)) e impostandolo nei CPD in StreamDefinition. Errore "Security token included in the request is invalid" durante lo streaming dei dati con l'applicazione demo GStreamer Questo errore indica che è presente un problema con le credenziali. Verificare quanto segue: • Se si utilizzano credenziali di sicurezza temporanee, è necessario specificare il token di sessione. • Verificare che le credenziali temporanee non siano scadute. • Verificare che siano impostati gli opportuni diritti. • Su macOS, verificare che non vi siano credenziali memorizzate nella cache in Keychain. Errore "Failed to submit frame to Kinesis Video client" Questo errore indica che i timestamp non sono impostati in modo corretto nel flusso sorgente. Eseguire quanto segue: • Utilizzare l'SDK di esempio più recente, che potrebbe includere un aggiornamento per la risoluzione del problema. • Impostare il flusso di alta qualità a un bit rate superiore e risolvere eventuali instabilità nel flusso di origine, se la videocamera lo supporta. 179 Amazon Kinesis Video Streams Guida per gli sviluppatori L'applicazione GStreamer viene arrestata con il messaggio "streaming stopped, reason not-negotiated" su OS X L'applicazione GStreamer viene arrestata con il messaggio "streaming stopped, reason not-negotiated" su OS X Lo streaming potrebbe essere arrestato su OS X con il seguente messaggio: Debugging information: gstbasesrc.c(2939): void gst_base_src_loop(GstPad *) (): / GstPipeline:test-pipeline/GstAutoVideoSrc:source/GstAVFVideoSrc:source-actual-src-avfvide: streaming stopped, reason not-negotiated (-4) Una possibile soluzione per questo problema è rimuovere i parametri relativi al framerate dalla chiamata gst_caps_new_simple in kinesis_video_gstreamer_sample_app.cpp: GstCaps *h264_caps = gst_caps_new_simple("video/x-h264", "profile", G_TYPE_STRING, "baseline", "stream-format", G_TYPE_STRING, "avc", "alignment", G_TYPE_STRING, "au", "width", GST_TYPE_INT_RANGE, 320, 1920, "height", GST_TYPE_INT_RANGE, 240, 1080, "framerate", GST_TYPE_FRACTION_RANGE, 0, 1, 30, 1, NULL); Errore "Failed to allocate heap" durante la creazione del client Kinesis Video nella demo GStreamer su Raspberry Pi L'applicazione di esempio GStreamer cerca di allocare 512 MB di RAM, che potrebbero non essere disponibili nel sistema. È possibile diminuire tale allocazione riducendo il seguente valore in KinesisVideoProducer.cpp: device_info.storageInfo.storageSize = 512 * 1024 * 1024; Errore "Illegal Instruction" durante l'esecuzione della demo GStreamer su Raspberry Pi Se si verifica il seguente errore durante l'esecuzione della demo GStreamer, accertarsi di aver compilato l'applicazione per la versione corretta del dispositivo. Ad esempio, assicurarsi di non eseguire la compilazione per Raspberry Pi 3 se è in esecuzione Raspberry Pi 2. INFO - Initializing curl. Illegal instruction La videocamera non viene caricata su Raspberry Pi Per controllare se la videocamera viene caricata, eseguire quanto segue: $ ls /dev/video* 180 Amazon Kinesis Video Streams Guida per gli sviluppatori Impossibile trovare la videocamera su macOS High Sierra Se l'operazione non ha esito, eseguire quanto segue: $ vcgencmd get_camera L'output visualizzato dovrebbe essere simile al seguente: supported=1 detected=1 Se il driver non rileva la videocamera, procedere come segue: 1. Controllare la configurazione fisica della videocamera e verificare che sia collegata correttamente. 2. Eseguire quanto segue per aggiornare il firmware: $ sudo rpi-update 3. Riavviare il dispositivo. 4. Eseguire quanto segue per caricare il driver: $ sudo modprobe bcm2835-v4l2 5. Verificare che la videocamera sia stata rilevata: $ ls /dev/video* Impossibile trovare la videocamera su macOS High Sierra Su macOS High Sierra, l'applicazione demo non è in grado di trovare la videocamera se ne è disponibile più di una. File jni.h non trovato durante la compilazione su macOS High Sierra Per risolvere questo errore, aggiornare l'installazione di Xcode alla versione più recente. Errori di curl durante l'esecuzione dell'applicazione demo GStreamer Per risolvere gli errori di curl durante l'esecuzione dell'applicazione demo GStreamer, copiare questo file di certificato in /etc/ssl/cert.pem. Asserzione timestamp/intervallo in fase di runtime su Raspberry Pi Se si verifica un'asserzione di intervallo timestamp in fase di runtime, aggiornare il firmware e riavviare il dispositivo: 181 Amazon Kinesis Video Streams Guida per gli sviluppatori Asserzione su gst_value_set_fraction_range_full su Raspberry Pi $ sudo rpi-update $ sudo reboot Asserzione su gst_value_set_fraction_range_full su Raspberry Pi La seguente asserzione viene visualizzata se è in esecuzione il servizio uv4l: gst_util_fraction_compare (numerator_start, denominator_start, numerator_end, denominator_end) < 0' failed In questo caso, interrompere il servizio uv4l e riavviare l'applicazione. STATUS_MKV_INVALID_ANNEXB_NALU_IN_FRAME_DATA (0x3200000d) error on Android Il seguente errore viene visualizzato se Flag di adattamento del NAL (p. 101) non sono corretti per il flusso di file multimediali: putKinesisVideoFrame(): Failed to put a frame with status code 0x3200000d Se si verifica questo errore, specificare il flag .withNalAdaptationFlags corretto per i file multimediali (ad esempio, NAL_ADAPTATION_ANNEXB_CPD_NALS). Fornire questo flag nella seguente riga di Android Producer Library (p. 51): https://github.com/awslabs/aws-sdk-android-samples/blob/master/AmazonKinesisVideoDemoApp/src/main/ java/com/amazonaws/kinesisvideo/demoapp/fragment/StreamConfigurationFragment.java#L169 Errore di durata massima del frammento raggiunta Questo errore si verifica quando un frammenti di file multimediale in un flusso supera il limite massimo di durata. Per impostazione predefinita, Kinesis Streams imposta la durata massima del frammento di un flusso su 10 secondi. Per risolvere il problema, prova a eseguire queste operazioni: • Se stai usando una webcam/fotocamera USB, procedi in uno dei seguenti modi: • Se stai usando la frammentazione basata su keyframe, imposta il codificatore per fornire keyframe entro 10 secondi. • Se non utilizzi la frammentazione basata su keyframe, quando definisci il flusso nella Fase 2: scrittura e analisi del codice (p. 59), imposta il limite di durata massima del frammento su un valore inferiore a 10 secondi. • Se stai usando codificatori software (ad esempio x264) nella pipeline GStreamer, puoi impostare l'attributo key-int-max su un valore compreso entro i 10 secondi (per esempio, imposta key-int-max su 60, con fps impostato su 30 per abilitare i keyframe ogni 2 secondi). • Se stai usando una fotocamera RPI, imposta l’attributo eyframe-interval su un valore inferiore a 10 secondi. • Se stai usando una fotocamera IP (RTSP), imposta la dimensione GOP su 60. 182 Amazon Kinesis Video Streams Guida per gli sviluppatori Errore "Invalid thing name passed (Passato nome di cosa non valido)" quando si utilizza l'autorizzazione IoT Errore "Invalid thing name passed (Passato nome di cosa non valido)" quando si utilizza l'autorizzazione IoT Per evitare questo errore (HTTP Error 403: Response: {"message":"Invalid thing name passed"}) quando utilizzo le credenziali IoT per l'autorizzazione, fai in modo che il valore di stream- name (un parametro obbligatorio dell'elemento kvssink) sia identico al valore di iot-thingname. Per ulteriori informazioni, consulta Riferimento ai parametri degli elementiGStreamer (p. 135). Risoluzione dei problemi con la libreria parser del flusso Questa sezione descrive i problemi che possono verificarsi durante l'utilizzo della Libreria parser del flusso (p. 121). Problemi • Impossibile accedere a un singolo fotogramma del flusso (p. 183) • Errore di decodifica frammento (p. 183) Impossibile accedere a un singolo fotogramma del flusso Per accedere a un singolo fotogramma da una sorgente di streaming nell'applicazione consumer, accertarsi che il flusso contenga i corretti dati privati del codec. Per informazioni sul formato dei dati in un flusso, consultare Modello di dati (p. 18). Per ulteriori informazioni su come utilizzare i dati privati del codec per accedere a un fotogramma, consultare il seguente file di prova sul sito Web di GitHub: KinesisVideoRendererExampleTest.java Errore di decodifica frammento Se i frammenti non sono correttamente codificati in un formato H.264 e in un livello supportato dal browser, durante la riproduzione del flusso nella console può essere generato il seguente errore: Fragment Decoding Error There was an error decoding the video data. Verify that the stream contains valid H.264 content In questo caso, verificare quanto segue: • La risoluzione dei fotogrammi corrisponde alla risoluzione specificata nei dati privati del codec (Codec Private Data). • Il profilo e il livello H.264 dei fotogrammi codificati corrispondono al profilo e al livello specificati nei dati privati del codec (Codec Private Data). • Il browser supporta la combinazione profilo/livello. La maggior parte dei browser attuali supporta tutte le combinazioni di profilo e livello. • I timestamp sono accurati e nell'ordine corretto, senza creazione di duplicati in corso. 183 Amazon Kinesis Video Streams Guida per gli sviluppatori Errore di decodifica frammento • L'applicazione codifica i dati dei fotogrammi utilizzando il formato H.264. 184 Amazon Kinesis Video Streams Guida per gli sviluppatori Cronologia documento per Amazon Kinesis Video Streams Nella tabella seguente vengono descritte le modifiche importanti apportate alla documentazione dall'ultima versione di Amazon Kinesis Video Streams. • Versione API più recente: 2017-11-29 • Ultimo aggiornamento della documentazione: 21 gennaio 2019 Modifica Descrizione Data Nozioni di base: invio di dati a un Tutorial di base per l'invio di dati 21 gennaio 2019 Kinesis video stream multimediali da una fotocamera a Kinesis video stream. Per ulteriori informazioni, consulta Fase 3: invio dei dati al flusso video Kinesis (p. 27). Modello di libreria per Applicazione di esempio 19 novembre 2018 l'integrazione con SageMaker per Kinesis Video Streams che utilizza SageMaker per identificare quando determinati oggetti appaiono in uno stream video di Amazon Kinesis. Per ulteriori informazioni, consulta SageMaker (p. 144). Streaming di metadati Puoi utilizzare Producer SDK 28 settembre 2018 per incorporare i metadati in un Kinesis video stream. Per ulteriori informazioni, consulta Utilizzo dei metadati di streaming con Kinesis Video Streams (p. 15). Logging di C++ Producer SDK Puoi configurare il logging per 18 luglio 2018 le applicazioni C++ Producer SDK. Per ulteriori informazioni, consulta Uso del logging con l'SDK di C++ Producer (p. 65). Streaming di video HLS Ora puoi visualizzare un 13 luglio 2018 Kinesis video stream usando lo streaming in tempo reale HTTP. Per ulteriori informazioni, consulta Riproduzione Kinesis Video Streams (p. 9). Streaming da un'origine RTSP Applicazione di esempio per 20 giugno 2018 Kinesis Video Streams eseguita in un container Docker e video in streaming da un'origine 185 Amazon Kinesis Video Streams Guida per gli sviluppatori Modifica Descrizione Data RTSP. Per ulteriori informazioni, consulta RTSP e Docker (p. 141). Plugin C++ Producer SDK Mostra come creare un C+ 15 giugno 2018 GStreamer + Producer Library (p. 56) da utilizzare come destinazione GStreamer. Per ulteriori informazioni, consulta GStreamer (p. 129). Documentazione di riferimento Documentazione di riferimento 12 giugno 2018 sui callback dell'SDK producer per i callback utilizzati da Kinesis Video Streams Producer Library (p. 46). Per ulteriori informazioni, consulta Callback dell'SDK Producer (p. 115). Requisiti di sistema Documentazione relativa 30 maggio 2018 ai requisiti di memoria e di storage per i dispositivi producer e SDK. Per ulteriori informazioni, consulta Kinesis Video StreamsRequisiti di sistema di (p. 3). Supporto CloudTrail Documentazione per l'utilizzo di 24 maggio 2018 CloudTrail per il monitoraggio dell'utilizzo delle API. Per ulteriori informazioni, consulta Registrazione di chiamate dell'API di Kinesis Video Streams con AWS CloudTrail (p. 162). Documentazione di riferimento Documentazione di riferimento 7 maggio 2018 sulle strutture SDK producer per le strutture utilizzate da Kinesis Video Streams Producer Library (p. 46). Per ulteriori informazioni, consulta Strutture dell'SDK producer (p. 102) e KinesisStrutture di flussi video di (p. 104). Documentazione di esempio di Documentazione per 15 marzo 2018 Renderer l'applicazione di esempio Renderer, che mostra come decodificare e visualizzare i frame da un Kinesis video stream. Per ulteriori informazioni, consulta Esempio: analisi e rendering dei frammenti Kinesis Video Streams (p. 142). 186 Amazon Kinesis Video Streams Guida per gli sviluppatori Modifica Descrizione Data Documentazione di riferimento Le informazioni sui limiti per 13 marzo 2018 sui limiti dell'SDK producer le operazioni in C++ Producer Library (p. 56). Per ulteriori informazioni, consulta Limiti dell'SDK producer (p. 72). Monitoraggio Informazioni sui parametri di 5 febbraio 2018 monitoraggio Kinesis Video Streams e le chiamate API utilizzando Amazon CloudWatch e AWS CloudTrail. Per ulteriori informazioni, consulta Monitoraggio di Kinesis Video Streams (p. 151). Documentazione di riferimento Informazioni sull'impostazione 15 gennaio 2018 per i flag di adattamento del dei flag di adattamento NAL Network Abstraction Layer (NAL) nell'utilizzo di streaming di video. Per ulteriori informazioni, consulta Flag di adattamento del NAL (p. 101). Supporto Android per lo Kinesis Video Streams ora 12 gennaio 2018 streaming di video supporta lo streaming di video dai dispositivi Android. Per ulteriori informazioni, consulta Android Producer Library (p. 51). KinesisDocumentazione di Documentazione per 9 gennaio 2018 esempio video di l'applicazione di esempio video di Kinesis, che mostra come utilizzare la Libreria parser del flusso video Kinesis (p. 121) in un'applicazione. Per ulteriori informazioni, consulta KinesisVideoExample (p. 125). Kinesis Video StreamsRilascio Rilascio iniziale della Developer 29 Novembre 2017 della documentazione di Guide di Amazon Kinesis Video Streams. 187 Amazon Kinesis Video Streams Guida per gli sviluppatori Actions Riferimento alle API Le sezioni di questo nodo contengono la documentazione di riferimento delle API di . Utilizza il sommario nel riquadro a sinistra per andare alle diverse sezioni di riferimento dell'API. Actions The following actions are supported by Amazon Kinesis Video Streams: • CreateSignalingChannel (p. 190) • CreateStream (p. 193) • DeleteSignalingChannel (p. 197) • DeleteStream (p. 200) • DescribeSignalingChannel (p. 203) • DescribeStream (p. 206) • GetDataEndpoint (p. 209) • GetSignalingChannelEndpoint (p. 212) • ListSignalingChannels (p. 215) • ListStreams (p. 218) • ListTagsForResource (p. 221) • ListTagsForStream (p. 224) • TagResource (p. 227) • TagStream (p. 229) • UntagResource (p. 232) • UntagStream (p. 234) • UpdateDataRetention (p. 237) • UpdateSignalingChannel (p. 240) • UpdateStream (p. 243) The following actions are supported by Amazon Kinesis Video Streams Media: • GetMedia (p. 247) • PutMedia (p. 251) The following actions are supported by Amazon Kinesis Video Streams Archived Media: • GetClip (p. 258) • GetDASHStreamingSessionURL (p. 262) • GetHLSStreamingSessionURL (p. 269) • GetMediaForFragmentList (p. 277) • ListFragments (p. 281) Amazon Kinesis Video Streams The following actions are supported by Amazon Kinesis Video Streams: 188 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • CreateSignalingChannel (p. 190) • CreateStream (p. 193) • DeleteSignalingChannel (p. 197) • DeleteStream (p. 200) • DescribeSignalingChannel (p. 203) • DescribeStream (p. 206) • GetDataEndpoint (p. 209) • GetSignalingChannelEndpoint (p. 212) • ListSignalingChannels (p. 215) • ListStreams (p. 218) • ListTagsForResource (p. 221) • ListTagsForStream (p. 224) • TagResource (p. 227) • TagStream (p. 229) • UntagResource (p. 232) • UntagStream (p. 234) • UpdateDataRetention (p. 237) • UpdateSignalingChannel (p. 240) • UpdateStream (p. 243) 189 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams CreateSignalingChannel Service: Amazon Kinesis Video Streams Creates a signaling channel. CreateSignalingChannel is an asynchronous operation. Request Syntax POST /createSignalingChannel HTTP/1.1 Content-type: application/json { "ChannelName": "string", "ChannelType": "string", "SingleMasterConfiguration": { "MessageTtlSeconds": number }, "Tags": [ { "Key": "string", "Value": "string" } ] } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ChannelName (p. 190) A name for the signaling channel that you are creating. It must be unique for each AWS account and AWS Region. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: Yes ChannelType (p. 190) A type of the signaling channel that you are creating. Currently, SINGLE_MASTER is the only supported channel type. Type: String Valid Values: SINGLE_MASTER | FULL_MESH Required: No SingleMasterConfiguration (p. 190) A structure containing the configuration for the SINGLE_MASTER channel type. 190 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Type: SingleMasterConfiguration (p. 291) object Required: No Tags (p. 190) A set of tags (key-value pairs) that you want to associate with this channel. Type: Array of Tag (p. 295) objects Array Members: Minimum number of 0 items. Maximum number of 50 items. Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "ChannelARN": "string" } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. ChannelARN (p. 191) The Amazon Resource Name (ARN) of the created channel. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 AccountChannelLimitExceededException You have reached the maximum limit of active signaling channels for this AWS account in this region. HTTP Status Code: 400 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. 191 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 TagsPerResourceExceededLimitException You have exceeded the limit of tags that you can associate with the resource. Kinesis video streams support up to 50 tags. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 192 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams CreateStream Service: Amazon Kinesis Video Streams Creates a new Kinesis video stream. When you create a new stream, Kinesis Video Streams assigns it a version number. When you change the stream's metadata, Kinesis Video Streams updates the version. CreateStream is an asynchronous operation. For information about how the service works, see How it Works. You must have permissions for the KinesisVideo:CreateStream action. Request Syntax POST /createStream HTTP/1.1 Content-type: application/json { "DataRetentionInHours": number, "DeviceName": "string", "KmsKeyId": "string", "MediaType": "string", "StreamName": "string", "Tags": { "string" : "string" } } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. DataRetentionInHours (p. 193) The number of hours that you want to retain the data in the stream. Kinesis Video Streams retains the data in a data store that is associated with the stream. The default value is 0, indicating that the stream does not persist data. When the DataRetentionInHours value is 0, consumers can still consume the fragments that remain in the service host buffer, which has a retention time limit of 5 minutes and a retention memory limit of 200 MB. Fragments are removed from the buffer when either limit is reached. Type: Integer Valid Range: Minimum value of 0. Required: No DeviceName (p. 193) The name of the device that is writing to the stream. Note In the current implementation, Kinesis Video Streams does not use this name. 193 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: [a-zA-Z0-9_.-]+ Required: No KmsKeyId (p. 193) The ID of the AWS Key Management Service (AWS KMS) key that you want Kinesis Video Streams to use to encrypt stream data. If no key ID is specified, the default, Kinesis Video-managed key (aws/kinesisvideo) is used. For more information, see DescribeKey. Type: String Length Constraints: Minimum length of 1. Maximum length of 2048. Pattern: .+ Required: No MediaType (p. 193) The media type of the stream. Consumers of the stream can use this information when processing the stream. For more information about media types, see Media Types. If you choose to specify the MediaType, see Naming Requirements for guidelines. Example valid values include "video/h264" and "video/h264,audio/aac". This parameter is optional; the default value is null (or empty in JSON). Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: [\w\-\.\+]+/[\w\-\.\+]+(,[\w\-\.\+]+/[\w\-\.\+]+)* Required: No StreamName (p. 193) A name for the stream that you are creating. The stream name is an identifier for the stream, and must be unique for each account and region. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: Yes Tags (p. 193) A list of tags to associate with the specified stream. Each tag is a key-value pair (the value is optional). Type: String to string map Map Entries: Maximum number of 50 items. Key Length Constraints: Minimum length of 1. Maximum length of 128. 194 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Value Length Constraints: Minimum length of 0. Maximum length of 256. Value Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]* Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "StreamARN": "string" } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. StreamARN (p. 195) The Amazon Resource Name (ARN) of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccountStreamLimitExceededException The number of streams created for the account is too high. HTTP Status Code: 400 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 DeviceStreamLimitExceededException Not implemented. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. 195 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams HTTP Status Code: 400 InvalidDeviceException Not implemented. HTTP Status Code: 400 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 TagsPerResourceExceededLimitException You have exceeded the limit of tags that you can associate with the resource. Kinesis video streams support up to 50 tags. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 196 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams DeleteSignalingChannel Service: Amazon Kinesis Video Streams Deletes a specified signaling channel. DeleteSignalingChannel is an asynchronous operation. If you don't specify the channel's current version, the most recent version is deleted. Request Syntax POST /deleteSignalingChannel HTTP/1.1 Content-type: application/json { "ChannelARN": "string", "CurrentVersion": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ChannelARN (p. 197) The Amazon Resource Name (ARN) of the signaling channel that you want to delete. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: Yes CurrentVersion (p. 197) The current version of the signaling channel that you want to delete. You can obtain the current version by invoking the DescribeSignalingChannel or ListSignalingChannels API operations. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: No Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. 197 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 VersionMismatchException The stream version that you specified is not the latest version. To get the latest version, use the DescribeStream API. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 198 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams 199 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams DeleteStream Service: Amazon Kinesis Video Streams Deletes a Kinesis video stream and the data contained in the stream. This method marks the stream for deletion, and makes the data in the stream inaccessible immediately. To ensure that you have the latest version of the stream before deleting it, you can specify the stream version. Kinesis Video Streams assigns a version to each stream. When you update a stream, Kinesis Video Streams assigns a new version number. To get the latest stream version, use the DescribeStream API. This operation requires permission for the KinesisVideo:DeleteStream action. Request Syntax POST /deleteStream HTTP/1.1 Content-type: application/json { "CurrentVersion": "string", "StreamARN": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. CurrentVersion (p. 200) Optional: The version of the stream that you want to delete. Specify the version as a safeguard to ensure that your are deleting the correct stream. To get the stream version, use the DescribeStream API. If not specified, only the CreationTime is checked before deleting the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: No StreamARN (p. 200) The Amazon Resource Name (ARN) of the stream that you want to delete. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ 200 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Required: Yes Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 VersionMismatchException The stream version that you specified is not the latest version. To get the latest version, use the DescribeStream API. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: 201 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 202 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams DescribeSignalingChannel Service: Amazon Kinesis Video Streams Returns the most current information about the signaling channel. You must specify either the name or the Amazon Resource Name (ARN) of the channel that you want to describe. Request Syntax POST /describeSignalingChannel HTTP/1.1 Content-type: application/json { "ChannelARN": "string", "ChannelName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ChannelARN (p. 203) The ARN of the signaling channel that you want to describe. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No ChannelName (p. 203) The name of the signaling channel that you want to describe. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "ChannelInfo": { "ChannelARN": "string", "ChannelName": "string", "ChannelStatus": "string", 203 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams "ChannelType": "string", "CreationTime": number, "SingleMasterConfiguration": { "MessageTtlSeconds": number }, "Version": "string" } } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. ChannelInfo (p. 203) A structure that encapsulates the specified signaling channel's metadata and properties. Type: ChannelInfo (p. 286) object Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript 204 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 205 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams DescribeStream Service: Amazon Kinesis Video Streams Returns the most current information about the specified stream. You must specify either the StreamName or the StreamARN. Request Syntax POST /describeStream HTTP/1.1 Content-type: application/json { "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. StreamARN (p. 206) The Amazon Resource Name (ARN) of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 206) The name of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "StreamInfo": { "CreationTime": number, "DataRetentionInHours": number, "DeviceName": "string", 206 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams "KmsKeyId": "string", "MediaType": "string", "Status": "string", "StreamARN": "string", "StreamName": "string", "Version": "string" } } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. StreamInfo (p. 206) An object that describes the stream. Type: StreamInfo (p. 292) object Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript 207 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 208 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams GetDataEndpoint Service: Amazon Kinesis Video Streams Gets an endpoint for a specified stream for either reading or writing. Use this endpoint in your application to read from the specified stream (using the GetMedia or GetMediaForFragmentList operations) or write to it (using the PutMedia operation). Note The returned endpoint does not have the API name appended. The client needs to add the API name to the returned endpoint. In the request, specify the stream either by StreamName or StreamARN. Request Syntax POST /getDataEndpoint HTTP/1.1 Content-type: application/json { "APIName": "string", "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. APIName (p. 209) The name of the API action for which to get an endpoint. Type: String Valid Values: PUT_MEDIA | GET_MEDIA | LIST_FRAGMENTS | GET_MEDIA_FOR_FRAGMENT_LIST | GET_HLS_STREAMING_SESSION_URL | GET_DASH_STREAMING_SESSION_URL | GET_CLIP Required: Yes StreamARN (p. 209) The Amazon Resource Name (ARN) of the stream that you want to get the endpoint for. You must specify either this parameter or a StreamName in the request. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No 209 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams StreamName (p. 209) The name of the stream that you want to get the endpoint for. You must specify either this parameter or a StreamARN in the request. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "DataEndpoint": "string" } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. DataEndpoint (p. 210) The endpoint value. To read data from the stream or to write data to it, specify this endpoint in your application. Type: String Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. 210 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 211 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams GetSignalingChannelEndpoint Service: Amazon Kinesis Video Streams Provides an endpoint for the specified signaling channel to send and receive messages. This API uses the SingleMasterChannelEndpointConfiguration input parameter, which consists of the Protocols and Role properties. Protocols is used to determine the communication mechanism. For example, if you specify WSS as the protocol, this API produces a secure websocket endpoint. If you specify HTTPS as the protocol, this API generates an HTTPS endpoint. Role determines the messaging permissions. A MASTER role results in this API generating an endpoint that a client can use to communicate with any of the viewers on the channel. A VIEWER role results in this API generating an endpoint that a client can use to communicate only with a MASTER. Request Syntax POST /getSignalingChannelEndpoint HTTP/1.1 Content-type: application/json { "ChannelARN": "string", "SingleMasterChannelEndpointConfiguration": { "Protocols": [ "string" ], "Role": "string" } } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ChannelARN (p. 212) The Amazon Resource Name (ARN) of the signalling channel for which you want to get an endpoint. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: Yes SingleMasterChannelEndpointConfiguration (p. 212) A structure containing the endpoint configuration for the SINGLE_MASTER channel type. Type: SingleMasterChannelEndpointConfiguration (p. 290) object Required: No Response Syntax HTTP/1.1 200 212 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Content-type: application/json { "ResourceEndpointList": [ { "Protocol": "string", "ResourceEndpoint": "string" } ] } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. ResourceEndpointList (p. 212) A list of endpoints for the specified signaling channel. Type: Array of ResourceEndpointListItem (p. 289) objects Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 213 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 214 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ListSignalingChannels Service: Amazon Kinesis Video Streams Returns an array of ChannelInfo objects. Each object describes a signaling channel. To retrieve only those channels that satisfy a specific condition, you can specify a ChannelNameCondition. Request Syntax POST /listSignalingChannels HTTP/1.1 Content-type: application/json { "ChannelNameCondition": { "ComparisonOperator": "string", "ComparisonValue": "string" }, "MaxResults": number, "NextToken": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ChannelNameCondition (p. 215) Optional: Returns only the channels that satisfy a specific condition. Type: ChannelNameCondition (p. 288) object Required: No MaxResults (p. 215) The maximum number of channels to return in the response. The default is 500. Type: Integer Valid Range: Minimum value of 1. Maximum value of 10000. Required: No NextToken (p. 215) If you specify this parameter, when the result of a ListSignalingChannels operation is truncated, the call returns the NextToken in the response. To get another batch of channels, provide this token in your next request. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Required: No 215 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Response Syntax HTTP/1.1 200 Content-type: application/json { "ChannelInfoList": [ { "ChannelARN": "string", "ChannelName": "string", "ChannelStatus": "string", "ChannelType": "string", "CreationTime": number, "SingleMasterConfiguration": { "MessageTtlSeconds": number }, "Version": "string" } ], "NextToken": "string" } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. ChannelInfoList (p. 216) An array of ChannelInfo objects. Type: Array of ChannelInfo (p. 286) objects NextToken (p. 216) If the response is truncated, the call returns this element with a token. To get the next batch of streams, use this token in your next request. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 216 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 217 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ListStreams Service: Amazon Kinesis Video Streams Returns an array of StreamInfo objects. Each object describes a stream. To retrieve only streams that satisfy a specific condition, you can specify a StreamNameCondition. Request Syntax POST /listStreams HTTP/1.1 Content-type: application/json { "MaxResults": number, "NextToken": "string", "StreamNameCondition": { "ComparisonOperator": "string", "ComparisonValue": "string" } } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. MaxResults (p. 218) The maximum number of streams to return in the response. The default is 10,000. Type: Integer Valid Range: Minimum value of 1. Maximum value of 10000. Required: No NextToken (p. 218) If you specify this parameter, when the result of a ListStreams operation is truncated, the call returns the NextToken in the response. To get another batch of streams, provide this token in your next request. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Required: No StreamNameCondition (p. 218) Optional: Returns only streams that satisfy a specific condition. Currently, you can specify only the prefix of a stream name as a condition. Type: StreamNameCondition (p. 294) object Required: No 218 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Response Syntax HTTP/1.1 200 Content-type: application/json { "NextToken": "string", "StreamInfoList": [ { "CreationTime": number, "DataRetentionInHours": number, "DeviceName": "string", "KmsKeyId": "string", "MediaType": "string", "Status": "string", "StreamARN": "string", "StreamName": "string", "Version": "string" } ] } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. NextToken (p. 219) If the response is truncated, the call returns this element with a token. To get the next batch of streams, use this token in your next request. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* StreamInfoList (p. 219) An array of StreamInfo objects. Type: Array of StreamInfo (p. 292) objects Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 219 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 220 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ListTagsForResource Service: Amazon Kinesis Video Streams Returns a list of tags associated with the specified signaling channel. Request Syntax POST /ListTagsForResource HTTP/1.1 Content-type: application/json { "NextToken": "string", "ResourceARN": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. NextToken (p. 221) If you specify this parameter and the result of a ListTagsForResource call is truncated, the response includes a token that you can use in the next request to fetch the next batch of tags. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Required: No ResourceARN (p. 221) The Amazon Resource Name (ARN) of the signaling channel for which you want to list tags. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: Yes Response Syntax HTTP/1.1 200 Content-type: application/json { "NextToken": "string", "Tags": { "string" : "string" } 221 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. NextToken (p. 221) If you specify this parameter and the result of a ListTagsForResource call is truncated, the response includes a token that you can use in the next request to fetch the next set of tags. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Tags (p. 221) A map of tag keys and values associated with the specified signaling channel. Type: String to string map Map Entries: Maximum number of 50 items. Key Length Constraints: Minimum length of 1. Maximum length of 128. Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Value Length Constraints: Minimum length of 0. Maximum length of 256. Value Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]* Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 222 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 223 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ListTagsForStream Service: Amazon Kinesis Video Streams Returns a list of tags associated with the specified stream. In the request, you must specify either the StreamName or the StreamARN. Request Syntax POST /listTagsForStream HTTP/1.1 Content-type: application/json { "NextToken": "string", "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. NextToken (p. 224) If you specify this parameter and the result of a ListTagsForStream call is truncated, the response includes a token that you can use in the next request to fetch the next batch of tags. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Required: No StreamARN (p. 224) The Amazon Resource Name (ARN) of the stream that you want to list tags for. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 224) The name of the stream that you want to list tags for. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ 224 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "NextToken": "string", "Tags": { "string" : "string" } } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. NextToken (p. 225) If you specify this parameter and the result of a ListTags call is truncated, the response includes a token that you can use in the next request to fetch the next set of tags. Type: String Length Constraints: Minimum length of 0. Maximum length of 512. Pattern: [a-zA-Z0-9+/=]* Tags (p. 225) A map of tag keys and values associated with the specified stream. Type: String to string map Map Entries: Maximum number of 50 items. Key Length Constraints: Minimum length of 1. Maximum length of 128. Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Value Length Constraints: Minimum length of 0. Maximum length of 256. Value Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]* Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. 225 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams HTTP Status Code: 400 InvalidResourceFormatException The format of the StreamARN is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 226 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams TagResource Service: Amazon Kinesis Video Streams Adds one or more tags to a signaling channel. A tag is a key-value pair (the value is optional) that you can define and assign to AWS resources. If you specify a tag that already exists, the tag value is replaced with the value that you specify in the request. For more information, see Using Cost Allocation Tags in the AWS Billing and Cost Management User Guide. Request Syntax POST /TagResource HTTP/1.1 Content-type: application/json { "ResourceARN": "string", "Tags": [ { "Key": "string", "Value": "string" } ] } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ResourceARN (p. 227) The Amazon Resource Name (ARN) of the signaling channel to which you want to add tags. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: Yes Tags (p. 227) A list of tags to associate with the specified signaling channel. Each tag is a key-value pair. Type: Array of Tag (p. 295) objects Array Members: Minimum number of 1 item. Maximum number of 50 items. Required: Yes Response Syntax HTTP/1.1 200 227 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 TagsPerResourceExceededLimitException You have exceeded the limit of tags that you can associate with the resource. Kinesis video streams support up to 50 tags. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 228 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams TagStream Service: Amazon Kinesis Video Streams Adds one or more tags to a stream. A tag is a key-value pair (the value is optional) that you can define and assign to AWS resources. If you specify a tag that already exists, the tag value is replaced with the value that you specify in the request. For more information, see Using Cost Allocation Tags in the AWS Billing and Cost Management User Guide. You must provide either the StreamName or the StreamARN. This operation requires permission for the KinesisVideo:TagStream action. Kinesis video streams support up to 50 tags. Request Syntax POST /tagStream HTTP/1.1 Content-type: application/json { "StreamARN": "string", "StreamName": "string", "Tags": { "string" : "string" } } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. StreamARN (p. 229) The Amazon Resource Name (ARN) of the resource that you want to add the tag or tags to. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 229) The name of the stream that you want to add the tag or tags to. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No 229 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Tags (p. 229) A list of tags to associate with the specified stream. Each tag is a key-value pair (the value is optional). Type: String to string map Map Entries: Maximum number of 50 items. Key Length Constraints: Minimum length of 1. Maximum length of 128. Key Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Value Length Constraints: Minimum length of 0. Maximum length of 256. Value Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]* Required: Yes Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 InvalidResourceFormatException The format of the StreamARN is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 230 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams TagsPerResourceExceededLimitException You have exceeded the limit of tags that you can associate with the resource. Kinesis video streams support up to 50 tags. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 231 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams UntagResource Service: Amazon Kinesis Video Streams Removes one or more tags from a signaling channel. In the request, specify only a tag key or keys; don't specify the value. If you specify a tag key that does not exist, it's ignored. Request Syntax POST /UntagResource HTTP/1.1 Content-type: application/json { "ResourceARN": "string", "TagKeyList": [ "string" ] } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ResourceARN (p. 232) The Amazon Resource Name (ARN) of the signaling channel from which you want to remove tags. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: Yes TagKeyList (p. 232) A list of the keys of the tags that you want to remove. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 50 items. Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Required: Yes Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. 232 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 233 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams UntagStream Service: Amazon Kinesis Video Streams Removes one or more tags from a stream. In the request, specify only a tag key or keys; don't specify the value. If you specify a tag key that does not exist, it's ignored. In the request, you must provide the StreamName or StreamARN. Request Syntax POST /untagStream HTTP/1.1 Content-type: application/json { "StreamARN": "string", "StreamName": "string", "TagKeyList": [ "string" ] } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. StreamARN (p. 234) The Amazon Resource Name (ARN) of the stream that you want to remove tags from. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 234) The name of the stream that you want to remove tags from. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No TagKeyList (p. 234) A list of the keys of the tags that you want to remove. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 50 items. Length Constraints: Minimum length of 1. Maximum length of 128. 234 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Required: Yes Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 InvalidResourceFormatException The format of the StreamARN is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 235 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • AWS SDK for Python • AWS SDK for Ruby V3 236 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams UpdateDataRetention Service: Amazon Kinesis Video Streams Increases or decreases the stream's data retention period by the value that you specify. To indicate whether you want to increase or decrease the data retention period, specify the Operation parameter in the request body. In the request, you must specify either the StreamName or the StreamARN. Note The retention period that you specify replaces the current value. This operation requires permission for the KinesisVideo:UpdateDataRetention action. Changing the data retention period affects the data in the stream as follows: • If the data retention period is increased, existing data is retained for the new retention period. For example, if the data retention period is increased from one hour to seven hours, all existing data is retained for seven hours. • If the data retention period is decreased, existing data is retained for the new retention period. For example, if the data retention period is decreased from seven hours to one hour, all existing data is retained for one hour, and any data older than one hour is deleted immediately. Request Syntax POST /updateDataRetention HTTP/1.1 Content-type: application/json { "CurrentVersion": "string", "DataRetentionChangeInHours": number, "Operation": "string", "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. CurrentVersion (p. 237) The version of the stream whose retention period you want to change. To get the version, call either the DescribeStream or the ListStreams API. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: Yes DataRetentionChangeInHours (p. 237) The retention period, in hours. The value you specify replaces the current value. The maximum value for this parameter is 87600 (ten years). 237 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Type: Integer Valid Range: Minimum value of 1. Required: Yes Operation (p. 237) Indicates whether you want to increase or decrease the retention period. Type: String Valid Values: INCREASE_DATA_RETENTION | DECREASE_DATA_RETENTION Required: Yes StreamARN (p. 237) The Amazon Resource Name (ARN) of the stream whose retention period you want to change. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 237) The name of the stream whose retention period you want to change. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. 238 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 VersionMismatchException The stream version that you specified is not the latest version. To get the latest version, use the DescribeStream API. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 239 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams UpdateSignalingChannel Service: Amazon Kinesis Video Streams Updates the existing signaling channel. This is an asynchronous operation and takes time to complete. If the MessageTtlSeconds value is updated (either increased or reduced), it only applies to new messages sent via this channel after it's been updated. Existing messages are still expired as per the previous MessageTtlSeconds value. Request Syntax POST /updateSignalingChannel HTTP/1.1 Content-type: application/json { "ChannelARN": "string", "CurrentVersion": "string", "SingleMasterConfiguration": { "MessageTtlSeconds": number } } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ChannelARN (p. 240) The Amazon Resource Name (ARN) of the signaling channel that you want to update. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: Yes CurrentVersion (p. 240) The current version of the signaling channel that you want to update. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: Yes SingleMasterConfiguration (p. 240) The structure containing the configuration for the SINGLE_MASTER type of the signaling channel that you want to update. Type: SingleMasterConfiguration (p. 291) object 240 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Required: No Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). AccessDeniedException You do not have required permissions to perform this operation. HTTP Status Code: 401 ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 VersionMismatchException The stream version that you specified is not the latest version. To get the latest version, use the DescribeStream API. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: 241 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 242 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams UpdateStream Service: Amazon Kinesis Video Streams Updates stream metadata, such as the device name and media type. You must provide the stream name or the Amazon Resource Name (ARN) of the stream. To make sure that you have the latest version of the stream before updating it, you can specify the stream version. Kinesis Video Streams assigns a version to each stream. When you update a stream, Kinesis Video Streams assigns a new version number. To get the latest stream version, use the DescribeStream API. UpdateStream is an asynchronous operation, and takes time to complete. Request Syntax POST /updateStream HTTP/1.1 Content-type: application/json { "CurrentVersion": "string", "DeviceName": "string", "MediaType": "string", "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. CurrentVersion (p. 243) The version of the stream whose metadata you want to update. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: Yes DeviceName (p. 243) The name of the device that is writing to the stream. Note In the current implementation, Kinesis Video Streams does not use this name. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: [a-zA-Z0-9_.-]+ 243 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Required: No MediaType (p. 243) The stream's media type. Use MediaType to specify the type of content that the stream contains to the consumers of the stream. For more information about media types, see Media Types. If you choose to specify the MediaType, see Naming Requirements. To play video on the console, you must specify the correct video type. For example, if the video in the stream is H.264, specify video/h264 as the MediaType. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: [\w\-\.\+]+/[\w\-\.\+]+(,[\w\-\.\+]+/[\w\-\.\+]+)* Required: No StreamARN (p. 243) The ARN of the stream whose metadata you want to update. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 243) The name of the stream whose metadata you want to update. The stream name is an identifier for the stream, and must be unique for each account and region. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Response Elements If the action is successful, the service sends back an HTTP 200 response with an empty HTTP body. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. 244 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform this operation. HTTP Status Code: 401 ResourceInUseException The resource is currently not available for this operation. New resources cannot be created with the same name as existing resources. Also, resources cannot be updated or deleted unless they are in an ACTIVE state. If this exception is returned, do not use it to determine whether the requested resource already exists. Instead, it is recommended you use the resource-specific describe API, for exmaple, DescribeStream for video streams. HTTP Status Code: 400 ResourceNotFoundException Amazon Kinesis Video Streams can't find the stream that you specified. HTTP Status Code: 404 VersionMismatchException The stream version that you specified is not the latest version. To get the latest version, use the DescribeStream API. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 Amazon Kinesis Video Streams Media The following actions are supported by Amazon Kinesis Video Streams Media: • GetMedia (p. 247) • PutMedia (p. 251) 245 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media 246 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media GetMedia Service: Amazon Kinesis Video Streams Media Use this API to retrieve media content from a Kinesis video stream. In the request, you identify the stream name or stream Amazon Resource Name (ARN), and the starting chunk. Kinesis Video Streams then returns a stream of chunks in order by fragment number. Note You must first call the GetDataEndpoint API to get an endpoint. Then send the GetMedia requests to this endpoint using the --endpoint-url parameter. When you put media data (fragments) on a stream, Kinesis Video Streams stores each incoming fragment and related metadata in what is called a "chunk." For more information, see PutMedia. The GetMedia API returns a stream of these chunks starting from the chunk that you specify in the request. The following limits apply when using the GetMedia API: • A client can call GetMedia up to five times per second per stream. • Kinesis Video Streams sends media data at a rate of up to 25 megabytes per second (or 200 megabits per second) during a GetMedia session. Note If an error is thrown after invoking a Kinesis Video Streams media API, in addition to the HTTP status code and the response body, it includes the following pieces of information: • x-amz-ErrorType HTTP header – contains a more specific error type in addition to what the HTTP status code provides. • x-amz-RequestId HTTP header – if you want to report an issue to AWS, the support team can better diagnose the problem if given the Request Id. Both the HTTP status code and the ErrorType header can be utilized to make programmatic decisions about whether errors are retry-able and under what conditions, as well as provide information on what actions the client programmer might need to take in order to successfully try again. For more information, see the Errors section at the bottom of this topic, as well as Common Errors. Request Syntax POST /getMedia HTTP/1.1 Content-type: application/json { "StartSelector": { "AfterFragmentNumber": "string", "ContinuationToken": "string", "StartSelectorType": "string", "StartTimestamp": number }, "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. 247 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media Request Body The request accepts the following data in JSON format. StartSelector (p. 247) Identifies the starting chunk to get from the specified stream. Type: StartSelector (p. 296) object Required: Yes StreamARN (p. 247) The ARN of the stream from where you want to get the media content. If you don't specify the streamARN, you must specify the streamName. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 247) The Kinesis video stream name from where you want to get the media content. If you don't specify the streamName, you must specify the streamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-Type: ContentType Payload Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ContentType (p. 248) The content type of the requested media. Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^[a-zA-Z0-9_\.\-]+$ The response returns the following as the HTTP body. 248 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media Payload (p. 248) The payload Kinesis Video Streams returns is a sequence of chunks from the specified stream. For more information about the chunks, see PutMedia. The chunks that Kinesis Video Streams returns in the GetMedia call also include the following additional Matroska (MKV) tags: • AWS_KINESISVIDEO_CONTINUATION_TOKEN (UTF-8 string) - In the event your GetMedia call terminates, you can use this continuation token in your next request to get the next chunk where the last request terminated. • AWS_KINESISVIDEO_MILLIS_BEHIND_NOW (UTF-8 string) - Client applications can use this tag value to determine how far behind the chunk returned in the response is from the latest chunk on the stream. • AWS_KINESISVIDEO_FRAGMENT_NUMBER - Fragment number returned in the chunk. • AWS_KINESISVIDEO_SERVER_TIMESTAMP - Server timestamp of the fragment. • AWS_KINESISVIDEO_PRODUCER_TIMESTAMP - Producer timestamp of the fragment. The following tags will be present if an error occurs: • AWS_KINESISVIDEO_ERROR_CODE - String description of an error that caused GetMedia to stop. • AWS_KINESISVIDEO_ERROR_ID: Integer code of the error. The error codes are as follows: • 3002 - Error writing to the stream • 4000 - Requested fragment is not found • 4500 - Access denied for the stream's KMS key • 4501 - Stream's KMS key is disabled • 4502 - Validation error on the stream's KMS key • 4503 - KMS key specified in the stream is unavailable • 4504 - Invalid usage of the KMS key specified in the stream • 4505 - Invalid state of the KMS key specified in the stream • 4506 - Unable to find the KMS key specified in the stream • 5000 - Internal error Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 ConnectionLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client connections. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 249 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media InvalidEndpointException Caller used wrong endpoint to write data to a stream. On receiving such an exception, the user must call GetDataEndpoint with APIName set to PUT_MEDIA and use the endpoint from response to invoke the next PutMedia call. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 ResourceNotFoundException Status Code: 404, The stream with the given name does not exist. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 250 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media PutMedia Service: Amazon Kinesis Video Streams Media Use this API to send media data to a Kinesis video stream. Note Before using this API, you must call the GetDataEndpoint API to get an endpoint. You then specify the endpoint in your PutMedia request. In the request, you use the HTTP headers to provide parameter information, for example, stream name, timestamp, and whether the timestamp value is absolute or relative to when the producer started recording. You use the request body to send the media data. Kinesis Video Streams supports only the Matroska (MKV) container format for sending media data using this API. You have the following options for sending data using this API: • Send media data in real time: For example, a security camera can send frames in real time as it generates them. This approach minimizes the latency between the video recording and data sent on the wire. This is referred to as a continuous producer. In this case, a consumer application can read the stream in real time or when needed. • Send media data offline (in batches): For example, a body camera might record video for hours and store it on the device. Later, when you connect the camera to the docking port, the camera can start a PutMedia session to send data to a Kinesis video stream. In this scenario, latency is not an issue. When using this API, note the following considerations: • You must specify either streamName or streamARN, but not both. • To be able to play the media on the console or via HLS, track 1 of each fragment should contain h.264 encoded video, the CodecID in the fragment metadata should be "V_MPEG/ISO/AVC", and the fragment metadata should include AVCC formatted h.264 codec private data. Optionally, track 2 of each fragment should contain AAC encoded audio, the CodecID in the fragment metadata should be "A_AAC", and the fragment metadata should include AAC codec private data. • You might find it easier to use a single long-running PutMedia session and send a large number of media data fragments in the payload. For each fragment received, Kinesis Video Streams sends one or more acknowledgements. Potential network considerations might cause you to not get all these acknowledgements as they are generated. • You might choose multiple consecutive PutMedia sessions, each with fewer fragments to ensure that you get all acknowledgements from the service in real time. Note If you send data to the same stream on multiple simultaneous PutMedia sessions, the media fragments get interleaved on the stream. You should make sure that this is OK in your application scenario. The following limits apply when using the PutMedia API: • A client can call PutMedia up to five times per second per stream. • A client can send up to five fragments per second per stream. • Kinesis Video Streams reads media data at a rate of up to 12.5 MB/second, or 100 Mbps during a PutMedia session. Note the following constraints. In these cases, Kinesis Video Streams sends the Error acknowledgement in the response. 251 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media • Fragments that have time codes spanning longer than 10 seconds and that contain more than 50 MB of data are not allowed. • Fragments containing more than three tracks are not allowed. Each frame in every fragment must have the same track number as one of the tracks defined in the fragment header. Additionally, every fragment must contain at least one frame for each track defined in the fragment header. • Each fragment must contain at least one frame for each track defined in the fragment metadata. • The earliest frame timestamp in a fragment must be after the latest frame timestamp in the previous fragment. • An MKV stream containing more than one MKV segment or containing disallowed MKV elements (like track*) also results in the Error acknowledgement. Kinesis Video Streams stores each incoming fragment and related metadata in what is called a "chunk." The fragment metadata includes the following: • The MKV headers provided at the start of the PutMedia request • The following Kinesis Video Streams-specific metadata for the fragment: • server_timestamp - Timestamp when Kinesis Video Streams started receiving the fragment. • producer_timestamp - Timestamp, when the producer started recording the fragment. Kinesis Video Streams uses three pieces of information received in the request to calculate this value. • The fragment timecode value received in the request body along with the fragment. • Two request headers: producerStartTimestamp (when the producer started recording) and fragmentTimeCodeType (whether the fragment timecode in the payload is absolute or relative). Kinesis Video Streams then computes the producer_timestamp for the fragment as follows: If fragmentTimeCodeType is relative, then producer_timestamp = producerStartTimeStamp + fragment timecode If fragmentTimeCodeType is absolute, then producer_timestamp = fragment timecode (converted to milliseconds) • Unique fragment number assigned by Kinesis Video Streams. Note When you make the GetMedia request, Kinesis Video Streams returns a stream of these chunks. The client can process the metadata as needed. Note This operation is only available for the AWS SDK for Java. It is not supported in AWS SDKs for other languages. Note Kinesis Video Streams does not parse and validate the codec private data during ingestion and archival via the PutMedia API. KVS extracts and validates the necessary information from the codec private data for MPEG-TS and MP4 fragment packaging when consuming the stream via the HLS APIs. Note If an error is thrown after invoking a Kinesis Video Streams media API, in addition to the HTTP status code and the response body, it includes the following pieces of information: 252 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media • x-amz-ErrorType HTTP header – contains a more specific error type in addition to what the HTTP status code provides. • x-amz-RequestId HTTP header – if you want to report an issue to AWS, the support team can better diagnose the problem if given the Request Id. Both the HTTP status code and the ErrorType header can be utilized to make programmatic decisions about whether errors are retry-able and under what conditions, as well as provide information on what actions the client programmer might need to take in order to successfully try again. For more information, see the Errors section at the bottom of this topic, as well as Common Errors. Request Syntax POST /putMedia HTTP/1.1 x-amzn-stream-name: StreamName x-amzn-stream-arn: StreamARN x-amzn-fragment-timecode-type: FragmentTimecodeType x-amzn-producer-start-timestamp: ProducerStartTimestamp Payload URI Request Parameters The request uses the following URI parameters. FragmentTimecodeType (p. 253) You pass this value as the x-amzn-fragment-timecode-type HTTP header. Indicates whether timecodes in the fragments (payload, HTTP request body) are absolute or relative to producerStartTimestamp. Kinesis Video Streams uses this information to compute the producer_timestamp for the fragment received in the request, as described in the API overview. Valid Values: ABSOLUTE | RELATIVE Required: Yes ProducerStartTimestamp (p. 253) You pass this value as the x-amzn-producer-start-timestamp HTTP header. This is the producer timestamp at which the producer started recording the media (not the timestamp of the specific fragments in the request). StreamARN (p. 253) You pass this value as the x-amzn-stream-arn HTTP header. Amazon Resource Name (ARN) of the Kinesis video stream where you want to write the media content. If you don't specify the streamARN, you must specify the streamName. Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ StreamName (p. 253) You pass this value as the x-amzn-stream-name HTTP header. Name of the Kinesis video stream where you want to write the media content. If you don't specify the streamName, you must specify the streamARN. 253 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Request Body The request accepts the following binary data. Payload (p. 253) The media content to write to the Kinesis video stream. In the current implementation, Kinesis Video Streams supports only the Matroska (MKV) container format with a single MKV segment. A segment can contain one or more clusters. Note Each MKV cluster maps to a Kinesis video stream fragment. Whatever cluster duration you choose becomes the fragment duration. Response Syntax HTTP/1.1 200 Payload Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following as the HTTP body. Payload (p. 254) After Kinesis Video Streams successfully receives a PutMedia request, the service validates the request headers. The service then starts reading the payload and first sends an HTTP 200 response. The service then returns a stream containing a series of JSON objects (Acknowledgement objects) separated by newlines. The acknowledgements are received on the same connection on which the media data is sent. There can be many acknowledgements for a PutMedia request. Each Acknowledgement consists of the following key-value pairs: • AckEventType - Event type the acknowledgement represents. • Buffering: Kinesis Video Streams has started receiving the fragment. Kinesis Video Streams sends the first Buffering acknowledgement when the first byte of fragment data is received. • Received: Kinesis Video Streams received the entire fragment. If you did not configure the stream to persist the data, the producer can stop buffering the fragment upon receiving this acknowledgement. • Persisted: Kinesis Video Streams has persisted the fragment (for example, to Amazon S3). You get this acknowledgement if you configured the stream to persist the data. After you receive this acknowledgement, the producer can stop buffering the fragment. • Error: Kinesis Video Streams ran into an error while processing the fragment. You can review the error code and determine the next course of action. • Idle: The PutMedia session is in-progress. However, Kinesis Video Streams is currently not receiving data. Kinesis Video Streams sends this acknowledgement periodically for up to 30 seconds after the last received data. If no data is received within the 30 seconds, Kinesis Video Streams closes the request. 254 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media Note This acknowledgement can help a producer determine if the PutMedia connection is alive, even if it is not sending any data. • FragmentTimeCode - Fragment timecode for which acknowledgement is sent. The element can be missing if the AckEventType is Idle. • FragmentNumber - Kinesis Video Streams-generated fragment number for which the acknowledgement is sent. • ErrorId and ErrorCode - If the AckEventType is ErrorId, this field provides corresponding error code. The following is the list of error IDs and their corresponding error codes and error messages: • 4000 - STREAM_READ_ERROR - Error reading the data stream. • 4001 - MAX_FRAGMENT_SIZE_REACHED - Fragment size is greater than maximum limit, 50 MB, allowed. • 4002 - MAX_FRAGMENT_DURATION_REACHED - Fragment duration is greater than maximum limit, 10 seconds, allowed. • 4003 - MAX_CONNECTION_DURATION_REACHED - Connection duration is greater than maximum allowed threshold. • 4004 - FRAGMENT_TIMECODE_LESSER_THAN_PREVIOUS - Fragment timecode is less than the timecode previous time code (within a PutMedia call, you cannot send fragments out of order). • 4005 - MORE_THAN_ALLOWED_TRACKS_FOUND - More than one track is found in MKV. (deprecated) • 4006 - INVALID_MKV_DATA - Failed to parse the input stream as valid MKV format. • 4007 - INVALID_PRODUCER_TIMESTAMP - Invalid producer timestamp. • 4008 - STREAM_NOT_ACTIVE - Stream no longer exists (deleted). • 4009 - FRAGMENT_METADATA_LIMIT_REACHED - Fragment metadata limit reached. • 4010 - TRACK_NUMBER_MISMATCH - The track number in an MKV frame did not match the tracks in the MKV header. • 4011 - FRAMES_MISSING_FOR_TRACK - The fragment did not contain any frames for at least one of the tracks in the MKV header. • 4500 - KMS_KEY_ACCESS_DENIED - Access to the stream's specified KMS key is denied. • 4501 - KMS_KEY_DISABLED - The stream's specified KMS key is disabled. • 4502 - KMS_KEY_VALIDATION_ERROR - The stream's specified KMS key failed validation. • 4503 - KMS_KEY_UNAVAILABLE - The stream's specified KMS key is unavailable. • 4504 - KMS_KEY_INVALID_USAGE - Invalid usage of the stream's specified KMS key. • 4505 - KMS_KEY_INVALID_STATE - The stream's specified KMS key is in an invalid state. • 4506 - KMS_KEY_NOT_FOUND - The stream's specified KMS key is not found. • 5000 - INTERNAL_ERROR - Internal service error • 5001 - ARCHIVAL_ERROR - Kinesis Video Streams failed to persist fragments to the data store. Note The producer, while sending the payload for a long running PutMedia request, should read the response for acknowledgements. A producer might receive chunks of acknowledgements at the same time, due to buffering on an intermediate proxy server. A producer that wants to receive timely acknowledgements can send fewer fragments in each PutMedia request. Errors For information about the errors that are common to all actions, see Common Errors (p. 306). 255 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client calls. Try making the call later. HTTP Status Code: 400 ConnectionLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded the limit of allowed client connections. HTTP Status Code: 400 InvalidArgumentException The value for this input parameter is invalid. HTTP Status Code: 400 InvalidEndpointException Caller used wrong endpoint to write data to a stream. On receiving such an exception, the user must call GetDataEndpoint with APIName set to PUT_MEDIA and use the endpoint from response to invoke the next PutMedia call. HTTP Status Code: 400 NotAuthorizedException The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 ResourceNotFoundException Status Code: 404, The stream with the given name does not exist. HTTP Status Code: 404 Examples Acknowledgement Format The format of the acknowledgement is as follows: { Acknowledgement : { "EventType": enum "FragmentTimecode": Long, "FragmentNumber": Long, "ErrorId" : String } } See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET 256 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 Amazon Kinesis Video Streams Archived Media The following actions are supported by Amazon Kinesis Video Streams Archived Media: • GetClip (p. 258) • GetDASHStreamingSessionURL (p. 262) • GetHLSStreamingSessionURL (p. 269) • GetMediaForFragmentList (p. 277) • ListFragments (p. 281) 257 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media GetClip Service: Amazon Kinesis Video Streams Archived Media Downloads an MP4 file (clip) containing the archived, on-demand media from the specified video stream over the specified time range. Both the StreamName and the StreamARN parameters are optional, but you must specify either the StreamName or the StreamARN when invoking this API operation. As a prerequisite to using GetCLip API, you must obtain an endpoint using GetDataEndpoint, specifying GET_CLIP for the APIName parameter. An Amazon Kinesis video stream has the following requirements for providing data through MP4: • The media must contain h.264 or h.265 encoded video and, optionally, AAC or G.711 encoded audio. Specifically, the codec ID of track 1 should be V_MPEG/ISO/AVC (for h.264) or V_MPEGH/ISO/HEVC (for H.265). Optionally, the codec ID of track 2 should be A_AAC (for AAC) or A_MS/ACM (for G.711). • Data retention must be greater than 0. • The video track of each fragment must contain codec private data in the Advanced Video Coding (AVC) for H.264 format and HEVC for H.265 format. For more information, see MPEG-4 specification ISO/IEC 14496-15. For information about adapting stream data to a given format, see NAL Adaptation Flags. • The audio track (if present) of each fragment must contain codec private data in the AAC format (AAC specification ISO/IEC 13818-7) or the MS Wave format. You can monitor the amount of outgoing data by monitoring the GetClip.OutgoingBytes Amazon CloudWatch metric. For information about using CloudWatch to monitor Kinesis Video Streams, see Monitoring Kinesis Video Streams. For pricing information, see Amazon Kinesis Video Streams Pricing and AWS Pricing. Charges for outgoing AWS data apply. Request Syntax POST /getClip HTTP/1.1 Content-type: application/json { "ClipFragmentSelector": { "FragmentSelectorType": "string", "TimestampRange": { "EndTimestamp": number, "StartTimestamp": number } }, "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ClipFragmentSelector (p. 258) The time range of the requested clip and the source of the timestamps. 258 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Type: ClipFragmentSelector (p. 298) object Required: Yes StreamARN (p. 258) The Amazon Resource Name (ARN) of the stream for which to retrieve the media clip. You must specify either the StreamName or the StreamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 258) The name of the stream for which to retrieve the media clip. You must specify either the StreamName or the StreamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-Type: ContentType Payload Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ContentType (p. 259) The content type of the media in the requested clip. Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^[a-zA-Z0-9_\.\-]+$ The response returns the following as the HTTP body. Payload (p. 259) Traditional MP4 file that contains the media clip from the specified video stream. The output will contain the first 100 MB or the first 200 fragments from the specified start timestamp. For more information, see Kinesis Video Streams Limits. 259 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded a limit. Try making the call later. For information about limits, see Kinesis Video Streams Limits. HTTP Status Code: 400 InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or can't be used. HTTP Status Code: 400 InvalidCodecPrivateDataException The codec private data in at least one of the tracks of the video stream is not valid for this operation. HTTP Status Code: 400 InvalidMediaFrameException One or more frames in the requested clip could not be parsed based on the specified codec. HTTP Status Code: 400 MissingCodecPrivateDataException No codec private data was found in at least one of tracks of the video stream. HTTP Status Code: 400 NoDataRetentionException A streaming session was requested for a stream that does not retain data (that is, has a DataRetentionInHours of 0). HTTP Status Code: 400 NotAuthorizedException Status Code: 403, The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 ResourceNotFoundException GetMedia throws this error when Kinesis Video Streams can't find the stream that you specified. GetHLSStreamingSessionURL and GetDASHStreamingSessionURL throw this error if a session with a PlaybackMode of ON_DEMAND or LIVE_REPLAYis requested for a stream that has no fragments within the requested time range, or if a session with a PlaybackMode of LIVE is requested for a stream that has no fragments within the last 30 seconds. HTTP Status Code: 404 UnsupportedStreamMediaTypeException The type of the media (for example, h.264 or h.265 video or ACC or G.711 audio) could not be determined from the codec IDs of the tracks in the first fragment for a playback session. The codec ID for track 1 should be V_MPEG/ISO/AVC and, optionally, the codec ID for track 2 should be A_AAC. HTTP Status Code: 400 260 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 261 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media GetDASHStreamingSessionURL Service: Amazon Kinesis Video Streams Archived Media Retrieves an MPEG Dynamic Adaptive Streaming over HTTP (DASH) URL for the stream. You can then open the URL in a media player to view the stream contents. Both the StreamName and the StreamARN parameters are optional, but you must specify either the StreamName or the StreamARN when invoking this API operation. An Amazon Kinesis video stream has the following requirements for providing data through MPEG-DASH: • The media must contain h.264 or h.265 encoded video and, optionally, AAC or G.711 encoded audio. Specifically, the codec ID of track 1 should be V_MPEG/ISO/AVC (for h.264) or V_MPEGH/ISO/HEVC (for H.265). Optionally, the codec ID of track 2 should be A_AAC (for AAC) or A_MS/ACM (for G.711). • Data retention must be greater than 0. • The video track of each fragment must contain codec private data in the Advanced Video Coding (AVC) for H.264 format and HEVC for H.265 format. For more information, see MPEG-4 specification ISO/IEC 14496-15. For information about adapting stream data to a given format, see NAL Adaptation Flags. • The audio track (if present) of each fragment must contain codec private data in the AAC format (AAC specification ISO/IEC 13818-7) or the MS Wave format. The following procedure shows how to use MPEG-DASH with Kinesis Video Streams: 1. Get an endpoint using GetDataEndpoint, specifying GET_DASH_STREAMING_SESSION_URL for the APIName parameter. 2. Retrieve the MPEG-DASH URL using GetDASHStreamingSessionURL. Kinesis Video Streams creates an MPEG-DASH streaming session to be used for accessing content in a stream using the MPEG-DASH protocol. GetDASHStreamingSessionURL returns an authenticated URL (that includes an encrypted session token) for the session's MPEG-DASH manifest (the root resource needed for streaming with MPEG-DASH). Note Don't share or store this token where an unauthorized entity can access it. The token provides access to the content of the stream. Safeguard the token with the same measures that you use with your AWS credentials. The media that is made available through the manifest consists only of the requested stream, time range, and format. No other media data (such as frames outside the requested window or alternate bitrates) is made available. 3. Provide the URL (containing the encrypted session token) for the MPEG-DASH manifest to a media player that supports the MPEG-DASH protocol. Kinesis Video Streams makes the initialization fragment and media fragments available through the manifest URL. The initialization fragment contains the codec private data for the stream, and other data needed to set up the video or audio decoder and renderer. The media fragments contain encoded video frames or encoded audio samples. 4. The media player receives the authenticated URL and requests stream metadata and media data normally. When the media player requests data, it calls the following actions: • GetDASHManifest: Retrieves an MPEG DASH manifest, which contains the metadata for the media that you want to playback. • GetMP4InitFragment: Retrieves the MP4 initialization fragment. The media player typically loads the initialization fragment before loading any media fragments. This fragment contains the "fytp" and "moov" MP4 atoms, and the child atoms that are needed to initialize the media player decoder. The initialization fragment does not correspond to a fragment in a Kinesis video stream. It contains only the codec private data for the stream and respective track, which the media player needs to decode the media frames. 262 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media • GetMP4MediaFragment: Retrieves MP4 media fragments. These fragments contain the "moof" and "mdat" MP4 atoms and their child atoms, containing the encoded fragment's media frames and their timestamps. Note After the first media fragment is made available in a streaming session, any fragments that don't contain the same codec private data cause an error to be returned when those different media fragments are loaded. Therefore, the codec private data should not change between fragments in a session. This also means that the session fails if the fragments in a stream change from having only video to having both audio and video. Data retrieved with this action is billable. See Pricing for details. Note For restrictions that apply to MPEG-DASH sessions, see Kinesis Video Streams Limits. You can monitor the amount of data that the media player consumes by monitoring the GetMP4MediaFragment.OutgoingBytes Amazon CloudWatch metric. For information about using CloudWatch to monitor Kinesis Video Streams, see Monitoring Kinesis Video Streams. For pricing information, see Amazon Kinesis Video Streams Pricing and AWS Pricing. Charges for both HLS sessions and outgoing AWS data apply. For more information about HLS, see HTTP Live Streaming on the Apple Developer site. Important If an error is thrown after invoking a Kinesis Video Streams archived media API, in addition to the HTTP status code and the response body, it includes the following pieces of information: • x-amz-ErrorType HTTP header – contains a more specific error type in addition to what the HTTP status code provides. • x-amz-RequestId HTTP header – if you want to report an issue to AWS, the support team can better diagnose the problem if given the Request Id. Both the HTTP status code and the ErrorType header can be utilized to make programmatic decisions about whether errors are retry-able and under what conditions, as well as provide information on what actions the client programmer might need to take in order to successfully try again. For more information, see the Errors section at the bottom of this topic, as well as Common Errors. Request Syntax 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, 263 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media "PlaybackMode": "string", "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. DASHFragmentSelector (p. 263) The time range of the requested fragment and the source of the timestamps. This parameter is required if PlaybackMode is ON_DEMAND or LIVE_REPLAY. This parameter is optional if PlaybackMode is LIVE. If PlaybackMode is LIVE, the FragmentSelectorType can be set, but the TimestampRange should not be set. If PlaybackMode is ON_DEMAND or LIVE_REPLAY, both FragmentSelectorType and TimestampRange must be set. Type: DASHFragmentSelector (p. 300) object Required: No DisplayFragmentNumber (p. 263) Fragments are identified in the manifest file based on their sequence number in the session. If DisplayFragmentNumber is set to ALWAYS, the Kinesis Video Streams fragment number is added to each S element in the manifest file with the attribute name “kvs:fn”. These fragment numbers can be used for logging or for use with other APIs (e.g. GetMedia and GetMediaForFragmentList). A custom MPEG-DASH media player is necessary to leverage these this custom attribute. The default value is NEVER. Type: String Valid Values: ALWAYS | NEVER Required: No DisplayFragmentTimestamp (p. 263) Per the MPEG-DASH specification, the wall-clock time of fragments in the manifest file can be derived using attributes in the manifest itself. However, typically, MPEG-DASH compatible media players do not properly handle gaps in the media timeline. Kinesis Video Streams adjusts the media timeline in the manifest file to enable playback of media with discontinuities. Therefore, the wall-clock time derived from the manifest file may be inaccurate. If DisplayFragmentTimestamp is set to ALWAYS, the accurate fragment timestamp is added to each S element in the manifest file with the attribute name “kvs:ts”. A custom MPEG-DASH media player is necessary to leverage this custom attribute. The default value is NEVER. When DASHFragmentSelector (p. 300) is SERVER_TIMESTAMP, the timestamps will be the server start timestamps. Similarly, when DASHFragmentSelector (p. 300) is PRODUCER_TIMESTAMP, the timestamps will be the producer start timestamps. Type: String Valid Values: ALWAYS | NEVER Required: No 264 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Expires (p. 263) The time in seconds until the requested session expires. This value can be between 300 (5 minutes) and 43200 (12 hours). When a session expires, no new calls to GetDashManifest, GetMP4InitFragment, or GetMP4MediaFragment can be made for that session. The default is 300 (5 minutes). Type: Integer Valid Range: Minimum value of 300. Maximum value of 43200. Required: No MaxManifestFragmentResults (p. 263) The maximum number of fragments that are returned in the MPEG-DASH manifest. When the PlaybackMode is LIVE, the most recent fragments are returned up to this value. When the PlaybackMode is ON_DEMAND, the oldest fragments are returned, up to this maximum number. When there are a higher number of fragments available in a live MPEG-DASH manifest, video players often buffer content before starting playback. Increasing the buffer size increases the playback latency, but it decreases the likelihood that rebuffering will occur during playback. We recommend that a live MPEG-DASH manifest have a minimum of 3 fragments and a maximum of 10 fragments. The default is 5 fragments if PlaybackMode is LIVE or LIVE_REPLAY, and 1,000 if PlaybackMode is ON_DEMAND. The maximum value of 1,000 fragments corresponds to more than 16 minutes of video on streams with 1-second fragments, and more than 2 1/2 hours of video on streams with 10-second fragments. Type: Long Valid Range: Minimum value of 1. Maximum value of 5000. Required: No PlaybackMode (p. 263) Whether to retrieve live, live replay, or archived, on-demand data. Features of the three types of sessions include the following: • LIVE : For sessions of this type, the MPEG-DASH manifest is continually updated with the latest fragments as they become available. We recommend that the media player retrieve a new manifest on a one-second interval. When this type of session is played in a media player, the user interface typically displays a "live" notification, with no scrubber control for choosing the position in the playback window to display. Note In LIVE mode, the newest available fragments are included in an MPEG-DASH manifest, even if there is a gap between fragments (that is, if a fragment is missing). A gap like this might cause a media player to halt or cause a jump in playback. In this mode, fragments are not added to the MPEG-DASH manifest if they are older than the newest fragment in the playlist. If the missing fragment becomes available after a subsequent fragment is added to the manifest, the older fragment is not added, and the gap is not filled. • LIVE_REPLAY : For sessions of this type, the MPEG-DASH manifest is updated similarly to how it is updated for LIVE mode except that it starts by including fragments from a given start time. 265 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Instead of fragments being added as they are ingested, fragments are added as the duration of the next fragment elapses. For example, if the fragments in the session are two seconds long, then a new fragment is added to the manifest every two seconds. This mode is useful to be able to start playback from when an event is detected and continue live streaming media that has not yet been ingested as of the time of the session creation. This mode is also useful to stream previously archived media without being limited by the 1,000 fragment limit in the ON_DEMAND mode. • ON_DEMAND : For sessions of this type, the MPEG-DASH manifest contains all the fragments for the session, up to the number that is specified in MaxManifestFragmentResults. The manifest must be retrieved only once for each session. When this type of session is played in a media player, the user interface typically displays a scrubber control for choosing the position in the playback window to display. In all playback modes, if FragmentSelectorType is PRODUCER_TIMESTAMP, and if there are multiple fragments with the same start timestamp, the fragment that has the larger fragment number (that is, the newer fragment) is included in the MPEG-DASH manifest. The other fragments are not included. Fragments that have different timestamps but have overlapping durations are still included in the MPEG-DASH manifest. This can lead to unexpected behavior in the media player. The default is LIVE. Type: String Valid Values: LIVE | LIVE_REPLAY | ON_DEMAND Required: No StreamARN (p. 263) The Amazon Resource Name (ARN) of the stream for which to retrieve the MPEG-DASH manifest URL. You must specify either the StreamName or the StreamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 263) The name of the stream for which to retrieve the MPEG-DASH manifest URL. You must specify either the StreamName or the StreamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-type: application/json 266 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media { "DASHStreamingSessionURL": "string" } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. DASHStreamingSessionURL (p. 266) The URL (containing the session token) that a media player can use to retrieve the MPEG-DASH manifest. Type: String Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded a limit. Try making the call later. For information about limits, see Kinesis Video Streams Limits. HTTP Status Code: 400 InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or can't be used. HTTP Status Code: 400 InvalidCodecPrivateDataException The codec private data in at least one of the tracks of the video stream is not valid for this operation. HTTP Status Code: 400 MissingCodecPrivateDataException No codec private data was found in at least one of tracks of the video stream. HTTP Status Code: 400 NoDataRetentionException A streaming session was requested for a stream that does not retain data (that is, has a DataRetentionInHours of 0). HTTP Status Code: 400 NotAuthorizedException Status Code: 403, The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 ResourceNotFoundException GetMedia throws this error when Kinesis Video Streams can't find the stream that you specified. 267 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media GetHLSStreamingSessionURL and GetDASHStreamingSessionURL throw this error if a session with a PlaybackMode of ON_DEMAND or LIVE_REPLAYis requested for a stream that has no fragments within the requested time range, or if a session with a PlaybackMode of LIVE is requested for a stream that has no fragments within the last 30 seconds. HTTP Status Code: 404 UnsupportedStreamMediaTypeException The type of the media (for example, h.264 or h.265 video or ACC or G.711 audio) could not be determined from the codec IDs of the tracks in the first fragment for a playback session. The codec ID for track 1 should be V_MPEG/ISO/AVC and, optionally, the codec ID for track 2 should be A_AAC. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 268 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media GetHLSStreamingSessionURL Service: Amazon Kinesis Video Streams Archived Media Retrieves an HTTP Live Streaming (HLS) URL for the stream. You can then open the URL in a browser or media player to view the stream contents. Both the StreamName and the StreamARN parameters are optional, but you must specify either the StreamName or the StreamARN when invoking this API operation. An Amazon Kinesis video stream has the following requirements for providing data through HLS: • The media must contain h.264 or h.265 encoded video and, optionally, AAC encoded audio. Specifically, the codec ID of track 1 should be V_MPEG/ISO/AVC (for h.264) or V_MPEG/ISO/HEVC (for h.265). Optionally, the codec ID of track 2 should be A_AAC. • Data retention must be greater than 0. • The video track of each fragment must contain codec private data in the Advanced Video Coding (AVC) for H.264 format or HEVC for H.265 format (MPEG-4 specification ISO/IEC 14496-15). For information about adapting stream data to a given format, see NAL Adaptation Flags. • The audio track (if present) of each fragment must contain codec private data in the AAC format (AAC specification ISO/IEC 13818-7). Kinesis Video Streams HLS sessions contain fragments in the fragmented MPEG-4 form (also called fMP4 or CMAF) or the MPEG-2 form (also called TS chunks, which the HLS specification also supports). For more information about HLS fragment types, see the HLS specification. The following procedure shows how to use HLS with Kinesis Video Streams: 1. Get an endpoint using GetDataEndpoint, specifying GET_HLS_STREAMING_SESSION_URL for the APIName parameter. 2. Retrieve the HLS URL using GetHLSStreamingSessionURL. Kinesis Video Streams creates an HLS streaming session to be used for accessing content in a stream using the HLS protocol. GetHLSStreamingSessionURL returns an authenticated URL (that includes an encrypted session token) for the session's HLS master playlist (the root resource needed for streaming with HLS). Note Don't share or store this token where an unauthorized entity could access it. The token provides access to the content of the stream. Safeguard the token with the same measures that you would use with your AWS credentials. The media that is made available through the playlist consists only of the requested stream, time range, and format. No other media data (such as frames outside the requested window or alternate bitrates) is made available. 3. Provide the URL (containing the encrypted session token) for the HLS master playlist to a media player that supports the HLS protocol. Kinesis Video Streams makes the HLS media playlist, initialization fragment, and media fragments available through the master playlist URL. The initialization fragment contains the codec private data for the stream, and other data needed to set up the video or audio decoder and renderer. The media fragments contain H.264-encoded video frames or AAC-encoded audio samples. 4. The media player receives the authenticated URL and requests stream metadata and media data normally. When the media player requests data, it calls the following actions: • GetHLSMasterPlaylist: Retrieves an HLS master playlist, which contains a URL for the GetHLSMediaPlaylist action for each track, and additional metadata for the media player, including estimated bitrate and resolution. • GetHLSMediaPlaylist: Retrieves an HLS media playlist, which contains a URL to access the MP4 initialization fragment with the GetMP4InitFragment action, and URLs to access the MP4 media 269 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media fragments with the GetMP4MediaFragment actions. The HLS media playlist also contains metadata about the stream that the player needs to play it, such as whether the PlaybackMode is LIVE or ON_DEMAND. The HLS media playlist is typically static for sessions with a PlaybackType of ON_DEMAND. The HLS media playlist is continually updated with new fragments for sessions with a PlaybackType of LIVE. There is a distinct HLS media playlist for the video track and the audio track (if applicable) that contains MP4 media URLs for the specific track. • GetMP4InitFragment: Retrieves the MP4 initialization fragment. The media player typically loads the initialization fragment before loading any media fragments. This fragment contains the "fytp" and "moov" MP4 atoms, and the child atoms that are needed to initialize the media player decoder. The initialization fragment does not correspond to a fragment in a Kinesis video stream. It contains only the codec private data for the stream and respective track, which the media player needs to decode the media frames. • GetMP4MediaFragment: Retrieves MP4 media fragments. These fragments contain the "moof" and "mdat" MP4 atoms and their child atoms, containing the encoded fragment's media frames and their timestamps. Note After the first media fragment is made available in a streaming session, any fragments that don't contain the same codec private data cause an error to be returned when those different media fragments are loaded. Therefore, the codec private data should not change between fragments in a session. This also means that the session fails if the fragments in a stream change from having only video to having both audio and video. Data retrieved with this action is billable. See Pricing for details. • GetTSFragment: Retrieves MPEG TS fragments containing both initialization and media data for all tracks in the stream. Note If the ContainerFormat is MPEG_TS, this API is used instead of GetMP4InitFragment and GetMP4MediaFragment to retrieve stream media. Data retrieved with this action is billable. For more information, see Kinesis Video Streams pricing. A streaming session URL must not be shared between players. The service might throttle a session if multiple media players are sharing it. For connection limits, see Kinesis Video Streams Limits. You can monitor the amount of data that the media player consumes by monitoring the GetMP4MediaFragment.OutgoingBytes Amazon CloudWatch metric. For information about using CloudWatch to monitor Kinesis Video Streams, see Monitoring Kinesis Video Streams. For pricing information, see Amazon Kinesis Video Streams Pricing and AWS Pricing. Charges for both HLS sessions and outgoing AWS data apply. For more information about HLS, see HTTP Live Streaming on the Apple Developer site. Important If an error is thrown after invoking a Kinesis Video Streams archived media API, in addition to the HTTP status code and the response body, it includes the following pieces of information: • x-amz-ErrorType HTTP header – contains a more specific error type in addition to what the HTTP status code provides. • x-amz-RequestId HTTP header – if you want to report an issue to AWS, the support team can better diagnose the problem if given the Request Id. 270 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Both the HTTP status code and the ErrorType header can be utilized to make programmatic decisions about whether errors are retry-able and under what conditions, as well as provide information on what actions the client programmer might need to take in order to successfully try again. For more information, see the Errors section at the bottom of this topic, as well as Common Errors. Request Syntax 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" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. ContainerFormat (p. 271) Specifies which format should be used for packaging the media. Specifying the FRAGMENTED_MP4 container format packages the media into MP4 fragments (fMP4 or CMAF). This is the recommended packaging because there is minimal packaging overhead. The other container format option is MPEG_TS. HLS has supported MPEG TS chunks since it was released and is sometimes the only supported packaging on older HLS players. MPEG TS typically has a 5-25 percent packaging overhead. This means MPEG TS typically requires 5-25 percent more bandwidth and cost than fMP4. The default is FRAGMENTED_MP4. Type: String Valid Values: FRAGMENTED_MP4 | MPEG_TS Required: No DiscontinuityMode (p. 271) Specifies when flags marking discontinuities between fragments are added to the media playlists. Media players typically build a timeline of media content to play, based on the timestamps of each fragment. This means that if there is any overlap or gap between fragments (as is typical if 271 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media HLSFragmentSelector (p. 304) is set to SERVER_TIMESTAMP), the media player timeline will also have small gaps between fragments in some places, and will overwrite frames in other places. Gaps in the media player timeline can cause playback to stall and overlaps can cause playback to be jittery. When there are discontinuity flags between fragments, the media player is expected to reset the timeline, resulting in the next fragment being played immediately after the previous fragment. The following modes are supported: • ALWAYS: a discontinuity marker is placed between every fragment in the HLS media playlist. It is recommended to use a value of ALWAYS if the fragment timestamps are not accurate. • NEVER: no discontinuity markers are placed anywhere. It is recommended to use a value of NEVER to ensure the media player timeline most accurately maps to the producer timestamps. • ON_DISCONTINUITY: a discontinuity marker is placed between fragments that have a gap or overlap of more than 50 milliseconds. For most playback scenarios, it is recommended to use a value of ON_DISCONTINUITY so that the media player timeline is only reset when there is a significant issue with the media timeline (e.g. a missing fragment). The default is ALWAYS when HLSFragmentSelector (p. 304) is set to SERVER_TIMESTAMP, and NEVER when it is set to PRODUCER_TIMESTAMP. Type: String Valid Values: ALWAYS | NEVER | ON_DISCONTINUITY Required: No DisplayFragmentTimestamp (p. 271) Specifies when the fragment start timestamps should be included in the HLS media playlist. Typically, media players report the playhead position as a time relative to the start of the first fragment in the playback session. However, when the start timestamps are included in the HLS media playlist, some media players might report the current playhead as an absolute time based on the fragment timestamps. This can be useful for creating a playback experience that shows viewers the wall-clock time of the media. The default is NEVER. When HLSFragmentSelector (p. 304) is SERVER_TIMESTAMP, the timestamps will be the server start timestamps. Similarly, when HLSFragmentSelector (p. 304) is PRODUCER_TIMESTAMP, the timestamps will be the producer start timestamps. Type: String Valid Values: ALWAYS | NEVER Required: No Expires (p. 271) The time in seconds until the requested session expires. This value can be between 300 (5 minutes) and 43200 (12 hours). When a session expires, no new calls to GetHLSMasterPlaylist, GetHLSMediaPlaylist, GetMP4InitFragment, GetMP4MediaFragment, or GetTSFragment can be made for that session. The default is 300 (5 minutes). Type: Integer Valid Range: Minimum value of 300. Maximum value of 43200. Required: No 272 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media HLSFragmentSelector (p. 271) The time range of the requested fragment and the source of the timestamps. This parameter is required if PlaybackMode is ON_DEMAND or LIVE_REPLAY. This parameter is optional if PlaybackMode is LIVE. If PlaybackMode is LIVE, the FragmentSelectorType can be set, but the TimestampRange should not be set. If PlaybackMode is ON_DEMAND or LIVE_REPLAY, both FragmentSelectorType and TimestampRange must be set. Type: HLSFragmentSelector (p. 304) object Required: No MaxMediaPlaylistFragmentResults (p. 271) The maximum number of fragments that are returned in the HLS media playlists. When the PlaybackMode is LIVE, the most recent fragments are returned up to this value. When the PlaybackMode is ON_DEMAND, the oldest fragments are returned, up to this maximum number. When there are a higher number of fragments available in a live HLS media playlist, video players often buffer content before starting playback. Increasing the buffer size increases the playback latency, but it decreases the likelihood that rebuffering will occur during playback. We recommend that a live HLS media playlist have a minimum of 3 fragments and a maximum of 10 fragments. The default is 5 fragments if PlaybackMode is LIVE or LIVE_REPLAY, and 1,000 if PlaybackMode is ON_DEMAND. The maximum value of 5,000 fragments corresponds to more than 80 minutes of video on streams with 1-second fragments, and more than 13 hours of video on streams with 10-second fragments. Type: Long Valid Range: Minimum value of 1. Maximum value of 5000. Required: No PlaybackMode (p. 271) Whether to retrieve live, live replay, or archived, on-demand data. Features of the three types of sessions include the following: • LIVE : For sessions of this type, the HLS media playlist is continually updated with the latest fragments as they become available. We recommend that the media player retrieve a new playlist on a one-second interval. When this type of session is played in a media player, the user interface typically displays a "live" notification, with no scrubber control for choosing the position in the playback window to display. Note In LIVE mode, the newest available fragments are included in an HLS media playlist, even if there is a gap between fragments (that is, if a fragment is missing). A gap like this might cause a media player to halt or cause a jump in playback. In this mode, fragments are not added to the HLS media playlist if they are older than the newest fragment in the playlist. If the missing fragment becomes available after a subsequent fragment is added to the playlist, the older fragment is not added, and the gap is not filled. • LIVE_REPLAY : For sessions of this type, the HLS media playlist is updated similarly to how it is updated for LIVE mode except that it starts by including fragments from a given start time. Instead of fragments being added as they are ingested, fragments are added as the duration of the next fragment elapses. For example, if the fragments in the session are two seconds long, then a new fragment is added to the media playlist every two seconds. This mode is useful to be able to start 273 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media playback from when an event is detected and continue live streaming media that has not yet been ingested as of the time of the session creation. This mode is also useful to stream previously archived media without being limited by the 1,000 fragment limit in the ON_DEMAND mode. • ON_DEMAND : For sessions of this type, the HLS media playlist contains all the fragments for the session, up to the number that is specified in MaxMediaPlaylistFragmentResults. The playlist must be retrieved only once for each session. When this type of session is played in a media player, the user interface typically displays a scrubber control for choosing the position in the playback window to display. In all playback modes, if FragmentSelectorType is PRODUCER_TIMESTAMP, and if there are multiple fragments with the same start timestamp, the fragment that has the largest fragment number (that is, the newest fragment) is included in the HLS media playlist. The other fragments are not included. Fragments that have different timestamps but have overlapping durations are still included in the HLS media playlist. This can lead to unexpected behavior in the media player. The default is LIVE. Type: String Valid Values: LIVE | LIVE_REPLAY | ON_DEMAND Required: No StreamARN (p. 271) The Amazon Resource Name (ARN) of the stream for which to retrieve the HLS master playlist URL. You must specify either the StreamName or the StreamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 271) The name of the stream for which to retrieve the HLS master playlist URL. You must specify either the StreamName or the StreamARN. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-type: application/json { "HLSStreamingSessionURL": "string" } 274 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. HLSStreamingSessionURL (p. 274) The URL (containing the session token) that a media player can use to retrieve the HLS master playlist. Type: String Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded a limit. Try making the call later. For information about limits, see Kinesis Video Streams Limits. HTTP Status Code: 400 InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or can't be used. HTTP Status Code: 400 InvalidCodecPrivateDataException The codec private data in at least one of the tracks of the video stream is not valid for this operation. HTTP Status Code: 400 MissingCodecPrivateDataException No codec private data was found in at least one of tracks of the video stream. HTTP Status Code: 400 NoDataRetentionException A streaming session was requested for a stream that does not retain data (that is, has a DataRetentionInHours of 0). HTTP Status Code: 400 NotAuthorizedException Status Code: 403, The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 ResourceNotFoundException GetMedia throws this error when Kinesis Video Streams can't find the stream that you specified. GetHLSStreamingSessionURL and GetDASHStreamingSessionURL throw this error if a session with a PlaybackMode of ON_DEMAND or LIVE_REPLAYis requested for a stream that has no fragments within the requested time range, or if a session with a PlaybackMode of LIVE is requested for a stream that has no fragments within the last 30 seconds. 275 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media HTTP Status Code: 404 UnsupportedStreamMediaTypeException The type of the media (for example, h.264 or h.265 video or ACC or G.711 audio) could not be determined from the codec IDs of the tracks in the first fragment for a playback session. The codec ID for track 1 should be V_MPEG/ISO/AVC and, optionally, the codec ID for track 2 should be A_AAC. HTTP Status Code: 400 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 276 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media GetMediaForFragmentList Service: Amazon Kinesis Video Streams Archived Media Gets media for a list of fragments (specified by fragment number) from the archived data in an Amazon Kinesis video stream. Note You must first call the GetDataEndpoint API to get an endpoint. Then send the GetMediaForFragmentList requests to this endpoint using the --endpoint-url parameter. For limits, see Kinesis Video Streams Limits. Important If an error is thrown after invoking a Kinesis Video Streams archived media API, in addition to the HTTP status code and the response body, it includes the following pieces of information: • x-amz-ErrorType HTTP header – contains a more specific error type in addition to what the HTTP status code provides. • x-amz-RequestId HTTP header – if you want to report an issue to AWS, the support team can better diagnose the problem if given the Request Id. Both the HTTP status code and the ErrorType header can be utilized to make programmatic decisions about whether errors are retry-able and under what conditions, as well as provide information on what actions the client programmer might need to take in order to successfully try again. For more information, see the Errors section at the bottom of this topic, as well as Common Errors. Request Syntax POST /getMediaForFragmentList HTTP/1.1 Content-type: application/json { "Fragments": [ "string" ], "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. Fragments (p. 277) A list of the numbers of fragments for which to retrieve media. You retrieve these values with ListFragments (p. 281). Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 1000 items. Length Constraints: Minimum length of 1. Maximum length of 128. 277 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Pattern: ^[0-9]+$ Required: Yes StreamARN (p. 277) The Amazon Resource Name (ARN) of the stream from which to retrieve fragment media. Specify either this parameter or the StreamName parameter. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 277) The name of the stream from which to retrieve fragment media. Specify either this parameter or the StreamARN parameter. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 Content-Type: ContentType Payload Response Elements If the action is successful, the service sends back an HTTP 200 response. The response returns the following HTTP headers. ContentType (p. 278) The content type of the requested media. Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^[a-zA-Z0-9_\.\-]+$ The response returns the following as the HTTP body. Payload (p. 278) The payload that Kinesis Video Streams returns is a sequence of chunks from the specified stream. For information about the chunks, see PutMedia. The chunks that Kinesis Video Streams returns in the GetMediaForFragmentList call also include the following additional Matroska (MKV) tags: • AWS_KINESISVIDEO_FRAGMENT_NUMBER - Fragment number returned in the chunk. 278 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media • AWS_KINESISVIDEO_SERVER_SIDE_TIMESTAMP - Server-side timestamp of the fragment. • AWS_KINESISVIDEO_PRODUCER_SIDE_TIMESTAMP - Producer-side timestamp of the fragment. The following tags will be included if an exception occurs: • AWS_KINESISVIDEO_FRAGMENT_NUMBER - The number of the fragment that threw the exception • AWS_KINESISVIDEO_EXCEPTION_ERROR_CODE - The integer code of the exception • AWS_KINESISVIDEO_EXCEPTION_MESSAGE - A text description of the exception Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded a limit. Try making the call later. For information about limits, see Kinesis Video Streams Limits. HTTP Status Code: 400 InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or can't be used. HTTP Status Code: 400 NotAuthorizedException Status Code: 403, The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 ResourceNotFoundException GetMedia throws this error when Kinesis Video Streams can't find the stream that you specified. GetHLSStreamingSessionURL and GetDASHStreamingSessionURL throw this error if a session with a PlaybackMode of ON_DEMAND or LIVE_REPLAYis requested for a stream that has no fragments within the requested time range, or if a session with a PlaybackMode of LIVE is requested for a stream that has no fragments within the last 30 seconds. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 279 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media 280 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media ListFragments Service: Amazon Kinesis Video Streams Archived Media Returns a list of Fragment (p. 302) objects from the specified stream and timestamp range within the archived data. Listing fragments is eventually consistent. This means that even if the producer receives an acknowledgment that a fragment is persisted, the result might not be returned immediately from a request to ListFragments. However, results are typically available in less than one second. Note You must first call the GetDataEndpoint API to get an endpoint. Then send the ListFragments requests to this endpoint using the --endpoint-url parameter. Important If an error is thrown after invoking a Kinesis Video Streams archived media API, in addition to the HTTP status code and the response body, it includes the following pieces of information: • x-amz-ErrorType HTTP header – contains a more specific error type in addition to what the HTTP status code provides. • x-amz-RequestId HTTP header – if you want to report an issue to AWS, the support team can better diagnose the problem if given the Request Id. Both the HTTP status code and the ErrorType header can be utilized to make programmatic decisions about whether errors are retry-able and under what conditions, as well as provide information on what actions the client programmer might need to take in order to successfully try again. For more information, see the Errors section at the bottom of this topic, as well as Common Errors. Request Syntax POST /listFragments HTTP/1.1 Content-type: application/json { "FragmentSelector": { "FragmentSelectorType": "string", "TimestampRange": { "EndTimestamp": number, "StartTimestamp": number } }, "MaxResults": number, "NextToken": "string", "StreamARN": "string", "StreamName": "string" } URI Request Parameters The request does not use any URI parameters. Request Body The request accepts the following data in JSON format. 281 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media FragmentSelector (p. 281) Describes the timestamp range and timestamp origin for the range of fragments to return. Type: FragmentSelector (p. 303) object Required: No MaxResults (p. 281) The total number of fragments to return. If the total number of fragments available is more than the value specified in max-results, then a ListFragments:NextToken (p. 283) is provided in the output that you can use to resume pagination. Type: Long Valid Range: Minimum value of 1. Maximum value of 1000. Required: No NextToken (p. 281) A token to specify where to start paginating. This is the ListFragments:NextToken (p. 283) from a previously truncated response. Type: String Length Constraints: Minimum length of 1. Maximum length of 4096. Pattern: [a-zA-Z0-9+/]+={0,2} Required: No StreamARN (p. 281) The Amazon Resource Name (ARN) of the stream from which to retrieve a fragment list. Specify either this parameter or the StreamName parameter. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName (p. 281) The name of the stream from which to retrieve a fragment list. Specify either this parameter or the StreamARN parameter. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Response Syntax HTTP/1.1 200 282 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Content-type: application/json { "Fragments": [ { "FragmentLengthInMilliseconds": number, "FragmentNumber": "string", "FragmentSizeInBytes": number, "ProducerTimestamp": number, "ServerTimestamp": number } ], "NextToken": "string" } Response Elements If the action is successful, the service sends back an HTTP 200 response. The following data is returned in JSON format by the service. Fragments (p. 282) A list of archived Fragment (p. 302) objects from the stream that meet the selector criteria. Results are in no specific order, even across pages. Type: Array of Fragment (p. 302) objects NextToken (p. 282) If the returned list is truncated, the operation returns this token to use to retrieve the next page of results. This value is null when there are no more results to return. Type: String Length Constraints: Minimum length of 1. Maximum length of 4096. Pattern: [a-zA-Z0-9+/]+={0,2} Errors For information about the errors that are common to all actions, see Common Errors (p. 306). ClientLimitExceededException Kinesis Video Streams has throttled the request because you have exceeded a limit. Try making the call later. For information about limits, see Kinesis Video Streams Limits. HTTP Status Code: 400 InvalidArgumentException A specified parameter exceeds its restrictions, is not supported, or can't be used. HTTP Status Code: 400 NotAuthorizedException Status Code: 403, The caller is not authorized to perform an operation on the given stream, or the token has expired. HTTP Status Code: 401 283 Amazon Kinesis Video Streams Guida per gli sviluppatori Data Types ResourceNotFoundException GetMedia throws this error when Kinesis Video Streams can't find the stream that you specified. GetHLSStreamingSessionURL and GetDASHStreamingSessionURL throw this error if a session with a PlaybackMode of ON_DEMAND or LIVE_REPLAYis requested for a stream that has no fragments within the requested time range, or if a session with a PlaybackMode of LIVE is requested for a stream that has no fragments within the last 30 seconds. HTTP Status Code: 404 See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS Command Line Interface • AWS SDK for .NET • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for JavaScript • AWS SDK for PHP V3 • AWS SDK for Python • AWS SDK for Ruby V3 Data Types The following data types are supported by Amazon Kinesis Video Streams: • ChannelInfo (p. 286) • ChannelNameCondition (p. 288) • ResourceEndpointListItem (p. 289) • SingleMasterChannelEndpointConfiguration (p. 290) • SingleMasterConfiguration (p. 291) • StreamInfo (p. 292) • StreamNameCondition (p. 294) • Tag (p. 295) The following data types are supported by Amazon Kinesis Video Streams Media: • StartSelector (p. 296) The following data types are supported by Amazon Kinesis Video Streams Archived Media: • ClipFragmentSelector (p. 298) • ClipTimestampRange (p. 299) • DASHFragmentSelector (p. 300) • DASHTimestampRange (p. 301) • Fragment (p. 302) 284 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams • FragmentSelector (p. 303) • HLSFragmentSelector (p. 304) • HLSTimestampRange (p. 305) • TimestampRange (p. 306) Amazon Kinesis Video Streams The following data types are supported by Amazon Kinesis Video Streams: • ChannelInfo (p. 286) • ChannelNameCondition (p. 288) • ResourceEndpointListItem (p. 289) • SingleMasterChannelEndpointConfiguration (p. 290) • SingleMasterConfiguration (p. 291) • StreamInfo (p. 292) • StreamNameCondition (p. 294) • Tag (p. 295) 285 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ChannelInfo Service: Amazon Kinesis Video Streams A structure that encapsulates a signaling channel's metadata and properties. Contents ChannelARN The Amazon Resource Name (ARN) of the signaling channel. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No ChannelName The name of the signaling channel. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No ChannelStatus Current status of the signaling channel. Type: String Valid Values: CREATING | ACTIVE | UPDATING | DELETING Required: No ChannelType The type of the signaling channel. Type: String Valid Values: SINGLE_MASTER | FULL_MESH Required: No CreationTime The time at which the signaling channel was created. Type: Timestamp Required: No SingleMasterConfiguration A structure that contains the configuration for the SINGLE_MASTER channel type. Type: SingleMasterConfiguration (p. 291) object 286 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Required: No Version The current version of the signaling channel. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 287 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ChannelNameCondition Service: Amazon Kinesis Video Streams An optional input parameter for the ListSignalingChannels API. When this parameter is specified while invoking ListSignalingChannels, the API returns only the channels that satisfy a condition specified in ChannelNameCondition. Contents ComparisonOperator A comparison operator. Currently, you can only specify the BEGINS_WITH operator, which finds signaling channels whose names begin with a given prefix. Type: String Valid Values: BEGINS_WITH Required: No ComparisonValue A value to compare. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 288 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams ResourceEndpointListItem Service: Amazon Kinesis Video Streams An object that describes the endpoint of the signaling channel returned by the GetSignalingChannelEndpoint API. Contents Protocol The protocol of the signaling channel returned by the GetSignalingChannelEndpoint API. Type: String Valid Values: WSS | HTTPS Required: No ResourceEndpoint The endpoint of the signaling channel returned by the GetSignalingChannelEndpoint API. Type: String Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 289 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams SingleMasterChannelEndpointConfiguration Service: Amazon Kinesis Video Streams An object that contains the endpoint configuration for the SINGLE_MASTER channel type. Contents Protocols This property is used to determine the nature of communication over this SINGLE_MASTER signaling channel. If WSS is specified, this API returns a websocket endpoint. If HTTPS is specified, this API returns an HTTPS endpoint. Type: Array of strings Array Members: Minimum number of 1 item. Maximum number of 5 items. Valid Values: WSS | HTTPS Required: No Role This property is used to determine messaging permissions in this SINGLE_MASTER signaling channel. If MASTER is specified, this API returns an endpoint that a client can use to receive offers from and send answers to any of the viewers on this signaling channel. If VIEWER is specified, this API returns an endpoint that a client can use only to send offers to another MASTER client on this signaling channel. Type: String Valid Values: MASTER | VIEWER Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 290 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams SingleMasterConfiguration Service: Amazon Kinesis Video Streams A structure that contains the configuration for the SINGLE_MASTER channel type. Contents MessageTtlSeconds The period of time a signaling channel retains underlivered messages before they are discarded. Type: Integer Valid Range: Minimum value of 5. Maximum value of 120. Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 291 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams StreamInfo Service: Amazon Kinesis Video Streams An object describing a Kinesis video stream. Contents CreationTime A time stamp that indicates when the stream was created. Type: Timestamp Required: No DataRetentionInHours How long the stream retains data, in hours. Type: Integer Valid Range: Minimum value of 0. Required: No DeviceName The name of the device that is associated with the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: [a-zA-Z0-9_.-]+ Required: No KmsKeyId The ID of the AWS Key Management Service (AWS KMS) key that Kinesis Video Streams uses to encrypt data on the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 2048. Pattern: .+ Required: No MediaType The MediaType of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: [\w\-\.\+]+/[\w\-\.\+]+(,[\w\-\.\+]+/[\w\-\.\+]+)* Required: No Status The status of the stream. 292 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Type: String Valid Values: CREATING | ACTIVE | UPDATING | DELETING Required: No StreamARN The Amazon Resource Name (ARN) of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 1024. Pattern: arn:[a-z\d-]+:kinesisvideo:[a-z0-9-]+:[0-9]+:[a-z]+/[a-zA-Z0-9_.-]+/ [0-9]+ Required: No StreamName The name of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No Version The version of the stream. Type: String Length Constraints: Minimum length of 1. Maximum length of 64. Pattern: [a-zA-Z0-9]+ Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 293 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams StreamNameCondition Service: Amazon Kinesis Video Streams Specifies the condition that streams must satisfy to be returned when you list streams (see the ListStreams API). A condition has a comparison operation and a value. Currently, you can specify only the BEGINS_WITH operator, which finds streams whose names start with a given prefix. Contents ComparisonOperator A comparison operator. Currently, you can specify only the BEGINS_WITH operator, which finds streams whose names start with a given prefix. Type: String Valid Values: BEGINS_WITH Required: No ComparisonValue A value to compare. Type: String Length Constraints: Minimum length of 1. Maximum length of 256. Pattern: [a-zA-Z0-9_.-]+ Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 294 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media Tag Service: Amazon Kinesis Video Streams A key and value pair that is associated with the specified signaling channel. Contents Key The key of the tag that is associated with the specified signaling channel. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^([\p{L}\p{Z}\p{N}_.:/=+\-@]*)$ Required: Yes Value The value of the tag that is associated with the specified signaling channel. Type: String Length Constraints: Minimum length of 0. Maximum length of 256. Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]* Required: Yes See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 Amazon Kinesis Video Streams Media The following data types are supported by Amazon Kinesis Video Streams Media: • StartSelector (p. 296) 295 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Media StartSelector Service: Amazon Kinesis Video Streams Media Identifies the chunk on the Kinesis video stream where you want the GetMedia API to start returning media data. You have the following options to identify the starting chunk: • Choose the latest (or oldest) chunk. • Identify a specific chunk. You can identify a specific chunk either by providing a fragment number or timestamp (server or producer). • Each chunk's metadata includes a continuation token as a Matroska (MKV) tag (AWS_KINESISVIDEO_CONTINUATION_TOKEN). If your previous GetMedia request terminated, you can use this tag value in your next GetMedia request. The API then starts returning chunks starting where the last API ended. Contents AfterFragmentNumber Specifies the fragment number from where you want the GetMedia API to start returning the fragments. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^[0-9]+$ Required: No ContinuationToken Continuation token that Kinesis Video Streams returned in the previous GetMedia response. The GetMedia API then starts with the chunk identified by the continuation token. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^[a-zA-Z0-9_\.\-]+$ Required: No StartSelectorType Identifies the fragment on the Kinesis video stream where you want to start getting the data from. • NOW - Start with the latest chunk on the stream. • EARLIEST - Start with earliest available chunk on the stream. • FRAGMENT_NUMBER - Start with the chunk after a specific fragment. You must also specify the AfterFragmentNumber parameter. • PRODUCER_TIMESTAMP or SERVER_TIMESTAMP - Start with the chunk containing a fragment with the specified producer or server timestamp. You specify the timestamp by adding StartTimestamp. • CONTINUATION_TOKEN - Read using the specified continuation token. Note If you choose the NOW, EARLIEST, or CONTINUATION_TOKEN as the startSelectorType, you don't provide any additional information in the startSelector. 296 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Type: String Valid Values: FRAGMENT_NUMBER | SERVER_TIMESTAMP | PRODUCER_TIMESTAMP | NOW | EARLIEST | CONTINUATION_TOKEN Required: Yes StartTimestamp A timestamp value. This value is required if you choose the PRODUCER_TIMESTAMP or the SERVER_TIMESTAMP as the startSelectorType. The GetMedia API then starts with the chunk containing the fragment that has the specified timestamp. Type: Timestamp Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 Amazon Kinesis Video Streams Archived Media The following data types are supported by Amazon Kinesis Video Streams Archived Media: • ClipFragmentSelector (p. 298) • ClipTimestampRange (p. 299) • DASHFragmentSelector (p. 300) • DASHTimestampRange (p. 301) • Fragment (p. 302) • FragmentSelector (p. 303) • HLSFragmentSelector (p. 304) • HLSTimestampRange (p. 305) • TimestampRange (p. 306) 297 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media ClipFragmentSelector Service: Amazon Kinesis Video Streams Archived Media Describes the timestamp range and timestamp origin of a range of fragments. Fragments that have duplicate producer timestamps are deduplicated. This means that if producers are producing a stream of fragments with producer timestamps that are approximately equal to the true clock time, the clip will contain all of the fragments within the requested timestamp range. If some fragments are ingested within the same time range and very different points in time, only the oldest ingested collection of fragments are returned. Contents FragmentSelectorType The origin of the timestamps to use (Server or Producer). Type: String Valid Values: PRODUCER_TIMESTAMP | SERVER_TIMESTAMP Required: Yes TimestampRange The range of timestamps to return. Type: ClipTimestampRange (p. 299) object Required: Yes See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 298 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media ClipTimestampRange Service: Amazon Kinesis Video Streams Archived Media The range of timestamps for which to return fragments. Contents EndTimestamp The end of the timestamp range for the requested media. This value must be within 24 hours of the specified StartTimestamp, and it must be later than the StartTimestamp value. If FragmentSelectorType for the request is SERVER_TIMESTAMP, this value must be in the past. This value is inclusive. The EndTimestamp is compared to the (starting) timestamp of the fragment. Fragments that start before the EndTimestamp value and continue past it are included in the session. Type: Timestamp Required: Yes StartTimestamp The starting timestamp in the range of timestamps for which to return fragments. Only fragments that start exactly at or after StartTimestamp are included in the session. Fragments that start before StartTimestamp and continue past it aren't included in the session. If FragmentSelectorType is SERVER_TIMESTAMP, the StartTimestamp must be later than the stream head. Type: Timestamp Required: Yes See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 299 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media DASHFragmentSelector Service: Amazon Kinesis Video Streams Archived Media Contains the range of timestamps for the requested media, and the source of the timestamps. Contents FragmentSelectorType The source of the timestamps for the requested media. When FragmentSelectorType is set to PRODUCER_TIMESTAMP and GetDASHStreamingSessionURL:PlaybackMode (p. 265) is ON_DEMAND or LIVE_REPLAY, the first fragment ingested with a producer timestamp within the specified FragmentSelector:TimestampRange (p. 303) is included in the media playlist. In addition, the fragments with producer timestamps within the TimestampRange ingested immediately following the first fragment (up to the GetDASHStreamingSessionURL:MaxManifestFragmentResults (p. 265) value) are included. Fragments that have duplicate producer timestamps are deduplicated. This means that if producers are producing a stream of fragments with producer timestamps that are approximately equal to the true clock time, the MPEG-DASH manifest will contain all of the fragments within the requested timestamp range. If some fragments are ingested within the same time range and very different points in time, only the oldest ingested collection of fragments are returned. When FragmentSelectorType is set to PRODUCER_TIMESTAMP and GetDASHStreamingSessionURL:PlaybackMode (p. 265) is LIVE, the producer timestamps are used in the MP4 fragments and for deduplication. But the most recently ingested fragments based on server timestamps are included in the MPEG-DASH manifest. This means that even if fragments ingested in the past have producer timestamps with values now, they are not included in the HLS media playlist. The default is SERVER_TIMESTAMP. Type: String Valid Values: PRODUCER_TIMESTAMP | SERVER_TIMESTAMP Required: No TimestampRange The start and end of the timestamp range for the requested media. This value should not be present if PlaybackType is LIVE. Type: DASHTimestampRange (p. 301) object Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 300 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media DASHTimestampRange Service: Amazon Kinesis Video Streams Archived Media The start and end of the timestamp range for the requested media. This value should not be present if PlaybackType is LIVE. The values in DASHimestampRange are inclusive. Fragments that start exactly at or after the start time are included in the session. Fragments that start before the start time and continue past it are not included in the session. Contents EndTimestamp The end of the timestamp range for the requested media. This value must be within 24 hours of the specified StartTimestamp, and it must be later than the StartTimestamp value. If FragmentSelectorType for the request is SERVER_TIMESTAMP, this value must be in the past. The EndTimestamp value is required for ON_DEMAND mode, but optional for LIVE_REPLAY mode. If the EndTimestamp is not set for LIVE_REPLAY mode then the session will continue to include newly ingested fragments until the session expires. Note This value is inclusive. The EndTimestamp is compared to the (starting) timestamp of the fragment. Fragments that start before the EndTimestamp value and continue past it are included in the session. Type: Timestamp Required: No StartTimestamp The start of the timestamp range for the requested media. If the DASHTimestampRange value is specified, the StartTimestamp value is required. Only fragments that start exactly at or after StartTimestamp are included in the session. Fragments that start before StartTimestamp and continue past it aren't included in the session. If FragmentSelectorType is SERVER_TIMESTAMP, the StartTimestamp must be later than the stream head. Type: Timestamp Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 301 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media Fragment Service: Amazon Kinesis Video Streams Archived Media Represents a segment of video or other time-delimited data. Contents FragmentLengthInMilliseconds The playback duration or other time value associated with the fragment. Type: Long Required: No FragmentNumber The unique identifier of the fragment. This value monotonically increases based on the ingestion order. Type: String Length Constraints: Minimum length of 1. Maximum length of 128. Pattern: ^[0-9]+$ Required: No FragmentSizeInBytes The total fragment size, including information about the fragment and contained media data. Type: Long Required: No ProducerTimestamp The timestamp from the producer corresponding to the fragment. Type: Timestamp Required: No ServerTimestamp The timestamp from the AWS server corresponding to the fragment. Type: Timestamp Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 302 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media FragmentSelector Service: Amazon Kinesis Video Streams Archived Media Describes the timestamp range and timestamp origin of a range of fragments. Only fragments with a start timestamp greater than or equal to the given start time and less than or equal to the end time are returned. For example, if a stream contains fragments with the following start timestamps: • 00:00:00 • 00:00:02 • 00:00:04 • 00:00:06 A fragment selector range with a start time of 00:00:01 and end time of 00:00:04 would return the fragments with start times of 00:00:02 and 00:00:04. Contents FragmentSelectorType The origin of the timestamps to use (Server or Producer). Type: String Valid Values: PRODUCER_TIMESTAMP | SERVER_TIMESTAMP Required: Yes TimestampRange The range of timestamps to return. Type: TimestampRange (p. 306) object Required: Yes See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 303 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media HLSFragmentSelector Service: Amazon Kinesis Video Streams Archived Media Contains the range of timestamps for the requested media, and the source of the timestamps. Contents FragmentSelectorType The source of the timestamps for the requested media. When FragmentSelectorType is set to PRODUCER_TIMESTAMP and GetHLSStreamingSessionURL:PlaybackMode (p. 273) is ON_DEMAND or LIVE_REPLAY, the first fragment ingested with a producer timestamp within the specified FragmentSelector:TimestampRange (p. 303) is included in the media playlist. In addition, the fragments with producer timestamps within the TimestampRange ingested immediately following the first fragment (up to the GetHLSStreamingSessionURL:MaxMediaPlaylistFragmentResults (p. 273) value) are included. Fragments that have duplicate producer timestamps are deduplicated. This means that if producers are producing a stream of fragments with producer timestamps that are approximately equal to the true clock time, the HLS media playlists will contain all of the fragments within the requested timestamp range. If some fragments are ingested within the same time range and very different points in time, only the oldest ingested collection of fragments are returned. When FragmentSelectorType is set to PRODUCER_TIMESTAMP and GetHLSStreamingSessionURL:PlaybackMode (p. 273) is LIVE, the producer timestamps are used in the MP4 fragments and for deduplication. But the most recently ingested fragments based on server timestamps are included in the HLS media playlist. This means that even if fragments ingested in the past have producer timestamps with values now, they are not included in the HLS media playlist. The default is SERVER_TIMESTAMP. Type: String Valid Values: PRODUCER_TIMESTAMP | SERVER_TIMESTAMP Required: No TimestampRange The start and end of the timestamp range for the requested media. This value should not be present if PlaybackType is LIVE. Type: HLSTimestampRange (p. 305) object Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 304 Amazon Kinesis Video Streams Guida per gli sviluppatori Amazon Kinesis Video Streams Archived Media HLSTimestampRange Service: Amazon Kinesis Video Streams Archived Media The start and end of the timestamp range for the requested media. This value should not be present if PlaybackType is LIVE. Contents EndTimestamp The end of the timestamp range for the requested media. This value must be within 24 hours of the specified StartTimestamp, and it must be later than the StartTimestamp value. If FragmentSelectorType for the request is SERVER_TIMESTAMP, this value must be in the past. The EndTimestamp value is required for ON_DEMAND mode, but optional for LIVE_REPLAY mode. If the EndTimestamp is not set for LIVE_REPLAY mode then the session will continue to include newly ingested fragments until the session expires. Note This value is inclusive. The EndTimestamp is compared to the (starting) timestamp of the fragment. Fragments that start before the EndTimestamp value and continue past it are included in the session. Type: Timestamp Required: No StartTimestamp The start of the timestamp range for the requested media. If the HLSTimestampRange value is specified, the StartTimestamp value is required. Only fragments that start exactly at or after StartTimestamp are included in the session. Fragments that start before StartTimestamp and continue past it aren't included in the session. If FragmentSelectorType is SERVER_TIMESTAMP, the StartTimestamp must be later than the stream head. Type: Timestamp Required: No See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 305 Amazon Kinesis Video Streams Guida per gli sviluppatori Common Errors TimestampRange Service: Amazon Kinesis Video Streams Archived Media The range of timestamps for which to return fragments. Contents EndTimestamp The ending timestamp in the range of timestamps for which to return fragments. Type: Timestamp Required: Yes StartTimestamp The starting timestamp in the range of timestamps for which to return fragments. Type: Timestamp Required: Yes See Also For more information about using this API in one of the language-specific AWS SDKs, see the following: • AWS SDK for C++ • AWS SDK for Go • AWS SDK for Java V2 • AWS SDK for Ruby V3 Common Errors This section lists the errors common to the API actions of all AWS services. For errors specific to an API action for this service, see the topic for that API action. AccessDeniedException You do not have sufficient access to perform this action. HTTP Status Code: 400 IncompleteSignature The request signature does not conform to AWS standards. HTTP Status Code: 400 InternalFailure The request processing has failed because of an unknown error, exception or failure. HTTP Status Code: 500 InvalidAction The action or operation requested is invalid. Verify that the action is typed correctly. 306 Amazon Kinesis Video Streams Guida per gli sviluppatori Common Errors HTTP Status Code: 400 InvalidClientTokenId The X.509 certificate or AWS access key ID provided does not exist in our records. HTTP Status Code: 403 InvalidParameterCombination Parameters that must not be used together were used together. HTTP Status Code: 400 InvalidParameterValue An invalid or out-of-range value was supplied for the input parameter. HTTP Status Code: 400 InvalidQueryParameter The AWS query string is malformed or does not adhere to AWS standards. HTTP Status Code: 400 MalformedQueryString The query string contains a syntax error. HTTP Status Code: 404 MissingAction The request is missing an action or a required parameter. HTTP Status Code: 400 MissingAuthenticationToken The request must contain either a valid (registered) AWS access key ID or X.509 certificate. HTTP Status Code: 403 MissingParameter A required parameter for the specified action is not supplied. HTTP Status Code: 400 NotAuthorized You do not have permission to perform this action. HTTP Status Code: 400 OptInRequired The AWS access key ID needs a subscription for the service. HTTP Status Code: 403 RequestExpired The request reached the service more than 15 minutes after the date stamp on the request or more than 15 minutes after the request expiration date (such as for pre-signed URLs), or the date stamp on the request is more than 15 minutes in the future. HTTP Status Code: 400 307 Amazon Kinesis Video Streams Guida per gli sviluppatori Common Parameters ServiceUnavailable The request has failed due to a temporary failure of the server. HTTP Status Code: 503 ThrottlingException The request was denied due to request throttling. HTTP Status Code: 400 ValidationError The input fails to satisfy the constraints specified by an AWS service. HTTP Status Code: 400 Common Parameters The following list contains the parameters that all actions use for signing Signature Version 4 requests with a query string. Any action-specific parameters are listed in the topic for that action. For more information about Signature Version 4, see Signature Version 4 Signing Process in the Amazon Web Services General Reference. Action The action to be performed. Type: string Required: Yes Version The API version that the request is written for, expressed in the format YYYY-MM-DD. Type: string Required: Yes X-Amz-Algorithm The hash algorithm that you used to create the request signature. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Valid Values: AWS4-HMAC-SHA256 Required: Conditional X-Amz-Credential The credential scope value, which is a string that includes your access key, the date, the region you are targeting, the service you are requesting, and a termination string ("aws4_request"). The value is expressed in the following format: access_key/YYYYMMDD/region/service/aws4_request. For more information, see Task 2: Create a String to Sign for Signature Version 4 in the Amazon Web Services General Reference. 308 Amazon Kinesis Video Streams Guida per gli sviluppatori Common Parameters Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional X-Amz-Date The date that is used to create the signature. The format must be ISO 8601 basic format (YYYYMMDD'T'HHMMSS'Z'). For example, the following date time is a valid X-Amz-Date value: 20120325T120000Z. Condition: X-Amz-Date is optional for all requests; it can be used to override the date used for signing requests. If the Date header is specified in the ISO 8601 basic format, X-Amz-Date is not required. When X-Amz-Date is used, it always overrides the value of the Date header. For more information, see Handling Dates in Signature Version 4 in the Amazon Web Services General Reference. Type: string Required: Conditional X-Amz-Security-Token The temporary security token that was obtained through a call to AWS Security Token Service (AWS STS). For a list of services that support temporary security credentials from AWS Security Token Service, go to AWS Services That Work with IAM in the IAM User Guide. Condition: If you're using temporary security credentials from the AWS Security Token Service, you must include the security token. Type: string Required: Conditional X-Amz-Signature Specifies the hex-encoded signature that was calculated from the string to sign and the derived signing key. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional X-Amz-SignedHeaders Specifies all the HTTP headers that were included as part of the canonical request. For more information about specifying signed headers, see Task 1: Create a Canonical Request For Signature Version 4 in the Amazon Web Services General Reference. Condition: Specify this parameter when you include authentication information in a query string instead of in the HTTP authorization header. Type: string Required: Conditional 309 Amazon Kinesis Video Streams Guida per gli sviluppatori 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à. cccx