בקר מדיה מקיים אינטראקציה עם סשן מדיה כדי לשלוח שאילתות ולשלוט בהפעלה של אפליקציית מדיה. ב-Media3, ממשק ה-API של MediaController
מטמיע את הממשק Player
. דוגמאות לאפליקציות לקוח שמשתמשות בנגן מדיה:
- אמצעי הבקרה על המדיה במערכת Android
- אפליקציה נלווית ל-Android Wear OS
- Android Auto ו-Android Automotive OS
- עוזרים קוליים, כמו Google Assistant
- אפליקציית Media Controller Test
אפשר להשתמש בנגן מדיה גם באפליקציית מדיה, למשל אם הנגן וסשן המדיה נמצאים ב-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
מחבר את הבקר לסשן הנתון. התהליך מתבצע באופן אסינכרוני, לכן צריך להאזין לתוצאה ולהשתמש בה כשהיא זמינה.
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
מספקת רשימה מוגדרת של לחצנים להצגה, עם הסמל, המיקום והפעולה המיועדת שלהם.