L'SDK Cast include API integrate per il supporto di contenuti pubblicati. Include un'interfaccia utente flessibile e immediata, abbinata ad API che consentono agli sviluppatori di creare esperienze avanzate dal vivo con solo poche righe di codice. L'API Live supporta la visualizzazione delle ore di inizio e di fine, dei metadati del programma, dei controlli del DVR e delle finestre disponibili.
Questa guida mostra come configurare un flusso per le API Live, compresi esempi di codice e metadati per la configurazione degli scenari dal vivo principali, oltre a screenshot che mostrano l'aspetto di ogni scenario.
Prerequisiti
Prima di leggere questa guida è necessario conoscere i concetti di base dell'implementazione di un ricevitore web. Inoltre, per eseguire gli esempi di codice devi avere accesso a un live streaming conforme a uno dei tipi di contenuti multimediali supportati per la trasmissione. In generale, la funzionalità Live supporta le configurazioni di live streaming tipiche per i contenuti multimediali supportati.
Nell'ambito della guida vengono utilizzati i seguenti termini:
- Finestra ricercabile: l'intervallo di un live streaming in cui gli utenti possono cercare.
- Live Edge: la parte più recente di un live streaming disponibile per il player.
- Riproduci testa: un timestamp dell'interfaccia utente per la posizione di riproduzione attuale.
Trasmettere un live streaming
Esistono due modi per configurare l'SDK Web Receiver per l'utilizzo dell'API Live per i contenuti:
- utilizzando l'intercettatore di messaggi
LOADnell'applicazione Ricevitore web. (consigliato) - utilizzando una richiesta di carico generata dal mittente o lato destinatario.
L'intercettore fornisce un oggetto LoadRequestData contenente tutti i metadati importanti su una richiesta di carico. Per indicare che una richiesta di caricamento riguarda un live streaming, imposta semplicemente streamType nell'oggetto mediaInformation su StreamType.LIVE.
MediaInformation.duration dovrebbe essere -1 in quanto le istanze del player sono responsabili del calcolo quando i contenuti sono LIVE.
/*
* This interceptor is called before your content is loaded by a Cast device
*/
playerManager.setMessageInterceptor(
cast.framework.messages.MessageType.LOAD,
request => { /* cast.framework.messages.LoadRequestData */
request.media.streamType = cast.framework.messages.StreamType.LIVE;
return request;
});
Aggiungere dati della guida ai programmi
I live streaming, in particolare quelli a lunga esecuzione come, ad esempio, un canale TV, possono visualizzare i metadati della guida/programmazione sullo schermo in base all'attuale posizione di riproduzione in un live streaming. Per una migliore esperienza utente, consigliamo ai fornitori di contenuti di includere i metadati di programmazione nelle proprie applicazioni di ricezione web.
Puoi configurare i dati della guida iniziale per un flusso nell'intercettatore dei messaggi LOAD, nello stesso modo in cui abbiamo indicato che il flusso era un live streaming nell'esempio precedente. Singole sezioni o programmi nel live streaming sono rappresentati come oggetti MediaMetadata che vengono poi archiviati in una coda.
Esiste una classe MediaMetadata diversa per i diversi tipi di programmi, ad esempio
TvShowMediaMetadata,
MovieMediaMetadata,
MusicTrackMediaMetadata e così via.
Nel seguente snippet di codice, utilizziamo l'oggetto MediaMetadata per specificare l'ora di inizio di ogni programma con un timestamp UNIX con la proprietà sectionStartAbsoluteTime. La durata di un programma è espressa in secondi.
// The metadata for a single TV show
const currentShow = new cast.framework.messages.TvShowMediaMetadata();
currentShow.episode = 15;
currentShow.seriesTitle = 'The Odyssey';
currentShow.title = 'Scylla and Charybdis';
currentShow.sectionStartAbsoluteTime = toUnixTimestamp('9:00 PM');
currentShow.sectionDuration = HOUR_IN_SECONDS;
const previousShow = new ...;
const nextShow = new ...;
const containerMetadata = new cast.framework.messages.ContainerMetadata();
containerMetadata.title = 'My TV Channel';
containerMetadata.sections = [previousShow, currentShow, nextShow];
playerManager.getQueueManager().setContainerMetadata(containerMetadata);
Intervallo disponibile dal vivo
L'SDK Cast include controlli e elementi dell'interfaccia utente che consentono all'utente di spostare la testina di riproduzione all'interno dello stream utilizzando il controller espanso o i controlli touch sui dispositivi abilitati al tocco.
LiveSeekableRange rappresenta l'intervallo di tempo in uno stream in cui un utente può eseguire ricerche. Nel
Ricevitore web puoi accedere alle informazioni sull'intervallo disponibile tramite
PlayerManager.getLiveSeekableRange(),
che restituisce un oggetto
LiveSeekableRange. Le proprietà principali sull'oggetto di cui essere a conoscenza sono:
- start: l'ora di inizio (in secondi) dell'intervallo rispetto all'inizio del flusso in secondi.
- end: il tempo massimo possibile (in secondi) che il player può cercare, in base ai segmenti disponibili, rispetto all'inizio del flusso.
- isMovingWindow: un valore booleano che indica se l'intervallo disponibile viene spostato (ad esempio, vengono rimossi dal segmento i segmenti meno recenti) con lo stream; il valore dovrebbe essere true per tutti i live streaming.
- isLiveDone: un valore booleano che indica se il live streaming è terminato, ossia non sta generando nuovi segmenti.
Le dimensioni dell'intervallo disponibile, pari al tempo tra start e end, sono determinate dal numero di segmenti disponibili nello stream e si sposteranno con lo stream. Ad esempio, se all'inizio del flusso l'intervallo disponibile è {start:0, end: 600, isMovingWindow: false, isLiveDone: false}, dieci secondi dopo l'avvio del flusso può diventare {start: 10, end: 610,
isMovingWindow: true, isLiveDone: false}. È importante notare che le ore di inizio e fine dell'intervallo disponibile sono aggiornate in base al tempo necessario per generare un nuovo segmento. Pertanto, se la durata tipica di un segmento per il tuo stream è di 10 secondi, le ore di inizio e fine vengono aggiornate anche ogni 10 secondi.
Disattiva la ricerca
Per disattivare la ricerca all'interno di un flusso, devi rimuovere la funzionalità di ricerca dai comandi multimediali supportati sul ricevitore Web:
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
La rimozione del comando multimediale supportato per SEEK segnala alle applicazioni del mittente e al tocco di disabilitare la ricerca, ma non disattiva i comandi vocali, ad esempio "Hey Google, cerca indietro di 30 secondi". Per informazioni dettagliate su come disattivare i comandi multimediali per la voce, consulta la guida sui comandi multimediali supportati con voce.
Eventi del framework dal vivo
Nell'API Live sono inclusi due eventi, LIVE_ENDED e LIVE_IS_MOVING_WINDOW_CHANGED. Entrambi gli eventi passano un oggetto LiveStatusEvent, che contiene l'attuale intervallo disponibile per la ricerca.
| Evento | Descrizione |
|---|---|
LIVE_ENDED |
Si attiva quando termina un live streaming. A questo punto, il valore end in LiveSeekableRange non verrà più aggiornato; gli utenti potranno comunque visualizzare i contenuti nell'intervallo disponibile per la pubblicazione. |
LIVE_IS_MOVING_WINDOW_CHANGED |
Si attiva quando l'intervallo disponibile di un live streaming passa da una finestra fissa a una finestra mobile o viceversa. Nel caso di un live streaming, questo accadrà quando il player rileva che il manifest sta rimuovendo i segmenti precedenti. |
Scenari in live streaming
Esistono otto possibili scenari per i live streaming, ognuno dei quali è configurato impostando tre impostazioni principali:
- L'ora di inizio dello stream è
- Lo stream ha un'ora di fine
- Gli utenti sono autorizzati a eseguire ricerche all'interno della finestra disponibile per il live streaming
Per informazioni su come configurare questi valori, consulta la sezione Aggiunta dei dati della guida ai programmi.
Di seguito sono riportate descrizioni e screenshot degli scenari supportati dall'API Live. Le variabili T1 e T2 vengono utilizzate rispettivamente per rappresentare il timestamp a sinistra e a destra dell'interfaccia utente.
| Ora di inizio | Ora di fine | Cercabile | T1 | T2 | |
|---|---|---|---|---|---|
| Scenario 1 | No | No | No | Riproduci la testa | Non visualizzato |
| Scenario 7 | Sì | Sì | No | Mostra ora di inizio | Mostra ora di fine |
| Scenario 8 | Sì | Sì | Sì | Mostra ora di inizio | Mostra ora di fine |
Scenario 1
| Ora di inizio | Ora di fine | Cercabile | T1 | T2 |
|---|---|---|---|---|
| No | No | No | Riproduci la testa | Non visualizzato |
Lo scenario uno non ha un'ora di inizio o di fine e gli utenti non possono effettuare ricerche all'interno del stream. Quando un utente interrompe uno stream, la riproduzione riprenderà dal bordo pubblicato anziché da dove era stato messo in pausa.
Scenario sette
| Ora di inizio | Ora di fine | Cercabile | T1 | T2 |
|---|---|---|---|---|
| Sì | Sì | No | Riproduci la testa | Durata del programma |
Lo scenario sette ha un'ora di inizio e di fine, ma non è ricercabile. I due timestamp nell'interfaccia utente, T1 e T2, rappresentano rispettivamente l'attuale tempo di riproduzione e la durata totale del programma. Se un utente mette in pausa/riprende la riproduzione, lo stream riprenderà in corrispondenza del bordo live dello stream. Nell'esempio precedente, la sezione rossa della barra di ricerca rappresenta la parte del flusso da quando l'utente ha iniziato a guardare.
Scenario otto
| Ora di inizio | Ora di fine | Cercabile | T1 | T2 |
|---|---|---|---|---|
| Sì | Sì | Sì | Riproduci la testa | Durata del programma |
Lo scenario sette ha un'ora di inizio, un'ora di fine ed è ricercabile. I due timestamp nell'interfaccia utente, T1 e T2, rappresentano rispettivamente l'ora di riproduzione e la durata totale del programma. Se un utente mette in pausa/riprende la riproduzione, il flusso riprenderà al momento in cui l'utente è stato messo in pausa se si trova all'interno della finestra di ricerca, l'area in rosso sulla barra di ricerca rappresenta il punto in cui l'utente può tornare a guardare e l'area in bianco rappresenta il punto in cui è possibile guardare avanti.
Configurazione di uno scenario
La configurazione di un live streaming come scenario dal vivo specifico avviene in tre parti:
- Imposta il tipo di stream: contrassegna lo stream come live streaming.
- Aggiungi dati della guida al programma: imposta un'ora di inizio e una durata nell'oggetto
MediaMetadata. - Configurare la funzionalità di ricerca: abilita o disabilita la ricerca.
Comportamento della riproduzione
Quando è in pausa, l'interfaccia utente continuerà ad aggiornare i metadati di riproduzione, inclusi l'intestazione di riproduzione e i tempi di elaborazione dal vivo. Una volta ripresa la riproduzione in streaming, esistono alcuni comportamenti che variano in base alla configurazione del flusso.
Stream disponibili per la ricerca
Ripresa di uno stream disponibile:
- Il bordo attuale deve essere aggiornato nella posizione attiva e l'intervallo disponibile sarà adeguato di conseguenza.
- Se la testina di riproduzione supera il programma corrente, la barra di scorrimento viene aggiornata con i metadati del nuovo programma (inclusi ora di inizio e ora di fine, se disponibili).
- Se una finestra ricercabile ha una "X", l'intervallo disponibile può estendersi al massimo a "X" o all'inizio del programma, a seconda di quale sia la minore.
- Se l'utente è stato messo in pausa per un periodo abbastanza lungo da far sì che l'ora corrente non sia più nella finestra disponibile per la ricerca, il flusso riprenderà non appena possibile (all'estrema sinistra).
Vai su
LiveSeekableRange.end
per riprendere la riproduzione sul bordo live dopo la riattivazione.
let playerManager = cast.framework.CastReceiverContext.getInstance().getPlayerManager();
// Intercept the message to PLAY
playerManager.setMessageInterceptor(cast.framework.messages.MessageType.PLAY, (requestData) => {
...
if (playerManager.getLiveSeekableRange()) {
// Resume playback at the live edge
playerManager.seek(playerManager.getLiveSeekableRange().end);
} else {
return requestData;
}
...
});
Stream non disponibili per la ricerca
Ripresa di uno stream non ricercabile
- In questo caso, la riproduzione riprenderà dal bordo pubblicato.
- Se il limite dal vivo supera il programma corrente, la barra di scorrimento deve essere aggiornata con i metadati del nuovo programma (inclusi ora di inizio e ora di fine, se disponibili).
Modifiche alla piattaforma API e personalizzazione dell'interfaccia utente dal vivo
L'SDK Cast offre supporto integrato per la creazione di interfacce utente personalizzate anziché l'utilizzo immediato dell'interfaccia utente. Tuttavia, è importante seguire l'elenco di controllo per la progettazione dell'esperienza utente di Cast quando personalizzi l'interfaccia.
Ricevitore web
Nel Ricevitore web, la PlayerData include i seguenti campi per consentire agli sviluppatori di estendere le proprie interfacce personalizzate per i live streaming:
- isLive: un flag che indica se lo stream corrente è un live streaming, anziché VOD.
- liveSeekableRange - L'intervallo disponibile da mostrare sullo schermo che delimita la finestra DVR.
- mediaStartAbsoluteTime: quando la sezione è iniziata in tempo assoluto (epoca UNIX).
- sectionStartTimeInMedia: ora di inizio della sezione in secondi rispetto all'ora di inizio dei contenuti multimediali.
- sectionDuration: la durata della sezione in secondi.
Inoltre, ricorda di tenere conto dei due eventi dal vivo quando personalizzi la UI.
SDK Android
Nell'ambito della funzionalità Live, l'uso del widget Seekbar per Android in UIMediaController è deprecato. Usa invece CastSeekBar.