ภาพรวม MediaRouter

หากต้องการใช้เฟรมเวิร์ก MediaRouter ภายในแอป คุณต้องรับอินสแตนซ์ของออบเจ็กต์ MediaRouter และแนบออบเจ็กต์ MediaRouter.Callback เพื่อฟังเหตุการณ์การกำหนดเส้นทาง เนื้อหาที่ส่งผ่านเส้นทางสื่อจะผ่าน MediaRouteProvider ที่เชื่อมโยงกับเส้นทาง (ยกเว้นในบางกรณีพิเศษ เช่น อุปกรณ์เอาต์พุตบลูทูธ) รูปที่ 1 แสดงมุมมองระดับสูงของคลาสที่ใช้เพื่อกำหนดเส้นทางเนื้อหาระหว่างอุปกรณ์

รูปที่ 1 ภาพรวมของคลาส Media Router หลักที่แอปใช้

หมายเหตุ: หากต้องการให้แอปของคุณรองรับอุปกรณ์ Google Cast คุณควรใช้ Cast SDK และสร้างแอปเป็นผู้ส่ง Cast ทำตามวิธีการในเอกสารประกอบของ Cast แทนการใช้เฟรมเวิร์ก MediaRouter โดยตรง

ปุ่มเส้นทางสื่อ

แอป Android ควรใช้ปุ่มเส้นทางสื่อเพื่อควบคุมการกำหนดเส้นทางสื่อ เฟรมเวิร์ก MediaRouter มีอินเทอร์เฟซมาตรฐานสำหรับปุ่ม ซึ่งช่วยให้ผู้ใช้จดจำและใช้การกำหนดเส้นทางได้เมื่อพร้อมใช้งาน โดยปกติแล้ว ปุ่มเส้นทางสื่อจะอยู่ทางด้านขวาของแถบการดำเนินการของแอป ดังที่แสดงในรูปที่ 2

รูปที่ 2 ปุ่มเส้นทางสื่อในแถบการดำเนินการ

เมื่อผู้ใช้กดปุ่มเส้นทางสื่อ เส้นทางสื่อที่ใช้ได้จะปรากฏในรายการดังที่แสดงในรูปที่ 3

รูปที่ 3 รายการเส้นทางสื่อที่พร้อมใช้งาน ซึ่งจะแสดงหลังจากกดปุ่มเส้นทางสื่อ

ทำตามขั้นตอนต่อไปนี้เพื่อสร้างปุ่มเส้นทางสื่อ

  1. ใช้ AppCompatActivity
  2. กำหนดรายการเมนูปุ่มเส้นทางสื่อ
  3. สร้าง MediaRouteSelector
  4. เพิ่มปุ่มเส้นทางสื่อลงในแถบการดำเนินการ
  5. สร้างและจัดการเมธอด MediaRouter.Callback ในวงจรของกิจกรรม

ส่วนนี้จะอธิบาย 4 ขั้นตอนแรก ส่วนถัดไปจะอธิบายเมธอด Callback

ใช้ AppCompatActivity

เมื่อใช้เฟรมเวิร์กเราเตอร์สื่อในกิจกรรม คุณควรขยายกิจกรรมจาก AppCompatActivity และนำเข้าแพ็กเกจ androidx.appcompat.app คุณต้องเพิ่มไลบรารีสนับสนุน androidx.appcompat:appcompat และ androidx.mediarouter:mediarouter ลงในโปรเจ็กต์การพัฒนาแอป ดูข้อมูลเพิ่มเติมเกี่ยวกับการเพิ่มไลบรารีสนับสนุนลงในโปรเจ็กต์ได้ที่เริ่มต้นใช้งาน Android Jetpack

ข้อควรระวัง: อย่าลืมใช้การติดตั้งใช้งาน androidx ของเฟรมเวิร์ก Media Router อย่าใช้แพ็กเกจ android.media เวอร์ชันเก่า

สร้างไฟล์ XML ที่กำหนดรายการเมนูสำหรับปุ่มเส้นทางสื่อ การดำเนินการของรายการควรเป็นคลาส MediaRouteActionProvider ตัวอย่างไฟล์มีดังนี้

<menu xmlns:android="http://schemas.android.com/apk/res/android"
      xmlns:app="http://schemas.android.com/apk/res-auto"
      >

    <item android:id="@+id/media_route_menu_item"
        android:title="@string/media_route_menu_title"
        app:actionProviderClass="androidx.mediarouter.app.MediaRouteActionProvider"
        app:showAsAction="always"
    />
</menu>

สร้าง MediaRouteSelector

เส้นทางที่ปรากฏในเมนูปุ่มเส้นทางสื่อจะกำหนดโดย MediaRouteSelector ขยายกิจกรรมจาก AppCompatActivity และสร้างตัวเลือกเมื่อสร้างกิจกรรมโดยเรียก MediaRouteSelector.Builder จากเมธอด onCreate() ดังที่แสดงในตัวอย่างโค้ดต่อไปนี้ โปรดทราบว่าระบบจะบันทึกตัวเลือกไว้ในตัวแปรคลาส และระบุประเภทเส้นทางที่อนุญาตโดยการเพิ่มออบเจ็กต์ MediaControlIntent ดังนี้

class MediaRouterPlaybackActivity : AppCompatActivity() {

    private var mSelector: MediaRouteSelector? = null

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Create a route selector for the type of routes your app supports.
        mSelector = MediaRouteSelector.Builder()
            // These are the framework-supported intents.
            .addControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)
            .build()
    }
}

สำหรับแอปพลิเคชันส่วนใหญ่ ประเภทเส้นทางเดียวที่จำเป็นคือ CATEGORY_REMOTE_PLAYBACK เส้นทางประเภทนี้จะถือว่าอุปกรณ์ที่เรียกใช้แอปเป็นรีโมตคอนโทรล อุปกรณ์รับสัญญาณที่เชื่อมต่อจะจัดการการดึงข้อมูลเนื้อหา การถอดรหัส และการเล่นทั้งหมด นี่คือวิธีการทำงานของแอปที่รองรับ Google Cast เช่น Chromecast

ผู้ผลิตบางรายรองรับตัวเลือกการกำหนดเส้นทางพิเศษที่เรียกว่า "เอาต์พุตรอง" ด้วยการกำหนดเส้นทางนี้ แอปสื่อจะดึงข้อมูล แสดงผล และสตรีมวิดีโอหรือเพลงไปยังหน้าจอและ/หรือลำโพงบนอุปกรณ์รับสัญญาณระยะไกลที่เลือกโดยตรง ใช้เอาต์พุตรองเพื่อส่งเนื้อหาไปยังระบบเพลงหรือจอแสดงผลวิดีโอที่เปิดใช้ระบบไร้สาย หากต้องการเปิดใช้การค้นพบและเลือกอุปกรณ์เหล่านี้ คุณต้องเพิ่มหมวดหมู่การควบคุม CATEGORY_LIVE_AUDIO หรือ CATEGORY_LIVE_VIDEO ลงใน MediaRouteSelector นอกจากนี้ คุณยังต้องสร้างและจัดการกล่องโต้ตอบ Presentation ของคุณเองด้วย

เพิ่มปุ่มเส้นทางสื่อลงในแถบการดำเนินการ

เมื่อกำหนดเมนูเส้นทางสื่อและ MediaRouteSelector แล้ว คุณจะเพิ่มปุ่มเส้นทางสื่อลงในกิจกรรมได้ ลบล้างเมธอด onCreateOptionsMenu() สำหรับแต่ละกิจกรรมเพื่อเพิ่มเมนูตัวเลือก

override fun onCreateOptionsMenu(menu: Menu): Boolean {
    super.onCreateOptionsMenu(menu)

    // Inflate the menu and configure the media router action provider.
    menuInflater.inflate(R.menu.sample_media_router_menu, menu)

    // Attach the MediaRouteSelector to the menu item.
    val mediaRouteMenuItem = menu.findItem(R.id.media_route_menu_item)
    val mediaRouteActionProvider =
        MenuItemCompat.getActionProvider(mediaRouteMenuItem) as MediaRouteActionProvider

    // Attach the MediaRouteSelector that you built in onCreate().
    selector?.also(mediaRouteActionProvider::setRouteSelector)

    // Return true to show the menu.
    return true
}

ดูข้อมูลเพิ่มเติมเกี่ยวกับการใช้แถบการดำเนินการในแอปได้ที่คู่มือนักพัฒนาซอฟต์แวร์เรื่องแถบการดำเนินการ

นอกจากนี้ คุณยังเพิ่มปุ่มเส้นทางสื่อเป็น MediaRouteButton ในมุมมองใดก็ได้ คุณต้องแนบ MediaRouteSelector กับปุ่มโดยใช้เมธอด setRouteSelector() ดูรายการตรวจสอบการออกแบบ Google Cast เพื่อดูหลักเกณฑ์ในการรวมปุ่มเส้นทางสื่อไว้ในแอปพลิเคชัน

Callback ของ MediaRouter

แอปทั้งหมดที่ทำงานในอุปกรณ์เดียวกันจะแชร์อินสแตนซ์ MediaRouter เดียวและเส้นทางของอินสแตนซ์นั้น (กรองตามแอปโดย MediaRouteSelector ของแอป) แต่ละกิจกรรมจะสื่อสารกับ MediaRouter โดยใช้การใช้งานเมธอด MediaRouter.Callback ของตนเอง MediaRouter จะเรียกใช้เมธอด Callback ทุกครั้งที่ผู้ใช้เลือก เปลี่ยน หรือยกเลิกการเชื่อมต่อเส้นทาง

มีเมธอดหลายรายการใน Callback ที่คุณสามารถลบล้างเพื่อรับข้อมูลเกี่ยวกับเหตุการณ์การกำหนดเส้นทาง อย่างน้อยที่สุด การติดตั้งใช้งานคลาส MediaRouter.Callback ควรลบล้าง onRouteSelected() และ onRouteUnselected()

เนื่องจาก MediaRouter เป็นทรัพยากรที่ใช้ร่วมกัน แอปของคุณจึงต้องจัดการ Callback ของ MediaRouter เพื่อตอบสนองต่อ Callback ของวงจรกิจกรรมตามปกติ ดังนี้

  • เมื่อสร้างกิจกรรม (onCreate(Bundle)) ให้จับตัวชี้ไปยัง MediaRouter และเก็บไว้ตลอดอายุการใช้งานของแอป
  • แนบ Callback กับ MediaRouter เมื่อกิจกรรมปรากฏขึ้น (onStart()) และยกเลิกการแนบเมื่อกิจกรรมถูกซ่อน (onStop())

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีสร้างและบันทึกออบเจ็กต์ Callback, วิธีรับอินสแตนซ์ของ MediaRouter และวิธีจัดการ Callback โปรดทราบว่ามีการใช้แฟล็ก CALLBACK_FLAG_REQUEST_DISCOVERY เมื่อแนบ Callback ใน onStart() ซึ่งจะช่วยให้ MediaRouteSelector รีเฟรชรายการเส้นทางที่ใช้ได้ของปุ่มเส้นทางสื่อ

class MediaRouterPlaybackActivity : AppCompatActivity() {

    private var mediaRouter: MediaRouter? = null
    private var mSelector: MediaRouteSelector? = null

    // Variables to hold the currently selected route and its playback client.
    private var mRoute: MediaRouter.RouteInfo? = null
    private var remotePlaybackClient: RemotePlaybackClient? = null

    // Define the Callback object and its methods, save the object in a class variable.
    private val mediaRouterCallback = object : MediaRouter.Callback() {

        override fun onRouteSelected(
            router: MediaRouter,
            route: MediaRouter.RouteInfo,
            reason: Int
        ) {
            Log.d(TAG, "onRouteSelected: route=$route")
            if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {
                // Stop local playback (if necessary).
                // ...

                // Save the new route.
                mRoute = route

                // Attach a new playback client.
                remotePlaybackClient =
                    RemotePlaybackClient(this@MediaRouterPlaybackActivity, route)

                // Start remote playback (if necessary).
                // ...
            }
        }

        override fun onRouteUnselected(
            router: MediaRouter,
            route: MediaRouter.RouteInfo,
            reason: Int
        ) {
            Log.d(TAG, "onRouteUnselected: route=$route")
            if (route.supportsControlCategory(MediaControlIntent.CATEGORY_REMOTE_PLAYBACK)) {

                // Changed route: tear down previous client.
                mRoute?.also {
                    remotePlaybackClient?.release()
                    remotePlaybackClient = null
                }

                // Save the new route.
                mRoute = route

                when {
                    reason != MediaRouter.UNSELECT_REASON_ROUTE_CHANGED -> {
                        // Resume local playback (if necessary).
                        // ...
                    }
                }
            }
        }
    }

    // Retain a pointer to the MediaRouter.
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Get the media router service.
        mediaRouter = MediaRouter.getInstance(this)
        // ...
    }

    // Use this callback to run your MediaRouteSelector to generate the
    // list of available media routes.
    override fun onStart() {
        mSelector?.also { selector ->
            mediaRouter?.addCallback(
                selector, mediaRouterCallback,
                MediaRouter.CALLBACK_FLAG_REQUEST_DISCOVERY
            )
        }
        super.onStart()
    }

    // Remove the selector on stop to tell the media router that it no longer
    // needs to discover routes for your app.
    override fun onStop() {
        mediaRouter?.removeCallback(mediaRouterCallback)
        super.onStop()
    }
    // ...
}

เฟรมเวิร์ก Media Router ยังมีคลาส MediaRouteDiscoveryFragment ซึ่งจะดูแลการเพิ่มและนำ Callback สำหรับกิจกรรมออกด้วย

หมายเหตุ: หากคุณกำลังเขียนแอปเล่นเพลงและต้องการให้แอปเล่นเพลงขณะทำงานในเบื้องหลัง คุณต้องสร้าง Service สำหรับการเล่นและเรียกใช้เฟรมเวิร์กเราเตอร์สื่อจาก Lifecycle Callback ของบริการ

การควบคุมเส้นทางการเล่นระยะไกล

เมื่อคุณเลือกเส้นทางการเล่นระยะไกล แอปจะทำหน้าที่เป็นรีโมตคอนโทรล อุปกรณ์ที่ปลายทางของเส้นทางจะจัดการการดึงข้อมูล การถอดรหัส และฟังก์ชันการเล่นเนื้อหาทั้งหมด ตัวควบคุมใน UI ของแอปจะสื่อสารกับอุปกรณ์รับสัญญาณโดยใช้ออบเจ็กต์ RemotePlaybackClient

คลาส RemotePlaybackClient มีเมธอดเพิ่มเติมสำหรับการจัดการการเล่นเนื้อหา ต่อไปนี้คือวิธีการเล่นที่สำคัญบางส่วนจากคลาส RemotePlaybackClient

  • play() — เล่นไฟล์สื่อที่เฉพาะเจาะจงซึ่งระบุโดย Uri
  • pause() — หยุดแทร็กสื่อที่กำลังเล่นอยู่ชั่วคราว
  • resume() — เล่นแทร็กปัจจุบันต่อหลังจากคำสั่งหยุดชั่วคราว
  • seek() — ย้ายไปยังตำแหน่งที่เจาะจงในแทร็กปัจจุบัน
  • release() — ยกเลิกการเชื่อมต่อจากแอปไปยังอุปกรณ์การเล่นระยะไกล

คุณสามารถใช้วิธีการเหล่านี้เพื่อแนบการดำเนินการกับตัวควบคุมการเล่นที่มีให้ในแอป วิธีการเหล่านี้ส่วนใหญ่ยังช่วยให้คุณรวมออบเจ็กต์ Callback เพื่อให้คุณตรวจสอบความคืบหน้าของงานการเล่นหรือคำขอควบคุมได้ด้วย

คลาส RemotePlaybackClient ยังรองรับการจัดคิวรายการสื่อหลายรายการสำหรับการเล่นและการจัดการคิวสื่อด้วย

โค้ดตัวอย่าง

ตัวอย่าง Android BasicMediaRouter และ MediaRouter แสดงการใช้ MediaRouter API เพิ่มเติม