Sesje multimedialne zapewniają uniwersalny sposób interakcji z odtwarzaczem audio lub wideo. Dzięki poinformowaniu Androida, że w aplikacji są odtwarzane multimedia, można przekazać jej elementy sterujące odtwarzaniem. Integracja z sesją multimedialną umożliwia aplikacji przekazywanie informacji o odtwarzaniu multimediów źródłom zewnętrznym i otrzymywanie poleceń odtwarzania ze źródeł zewnętrznych. Źródłami mogą być przyciski fizyczne (np. przycisk odtwarzania na zestawie słuchawkowym lub pilocie do telewizora) albo polecenia pośrednie (np. polecenie „wstrzymaj” wydane Asystentowi Google). Sesja multimedialna przekazuje te polecenia do aplikacji, która stosuje je do odtwarzacza multimedialnego, dla którego źródło poleceń jest niewidoczne.
Sesja multimedialna działa razem z odtwarzaczem, którym zarządza. Sesję multimedialną należy utworzyć i zainicjować w metodzie onCreate() aktywności lub usługi, która jest właścicielem sesji multimedialnej i powiązanego z nią odtwarzacza.
Inicjowanie sesji multimedialnej
Nowo utworzona sesja multimedialna nie ma żadnych funkcji. Aby zainicjować sesję, wykonaj te czynności:
- Ustaw flagi, aby sesja multimedialna mogła otrzymywać wywołania zwrotne z kontrolerów multimediów i przycisków multimedialnych.
- Utwórz i zainicjuj instancję
PlaybackStateCompati przypisz ją do sesji. Stan odtwarzania zmienia się w trakcie sesji, dlatego zalecamy zapisanie obiektuPlaybackStateCompat.Builderw pamięci podręcznej, aby można było go użyć ponownie. - Utwórz instancję
MediaSessionCompat.Callbacki przypisz ją do sesji (więcej informacji o wywołaniach zwrotnych znajdziesz poniżej).
Sesję multimedialną należy utworzyć i zainicjować w metodzie onCreate() aktywności lub usługi, która jest właścicielem sesji.
Aby przyciski multimediów działały, gdy aplikacja jest nowo zainicjowana (lub zatrzymana), jej PlaybackState musi zawierać działanie odtwarzania pasujące do intencji wysyłanej przez przycisk multimediów. Dlatego podczas inicjowania do stanu sesji przypisywana jest wartość ACTION_PLAY. Więcej informacji znajdziesz w artykule Responding to Media Buttons (Reagowanie na przyciski multimedialne).
Utrzymywanie stanu odtwarzania i metadanych
Stan sesji multimedialnej reprezentują 2 klasy.
Klasa PlaybackStateCompat opisuje bieżący stan operacyjny odtwarzacza. Obejmuje to m.in.:
- Stan transportu (czy odtwarzacz odtwarza, jest wstrzymany, buforuje itp.
Patrz
getState()) - Kod błędu i opcjonalny komunikat o błędzie (jeśli dotyczy). (Zobacz
getErrorCode()i przeczytaj sekcję Stany i błędy poniżej). - Pozycja gracza
- Prawidłowe działania kontrolera, które można obsłużyć w obecnym stanie.
Klasa MediaMetadataCompat opisuje odtwarzany materiał:
- nazwę wykonawcy, albumu i utworu;
- czas trwania utworu,
- okładka albumu wyświetlana na ekranie blokady, Obraz jest bitmapą o maksymalnym rozmiarze 320 x 320 dp (jeśli jest większy, zostanie zmniejszony).
- Instancja
ContentUriswskazująca na większą wersję grafiki.
Stan odtwarzacza i metadane mogą się zmieniać w trakcie sesji multimedialnej. Za każdym razem, gdy zmienia się stan lub metadane, musisz użyć odpowiedniego kreatora dla każdej klasy, PlaybackStateCompat.Builder() lub MediaMetadataCompat.Builder(), a następnie przekazać nową instancję do sesji multimedialnej, wywołując setPlaybackState() lub setMetaData(). Aby zmniejszyć ogólne zużycie pamięci przez te częste operacje, warto utworzyć obiekty budujące raz i używać ich ponownie przez cały czas trwania sesji.
Stany i błędy
Pamiętaj, że PlaybackState to obiekt, który zawiera oddzielne wartości stanu odtwarzania sesji (getState()) i w razie potrzeby powiązany kod błędu (getErrorCode()). Błędy mogą być krytyczne lub niekrytyczne:
Za każdym razem, gdy odtwarzanie zostanie przerwane, należy wygenerować błąd krytyczny: ustaw stan transportu na STATE_ERROR i określ powiązany błąd za pomocą setErrorMessage(int, CharSequence). Dopóki odtwarzanie jest blokowane przez błąd, PlaybackState powinien nadal zgłaszać STATE_ERROR i błąd.
Błąd niekrytyczny występuje, gdy aplikacja nie może obsłużyć żądania, ale może kontynuować odtwarzanie: transport pozostaje w stanie „normalnym” (np. STATE_PLAYING), ale PlaybackState zawiera kod błędu. Jeśli na przykład odtwarzany jest ostatni utwór, a użytkownik poprosi o przejście do następnego, odtwarzanie może być kontynuowane, ale musisz utworzyć nowy obiekt PlaybackState z kodem błędu ERROR_CODE_END_OF_QUEUE, a następnie wywołać setPlaybackState(). Kontrolery multimediów dołączone do sesji otrzymają wywołanie zwrotne onPlaybackStateChanged() i wyjaśnią użytkownikowi, co się stało. Błąd niekrytyczny powinien być zgłaszany tylko raz, w momencie jego wystąpienia. Przy następnej aktualizacji sesji przez PlaybackState nie ustawiaj ponownie tego samego błędu niekrytycznego (chyba że błąd wystąpił w odpowiedzi na nowe żądanie).
Ekrany blokady sesji multimedialnej
Począwszy od Androida 4.0 (poziom interfejsu API 14), system może uzyskiwać dostęp do stanu odtwarzania i metadanych sesji multimedialnej. W ten sposób na ekranie blokady mogą wyświetlać się opcje sterowania multimediami i grafika. Działanie różni się w zależności od wersji Androida.
Okładka albumu
W Androidzie od wersji 4.0 (poziom interfejsu API 14) do wersji 10 (poziom interfejsu API 29) tło ekranu blokady wyświetla okładkę albumu, ale tylko wtedy, gdy metadane sesji multimedialnej zawierają bitmapę tła.
Elementy sterujące transportem
W Androidzie 4.0 (poziom interfejsu API 14) do Androida 4.4 (poziom interfejsu API 19), gdy sesja multimedialna jest aktywna, a metadane sesji multimedialnej zawierają bitmapę tła, na ekranie blokady automatycznie wyświetlają się elementy sterujące odtwarzaniem.
W Androidzie 5.0 (poziom interfejsu API 21) lub nowszym system nie udostępnia elementów sterujących odtwarzaniem na ekranie blokady. Zamiast tego do wyświetlania elementów sterujących odtwarzaniem używaj powiadomienia MediaStyle.
Dodawanie działań niestandardowych
Aplikacje multimedialne mogą definiować działania niestandardowe, np. kciuk w górę, polubienie lub przewinięcie o 30 sekund. Działanie niestandardowe powinno implementować zupełnie nowe zachowanie. Nie używaj działania niestandardowego, aby zastąpić jedno ze standardowych działań sterowania odtwarzaniem zdefiniowanych w PlaybackStateCompat.
Dodaj działania niestandardowe za pomocą addCustomAction(). Ten przykład pokazuje, jak dodać element sterujący do działania kciuka w górę:
Kotlin
stateBuilder.addCustomAction(
PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP,
resources.getString(R.string.thumbs_up),
thumbsUpIcon
).run {
setExtras(customActionExtras)
build()
}
)
Java
stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
.setExtras(customActionExtras)
.build());
Pełny przykład znajdziesz w aplikacji Universal Music Player.
Odpowiadasz na działanie, używając onCustomAction().
Kotlin
override fun onCustomAction(action: String, extras: Bundle?) {
when(action) {
CUSTOM_ACTION_THUMBS_UP -> {
...
}
}
}
Java
@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
...
}
}
Zobacz też Universal Music Player.
Wywołania zwrotne sesji multimedialnych
Główne metody wywołania zwrotnego sesji multimedialnej to onPlay(), onPause() i onStop(). W tym miejscu dodajesz kod, który steruje odtwarzaczem.
Ponieważ tworzysz instancję i ustawiasz wywołanie zwrotne sesji w czasie działania (w onCreate()), aplikacja może definiować alternatywne wywołania zwrotne, które używają różnych odtwarzaczy, i wybierać odpowiednią kombinację wywołania zwrotnego i odtwarzacza w zależności od urządzenia i poziomu systemu. Możesz zmienić odtwarzacz bez zmiany reszty aplikacji. Możesz na przykład używać ExoPlayera na Androidzie 4.1 (API na poziomie 16) lub nowszym, a MediaPlayer – we wcześniejszych systemach.
Oprócz sterowania odtwarzaczem i zarządzania przejściami stanu sesji multimedialnej wywołania zwrotne umożliwiają też włączanie i wyłączanie funkcji aplikacji oraz kontrolowanie sposobu, w jaki aplikacja współdziała z innymi aplikacjami i sprzętem urządzenia. (patrz Sterowanie wyjściem audio).
Implementacja metod wywołania zwrotnego sesji multimedialnej zależy od struktury aplikacji. Na osobnych stronach opisujących sposób używania wywołań zwrotnych w aplikacjach audio i aplikacjach wideo znajdziesz informacje o tym, jak należy je zaimplementować w przypadku każdego rodzaju aplikacji.