Aplikacje do multimediów często zawierają kolekcje elementów multimedialnych uporządkowane w hierarchii. na przykład utwory w albumie lub odcinki serialu na playliście. Ta hierarchia elementów multimedialnych jest nazywana biblioteką multimediów.
MediaLibraryService udostępnia standardowy interfejs API do obsługi biblioteki multimediów i uzyskiwania do niej dostępu. Może to być przydatne na przykład podczas dodawania obsługi Androida Auto do aplikacji do multimediów, która zapewnia własny, bezpieczny dla kierowcy interfejs biblioteki multimediów.
Utwórz MediaLibraryService
Implementacja MediaLibraryService jest podobna do implementacji MediaSessionService, z tą różnicą, że w metodzie onGetSession() należy zwrócić MediaLibrarySession zamiast MediaSession.
Kotlin
class PlaybackService : MediaLibraryService() { private var mediaLibrarySession: MediaLibrarySession? = null private val callback: MediaLibrarySession.Callback = object : MediaLibrarySession.Callback { /* ... */ } override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaLibrarySession? { // If desired, validate the controller before returning the media library session return mediaLibrarySession } // Create your player and media library session in the onCreate lifecycle event override fun onCreate() { super.onCreate() val player = ExoPlayer.Builder(this).build() mediaLibrarySession = MediaLibrarySession.Builder(this, player, callback).build() } // Remember to release the player and media library session in onDestroy override fun onDestroy() { mediaLibrarySession?.run { player.release() release() mediaLibrarySession = null } super.onDestroy() } }
Java
class PlaybackService extends MediaLibraryService { MediaLibrarySession mediaLibrarySession = null; MediaLibrarySession.Callback callback = new MediaLibrarySession.Callback() { /* ... */ }; @Override public MediaLibrarySession onGetSession(MediaSession.ControllerInfo controllerInfo) { // If desired, validate the controller before returning the media library session return mediaLibrarySession; } // Create your player and media library session in the onCreate lifecycle event @Override public void onCreate() { super.onCreate(); ExoPlayer player = new ExoPlayer.Builder(this).build(); mediaLibrarySession = new MediaLibrarySession.Builder(this, player, callback).build(); } // Remember to release the player and media library session in onDestroy @Override public void onDestroy() { if (mediaLibrarySession != null) { mediaLibrarySession.getPlayer().release(); mediaLibrarySession.release(); mediaLibrarySession = null; } super.onDestroy(); } }
Service i wymagane uprawnienia również w pliku manifestu:
<service
android:name=".PlaybackService"
android:foregroundServiceType="mediaPlayback"
android:exported="true">
<intent-filter>
<action android:name="androidx.media3.session.MediaLibraryService"/>
<action android:name="android.media.browse.MediaBrowserService"/>
</intent-filter>
</service>
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
Zalecamy zarejestrowanie usługi zarówno jako platformy, jak i interfejsu usługi Media3:
Aby zapewnić zgodność z klientami korzystającymi z interfejsów API sesji multimedialnych platformy, zalecamy uwzględnienie elementu
<action android:name="android.media.browse.MediaBrowserService"/>w elemencieintent-filter. Media3 automatycznie zapewnia zgodność wsteczną z tym interfejsem usługi.Aby zapewnić zgodność z przyszłymi rozwiązaniami i umożliwić aplikacjom korzystającym z Media3 komunikowanie się z Twoją usługą za pomocą interfejsu Media3 API, oprócz opcji platformy należy podać
<action android:name="androidx.media3.session.MediaLibraryService"/>.
Dzięki temu aplikacje mogą znaleźć Twoją usługę przez PackageManager i połączyć się z MediaBrowser za pomocą jednego z tych interfejsów.
Użyj MediaLibrarySession
Interfejs API MediaLibraryService oczekuje, że biblioteka multimediów będzie miała strukturę drzewa z jednym węzłem głównym i węzłami podrzędnymi, które mogą być odtwarzane lub przeglądane.
MediaLibrarySession rozszerza interfejs API MediaSession, aby dodać interfejsy API do przeglądania treści. W porównaniu z wywołaniem zwrotnym MediaSession wywołanie zwrotne MediaLibrarySession dodaje metody takie jak:
onGetLibraryRoot(), gdy klient żąda katalogu głównegoMediaItemdrzewa treści.onGetChildren(), gdy klient żąda elementów podrzędnychMediaItemw drzewie treści.onGetSearchResult(), gdy klient prosi o wyniki wyszukiwania z drzewa treści dla danego zapytania.
Odpowiednie metody wywołania zwrotnego będą zawierać obiekt LibraryParams z dodatkowymi sygnałami dotyczącymi typu drzewa treści, którym jest zainteresowana aplikacja kliencka.
Przyciski poleceń dla elementów multimedialnych
Aplikacja sesji może deklarować przyciski poleceń obsługiwane przez MediaItem w MediaMetadata. Umożliwia to przypisanie co najmniej 1 wpisu CommandButton do elementu multimedialnego, który kontroler może wyświetlać i używać do wysyłania niestandardowego polecenia dotyczącego elementu do sesji w wygodny sposób.
Konfigurowanie przycisków poleceń po stronie sesji
Podczas tworzenia sesji aplikacja sesji deklaruje zestaw przycisków poleceń, które sesja może obsługiwać jako polecenia niestandardowe:
Kotlin
val allCommandButtons = listOf( CommandButton.Builder(CommandButton.ICON_PLAYLIST_ADD) .setDisplayName(context.getString(R.string.add_to_playlist)) .setSessionCommand(SessionCommand(COMMAND_PLAYLIST_ADD, Bundle.EMPTY)) .setExtras(playlistAddExtras) .build(), CommandButton.Builder(CommandButton.ICON_RADIO) .setDisplayName(context.getString(R.string.radio_station)) .setSessionCommand(SessionCommand(COMMAND_RADIO, Bundle.EMPTY)) .setExtras(radioExtras) .build(), ) // Add all command buttons for media items supported by the session. val session = MediaSession.Builder(context, player) .setCommandButtonsForMediaItems(allCommandButtons) .build()
Java
ImmutableList<CommandButton> allCommandButtons = ImmutableList.of( new CommandButton.Builder(CommandButton.ICON_PLAYLIST_ADD) .setDisplayName(context.getString(R.string.add_to_playlist)) .setSessionCommand(new SessionCommand(COMMAND_PLAYLIST_ADD, Bundle.EMPTY)) .setExtras(playlistAddExtras) .build(), new CommandButton.Builder(CommandButton.ICON_RADIO) .setDisplayName(context.getString(R.string.radio_station)) .setSessionCommand(new SessionCommand(COMMAND_RADIO, Bundle.EMPTY)) .setExtras(radioExtras) .build()); // Add all command buttons for media items supported by the session. MediaSession session = new MediaSession.Builder(context, player) .setCommandButtonsForMediaItems(allCommandButtons) .build();
Podczas tworzenia elementu multimedialnego aplikacja sesji może dodać zestaw obsługiwanych identyfikatorów poleceń, które odwołują się do poleceń sesji przycisków poleceń skonfigurowanych podczas tworzenia sesji:
Kotlin
val mediaItem = MediaItem.Builder() .setMediaMetadata( MediaMetadata.Builder() .setSupportedCommands(listOf(COMMAND_PLAYLIST_ADD, COMMAND_RADIO)) .build() ) .build()
Java
MediaItem mediaItem = new MediaItem.Builder() .setMediaMetadata( new MediaMetadata.Builder() .setSupportedCommands(ImmutableList.of(COMMAND_PLAYLIST_ADD, COMMAND_RADIO)) .build()) .build();
Gdy kontroler lub przeglądarka łączy się z sesją Callback lub wywołuje inną jej metodę, aplikacja sesji może sprawdzić obiekt ControllerInfo przekazany do wywołania zwrotnego, aby uzyskać maksymalną liczbę przycisków poleceń, które może wyświetlić kontroler lub przeglądarka. Obiekt ControllerInfo przekazywany do metody wywołania zwrotnego udostępnia metodę pobierającą, która umożliwia wygodny dostęp do tej wartości. Domyślnie jest ustawiona wartość 0, co oznacza, że przeglądarka lub kontroler nie obsługuje tej funkcji:
Kotlin
override fun onGetItem( session: MediaLibrarySession, browser: MediaSession.ControllerInfo, mediaId: String, ): ListenableFuture<LibraryResult<MediaItem>> { val settableFuture = SettableFuture.create<LibraryResult<MediaItem>>() val maxCommandsForMediaItems = browser.maxCommandsForMediaItems loadMediaItemAsync(settableFuture, mediaId, maxCommandsForMediaItems) return settableFuture }
Java
@Override public ListenableFuture<LibraryResult<MediaItem>> onGetItem( MediaLibraryService.MediaLibrarySession session, ControllerInfo browser, String mediaId) { SettableFuture<LibraryResult<MediaItem>> settableFuture = SettableFuture.create(); int maxCommandsForMediaItems = browser.getMaxCommandsForMediaItems(); loadMediaItemAsync(settableFuture, mediaId, maxCommandsForMediaItems); return settableFuture; }
Podczas obsługi działania niestandardowego, które zostało wysłane w przypadku elementu multimedialnego, aplikacja sesji może uzyskać identyfikator elementu multimedialnego z argumentów Bundle przekazanych do onCustomCommand:
Kotlin
override fun onCustomCommand( session: MediaSession, controller: MediaSession.ControllerInfo, customCommand: SessionCommand, args: Bundle, ): ListenableFuture<SessionResult> { val mediaItemId = args.getString(MediaConstants.EXTRA_KEY_MEDIA_ID) return if (mediaItemId != null) handleCustomCommandForMediaItem(controller, customCommand, mediaItemId, args) else handleCustomCommand(controller, customCommand, args) }
Java
@Override public ListenableFuture<SessionResult> onCustomCommand( MediaSession session, ControllerInfo controller, SessionCommand customCommand, Bundle args) { String mediaItemId = args.getString(MediaConstants.EXTRA_KEY_MEDIA_ID); return mediaItemId != null ? handleCustomCommandForMediaItem(controller, customCommand, mediaItemId, args) : handleCustomCommand(controller, customCommand, args); }
Używanie przycisków poleceń jako przeglądarki lub kontrolera
Po stronie MediaController aplikacja może zadeklarować maksymalną liczbę przycisków poleceń, które obsługuje w przypadku elementu multimedialnego, podczas tworzenia MediaController lub MediaBrowser:
Kotlin
val browserFuture = MediaBrowser.Builder(context, sessionToken).setMaxCommandsForMediaItems(3).buildAsync()
Java
ListenableFuture<MediaBrowser> browserFuture = new MediaBrowser.Builder(context, sessionToken).setMaxCommandsForMediaItems(3).buildAsync();
Po połączeniu z sesją aplikacja kontrolera może odbierać przyciski poleceń, które są obsługiwane przez element multimedialny i w przypadku których kontroler ma dostępne polecenie przyznane przez aplikację sesji:
Kotlin
val commandButtonsForMediaItem = controller.getCommandButtonsForMediaItem(mediaItem)
Java
ImmutableList<CommandButton> commandButtonsForMediaItem = controller.getCommandButtonsForMediaItem(mediaItem);
Kotlin
val future = controller.sendCustomCommand( requireNotNull(addToPlaylistButton.sessionCommand), mediaItem, Bundle.EMPTY, )
Java
ListenableFuture<SessionResult> future = controller.sendCustomCommand( checkNotNull(addToPlaylistButton.sessionCommand), mediaItem, Bundle.EMPTY);