# Embedding di metadati all'interno di un flusso video I metadati temporizzati di Amazon Interactive Video Service (IVS) forniscono un modo per incorporare i metadati in un flusso Amazon IVS. Assicurano che tutti gli spettatori ricevano i metadati nel flusso video contemporaneamente, indipendentemente dalla latenza dello streaming o dalla posizione geografica. ## Che cosa sono i metadati temporizzati? I metadati *temporizzati* sono metadati con un timestamp. Possono essere inseriti in un flusso a livello di codice tramite API IVS o SDK di trasmissione IVS. Quando Amazon IVS elabora un flusso, i metadati temporizzati vengono sincronizzati con i fotogrammi audio e video. Durante la riproduzione, tutti gli spettatori dello stream ottengono i metadati contemporaneamente. Il codice temporale funge da punto di partenza e può essere utilizzato per attivare un'azione basata sui dati, ad esempio: + Aggiornamento delle statistiche dei giocatori per un flusso sportivo. + Invio dei dettagli del prodotto per uno streaming di shopping live. + Invio di domande per uno streaming di quiz dal vivo. I metadati temporizzati di Amazon IVS utilizzano i tag ID3 incorporati nei segmenti video. Di conseguenza, sono disponibili nel video registrato. ## Impostazione delle autorizzazioni IAM **Prerequisito:** prima di procedere, devi avere completato [Guida introduttiva allo streaming a bassa latenza IVS](getting-started.md) (inclusa la creazione di un utente IAM e la configurazione delle autorizzazioni). Successivamente, dovrai concedere all'utente IAM l'autorizzazione per utilizzare i metadati temporizzati. Completa la procedura riportata di seguito. 1. Accedi alla Gestione della Console AWS e apri la console IAM all'indirizzo [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/). 1. Nel riquadro di navigazione, seleziona **Utenti**, quindi scegli l'utente desiderato (il nome utente specificato al momento della creazione di un account AWS). 1. Nella finestra **Riepilogo** dell'utente, nella scheda **Autorizzazioni**, scegli **Aggiungi policy inline** (sul lato destro). 1. Nella scheda **JSON**, incolla quanto riportato di seguito: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "ivs:PutMetadata" ], "Resource": "arn:aws:ivs:*:*:channel/*" } ] } ``` ------ 1. Sempre nella finestra **Crea policy**, seleziona **Esamina policy**. Assegna un **nome** alla policy, quindi seleziona **Crea policy**. 1. A questo punto sarà visualizzata di nuovo la finestra **Riepilogo** dell'utente e il nome della nuova policy sarà disponibile. ## Inserimento dei metadati temporizzati È possibile inserire metadati temporizzati solo in un flusso attivo su un canale specificato. ### Utilizzo della AWS CLI A scopo di test, il modo più semplice per aggiungere metadati temporizzati è utilizzare la AWS CLI. L'utilizzo della AWS CLI richiede prima il download e la configurazione della CLI sul computer. Potresti averlo già fatto durante la fase [Guida introduttiva allo streaming a bassa latenza IVS](getting-started.md); in caso contrario, puoi farlo ora. Per maggiori dettagli, consulta la [Guida per l'utente dell'interfaccia a riga di comando di AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). Una volta che la CLI è disponibile: 1. Esegui il comando `put-metadata` e inoltra l'ARN del canale e i metadati: ``` aws ivs put-metadata --channel-arn --metadata ``` Ad esempio: ``` aws ivs put-metadata --channel-arn arn:aws:ivs:us-west-2:465369119046:channel/GbiYJna5hFoC --metadata '{"question": "What does IVS stand for?", "correctIndex": 0, "answers": ["interactive video service", "interesting video service", "ingenious video service"]}' ``` 1. Amazon IVS verifica se lo streaming è attivo. Se non lo è, viene visualizzato un errore; in caso contrario, l'interfaccia a riga di comando procede senza errori e i metadati (blob di testo) vengono inseriti nel flusso. Questo accade il più velocemente possibile. Non vi è alcuna garanzia su quando ciò si verifica; tuttavia, tutti gli spettatori vedono i metadati nello stesso punto del flusso. ### Utilizzo dell'API Amazon IVS Per inserire i metadati temporizzati a livello di programmazione, usa l'operazione dell'API [PutMetadata](https://docs.aws.amazon.com/ivs/latest/LowLatencyAPIReference/API_PutMetadata.html). Ecco un esempio di richiesta HTTP: ``` POST /PutMetadata HTTP/1.1 { "channelArn": "my_channel", "metadata": "{\"question\": \"What does IVS stand for?\", \"correctIndex\": 0, \"answers\": [\"interactive video service\", \"interesting video service\", \"ingenious video service\"]}" } ``` ### Utilizzo dell'SDK di trasmissione IVS È possibile inserire metadati temporizzati in banda utilizzando SDK di trasmissione IVS. Può essere utile per sincronizzare i metadati con i contenuti audio e video. + Android: in classe `BroadcastSession`, usa `sendTimedMetadata`. + iOS: in classe `IVSBroadcastSession`, usa `sendTimedMetadata`. ## Utilizzo di metadati temporizzati Utilizza il lettore Amazon IVS per utilizzare metadati temporizzati incorporati in un flusso video. Consulta [SDK del lettore IVS](player.md) e il resto della documentazione del lettore. Di seguito sono riportati alcuni frammenti di esempio che stampano tutti i metadati ricevuti sulla console utilizzando l'SDK del lettore Amazon IVS. Ogni volta che la riproduzione raggiunge un segmento con metadati incorporati viene attivato un evento. (L'evento è `TEXT_METADATA_CUE` per Web, `onCue()` per Android e `player(_:didOutputCue:)` per iOS.) È possibile utilizzare questo evento per avviare funzionalità all'interno dell'applicazione client, ad esempio l'aggiornamento di un widget interattivo. Questo evento viene attivato sia per il contenuto live che per quello registrato. **SDK del lettore Amazon IVS per Web:** ``` const player = IVSPlayer.create(); player.addEventListener(IVSPlayer.PlayerEventType.TEXT_METADATA_CUE, function (cue) { console.log('Timed metadata: ', cue.text); }); ``` **SDK del lettore Amazon IVS per Android:** ``` @Override public void onCue(@NonNull Cue cue) { if(cue instanceof TextMetadataCue) { Log.i("Timed Metadata: ", ((TextMetadataCue)cue).text); } } ``` **SDK del lettore Amazon IVS per iOS:** ``` func player(_ player: IVSPlayer, didOutputCue cue: IVSCue) { if let textMetadataCue = cue as? IVSTextMetadataCue { print("Timed Metadata: \(textMetadataCue.text)") } } ``` **Nota:** i metadati temporizzati sono supportati per iOS Safari e iOS Chrome nel lettore 1.3.0 e versioni successive. ### Consumo di dati SEI Quando le fasi IVS in tempo reale vengono registrate con la registrazione dei singoli partecipanti abilitata, i payload SEI (Supplemental Enhancement Information) vengono conservati e pubblicati come eventi `IVSPlayer.PlayerEventType.SEI`. Di seguito è riportato un frammento di esempio che stampa i dati SEI sulla console quando si utilizza l'SDK del lettore Web IVS: ``` const player = IVSPlayer.create(); player.addEventListener(IVSPlayer.MetadataEventType.SEI, (event) => { const data = new TextDecoder().decode(event.data); const message = JSON.parse(data); console.log(message); }); ``` **Nota:** per ulteriori informazioni su SEI, consulta [Supplemental Enhancement Information (SEI)](https://docs.aws.amazon.com/ivs/latest/RealTimeUserGuide/web-publish-subscribe.html#web-publish-subscribe-sei-attributes) nella *Guida all'SDK di trasmissione Web IVS* per lo streaming in tempo reale. ### Demo di esempio: App Quiz Esempi di codice di un'app di quiz interattiva sono disponibili su GitHub. Utilizziamo JSON tramite metadati temporizzati per popolare un'interfaccia utente di quiz per visualizzare domande e risposte. Le risposte sono selezionabili e rivelano se la selezione è corretta. | Piattaforma di SDK del lettore Amazon IVS | Repository di esempi | | --- | --- | | Web | [https://github.com/aws-samples/amazon-ivs-basic-web-sample](https://github.com/aws-samples/amazon-ivs-basic-web-sample)All'interno di questo repository, consulta la [Demo quiz](https://github.com/aws-samples/amazon-ivs-basic-web-sample/tree/master/simple-quiz) (e [Demo live](https://codepen.io/amazon-ivs/pen/XWmjEKN)). | | Android | [https://github.com/aws-samples/amazon-ivs-player-android-sample](https://github.com/aws-samples/amazon-ivs-player-android-sample)All'interno di questo repository, consulta la [Demo quiz](https://github.com/aws-samples/amazon-ivs-player-android-sample/tree/master/quizdemo). | | iOS | [https://github.com/aws-samples/amazon-ivs-player-ios-sample](https://github.com/aws-samples/amazon-ivs-player-ios-sample)All'interno di questo repository, consulta la [Demo quiz](https://github.com/aws-samples/amazon-ivs-player-ios-sample/tree/master/QuizDemo). | ## Visualizzazione dei metadati temporizzati Se lo desideri, puoi visualizzare i metadati temporizzati incorporati nel live streaming nella console: 1. Apri la [console Amazon IVS](https://console.aws.amazon.com/ivs). 1. In alto a sinistra, scegli l'icona dell'hamburger per aprire il riquadro di navigazione, quindi seleziona **Canali live**. 1. Scegli il canale di cui vuoi visualizzare lo streaming per andare alla pagina dei dettagli per quel canale. Il live streaming è in riproduzione nella sezione **Streaming live** della pagina. 1. Nella parte inferiore della finestra, seleziona **Metadati temporizzati**. Durante la riproduzione del lettore, quando viene ricevuto un evento con metadati temporizzati, vengono visualizzati il valore e l'ora di ricezione. ## Ulteriori informazioni Consulta [Utilizzo dei metadati temporizzati di Amazon Interactive Video Service](https://aws.amazon.com/blogs/media/part-1-using-amazon-interactive-video-service-timed-metadata/), la prima di una serie di blog in due parti sull'utilizzo dei metadati temporizzati di Amazon IVS.