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:
- Controlli multimediali del sistema Android
- App complementare Android Wear OS
- Android Auto e Automotive OS
- Assistenti vocali, come l'Assistente Google
- L'app di test del 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. Questa 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 MediaController
il comando verrà inviato a 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 viene 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 evento si verifica per primo.
Creare e utilizzare un 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
.
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());
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.
Il modo migliore per risolvere le preferenze dell'app e i vincoli e
i requisiti della tua UI è utilizzare 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.