Pakiet SDK Cast zawiera wbudowane interfejsy API do obsługi treści na żywo. Obejmuje to elastyczny, gotowy do użycia interfejs, a także interfejsy API, które umożliwiają programistom tworzenie atrakcyjnych wydarzeń na żywo za pomocą zaledwie kilku linijek kodu. Interfejs Live API obsługuje wyświetlanie godzin rozpoczęcia i zakończenia, metadanych programu, elementów sterujących DVR oraz okien do wyszukiwania.
Ten przewodnik pokazuje, jak skonfigurować strumień do interfejsów API Live, w tym przykłady kodu i metadanych dotyczące konfigurowania podstawowych scenariuszy na żywo, a także zrzuty ekranu przedstawiające poszczególne scenariusze.
Wymagania wstępne
Zanim zapoznasz się z tym przewodnikiem, musisz znać podstawy wdrażania odbiornika internetowego. Aby uruchomić przykładowy kod, musisz mieć dostęp do transmisji na żywo zgodnej z jednym z obsługiwanych typów multimediów w Cast. Ogólnie funkcja transmisji na żywo obsługuje typowe konfiguracje transmisji multimediów.
W tym przewodniku są używane te terminy:
- Okres, w którym można przewijać – zakres transmisji na żywo, który użytkownicy mogą przeszukiwać.
- Live Edge – najnowszy fragment transmisji na żywo dostępny dla odtwarzacza.
- Play Points – sygnatura czasowa interfejsu wskazująca bieżącą pozycję odtwarzania.
Przesyłam transmisję na żywo
Są 2 sposoby konfigurowania pakietu SDK Web odbiornika do korzystania z Live API w przypadku treści:
- używając modułu przechwytywania wiadomości
LOADw aplikacji odbiornika internetowego. (zalecane) - przy użyciu żądania obciążenia wygenerowanego po stronie nadawcy lub odbiorcy.
Element przechwytywania zawiera obiekt LoadRequestData zawierający wszystkie ważne metadane dotyczące żądania wczytywania. Aby wskazać, że żądanie wczytywania dotyczy transmisji na żywo, po prostu ustaw obiekt streamType w obiekcie mediaInformation na StreamType.LIVE.
Wartość MediaInformation.duration powinna wynosić -1, ponieważ instancje odtwarzacza są odpowiedzialne za obliczenie jej, gdy treść jest 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;
});
Dodawanie danych przewodnika po programach
W transmisji na żywo, zwłaszcza w długich transmisjach, takich jak kanały telewizyjne, można wyświetlać na ekranie przewodnik po programach lub metadane programu oparte na bieżącej pozycji odtwarzania. Zachęcamy dostawców treści do umieszczania metadanych programowych w odbiornikach internetowych, ponieważ są one wygodniejsze dla użytkowników.
Początkowe dane dotyczące transmisji możesz skonfigurować w narzędziu do przechwytywania wiadomości LOAD – tak samo jak w poprzednim przykładzie zaznaczyliśmy, że jest to transmisja na żywo. Poszczególne sekcje lub programy w transmisji na żywo są przedstawiane jako obiekty MediaMetadata, które są następnie przechowywane w kolejce.
Istnieje inna klasa MediaMetadata dla różnych typów programów, np. TvShowMediaMetadata, MovieMediaMetadata, MusicTrackMediaMetadata itd.
W tym fragmencie kodu używamy obiektu MediaMetadata, aby za pomocą właściwości sectionStartAbsoluteTime określić godzinę rozpoczęcia każdego programu za pomocą sygnatury czasowej UNIX. Czas trwania programu jest wyrażony w sekundach.
// 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);
Zakres wyszukiwania na żywo
Pakiet SDK Cast zawiera elementy interfejsu i elementy sterujące, które pozwalają użytkownikowi przesuwać suwak w strumieniu za pomocą rozwiniętego kontrolera lub elementów dotykowych na urządzeniach obsługujących dotyk.
LiveSeekableRange reprezentuje zakres czasu w strumieniu, w którym użytkownik może przewijać treści. W odbiorniku internetowym informacje na temat możliwego do znalezienia zakresu znajdziesz w narzędziu PlayerManager.getLiveSeekableRange(), które zwraca obiekt LiveSeekableRange. Główne właściwości obiektu, o których należy pamiętać, to:
- start – czas rozpoczęcia (w sekundach) zakresu od początku strumienia w sekundach.
- end – maksymalny możliwy czas (w sekundach), po którym odtwarzacz może przewijać reklamy (w zależności od dostępnych segmentów), od początku strumienia.
- isMoveWindow – wartość logiczna wskazująca, czy przeszukiwalny zakres (np. starsze segmenty są usuwane z pliku manifestu) powinien być zgodny z wartością true w przypadku wszystkich transmisji na żywo.
- isLiveDone – wartość logiczna wskazująca, czy transmisja na żywo została zakończona, co oznacza, że nie są generowane nowe segmenty.
Rozmiar zakresu, który można wyszukać, wyrażony jako czas między start a end, jest określany na podstawie liczby segmentów dostępnych w strumieniu i porusza się razem ze strumieniem. Jeśli na przykład na początku strumienia zakres, który można znaleźć, to {start:0, end: 600, isMovingWindow: false, isLiveDone: false}, dziesięć sekund po rozpoczęciu transmisji może zmienić się w {start: 10, end: 610,
isMovingWindow: true, isLiveDone: false}. Pamiętaj, że czas rozpoczęcia i zakończenia w zakresie możliwego do znalezienia jest aktualizowany na podstawie czasu potrzebnego do wygenerowania nowego segmentu. Dlatego jeśli typowa długość segmentu dla strumienia wynosi 10 sekund, czas rozpoczęcia i zakończenia również będą aktualizowane co 10 sekund.
Wyłącz przewijanie
Aby wyłączyć wyszukiwanie w strumieniu, musisz usunąć funkcję wyszukiwania z obsługiwanych poleceń multimedialnych w odbiorniku internetowym:
// disable seeking in the LOAD messageInterceptor
playerManager.removeSupportedMediaCommands(cast.framework.messages.Command.SEEK, true);
Usunięcie obsługiwanych poleceń multimedialnych dla SEEK sygnałów dla aplikacji nadawców i dotykowych ekranów w celu wyłączenia wyszukiwania, ale nie wyłącza poleceń głosowych, takich jak „OK Google, przewiń do tyłu o 30 sekund”. Zajrzyj do przewodnika dotyczącego obsługiwanych poleceń głosowych i dowiedz się, jak wyłączyć polecenia głosowe.
Bieżące wydarzenia dotyczące platformy
Interfejs API Live API zawiera 2 zdarzenia: LIVE_ENDED i LIVE_IS_MOVING_WINDOW_CHANGED. Oba zdarzenia są przekazywane w obiekcie LiveStatusEvent, który zawiera obecny zakres możliwego do wyszukania.
| Zdarzenie | Opis |
|---|---|
LIVE_ENDED |
Wywoływane po zakończeniu transmisji na żywo. W tym momencie wartość end w elemencie LiveSeekableRange przestanie być aktualizowana; użytkownicy nadal będą mogli wyświetlać treści z zakresu wyszukiwania na żywo. |
LIVE_IS_MOVING_WINDOW_CHANGED |
Wywoływane, gdy zakres wyszukiwania transmisji na żywo zmienia się z okna stałego na ruchomy lub odwrotnie. W przypadku transmisji na żywo dzieje się tak, gdy odtwarzacz wykryje, że plik manifestu usuwa wcześniejsze segmenty. |
Scenariusze transmisji na żywo
Dostępnych jest 8 możliwych scenariuszy transmisji na żywo. Każdy z nich konfiguruje się za pomocą 3 głównych ustawień:
- Transmisja ma czas rozpoczęcia
- Transmisja ma czas zakończenia
- Użytkownicy mogą wyszukiwać w widocznym oknie transmisji na żywo
Informacje o konfigurowaniu tych wartości znajdziesz w artykule Dodawanie danych przewodnika po programach.
Poniżej znajdziesz opisy i zrzuty ekranu przedstawiające scenariusze obsługiwane przez interfejs Live API. Zmienne T1 i T2 służą do reprezentowania sygnatury czasowej odpowiednio po lewej i prawej stronie interfejsu.
| Godzina rozpoczęcia | Godzina zakończenia | Przewijane | T1 | T2 | |
|---|---|---|---|---|---|
| Scenariusz 1 | Nie | Nie | Nie | Nagłówek Play | Niewyświetlane |
| Scenariusz 7 | Tak | Tak | Nie | Pokaż godzinę rozpoczęcia | Pokaż czas zakończenia |
| Scenariusz 8 | Tak | Tak | Tak | Pokaż godzinę rozpoczęcia | Pokaż czas zakończenia |
Scenariusz pierwszy
| Godzina rozpoczęcia | Godzina zakończenia | Przewijane | T1 | T2 |
|---|---|---|---|---|
| Nie | Nie | Nie | Odtwórz nagłówek | Niewyświetlane |
W pierwszym scenariuszu nie ma godziny rozpoczęcia ani zakończenia, a użytkownicy nie mogą przewijać strumienia. Gdy użytkownik zatrzyma transmisję, odtwarzanie zostanie wznowione od krawędzi na żywo zamiast w miejscu, w którym wstrzymano transmisję.
Scenariusz 7
| Godzina rozpoczęcia | Godzina zakończenia | Przewijane | T1 | T2 |
|---|---|---|---|---|
| Tak | Tak | Nie | Nagłówek Play | Czas trwania programu |
Scenariusz 7 ma godzinę rozpoczęcia i zakończenia, ale nie jest dostępny. Dwie sygnatury czasowe w interfejsie, T1 i T2, odpowiednio odzwierciedlają bieżący czas odtwarzania i całkowity czas trwania programu. Jeśli użytkownik wstrzyma/wznowi odtwarzanie, wznowi odtwarzanie na żywo. W powyższym przykładzie czerwona sekcja paska przewijania odpowiada części strumienia od momentu, gdy użytkownik rozpoczął oglądanie.
Scenariusz 8
| Godzina rozpoczęcia | Godzina zakończenia | Przewijane | T1 | T2 |
|---|---|---|---|---|
| Tak | Tak | Tak | Nagłówek Play | Czas trwania programu |
Scenariusz siódmy ma godzinę rozpoczęcia, zakończenia i możliwości wyszukiwania. Dwie sygnatury czasowe w interfejsie, T1 i T2, odpowiednio odzwierciedlają bieżący czas odtwarzania i całkowity czas trwania programu. Jeśli użytkownik wstrzyma/wznowi odtwarzanie odtwarzania, wznowi odtwarzanie natychmiast, gdy znajdzie się w widocznym oknie – czerwony obszar na pasku przewijania wskazuje, gdzie użytkownik może wrócić, a biały obszar wskazuje, gdzie się on stara.
Konfigurowanie scenariusza
Konfigurowanie strumienia jako konkretnego scenariusza na żywo odbywa się w 3 części:
- Ustaw typ transmisji – oznacz ją jako transmisję na żywo.
- Dodaj dane przewodnika po programach – ustaw czas rozpoczęcia i czas trwania obiektu
MediaMetadata. - Skonfiguruj funkcję wyszukiwania – włącz lub wyłącz przewijanie.
Zachowanie odtwarzania
Po wstrzymaniu interfejsu nadal są aktualizowane jego metadane odtwarzania, w tym czas odtwarzania w czasie rzeczywistym i czasie wyświetlania. Po wznowieniu transmisji musisz zwrócić uwagę na kilka zachowań, które różnią się w zależności od jej konfiguracji.
Strumienie możliwe do wyszukania
Po wznowieniu strumienia, który można wyszukać:
- Aktywna krawędź zostanie zaktualizowana do opublikowanej lokalizacji, a wyszukiwany zakres zostanie odpowiednio dostosowany.
- Jeśli suwak odtwarzania przeskoczy aktualny program, na pasku przewijania pojawią się metadane z nowego programu (w tym godzina rozpoczęcia i zakończenia, jeśli jest dostępna).
- Jeśli okno do przeszukiwania ma długość „X”, jego zasięg może być większy niż „X” lub do początku odtwarzania – zależnie od tego, który jest mniejszy.
- Jeśli użytkownik został wstrzymany na tyle długo, że bieżący czas nie znajduje się już w polu wyszukiwania, odtwarzanie zostanie wznowione w najwcześniejszym punkcie (dalej po lewej) okna, które można wyszukać.
Aby wznowić odtwarzanie po wznowieniu odtwarzania, naciśnij LiveSeekableRange.end.
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;
}
...
});
Strumienie niemożliwe do wyszukania
Po wznowieniu transmisji, której nie można wyszukać:
- W takim przypadku odtwarzanie zostanie wznowione na krawędzi ostrej.
- Jeśli transmisja na żywo przeskoczy bieżącą transmisję, pasek aktualizacji powinien zawierać metadane z nowego programu (w tym godzinę rozpoczęcia i godzinę zakończenia, jeśli są dostępne).
Zmiany interfejsu API i dostosowywanie interfejsu użytkownika na żywo
Pakiet SDK Cast ma wbudowaną obsługę niestandardowych interfejsów użytkownika, zamiast korzystać z gotowego interfejsu. Pamiętaj jednak, aby podczas dostosowywania interfejsu postępować zgodnie z listą kontrolną projektowania interfejsu użytkownika.
Odbiornik internetowy
PlayerData w odbiorniku zawiera te pola, które pozwalają deweloperom rozszerzać niestandardowe interfejsy transmisji na żywo:
- isLive – flaga wskazująca, czy obecna transmisja jest na żywo, a nie VOD.
- liveSeekableRange – zakres do wyświetlenia na ekranie degradującego okno DVR.
- mediaStartabsTime – gdy sekcja rozpoczęła się w bezwzględnym czasie (UNIX Epoch).
- sectionStartTimeInMedia – czas rozpoczęcia sekcji w sekundach zgodny z czasem rozpoczęcia multimediów.
- sectionDuration – czas trwania sekcji w sekundach.
Podczas dostosowywania interfejsu pamiętaj o dwóch wydarzeniach na żywo.
Android SDK
W ramach funkcji Na żywo wykorzystaliśmy widżet Android Seekbar w UIMediaController, a nie na CastSeekBar.