בקר מדיה מקיים אינטראקציה עם סשן מדיה כדי לשלוח שאילתות לגבי ההפעלה של אפליקציית מדיה ולשלוט בה. ב-Media3, ממשק ה-API MediaController
מטמיע את הממשק Player
. דוגמאות לאפליקציות לקוח שמשתמשות בבקר מדיה:
- אמצעי בקרה למדיה במערכת Android
- אפליקציה נלווית ל-Android Wear OS
- Android Auto ו-Automotive OS
- עוזרים קוליים, כמו Google Assistant
- אפליקציית הבדיקה של אמצעי הבקרה של המדיה
בנוסף, כדאי להשתמש באמצעי בקרה של מדיה באפליקציות מדיה, למשל אם נגן המדיה והסשן של המדיה נמצאים ב-Service
בנפרד מ-Activity
או מ-Fragment
עם ממשק המשתמש.
יצירת MediaController
כדי ליצור MediaController
, מתחילים ביצירת SessionToken
עבור MediaSession
התואם. אפשר להשתמש בשיטה onStart()
של Activity
או Fragment
.
Kotlin
val sessionToken =
SessionToken(context, ComponentName(context, PlaybackService::class.java))
Java
SessionToken sessionToken =
new SessionToken(context, new ComponentName(context, PlaybackService.class));
השימוש ב-SessionToken
הזה כדי ליצור MediaController
מחבר את בקר ה-IP לשיחה הנתונה. הפעולה הזו מתבצעת באופן אסינכרוני, ולכן צריך להמתין לתוצאה ולהשתמש בה כשהיא זמינה.
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());
שימוש ב-MediaController
MediaController
מטמיע את הממשק Player
, כך שאפשר להשתמש בפקודות שמוגדרות בממשק כדי לשלוט בהפעלה של MediaSession
המחובר.
כלומר, קריאה ל-play()
ב-MediaController
תשלח את הפקודה ל-MediaSession
המחובר, שיעביר את הפקודה ל-Player
הבסיסי שלו.
אפשר להוסיף Player.Listener
לבקר כדי להאזין לשינויים במצב Player
. פרטים נוספים על השימוש ב-Player.Listener
זמינים במדריך בנושא אירועים של נגנים.
בממשק MediaController.Listener
מוגדרות קריאות חוזרות נוספות לאירועים ולפקודות בהתאמה אישית מ-MediaSession
המחובר. לדוגמה, onCustomCommand()
כשבסשן נשלחת פקודה בהתאמה אישית, onAvailableSessionCommandsChanged()
כשבסשן משתנות הפקודות הזמינות או onDisconnected()
כשבקר מתנתק מהסשן.
אפשר להגדיר MediaController.Listener
כשיוצרים את בקר באמצעות 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();
כמו ברכיבים אחרים, חשוב לזכור לשחרר את MediaController
כשאין בו יותר צורך, למשל בשיטת onStop()
של Activity
או Fragment
.
Kotlin
MediaController.releaseFuture(controllerFuture)
Java
MediaController.releaseFuture(controllerFuture);
שחרור בקר עדיין יספק את כל הפקודות בהמתנה שנשלחו לסשן, ויבטל את הקישור לשירות הסשן רק אחרי שהפקודות האלה יטופלו או אחרי תקופת המתנה, לפי המוקדם מביניהם.
יצירה של MediaBrowser
ושימוש בה
MediaBrowser
מבוסס על היכולות שמוצעות על ידי MediaController
, וגם מאפשר גלישה בספריית המדיה שמוצעת על ידי 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());
כדי להתחיל לעיין בספריית התוכן של אפליקציית המדיה, קודם צריך לאחזר את צומת הבסיס באמצעות 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());
אחר כך תוכלו לנווט בספריית המדיה על ידי אחזור של צאצאים של MediaItem
בספרייה באמצעות getChildren()
. לדוגמה, כדי לאחזר את צאצאי צומת הבסיס 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());
הצגת אמצעי בקרה להפעלה של אפליקציית מדיה אחרת
כשמציגים אמצעי בקרה בממשק המשתמש עם לחצנים לאפליקציית מדיה אחרת, חשוב לפעול בהתאם להעדפות לחצני המדיה שהוגדרו באפליקציה הזו.
הדרך הכי טובה לפתור את הבעיות שקשורות להעדפות של האפליקציה ולמגבלות ולדרישות של ממשק המשתמש היא להשתמש ב-CommandButton.DisplayConstraints
. אתם יכולים להגדיר מגבלות והגבלות על הפעולות שאפשר לבצע בממשק המשתמש, והשיטה resolve
מספקת רשימה מוגדרת של לחצנים להצגה עם הסמל, המיקום והפעולה המיועדת שלהם.