SDK IVS Player: integrazione di Video.js - Amazon IVS
Nozioni di baseEventiErroriPlug-inPolicy di sicurezza dei contenutiFunzionicurrentTimeeliminaduratagetIVSEventsgetIVSPlayercaricaregiocareplaybackRatericercabile

SDK IVS Player: integrazione di Video.js

In questo documento sono descritte le funzioni più importanti disponibili nel lettore Video.js di Amazon Interactive Video Service (IVS).

Ultima versione dell'integrazione del lettore Video.js: 1.41.0 (Note di rilascio)

Nozioni di base

Il supporto Amazon IVS per Video.js viene implementato tramite la tecnologia di Video.js. Forniamo supporto attraverso tag di script e attraverso un modulo npm. Amazon IVS supporta le versioni Video.js 7.6.6 e 7* e 8* successive.

Tenere presente che quando si crea un'istanza del lettore, l'opzione sources di Video.js non è supportata. Invece, è possibile creare un'istanza del lettore normalmente e chiamare la funzione src() di Video.js. Se la riproduzione automatica è abilitata, il flusso inizierà la riproduzione; in caso contrario, utilizzare play() per avviare la riproduzione.

Demo

La seguente demo live mostra come utilizzare l'integrazione di Video.js con i tag script dalla nostra rete di distribuzione di contenuti (CDN): Integrazione del lettore Video.js per Amazon IVS.

Configurazione con tag di script

Per configurare la tecnologia Amazon IVS utilizzando il tag script:

  1. Includere il seguente tag (per l'ultima versione dell'integrazione del lettore).

    <script src="https://player.live-video.net/1.41.0/amazon-ivs-videojs-tech.min.js"></script>

  2. Registrare la tecnologia utilizzando la funzione registerIVSTech:

    registerIVSTech(videojs);

    dove videojs è l'oggetto fornito da Video.js.

  3. Quando si crea un'istanza del lettore, aggiungere AmazonIVScome prima tecnologia nell'opzione techOrder.

Quando si crea un'istanza del lettore, l'opzione sources di Video.js non è supportata. Invece, per impostare l'origine si può creare normalmente un'istanza del lettore e poi richiamare la funzione src() di Video.js su di essa. Se la riproduzione automatica è abilitata, il flusso inizierà la riproduzione; in caso contrario, utilizza play() per avviare la riproduzione.

Codice di esempio

In questo esempio, PLAYBACK_URL è il flusso di origine che si desidera caricare. Nell'esempio viene utilizzata la versione più recente del lettore Amazon IVS.

<!doctype html>
<html lang="en">
<head>
    <link href="https://cdnjs.cloudflare.com/ajax/libs/video.js/7.14.3/video-js.css" rel="stylesheet">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/7.14.3/video.min.js"></script>
    <script src="https://player.live-video.net/1.41.0/amazon-ivs-videojs-tech.min.js"></script>
</head>

<body>
    <div class="video-container">
        <video id="amazon-ivs-videojs" class="video-js vjs-4-3 vjs-big-play-centered" controls autoplay playsinline></video>
    </div>
    <style>
        body {
            margin: 0;
        }

        .video-container {
            width: 640px;
            height: 480px;
            margin: 15px;
        }
    </style>
    <script>
        (function play() {
            // Get playback URL from Amazon IVS API
            var PLAYBACK_URL = '';
            
            // Register Amazon IVS as playback technology for Video.js
            registerIVSTech(videojs);

            // Initialize player
            var player = videojs('amazon-ivs-videojs', {
               techOrder: ["AmazonIVS"]
            }, () => {
               console.log('Player is ready to use!');
               // Play stream
               player.src(PLAYBACK_URL);
            });
        })();
    </script>
</body>
</html>

Configurazione con NPM

Per utilizzare il lettore Amazon IVS tramite npm:

  1. Installare il pacchetto npm video.js o assicurarsi che il progetto abbia qualche altro accesso alla libreria Video.js.

  2. Installare il pacchetto npm amazon-ivs-player:

    npm install amazon-ivs-player

  3. Una volta pronti a registrare la tecnologia Amazon IVS, importare la funzione registerIVSTech:

    import { registerIVSTech } from 'amazon-ivs-player';

  4. Registra la tecnologia utilizzando la funzione registerIVSTech:

    registerIVSTech(videojs, options);

    dove:

    • videojs è l'oggetto fornito da Video.js.

    • options sono le opzioni per il livello tecnico di Amazon IVS. Le opzioni supportate sono:

      • wasmWorker: l'URL in cui è ospitato il file amazon-ivs-wasmworker.min.js.

      • wasmBinary: l'URL in cui è ospitato il file amazon-ivs-wasmworker.min.wasm.

      I file worker si trovano nella cartella node_modules/ in amazon-ivs-player/dist/. Per utilizzare il lettore IVS, questi file dovranno essere disponibili.

  5. Quando si crea un'istanza del lettore, aggiungere AmazonIVS come prima tecnologia nell'opzione techOrder:

    const player = videojs('videojs-player', {
    techOrder: ["AmazonIVS"]
});

TypeScript

Se si sta usando TypeScript, il nostro pacchetto npm include i seguenti tipi da poter importare e utilizzare.

  • VideoJSEvents, che descrive la struttura restituita da getIVSEvents().

  • VideoJSIVSTech, che descrive l'interfaccia di un'istanza del lettore che utilizza la tecnologia AmazonIVS. Ciò può aggiungersi al tipo VideoJsPlayer utilizzato dal pacchetto npm @types/video.js.

  • TechOptions, che descrive l'interfaccia che definisce le opzioni di configurazione che è possibile inviare aregisterIVSTech().

Per ulteriori informazioni su questi tipi, consultare SDK Amazon IVS Player: Documentazione di riferimento per il Web.

Eventi

Per ascoltare gli eventi Video.js standard, utilizzare la funzione on del lettore Video.js.

Per ascoltare gli eventi specifici di Amazon IVS, aggiungere e rimuovere i listener di eventi sul lettore Web Amazon IVS:

player.getIVSPlayer().addEventListener(event, callback);
player.getIVSPlayer().removeEventListener(event, callback);

dove callback è un callback definito e event è una delle seguenti opzioni: PlayerEventType o PlayerState. Per ulteriori informazioni sugli eventi, consultare SDK Amazon IVS Player: Documentazione di riferimento per il Web.

Errori

Per errori generali Video.js, ascoltare l'evento error generico sul lettore:

player.on("error", callback);

Per gli errori specifici di Amazon IVS, ascoltare il lettore Amazon IVS per i propri errori:

let playerEvent = player.getIVSEvents().PlayerEventType;
player.getIVSPlayer().addEventListener(playerEvent.ERROR, callback);

Il callback riceverà un oggetto con i seguenti campi:

Campo Descrizione

type

Il tipo di errore. Corrisponde agli eventi ErrorType. Per ulteriori informazioni, consultare SDK Amazon IVS Player: Documentazione di riferimento per il Web.

code

 Il codice di errore.

source

 L'origine dell'errore.

message

 Un messaggio di errore leggibile dall'utente.

Plug-in

Forniamo un plugin che crea un interruttore dell'interfaccia utente per le qualità disponibili. Per poter essere utilizzato, questo plugin deve essere caricato includendo il file amazon-ivs-quality-plugin.min.js se si sta usando la nostra tecnologia tramite il seguente tag script (per l'ultima versione di lettore IVS): 

<script src="https://player.live-video.net/1.41.0/amazon-ivs-quality-plugin.min.js"></script>

Se si utilizza npm, importare il registerIVSQualityPlugin dal modulo amazon-ivs-player:

import { registerIVSQualityPlugin } from 'amazon-ivs-player';

Quindi, una volta creata un'istanza del lettore Video.js, per registrarlo e abilitarlo saranno necessarie le seguenti chiamate:

registerIVSQualityPlugin(videojs); // where videojs is the video.js variable
player.enableIVSQualityPlugin(); // where player is the instance of the videojs player

Questa operazione creerà un pulsante di menu dell'interfaccia utente che consente di selezionare una qualità per il flusso.

Plugin e TypeScript

Se si sta usando TypeScript, il nostro pacchetto npm include il tipo VideoJSQualityPlugin da poter importare e utilizzare con il nostro plugin. I plugin sono essenzialmente misti, quindi l'interfaccia di questo tipo deve essere utilizzata come tipo di intersezione con l'interfaccia TypeScript VideoJSIVSTech.

Policy di sicurezza dei contenuti

L'API Video.js di Amazon IVS è configurata per funzionare sulle pagine che utilizzano le policy di sicurezza dei contenuti (CSP). Consultare la sezione "Utilizzo della policy di sicurezza dei contenuti" nella SDK IVS Player: guida per il web.

Funzioni

Riproduzione

L'API Video.js di Amazon IVS supporta le interfacce necessarie per l'uso interno da parte del framework Video.js. È probabile che l'applicazione client non necessiti di utilizzare direttamente questi metodi, poiché Video.js esegue l'integrazione necessaria e presenta un'interfaccia standard. Tuttavia, se necessario, un modo per accedere ai metodi interni di Video.js e del lettore Amazon IVS consiste nell'utilizzare l'oggetto del lettore Video.js in modo da ottenere l'handle dell'oggetto necessario alla tecnologia.

Per accedere all'API, recuperare l'istanza del lettore Video.js come si farebbe normalmente:

let player = videojs("videoTagId"); //replace videoTagId with your <video> tag’s id

Quindi richiamare le funzioni su quell'istanza.

Di seguito è riportata la serie di funzioni di Video.js che il livello tecnico di Amazon IVS sovrascrive. Per l'elenco completo delle funzioni di Video.js, consultare la documentazione dell'API Video.js.

Funzione Descrizione e informazioni specifiche su Amazon IVS

currentTime

Ottiene o imposta l'ora, espressa in secondi dall'inizio.

Amazon IVS: si consiglia di non impostare l'ora corrente per i live streaming.

elimina

Elimina l'istanza del lettore

Amazon IVS: elimina anche il backend tecnologico di Amazon IVS.

durata

Restituisce la durata del video, in secondi.

Amazon IVS: per i live streaming, restituisce Infinity.

caricare

Inizia a caricare i dati src().

Amazon IVS: questa istruzione non genera alcuna operazione.

giocare

Riproduce il flusso che è stato impostato tramite la chiamata src.

Amazon IVS: se un live streaming è stato messo in pausa, riproduce il live streaming dai fotogrammi più recenti invece di continuare dal punto in cui è stato messo in pausa.

playbackRate

Ottiene o imposta la velocità di riproduzione video. 1.0 significa velocità normale; 0,5 metà velocità normale; 2.0 due volte la velocità normale e così via.

Amazon IVS: su un live streaming, un get restituisce 1 e un set viene ignorato.

ricercabile

Restituisce il TimeRanges dei supporti in cui può essere effettuata la ricerca.

Amazon IVS: per i live streaming, l'invocazione di end(0) sul valore restituito (TimeRange) restituisce Infinity.

Specifico per Amazon IVS

La tecnologia Video.js di Amazon IVS dispone di funzioni aggiuntive per accedere a comportamenti specifici per le funzioni di Amazon IVS:

Funzione Descrizione

getIVSPlayer

Restituisce l'istanza del lettore Amazon IVS sottostante. L'API Web completa del lettore Amazon IVS è disponibile tramite questa istanza. Consigliamo di utilizzare il più possibile l'API di riproduzione Video.js di base e di utilizzare questa funzione solo per accedere alle funzionalità specifiche di Amazon IVS. Le funzioni più comuni a cui è probabile che sia necessario accedere sull'istanza del lettore Amazon IVS sono setQuality() e addEventListener()/removeEventListener().

getIVSEvents

Restituisce un oggetto che contiene enumerazioni specifiche di Amazon IVS. Viene utilizzato per l'ascolto di errori specifici di Amazon IVS. Per ulteriori informazioni, consultare Eventi e Errori.

currentTime

Ottiene o imposta l'ora, espressa in secondi dall'inizio.

Amazon IVS: si consiglia di non impostare l'ora corrente per i live streaming.

Signatures (Firme)

currentTime
currentTime(time)

Parametro

Parametro Tipo Descrizione

time

number

Se time è assente, si ottiene l'ora corrente. Se time è presente, imposta la riproduzione video a quell'ora.

Valore restituito

Tipo Descrizione

numero

L'ora corrente, espressa in secondi dall'inizio.

elimina

Elimina l'istanza del lettore.

Amazon IVS: elimina anche il backend tecnologico di Amazon IVS.

Firma

dispose()

Parametri

Nessuno

Valore restituito

Nessuno

durata

Restituisce la durata del video, in secondi.

Amazon IVS: per i live streaming, restituisce Infinity.

Firma

duration()

Parametri

Nessuno

Valore restituito

Tipo Descrizione

numero

La durata del flusso, in secondi. Per i live streaming, questo valore è Infinity.

getIVSEvents

Restituisce un oggetto che contiene enumerazioni specifiche di Amazon IVS. Viene utilizzato per l'ascolto di errori ed eventi specifici di Amazon IVS. Per ulteriori informazioni, consultare:

Firma

getIVSEvents()

Parametri

Nessuno

Valore restituito

Tipo Descrizione

object

Oggetto con le chiavi PlayerEventType, PlayerState e ErrorType mappate alle loro enumerazioni associate.

getIVSPlayer

Restituisce l'istanza del lettore Amazon IVS sottostante. L'API Web completa del lettore Amazon IVS è disponibile tramite questa istanza. Consigliamo di utilizzare il più possibile l'API di riproduzione Video.js di base e di utilizzare questa funzione solo per accedere alle funzionalità specifiche di Amazon IVS. Le funzioni più comuni a cui è probabile che sia necessario accedere sull'istanza del lettore Amazon IVS sono setQuality() e addEventListener()/removeEventListener().

Firma

getIVSPlayer()

Parametri

Nessuno

Valore restituito

Tipo Descrizione

MediaPlayer

L'istanza creata del lettore.

caricare

Inizia a caricare i dati src().

Amazon IVS: questa istruzione non genera alcuna operazione.

Firma

load()

Parametri

Nessuno

Valore restituito

Nessuno

giocare

Riproduce il flusso che è stato impostato tramite la chiamata src.

Amazon IVS: se un live streaming è stato messo in pausa, riproduce il live streaming dai fotogrammi più recenti invece di continuare dal punto in cui è stato messo in pausa.

Firma

play()

Parametri

Nessuno

Valore restituito

Nessuno

playbackRate

Ottiene o imposta la velocità di riproduzione video. 1.0 significa velocità normale; 0,5 metà velocità normale; 2.0 due volte la velocità normale e così via.

Amazon IVS: su un live streaming, un get restituisce 1 e un set viene ignorato.

Signatures (Firme)

playbackRate
playbackRate(rate)

Parametro

Parametro Tipo Descrizione

rate

numero

La velocità di riproduzione. Valori validi: valori nell'intervallo [0.25, 2.0].

Valore restituito

Tipo Descrizione

numero

La velocità di riproduzione.

ricercabile

Restituisce il TimeRanges dei supporti in cui può essere effettuata la ricerca.

Amazon IVS: per i live streaming, l'invocazione di end(0) sul valore restituito (TimeRange) restituisce Infinity.

Firma

seekable()

Parametro

Nessuno

Valore restituito

Tipo Descrizione

TimeRange

TimeRange del supporto che è disponibile per la ricerca.