Korzystanie z sesji multimediów

Sesje multimedialne to uniwersalny sposób na interakcję z dźwiękiem lub filmem . Jeśli informujesz Androida, że multimedia w aplikacji są odtwarzane, ustawienia można przekazać do aplikacji. Integracja z sesją multimediów pozwala aplikacja do reklamowania odtwarzania multimediów na zewnątrz i otrzymywania poleceń odtwarzania ze źródeł zewnętrznych. Źródłem tych mogą być fizyczne przyciski (np. przycisk odtwarzania na słuchawkach lub pilocie telewizora) ani za pomocą poleceń pośrednich (takich jak instrukcja „pause” do Asystenta Google). W sesji multimediów są przekazywane poleceń w aplikacji, które będą stosować je do odtwarzacza, w którym są przejrzyste informacje o pochodzeniu tych poleceń.

Sesja multimedialna działa razem z odtwarzaczem, którym zarządza. Należy utworzyć i zainicjujesz sesję multimediów w metodzie onCreate() aktywności lub usługę, 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 możliwości. Musisz zainicjować sesję, wykonując te czynności:

  • Ustaw flagi, aby sesja multimediów mogła odbierać wywołania zwrotne z kontrolerów i przycisków multimediów.
  • Utwórz i zainicjuj instancję PlaybackStateCompat, a następnie przypisz ją do sesji. Stan odtwarzania zmienia się podczas 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() funkcji aktywność lub usłudze, do której należy sesja.

Aby przyciski multimediów działały w przypadku nowo zainicjowanej (lub zatrzymanej) aplikacji jej PlaybackState musi zawierać działanie odtwarzania pasujące do intencji wysyłanej przez przycisk multimediów. To jest dlaczego funkcja ACTION_PLAY jest przypisana do stanu sesji podczas jego zainicjowanie. Więcej informacji znajdziesz w artykule Odpowiadanie na multimedia Przyciski.

Zachowywanie stanu odtwarzania i metadanych

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

PlaybackStateCompat opisuje bieżący stan operacyjny odtwarzacza. Przykładowe zabezpieczenia:

  • Stan przesyłania (czy odtwarzacz odtwarza, wstrzymany, buforuje itp. Patrz: getState()).
  • Kod błędu i opcjonalny komunikat o błędzie, jeśli dotyczy. (Patrz sekcja getErrorCode() i przeczytaj sekcję Stany i błędy poniżej).
  • Pozycja odtwarzacza
  • Prawidłowe działania kontrolera, które można obsługiwać w obecnym stanie

MediaMetadataCompat opisuje odtwarzany materiał:

  • nazwę 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 pomniejszony).
  • Wystąpienie ContentUris wskazujące większą wersję grafiki

Stan i metadane odtwarzacza mogą się zmieniać w trakcie sesji multimediów. 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 multimediów, wywołując setPlaybackState() lub setMetaData() Aby zmniejszyć ogólne wykorzystanie pamięci przez te częste operacje, warto utworzyć konstruktory raz i używać ich przez cały czas trwania sesji.

Stany i błędy

Zwróć uwagę, że PlaybackState to obiekt zawierający osobne wartości dla stan odtwarzania sesji (getState()) oraz w razie potrzeby powiązany kod błędu (getErrorCode()). Błędy mogą być krytyczne lub niekrytyczne:

Przy każdym przerwie odtwarzania powinien wystąpić błąd krytyczny: ustaw parametr stan przesyłania do STATE_ERROR i określ błąd powiązany z zasadą setErrorMessage(int, CharSequence). Jeśli odtwarzanie jest zablokowane z powodu błędu, PlaybackState nie może kontynuować , aby zgłosić błąd 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 „normalnym” stanie. (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żna kontynuować, ale zalecamy utworzenie nowego elementu PlaybackState z kodem błędu ERROR_CODE_END_OF_QUEUE i i wywołaj setPlaybackState(). Kontrolery multimediów podłączone do sesji otrzymają wywołanie zwrotne onPlaybackStateChanged() i wyjaśnij użytkownikowi, co się stało. Błąd niekrytyczny należy zgłaszać tylko raz, w momencie jego wystąpienia. Podczas następnej aktualizacji sesji PlaybackState nie ustawi ponownie tego samego błędu niekrytycznego (chyba że błąd wystąpił w odpowiedzi na nowe żądanie).

Ekran blokady sesji multimediów

Począwszy od Androida 4.0 (poziom interfejsu API 14) system ma dostęp do o stanie odtwarzania i metadanych. W ten sposób ekran blokady może wyświetlać opcje sterowania multimediami i dzieło sztuki. Działanie różni się w zależności od Wersja Androida.

Okładka albumu

W Androidzie w wersji od 4.0 (poziom interfejsu API 14) do 10 (poziom interfejsu API 29) tło wyświetli okładkę albumu, ale tylko wtedy, gdy czy metadane zawierają bitmapę tła.

Sterowanie transportem

W Androidzie 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ą mapę bitową tła, ekran blokady automatycznie wyświetla ustawienia transportu.

W Androidzie 5.0 (poziom interfejsu API 21) lub nowszym system nie udostępnia funkcji transportowych na ekranie blokady. Zamiast tego użyj interfejsu MediaStyle aby wyświetlić elementy sterujące transportem.

Dodaj działania niestandardowe

Aplikacje multimedialne mogą definiować działania niestandardowe, na przykład: kciuk w górę, polubienie, 30 sekund do tyłu. Działanie niestandardowe powinno wdrożyć zupełnie nowe zachowanie. Tak nie używaj działania niestandardowego do zastąpienia jednego ze standardowych działań związanych z transportem zdefiniowane w OdtwarzanieStateCompat.

Dodaj działania niestandardowe za pomocą funkcji 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 Universal Music Player.

Reagujesz na działanie przy użyciu emotikona 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łań zwrotnych głównej sesji multimediów to onPlay(), onPause() i onStop(). W tym miejscu należy dodać kod sterujący odtwarzaczem.

Ponieważ tworzysz i ustawiasz wywołanie zwrotne sesji w czasie działania (w zasadzie onCreate()), aplikacja może zdefiniować alternatywne wywołania zwrotne korzystające z różnych odtwarzaczy i wybrać odpowiednią kombinację wywołania zwrotnego/odtwarzacza w zależności od poziomu urządzenia lub systemu. Odtwarzacz możesz zmienić bez zmiany reszty aplikacji. Możesz na przykład użyć odtwarzacza ExoPlayer w przypadku Androida 4.1 (poziom interfejsu API 16) lub nowszego, a MediaPlayer we wcześniejszych systemach.

Wywołania zwrotne nie tylko pozwalają sterować odtwarzaczem i zarządzać zmianami stanu sesji multimediów, ale także włączać i wyłączać funkcje aplikacji oraz kontrolować jej interakcję z innymi aplikacjami i sprzętem urządzenia. (patrz Sterowanie wyjściem audio).

Sposób implementacji metod wywołania zwrotnego sesji multimediów zależy od struktury aplikacji. Instrukcje używania wywołań zwrotnych znajdziesz na osobnych stronach aplikacje audio oraz aplikacje wideo, opisują sposób implementacji wywołań zwrotnych w przypadku poszczególnych rodzajów aplikacji.