Connettersi a un'app multimediale

Esistono due modi per connettersi a un'app multimediale:

  1. MediaController
  2. MediaBrowser

MediaController

Un controller multimediale interagisce con una sessione multimediale per eseguire query e controllare la riproduzione di un'app multimediale. In Media3, l'API MediaController implementa l'interfaccia Player. Esempi di app client che utilizzano un controller multimediale:

Un controller multimediale può essere utile anche all'interno di un'app multimediale, ad esempio se il player e la sessione multimediale si trovano in un Service separato da Activity o Fragment con la UI.

Crea un MediaController

Per creare un MediaController, inizia creando un SessionToken per il MediaSession corrispondente. Il metodo onStart() del tuo Activity o Fragment può essere un buon punto di partenza.

Kotlin

val sessionToken =
  SessionToken(context, ComponentName(context, PlaybackService::class.java))

Java

SessionToken sessionToken =
  new SessionToken(context, new ComponentName(context, PlaybackService.class));

L'utilizzo di questo SessionToken per creare un MediaController connette il controller alla sessione specificata. L'operazione viene eseguita in modo asincrono, quindi devi ascoltare il risultato e utilizzarlo quando è disponibile.

Kotlin

val controllerFuture =
  MediaController.Builder(context, sessionToken).buildAsync()
controllerFuture.addListener({
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaController> controllerFuture =
  new MediaController.Builder(context, sessionToken).buildAsync();
controllerFuture.addListener(() -> {
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor());

Usa un MediaController

MediaController implementa l'interfaccia Player, quindi puoi utilizzare i comandi definiti nell'interfaccia per controllare la riproduzione di MediaSession connesso. Ciò significa che chiamando play() su un MediaController il comando verrà inviato al MediaSession connesso, che a sua volta lo delegherà al Player sottostante.

Puoi aggiungere un Player.Listener al controller per rilevare le modifiche nello stato di Player. Per ulteriori dettagli sull'utilizzo di un Player.Listener, consulta la guida Eventi del giocatore.

L'interfaccia MediaController.Listener definisce callback aggiuntivi per eventi e comandi personalizzati dal MediaSession connesso. Alcuni esempi sono onCustomCommand() quando la sessione invia un comando personalizzato, onAvailableSessionCommandsChanged() quando la sessione modifica i comandi disponibili per la sessione o onDisconnected() quando il controller è disconnesso dalla sessione.

È possibile impostare un MediaController.Listener durante la creazione del controller con un Builder:

Kotlin

MediaController.Builder(context, sessionToken)
    .setListener(
      object : MediaController.Listener {
        override fun onCustomCommand(
          controller: MediaController,
          command: SessionCommand,
          args: Bundle,
        ): ListenableFuture<SessionResult> {
          // Handle custom command.
          return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
        }

        override fun onDisconnected(controller: MediaController) {
          // Handle disconnection.
        }
      }
    )
    .buildAsync()

Java

new MediaController.Builder(context, sessionToken)
    .setListener(
        new MediaController.Listener() {
          @Override
          public ListenableFuture<SessionResult> onCustomCommand(
              MediaController controller, SessionCommand command, Bundle args) {
            // Handle custom command.
            return Futures.immediateFuture(new SessionResult(SessionResult.RESULT_SUCCESS));
          }

          @Override
          public void onDisconnected(MediaController controller) {
            // Handle disconnection.
          }
        })
    .buildAsync();

Come per gli altri componenti, ricordati di rilasciare MediaController quando non è più necessario, ad esempio nel metodo onStop() di un Activity o Fragment.

Kotlin

MediaController.releaseFuture(controllerFuture)

Java

MediaController.releaseFuture(controllerFuture);

Il rilascio del controller continuerà a inviare tutti i comandi in attesa alla sessione e si scollegherà dal servizio di sessione solo dopo che questi comandi sono stati gestiti o dopo un periodo di timeout, a seconda di quale condizione si verifica per prima.

MediaBrowser

Un MediaBrowser si basa sulle funzionalità offerte da un MediaController per consentire anche la navigazione nella raccolta multimediale offerta da un'app multimediale MediaLibraryService.

Crea un MediaBrowser

Kotlin

val browserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
browserFuture.addListener({
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaBrowser> browserFuture =
  new MediaBrowser.Builder(context, sessionToken).buildAsync();
browserFuture.addListener(() -> {
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor());

Usa un MediaBrowser

Per iniziare a sfogliare la raccolta di contenuti dell'app multimediale, recupera innanzitutto il nodo radice con getLibraryRoot():

Kotlin

// Get the library root to start browsing the library tree.
val rootFuture = mediaBrowser.getLibraryRoot(/* params= */ null)
rootFuture.addListener({
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor())

Java

// Get the library root to start browsing the library tree.
ListenableFuture<LibraryResult<MediaItem>> rootFuture =
  mediaBrowser.getLibraryRoot(/* params= */ null);
rootFuture.addListener(() -> {
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor());

Puoi quindi navigare nella raccolta multimediale recuperando i figli di un MediaItem nella raccolta con getChildren(). Ad esempio, per recuperare i nodi secondari del nodo radice MediaItem:

Kotlin

// Get the library root to start browsing the library tree.
val childrenFuture = 
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Int.MAX_VALUE, null)
childrenFuture.addListener({
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor())

Java

ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> childrenFuture =
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Integer.MAX_VALUE, null);
childrenFuture.addListener(() -> {
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor());

Visualizzare i controlli di riproduzione per un'altra app multimediale

Quando vengono visualizzati controlli dell'interfaccia utente con pulsanti per un'altra app multimediale, è importante seguire le preferenze dei pulsanti multimediali dichiarate di quell'app.

Per risolvere le preferenze dell'app con i vincoli e i requisiti della tua UI, utilizza CommandButton.DisplayConstraints. Puoi definire i limiti e le restrizioni della tua UI e il metodo resolve fornisce un elenco definitivo di pulsanti da visualizzare con la relativa icona, posizione e azione prevista. Se un utente fa clic su uno di questi pulsanti, puoi utilizzare CommandButton.executeAction per attivare l'azione associata nell'app multimediale.

Kotlin

// Get media button preferences from media app
val mediaButtonPreferences = controller.getMediaButtonPreferences()
// Declare constraints of UI (example: limit overflow button to one)
val displayConstraints =
  DisplayConstraints.Builder().setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1).build()
// Resolve media app preferences with constraints
val resolvedButtons = displayConstraints.resolve(mediaButtonPreferences, controller)
// Display buttons in UI
for (button in resolvedButtons) {
  generateUiButton(
    uiPosition = button.slots[0],
    icon = getIconRes(button.icon),
    onClick = { button.executeAction(controller) },
  )
}

Java

// Get media button preferences from media app
List<CommandButton> mediaButtonPreferences = controller.getMediaButtonPreferences();
// Declare constraints of UI (example: limit overflow button to one)
DisplayConstraints displayConstraints =
    new DisplayConstraints.Builder()
        .setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1)
        .build();
// Resolve media app preferences with constraints
List<CommandButton> resolvedButtons =
    displayConstraints.resolve(mediaButtonPreferences, controller);
// Display buttons in UI
for (CommandButton button : resolvedButtons) {
  generateUiButton(
      /* uiPosition= */ button.slots.get(0),
      /* icon= */ getIconRes(button.icon),
      /* onClick= */ () -> button.executeAction(controller));
}