เชื่อมต่อกับแอปสื่อ

ตัวควบคุมสื่อโต้ตอบกับเซสชันสื่อเพื่อค้นหาและควบคุมการเล่นของแอปสื่อ ใน Media3 นั้น MediaController API จะใช้อินเทอร์เฟซ Player ตัวอย่างแอปไคลเอ็นต์ที่ใช้ตัวควบคุมสื่อ ได้แก่

ตัวควบคุมสื่อยังมีประโยชน์ภายในแอปสื่อด้วย เช่น หากโปรแกรมเล่นและเซสชันสื่ออยู่ใน Service ที่แยกจาก Activity หรือ Fragment กับ UI

สร้าง 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());

แสดงตัวควบคุมการเล่นสำหรับแอปสื่ออื่น

เมื่อแสดงการควบคุม UI ด้วยปุ่มสำหรับแอปสื่ออื่น คุณต้องทำตามค่ากำหนดปุ่มสื่อที่ประกาศของแอปนั้น

วิธีที่ดีที่สุดในการแก้ไขค่ากําหนดของแอปและข้อจํากัดและข้อกําหนดของ UI คือการใช้ CommandButton.DisplayConstraints คุณสามารถกําหนดขีดจํากัดและข้อจํากัดของสิ่งที่ UI ทำได้ และเมธอด resolve จะแสดงรายการปุ่มที่แน่นอนเพื่อแสดงพร้อมไอคอน ตําแหน่ง และการดําเนินการที่ต้องการ