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

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