Włącz sterowanie odtwarzaniem

Aby włączyć odtwarzanie multimediów w Androidzie Auto i Androidzie Automotive OS (AAOS), zaimplementuj elementy sterujące odtwarzaniem, rejestrując sesję multimedialną i obsługując jej metody wywołania zwrotnego. Na tej stronie dowiesz się:

• Zarejestruj obiekt MediaSessionCompat w usłudze przeglądarki multimediów.

• Zaimplementuj metody MediaSessionCompat.Callback, aby odpowiadać na żądania użytkowników dotyczące odtwarzania.

• Skonfiguruj standardowe i niestandardowe działania związane z odtwarzaniem.

• Ustaw początkowy stan odtwarzania sesji multimedialnej.

• Dodaliśmy ikony oznaczające format audio.

• Tworzenie linków z aktualnie odtwarzanych elementów multimedialnych.

Android Auto i AAOS wysyłają polecenia sterowania odtwarzaniem przez MediaSessionCompat dla Twojej usługi. Musisz zarejestrować sesję i wdrożyć 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ę multimedialną. Ten fragment kodu pokazuje, jak utworzyć i zarejestrować sesję multimedialną:

Kotlin

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
    ...
}

Java

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 multimedialnej ustawiasz obiekt wywołania zwrotnego, który jest używany do obsługi żądań sterowania odtwarzaniem. Ten obiekt wywołania zwrotnego tworzysz, podając implementację klasy MediaSessionCompat.Callback w swojej aplikacji. W następnej sekcji dowiesz się, jak zaimplementować ten obiekt.

Uwaga: aby sprawdzić sesję multimedialną, uruchom adb shell dumpsys media_session

Implementowanie poleceń odtwarzania

Gdy użytkownik poprosi o odtwarzanie elementu multimedialnego z Twojej aplikacji, Android Automotive OS i Android Auto użyją klasy MediaSessionCompat.Callback z obiektu MediaSessionCompat Twojej aplikacji, który został uzyskany z usługi przeglądarki multimediów w Twojej aplikacji. 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 rozszerzać klasę abstrakcyjną MediaSessionCompat.Callback i wdrażać metody, które obsługuje.

Zaimplementuj każdą z tych metod wywołania zwrotnego, które są odpowiednie dla typu treści oferowanych przez Twoją aplikację:

onPrepare

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

onPlay

Wywoływane, gdy użytkownik wybierze odtwarzanie bez wybierania konkretnego elementu. Aplikacja musi odtwarzać domyślne treści lub, jeśli odtwarzanie zostało wstrzymane za pomocą przycisku onPause, wznowić odtwarzanie.

Uwaga: aplikacja nie może automatycznie rozpoczynać odtwarzania muzyki, gdy system operacyjny Android Automotive lub Android Auto połączy się z usługą przeglądarki multimediów. Więcej informacji znajdziesz w artykule Ustawianie początkowego stanu odtwarzania.

onPlayFromMediaId

Wywoływana, gdy użytkownik wybierze odtworzenie określonego elementu. Metoda otrzymuje identyfikator, który usługa przeglądarki multimediów przypisała do elementu multimedialnego w hierarchii treści.

onPlayFromSearch

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

onPause

Wywoływane, gdy użytkownik zdecyduje się wstrzymać odtwarzanie.

onSkipToNext

Wywoływana, gdy użytkownik zdecyduje się przejść do następnego elementu.

onSkipToPrevious

Wywoływana, gdy użytkownik zdecyduje się przejść do poprzedniego elementu.

onStop

Wywoływane, gdy użytkownik zdecyduje się zatrzymać odtwarzanie. Zastąp te metody w aplikacji, aby podać wybrany wynik. Nie musisz implementować metody, jeśli jej cel nie jest obsługiwany przez Twoją aplikację. Jeśli np. aplikacja odtwarza transmisję na żywo, np. transmisję sportową, nie musisz implementować metody onSkipToNext. Zamiast tego użyj domyślnej implementacji onSkipToNext.

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

Więcej informacji o odtwarzaniu treści audio znajdziesz w omówieniu odtwarzacza multimediów, omówieniu aplikacji audio i omówieniu ExoPlayera.

Ustawianie standardowych działań odtwarzania

Android Auto i AAOS wyświetlają elementy sterujące odtwarzaniem na podstawie działań włączonych w obiekcie PlaybackStateCompat. 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

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.

Dodaliśmy 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 zmieni się kolejka.

Uwaga: dodanie ikony Teraz odtwarzane jest wymagane tylko wtedy, gdy obsługujesz kolejkę odtwarzania.

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

Rezerwowanie nieużywanego 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 wykorzystują to miejsce 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 zawierającym stałe wartości 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 wartości logicznej true jako wartości.

Ustawianie początkowego stanu odtwarzania

Gdy Android Auto i AAOS komunikują się z 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łączy się z usługą przeglądarki multimediów. Zamiast tego polegaj na Androidzie Auto i AAOS, aby wznawiać lub rozpoczynać odtwarzanie na podstawie stanu samochodu lub działań użytkownika.

Aby to zrobić, ustaw początkowy stan PlaybackStateCompat sesji multimedialnej na STATE_STOPPED, STATE_PAUSED, STATE_NONE lub STATE_ERROR.

Uwaga: gdy wartość PlaybackStateCompat jest ustawiona na STATE_NONE, interfejs odtwarzania w Androidzie Auto i AAOS staje się niedostępny. Wysyłaj ten stan tylko wtedy, gdy aplikacja nie ma nic do odtworzenia, a użytkownik musi wybrać nowe treści, aby rozpocząć odtwarzanie.

Sesje multimedialne w Androidzie Auto i AAOS trwają tylko podczas jazdy, więc użytkownicy często je rozpoczynają i kończą. Aby zapewnić płynne przejście między przejazdami, śledź stan poprzedniej sesji użytkownika. Dzięki temu, gdy aplikacja multimedialna otrzyma prośbę o wznowienie, użytkownik będzie mógł automatycznie kontynuować od miejsca, w którym skończył. Może to być na przykład ostatnio odtwarzany element multimedialny, PlaybackStateCompat i kolejka.

Dodawanie niestandardowych działań odtwarzania

Możesz dodać niestandardowe działania odtwarzania, aby wyświetlać dodatkowe działania obsługiwane przez aplikację multimedialną. Jeśli jest wystarczająco dużo miejsca (a nie zarezerwujesz go), Android doda niestandardowe działania do elementów sterujących transportem. W przeciwnym razie działania niestandardowe pojawią się w menu Przepełnienie. 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 standardowych działań.

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

Kotlin

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()
    }
)

Java

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 w przykładowej aplikacji Universal Android Music Player na GitHubie. Po utworzeniu działania niestandardowego sesja multimedialna może odpowiadać na działania, zastępując metodę onCustomAction.

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

Kotlin

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

Java

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

Więcej informacji znajdziesz w 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 stałych CommandButton.ICON_, ustaw wartość całkowitą klucza EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT w dodatkach działania niestandardowego. W obsługiwanych systemach spowoduje to zastąpienie zasobu ikony przekazanego do funkcji CustomAction.Builder, co umożliwi komponentom systemu spójne renderowanie 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 pikseli, dlatego ikony muszą być rysunkami wektorowymi. Używaj obiektów rysowalnych wektorowo, aby skalować zasoby bez utraty szczegółów. Obraz wektorowy może wyrównywać krawędzie i rogi do granic pikseli przy mniejszych rozdzielczościach.

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

Podaj alternatywne style ikon dla wyłączonych działań

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

Rysunek 1. Przykłady ikon niestandardowych działań w nieodpowiednim stylu.

Określanie formatu audio

Aby wskazać, że odtwarzane multimedia korzystają ze specjalnego formatu audio, możesz określić ikony, które będą 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 (przekazywanego do MediaSession.setMetadata). Ustaw oba dodatki, aby dostosować je do różnych układów.

Możesz też ustawić wartość KEY_IMMERSIVE_AUDIO extra, aby poinformować producentów samochodów, że jest to dźwięk przestrzenny, i poprosić ich o zachowanie szczególnej ostrożności przy podejmowaniu decyzji o zastosowaniu efektów dźwiękowych, które mogą zakłócać odbiór treści przestrzennych.

Dodawanie linków z aktualnie odtwarzanego elementu

Możesz skonfigurować odtwarzany element multimedialny tak, aby jego napisy, opis lub oba te elementy były linkami do innych elementów multimedialnych. Dzięki temu użytkownik może szybko przejść do powiązanych elementów, np. innych utworów tego samego wykonawcy lub innych odcinków podcastu. Jeśli samochód obsługuje tę funkcję, użytkownicy mogą kliknąć link, aby wyświetlić te treści.

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