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

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

בקר מדיה יכול להיות שימושי גם בתוך אפליקציית מדיה, לדוגמה אם נגן ומדיה במצב פעיל ב-Service בנפרד מ-Activity או Fragment בממשק המשתמש.

יצירת MediaController

כדי ליצור MediaController, צריך להתחיל ביצירת SessionToken עבור MediaSession התואם. השיטה onStart() של Activity או Fragment יכול להיות מקום טוב לעשות את זה.

KotlinJava
val sessionToken = 
  SessionToken(context, ComponentName(context, PlaybackService::class.java))
 
SessionToken sessionToken = 
  new SessionToken(context, new ComponentName(context, PlaybackService.class));

שימוש ב-SessionToken כדי ליצור MediaController מחבר את הבקר לסשן הנתון. התהליך מתבצע באופן אסינכרוני, לכן צריך להאזין לתוצאה ולהשתמש בה כשהיא זמינה.

KotlinJava
val controllerFuture =
  MediaController.Builder(context, sessionToken).buildAsync()
controllerFuture.addListener({
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor())
 
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 הממשק מגדיר קריאות חוזרות (callbacks) נוספות עבור אירועים ופקודות נכנסות MediaSession מחובר, כמו onAvailableSessionCommandsChanged() למקרים שבהם סשן המדיה משנה את פקודות הסשן הזמינות onDisconnected() כשהבקר מנותק מהסשן.

כמו ברכיבים אחרים, חשוב לזכור לשחרר את MediaController כשאין בו יותר צורך, למשל בשיטה onStop() של Activity או של Fragment.

KotlinJava
MediaController.releaseFuture(controllerFuture)
 
MediaController.releaseFuture(controllerFuture);

שחרור השלט רחוק עדיין יעביר את כל הפקודות הממתינות שנשלחו אל ולבטל את הקישור לשירות ההפעלה רק כאשר לפקודות האלה מטופל או לאחר פרק זמן קצוב לתפוגה, המוקדם מביניהם.

יצירת MediaBrowser ושימוש בו

MediaBrowser מתבסס על היכולות שמוצעות MediaController כדי לאפשר גם לעיין בספריית המדיה המוצעת על ידי מדיה MediaLibraryService של האפליקציה.

KotlinJava
val browserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
browserFuture.addListener({
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor())
 
ListenableFuture<MediaBrowser> browserFuture =
  new MediaBrowser.Builder(context, sessionToken).buildAsync();
browserFuture.addListener(() -> {
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor());

כדי להתחיל לעיין בספריית התוכן של אפליקציית המדיה, קודם צריך לאחזר את צומת הבסיס באמצעות getLibraryRoot():

KotlinJava
// 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())
 
// 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:

KotlinJava
// 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())
 
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());