Korzystanie z sesji multimediów

Sesje multimedialne to uniwersalny sposób na interakcję z odtwarzaczem audio i wideo. Informując Androida o tym, że multimedia są odtwarzane w aplikacji, można przekazać do niej elementy sterujące odtwarzaniem. Integracja z sesją multimediów umożliwia aplikacji reklamowanie odtwarzania multimediów na zewnątrz i odbieranie poleceń odtwarzania ze źródeł zewnętrznych. Źródłem tych mogą być fizyczne przyciski (np. przycisk odtwarzania na słuchawkach lub pilocie do telewizora) lub pośrednie polecenia (na przykład polecenie „wstrzymania” Asystentowi Google). Sesja multimediów przekazuje te polecenia do aplikacji, która stosuje je do odtwarzacza, w przypadku którego są one przejrzyste.

Sesja multimediów jest umieszczona obok odtwarzacza, którym zarządza. Sesję multimediów należy utworzyć i zainicjować w metodzie onCreate() aktywności lub usługi, do której należy sesja multimediów i powiązany z nią odtwarzacz.

Inicjowanie sesji multimediów

Nowo utworzona sesja multimediów nie ma żadnych funkcji. Musisz zainicjować sesję, wykonując te czynności:

  • Ustaw flagi tak, aby sesja multimediów mogła odbierać wywołania zwrotne kontrolerów multimediów i przycisków multimediów.
  • Utwórz i zainicjuj instancję PlaybackStateCompat oraz przypisz ją do sesji. Stan odtwarzania zmienia się w trakcie sesji, dlatego zalecamy buforowanie PlaybackStateCompat.Builder w celu ponownego wykorzystania.
  • Utwórz instancję MediaSessionCompat.Callback i przypisz ją do sesji (więcej informacji o wywołaniach zwrotnych znajdziesz poniżej).

Sesję multimediów należy utworzyć i zainicjować w metodzie onCreate() działania lub usługi, do której należy sesja.

Aby przyciski multimediów działały po nowym zainicjowaniu (lub zatrzymaniu aplikacji), jej PlaybackState musi zawierać działanie odtwarzania zgodne z intencją przesłaną przez przycisk multimediów. Dlatego podczas inicjowania zasób ACTION_PLAY jest przypisywany do stanu sesji. Więcej informacji znajdziesz w artykule Reagowanie na przyciski multimediów.

Zachowywanie stanu odtwarzania i metadanych

Istnieją 2 klasy, które odzwierciedlają stan sesji multimediów.

Klasa PlaybackStateCompat opisuje bieżący stan działania odtwarzacza. Przykładowe działania:

  • Stan przesyłania (czy odtwarzacz jest odtwarzany, wstrzymany, buforowany itp. Patrz: getState()).
  • Kod błędu i opcjonalny komunikat o błędzie (jeśli dotyczy). (Zobacz getErrorCode() oraz przeczytaj Stany i błędy poniżej).
  • Pozycja odtwarzacza
  • Prawidłowe działania kontrolera, które mogą być obsługiwane w obecnym stanie

Zajęcia MediaMetadataCompat opisują odtwarzany materiał:

  • tytuł wykonawcy, albumu i utworu;
  • czas trwania utworu;
  • Okładka albumu do wyświetlania na ekranie blokady. Obraz jest bitmapą o maksymalnym rozmiarze 320 x 320 dp (jeśli jest większy, zostanie zmniejszony).
  • Wystąpienie elementu ContentUris wskazującego większą wersję grafiki

Stan odtwarzacza i metadane mogą się zmieniać z upływem czasu trwania sesji multimediów. Przy każdej zmianie stanu lub metadanych musisz użyć odpowiedniego konstruktora dla każdej klasy (PlaybackStateCompat.Builder() lub MediaMetadataCompat.Builder()), a następnie przekazać nową instancję do sesji multimediów, wywołując metodę setPlaybackState() lub setMetaData(). Aby zmniejszyć ogólne wykorzystanie pamięci przez te częste operacje, warto utworzyć konstruktora raz i używać ich w trakcie sesji.

Stany i błędy

Pamiętaj, że PlaybackState to obiekt zawierający osobne wartości stanu odtwarzania sesji (getState()) i w razie potrzeby powiązanego kodu błędu (getErrorCode()). Błędy mogą być krytyczne lub niekrytyczne:

Po przerwaniu odtwarzania powinien wystąpić błąd krytyczny. Ustaw stan przesyłania na STATE_ERROR i wskaż powiązany błąd w polu setErrorMessage(int, CharSequence). Dopóki odtwarzanie jest zablokowane w związku z błędem, PlaybackState powinno nadal zgłaszać STATE_ERROR i błąd.

Błąd niekrytyczny występuje, gdy aplikacja nie może obsłużyć żądania, ale można kontynuować odtwarzanie: transport pozostaje w stanie „normalnym” (np. STATE_PLAYING), ale element PlaybackState zawiera kod błędu. Jeśli na przykład jest odtwarzany ostatni utwór, a użytkownik poprosi o przejście do następnego utworu, odtwarzanie może być kontynuowane, ale trzeba utworzyć nowy element PlaybackState z kodem błędu ERROR_CODE_END_OF_QUEUE i wywołać setPlaybackState(). Kontrolery mediów podłączone do sesji otrzymają wywołanie zwrotne onPlaybackStateChanged() i wyjaśnią użytkownikowi, co się stało. Błędy niekrytyczne należy zgłaszać tylko raz, w chwili, gdy wystąpi. Przy następnej aktualizacji sesji PlaybackState nie ustawi ponownie tego samego błędu niekrytycznego (chyba że błąd wystąpił w odpowiedzi na nowe żądanie).

Ekrany blokady sesji multimediów

Począwszy od Androida 4.0 (poziom interfejsu API 14), system ma dostęp do stanu odtwarzania i metadanych sesji multimediów. W ten sposób na ekranie blokady mogą być wyświetlane elementy sterujące multimediami i grafika. Działanie różni się w zależności od wersji Androida.

Okładka albumu

W Androidzie od 4.0 (poziom interfejsu API od 14 do 14) do 10 (poziom interfejsu API 29) w tle ekranu blokady widoczna jest okładka albumu, ale tylko wtedy, gdy metadane sesji multimedialnej zawierają bitmapę w tle.

Kontrola transportu

Na urządzeniach z Androidem od 4.0 (poziom interfejsu API 14) do 4.4 (poziom interfejsu API 19), gdy sesja multimediów jest aktywna, a metadane sesji multimediów zawierają bitmapę w tle, na ekranie blokady automatycznie wyświetlają się ustawienia przesyłania.

W Androidzie 5.0 (poziom interfejsu API 21) i nowszych system nie udostępnia elementów sterujących przesyłaniem na ekranie blokady. Zamiast tego do wyświetlania elementów sterujących transportem należy użyć powiadomienia MediaStyle.

Dodaj działania niestandardowe

Aplikacje multimedialne mogą definiować działania niestandardowe, np. kliknięcie kciuka w górę, polubienie lub przewijanie do tyłu o 30 sekund. Działanie niestandardowe powinno wdrożyć zupełnie nowe zachowanie. Nie używaj działań niestandardowych do zastępowania jednego ze standardowych działań kontroli transportu zdefiniowanych w właściwości PlaybackStateCompat.

Dodaj działania niestandardowe w narzędziu addCustomAction(). Ten przykład pokazuje, jak dodać element sterujący dla 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 opisie Universal Music Player.

Na to działanie reagujesz poleceniem 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ż uniwersalny odtwarzacz muzyki.

Wywołania zwrotne sesji multimediów

Metody wywołania zwrotnego sesji multimediów to onPlay(), onPause() i onStop(). Tutaj dodajesz kod, który kontroluje odtwarzacz.

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 korzystają z różnych odtwarzaczy, i wybierać odpowiednią kombinację wywołania zwrotnego i odtwarzacza w zależności od poziomu urządzenia lub systemu. Możesz zmienić odtwarzacz bez zmieniania pozostałej części aplikacji. Możesz na przykład użyć ExoPlayer w Androidzie 4.1 (poziom interfejsu API 16) lub nowszym i użyć MediaPlayer we wcześniejszych systemach.

Wywołania zwrotne pozwalają nie tylko sterować odtwarzaczem i zarządzać przejściami stanu sesji multimediów. Wywołania zwrotne umożliwiają również włączanie i wyłączanie funkcji aplikacji oraz kontrolowanie jej interakcji z innymi aplikacjami i sprzętem urządzenia. (patrz Sterowanie wyjściem dźwięku).

Implementacja metod wywołań zwrotnych sesji multimediów zależy od struktury aplikacji. Opis sposobu implementacji wywołań zwrotnych w aplikacjach audio i wideo znajdziesz na osobnych stronach z opisem ich implementacji w przypadku poszczególnych rodzajów aplikacji.