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

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