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

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

• การควบคุมสื่อของระบบ Android
• แอปที่ใช้ร่วมกับ Android Wear OS
• Android Auto และ Automotive OS
• ผู้ช่วยแบบเสียง เช่น Google Assistant
• แอปทดสอบตัวควบคุมสื่อ

ตัวควบคุมสื่อยังมีประโยชน์ภายในแอปสื่อด้วย เช่น หากโปรแกรมเล่นและเซสชันสื่ออยู่ใน 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());

หมายเหตุ: ใช้ ContextCompat.getMainExecutor() แทน MoreExecutors.directExecutor() ในกรณีที่คุณเรียกใช้บริการในกระบวนการอื่นนอกเหนือจาก UI

หมายเหตุ: แอปที่กำหนดเป้าหมายเป็น SDK ระดับ 30 ขึ้นไปต้องมีองค์ประกอบ <queries> ในไฟล์ Manifest เพื่อเชื่อมต่อกับ MediaSessionService ของแอปอื่น (หรือคอมโพเนนต์ที่คล้ายกัน) ดูรายละเอียดเพิ่มเติมได้ในคำแนะนำเกี่ยวกับระดับการเข้าถึงแพ็กเกจ

ใช้ MediaController

MediaController จะใช้อินเทอร์เฟซ Player คุณจึงใช้คำสั่ง ที่กำหนดไว้ในอินเทอร์เฟซเพื่อควบคุมการเล่น MediaSession ที่เชื่อมต่ออยู่ กล่าวคือ การเรียกใช้ play() ใน MediaController จะส่งคำสั่งไปยัง MediaSession ที่เชื่อมต่ออยู่ ซึ่งจะมอบหมายคำสั่งนั้นให้กับ Player ที่อยู่เบื้องหลัง

เคล็ดลับ: ตัวควบคุมสื่อจะใช้อินเทอร์เฟซ Player คุณจึงสามารถใช้ ให้กำหนดให้กับโปรแกรมเล่นภายใน UI

ในทํานองเดียวกัน คุณสามารถเพิ่ม Player.Listener ลงในตัวควบคุมเพื่อรอรับการเปลี่ยนแปลงในสถานะ Player ดูรายละเอียดเพิ่มเติมเกี่ยวกับการใช้ Player.Listener ได้จากคู่มือเหตุการณ์ของผู้เล่น MediaController.Listener อินเทอร์เฟซจะกำหนด Callback เพิ่มเติมสำหรับเหตุการณ์และคำสั่งขาเข้าจาก 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());