חיבור לאפליקציית מדיה

בקר מדיה מקיים אינטראקציה עם סשן מדיה כדי לשלוח שאילתות ולשלוט בהפעלה של אפליקציית מדיה. ב-Media3, ממשק ה-API של MediaController מטמיע את הממשק Player. דוגמאות לאפליקציות לקוח שבהן משתמשים בבקרי מדיה:

שלט מדיה יכול להיות שימושי גם באפליקציית מדיה, לדוגמה אם הנגן והפעלת המדיה נמצאים ב-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 המחובר, כמו onAvailableSessionCommandsChanged() כשסשן המדיה משנה את פקודות הסשן הזמינות, ו-onDisconnected() כשהבקר מנותק מהסשן.

כמו ברכיבים אחרים, חשוב לזכור לשחרר את 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());