Włącz sterowanie odtwarzaniem

Aby włączyć odtwarzanie multimediów w Androidzie Auto i systemie operacyjnym Android Automotive (AAOS), zaimplementuj elementy sterujące odtwarzaniem, rejestrując sesję multimediów i obsługując jej metody wywołania zwrotnego. Z tej strony dowiesz się, jak:

• zarejestrować obiekt MediaSessionCompat w usłudze przeglądarki multimediów;

• zaimplementować metody MediaSessionCompat.Callback, aby odpowiadać na żądania odtwarzania użytkowników;

• skonfigurować standardowe i niestandardowe działania związane z odtwarzaniem;

• ustawić początkowy stan odtwarzania sesji multimediów;

• dodać ikony wskazujące format dźwięku;

• utworzyć linki z aktualnie odtwarzanych elementów multimedialnych.

Android Auto i AAOS wysyłają polecenia sterowania odtwarzaniem do Twojej usługi za pomocą MediaSessionCompat. Musisz zarejestrować sesję i zaimplementować powiązane z nią metody wywołania zwrotnego.

Rejestrowanie sesji multimediów

W metodzie onCreate usługi przeglądarki multimediów utwórz instancję MediaSessionCompat, a następnie wywołaj setSessionToken, aby zarejestrować sesję multimediów. Ten fragment kodu pokazuje, jak utworzyć i zarejestrować sesję multimediów:

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

Podczas tworzenia obiektu sesji multimediów ustawiasz obiekt wywołania zwrotnego, który służy do obsługi żądań sterowania odtwarzaniem. Ten obiekt wywołania zwrotnego tworzysz, implementując klasę MediaSessionCompat.Callback w swojej aplikacji. W następnej sekcji dowiesz się, jak zaimplementować ten obiekt.

Implementowanie poleceń odtwarzania

Gdy użytkownik poprosi o odtworzenie elementu multimedialnego z Twojej aplikacji, system operacyjny Android Automotive OS i Android Auto użyją MediaSessionCompat.Callback klasy z obiektu MediaSessionCompat aplikacji, który został pobrany z usługi przeglądarki multimediów. Gdy użytkownik chce sterować odtwarzaniem treści, np. wstrzymać odtwarzanie lub przejść do następnego utworu, Android Auto i Android Automotive OS wywołują jedną z metod obiektu wywołania zwrotnego.

Aby obsługiwać odtwarzanie treści, aplikacja musi rozszerzyć abstrakcyjną klasę MediaSessionCompat.Callback i zaimplementować metody, które obsługuje.

Zaimplementuj każdą z tych metod wywołania zwrotnego, które mają sens w przypadku typu treści oferowanych przez Twoją aplikację:

onPrepare

AAOS wywołuje tę metodę, gdy zmienia się źródło multimediów.

onPlay

Wywoływana, gdy użytkownik wybierze odtwarzanie bez wybierania konkretnego elementu. Aplikacja musi odtworzyć domyślną treść lub, jeśli odtwarzanie zostało wstrzymane za pomocą onPause, wznowić odtwarzanie.

onPlayFromMediaId

Wywoływana, gdy użytkownik wybierze odtworzenie konkretnego elementu. Metoda otrzymuje identyfikator przypisany do elementu multimedialnego w hierarchii treści przez usługę przeglądarki multimediów.

onPlayFromSearch

Wywoływana, gdy użytkownik wybierze odtwarzanie na podstawie zapytania. Aplikacja musi dokonać odpowiedniego wyboru na podstawie przekazanego ciągu wyszukiwania.

onPause

Wywoływana, gdy użytkownik wybierze wstrzymanie odtwarzania.

onSkipToNext

Wywoływana, gdy użytkownik wybierze przejście do następnego elementu.

onSkipToPrevious

Wywoływana, gdy użytkownik wybierze przejście do poprzedniego elementu.

onStop

Wywoływana, gdy użytkownik wybierze zatrzymanie odtwarzania. Zastąp te metody w swojej aplikacji, aby zapewnić wybrany wynik. Nie musisz implementować metody, jeśli jej cel nie jest obsługiwany przez Twoją aplikację. Jeśli na przykład aplikacja odtwarza transmisję na żywo, np. transmisję sportową, nie musisz implementować onSkipToNext. Zamiast tego użyj domyślnej implementacji onSkipToNext.

Aplikacja nie wymaga żadnej specjalnej logiki do odtwarzania treści przez głośniki samochodowe. Gdy aplikacja otrzyma prośbę o odtworzenie treści, odtwarza dźwięk w taki sam sposób, jak w przypadku odtwarzania treści przez głośniki lub słuchawki telefonu użytkownika. Android Auto i AAOS automatycznie wysyłają treści audio do systemu samochodowego, aby odtwarzać je przez głośniki samochodowe.

Więcej informacji o odtwarzaniu treści audio znajdziesz w artykułach Omówienie odtwarzacza multimediów, Omówienie aplikacji audio, i Omówienie biblioteki ExoPlayer overview.

Ustawianie standardowych działań związanych z odtwarzaniem

Android Auto i AAOS wyświetlają elementy sterujące odtwarzaniem na podstawie działań włączonych w PlaybackStateCompat obiekcie. Domyślnie aplikacja musi obsługiwać te działania:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

Jeśli jest to istotne dla treści aplikacji, może ona dodatkowo obsługiwać te działania:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

Opcjonalnie możesz też utworzyć kolejkę odtwarzania, która będzie wyświetlana użytkownikowi. Aby to zrobić, wywołaj metody setQueue i setQueueTitle, włącz działanie ACTION_SKIP_TO_QUEUE_ITEM i zdefiniuj wywołanie zwrotne onSkipToQueueItem.

Dodaj też obsługę ikony Teraz odtwarzane, która wskazuje, co jest odtwarzane. Aby to zrobić, wywołaj metodę setActiveQueueItemId i przekaż identyfikator odtwarzanego elementu w kolejce. Musisz aktualizować setActiveQueueItemId za każdym razem, gdy zmienia się kolejka.

Android Auto i AAOS wyświetlają przyciski dla każdego włączonego działania oraz kolejkę odtwarzania. Gdy użytkownicy klikną te przyciski, system wywoła odpowiednie wywołanie zwrotne z MediaSessionCompat.Callback.

Rezerwowanie niewykorzystanego miejsca

Android Auto i AAOS rezerwują miejsce w interfejsie na działania ACTION_SKIP_TO_PREVIOUS i ACTION_SKIP_TO_NEXT. Jeśli Twoja aplikacja nie obsługuje jednej z tych funkcji, Android Auto i AAOS użyją tego miejsca do wyświetlania utworzonych przez Ciebie działań niestandardowych.

Jeśli nie chcesz wypełniać tych miejsc działaniami niestandardowymi, możesz je zarezerwować, aby Android Auto i AAOS pozostawiały je puste, gdy Twoja aplikacja nie obsługuje odpowiedniej funkcji.

Aby to zrobić, wywołaj metodę setExtras z pakietem dodatków, który zawiera stałe odpowiadające zarezerwowanym funkcjom. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT odpowiada ACTION_SKIP_TO_NEXT, a SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV odpowiada ACTION_SKIP_TO_PREVIOUS. Użyj tych stałych jako kluczy w pakiecie, a jako wartości użyj wartości logicznej true.

Ustawianie początkowego stanu odtwarzania

Gdy Android Auto i AAOS komunikują się z Twoją usługą przeglądarki multimediów, sesja multimediów przekazuje stan odtwarzania treści za pomocą PlaybackStateCompat.

Aplikacja nie powinna automatycznie rozpoczynać odtwarzania muzyki, gdy AAOS lub Android Auto połączą się z Twoją usługą przeglądarki multimediów. Zamiast tego polegaj na Androidzie Auto i AAOS, które wznawiają lub rozpoczynają odtwarzanie na podstawie stanu samochodu lub działań użytkownika.

Aby to zrobić, ustaw początkowy PlaybackStateCompat sesji multimediów na STATE_STOPPED, STATE_PAUSED, STATE_NONE lub STATE_ERROR.

Sesje multimediów w Androidzie Auto i AAOS trwają tylko przez czas jazdy, więc użytkownicy często je rozpoczynają i zatrzymują. Aby zapewnić płynne przejście między jazdami, śledź stan poprzedniej sesji użytkownika, aby po otrzymaniu przez aplikację multimedialną prośby o wznowienie użytkownik mógł automatycznie kontynuować odtwarzanie od miejsca, w którym je przerwał. Może to być np. ostatnio odtwarzany element multimedialny, PlaybackStateCompat i kolejka.

Dodawanie niestandardowych działań związanych z odtwarzaniem

Możesz dodać niestandardowe działania związane z odtwarzaniem, aby wyświetlać dodatkowe działania obsługiwane przez aplikację do multimediów. Jeśli jest wystarczająco dużo miejsca (i nie jest ono zarezerwowane), Android dodaje działania niestandardowe do elementów sterujących transportem. W przeciwnym razie działania niestandardowe pojawiają się w menu Więcej. Android wyświetla działania niestandardowe w kolejności, w jakiej dodajesz je do PlaybackStateCompat.

Używaj działań niestandardowych, aby zapewnić zachowanie inne niż w przypadku działań standardowych. Nie używaj ich do zastępowania ani duplikowania działań standardowych.

Aby dodać działania niestandardowe, użyj metody addCustomAction w klasie PlaybackStateCompat.Builder. Ten fragment kodu pokazuje, jak dodać działanie niestandardowe „Uruchom kanał radiowy”:

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

Bardziej szczegółowy przykład tej metody znajdziesz w setCustomAction metodzie w przykładowej aplikacji Universal Android Music Player na GitHubie. Po utworzeniu działania niestandardowego sesja multimediów może odpowiadać na działania zastępując metodę onCustomAction.

Ten fragment kodu pokazuje, jak aplikacja może odpowiadać na działanie „Uruchom kanał radiowy”:

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

Więcej informacji znajdziesz w metodzie onCustomAction w przykładowej aplikacji Universal Android Music Player na GitHubie.

Tworzenie ikon działań niestandardowych

Każde utworzone przez Ciebie działanie niestandardowe wymaga ikony.

Jeśli opis tej ikony pasuje do jednej ze CommandButton.ICON_ stałych, ustaw wartość całkowitą dla EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT klucza w dodatkach działania niestandardowego. W obsługiwanych systemach spowoduje to zastąpienie zasobu ikony przekazanego do CustomAction.Builder, co pozwoli komponentom systemu na spójne renderowanie Twojego działania i innych działań związanych z odtwarzaniem.

Musisz też określić zasób ikony. Aplikacje w samochodach mogą działać na ekranach o różnych rozmiarach i gęstościach, dlatego ikony, które udostępniasz, muszą być obiektami rysowalnymi wektorowo. Użyj obiektu rysowalnego wektorowo, aby skalować zasoby bez utraty szczegółów. Obiekt rysowalny wektorowo może wyrównywać krawędzie i rogi do granic pikseli w mniejszych rozdzielczościach.

Jeśli działanie niestandardowe jest stanowe (przełącza ustawienie odtwarzania), podaj różne ikony dla różnych stanów, aby użytkownicy widzieli zmianę po wybraniu działania.

Podawanie alternatywnych stylów ikon dla wyłączonych działań

Gdy działanie niestandardowe jest niedostępne w bieżącym kontekście, zamień jego ikonę na alternatywną, która pokazuje, że działanie jest wyłączone.

Wskazywanie formatu dźwięku

Aby wskazać, że odtwarzane multimedia używają specjalnego formatu dźwięku, możesz określić ikony, które są renderowane w samochodach obsługujących tę funkcję. Możesz ustawić KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI i KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI w pakiecie dodatków aktualnie odtwarzanego elementu multimedialnego (przekazywanym do MediaSession.setMetadata). Ustaw oba dodatki, aby uwzględnić różne układy.

Możesz też ustawić dodatkowy klucz KEY_IMMERSIVE_AUDIO, aby poinformować producentów samochodów, że jest to dźwięk przestrzenny, i że powinni oni zachować szczególną ostrożność przy podejmowaniu decyzji o zastosowaniu efektów dźwiękowych, które mogą zakłócać działanie treści przestrzennych.

Dodawanie linków z aktualnie odtwarzanego elementu

Możesz skonfigurować odtwarzany element multimedialny tak, aby jego podtytuł, opis lub oba te elementy były linkami do innych elementów multimedialnych. Umożliwia to użytkownikowi szybkie przejście do powiązanych elementów, np. do innych utworów tego samego wykonawcy lub do innych odcinków podcastu. Jeśli samochód obsługuje tę funkcję, użytkownicy mogą kliknąć link, aby przejść do tych treści.

Aby dodać linki, skonfiguruj metadane KEY_SUBTITLE_LINK_MEDIA_ID (aby utworzyć link z podtytułu) lub KEY_DESCRIPTION_LINK_MEDIA_ID (aby utworzyć link z opisu). Szczegółowe informacje znajdziesz w dokumentacji tych pól metadanych.