סקירה כללית של MediaRouter

כדי להשתמש ב-MediaRouter באפליקציה, צריך לקבל מופע של האובייקט MediaRouter ולצרף אובייקט MediaRouter.Callback כדי להאזין לאירועי ניתוב. תוכן שנשלח דרך נתיב מדיה עובר דרך MediaRouteProvider שמשויך לנתיב (חוץ מכמה מקרים מיוחדים, כמו מכשיר להצגת מידע ב-Bluetooth). באיור 1 מוצגת סקירה כללית של המחלקות שמשמשות לניתוב תוכן בין מכשירים.

איור 1. סקירה כללית של המחלקות העיקריות של נתבי מדיה שמשמשות אפליקציות.

הערה: אם אתם רוצים שהאפליקציה תתמוך במכשירי Google Cast, אתם צריכים להשתמש ב-Cast SDK ולפתח את האפליקציה כ-Cast sender. צריך לפעול לפי ההוראות במסמכי התיעוד של Cast במקום להשתמש ישירות ב-MediaRouter framework.

כפתור הניתוב של המדיה

באפליקציות ל-Android צריך להשתמש בלחצן של נתיב מדיה כדי לשלוט בניתוב המדיה. ה-framework של MediaRouter מספק ממשק סטנדרטי ללחצן, שעוזר למשתמשים לזהות את הניתוב ולהשתמש בו כשהוא זמין. הלחצן "מסלול מדיה" ממוקם בדרך כלל בצד שמאל של סרגל הפעולות של האפליקציה, כמו שמוצג באיור 2.

איור 2. כפתור להעברת מדיה בסרגל הפעולות.

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

איור 3. רשימה של מסלולי מדיה זמינים, שמוצגת אחרי שלוחצים על כפתור מסלול המדיה.

כדי ליצור לחצן לניתוב מדיה:

  1. שימוש ב-AppCompatActivity
  2. הגדרת הפריט בתפריט של לחצן ניתוב המדיה
  3. יצירת MediaRouteSelector
  4. הוספת הלחצן "מסלול מדיה" לסרגל הפעולות
  5. יצירה וניהול של השיטות MediaRouter.Callback במחזור החיים של הפעילות

בקטע הזה מתוארים ארבעת השלבים הראשונים. בקטע הבא מתוארות שיטות קריאה חוזרת.

שימוש ב-AppCompatActivity

כשמשתמשים ב-framework של נתב המדיה בפעילות, צריך להרחיב את הפעילות מ-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 ללחצן באמצעות ה-method‏ setRouteSelector(). ברשימת המשימות לעיצוב ב-Google Cast מפורטות הנחיות לשילוב לחצן נתיב המדיה באפליקציה.

קריאות חוזרות (callbacks) של MediaRouter

כל האפליקציות שפועלות באותו מכשיר משתפות מופע אחד של MediaRouter והמסלולים שלו (מסוננים לכל אפליקציה לפי MediaRouteSelector של האפליקציה). כל פעילות מתקשרת עם MediaRouter באמצעות הטמעה משלה של שיטות MediaRouter.Callback. ‫MediaRouter קורא לשיטות הקריאה החוזרת בכל פעם שהמשתמש בוחר, משנה או מנתק מסלול.

יש כמה שיטות בקריאה החוזרת (callback) שאפשר לשנות כדי לקבל מידע על אירועי ניתוב. לכל הפחות, ההטמעה של המחלקה MediaRouter.Callback צריכה לשנות את onRouteSelected() ו-onRouteUnselected().

‫MediaRouter הוא משאב משותף, ולכן האפליקציה צריכה לנהל את הקריאות החוזרות (callbacks) של MediaRouter בתגובה לקריאות החוזרות במחזור החיים של הפעילות:

  • כשהפעילות נוצרת (onCreate(Bundle)), צריך לתפוס מצביע אל MediaRouter ולהחזיק אותו למשך כל חיי האפליקציה.
  • מצרפים קריאות חוזרות (callbacks) ל-MediaRouter כשהפעילות הופכת לגלויה (onStart()), ומנתקים אותן כשהיא מוסתרת (onStop()).

בדוגמת הקוד הבאה מוסבר איך ליצור ולשמור את אובייקט הקריאה החוזרת, איך לקבל מופע של MediaRouter ואיך לנהל קריאות חוזרות. שימו לב לשימוש בדגל 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()
    }
    // ...
}

ה-framework של Media Router מספק גם את המחלקה MediaRouteDiscoveryFragment, שמוסיפה ומסירה את הקריאה החוזרת (callback) של פעילות.

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

שליטה בנתיב הפעלה מרחוק

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

הכיתה RemotePlaybackClient מספקת שיטות נוספות לניהול הפעלת התוכן. הנה כמה מהשיטות העיקריות להפעלה מהמחלקה RemotePlaybackClient:

  • ‫play() – הפעלה של קובץ מדיה ספציפי, שצוין באמצעות Uri.
  • pause() — השהיית הטראק שמופעל כרגע.
  • ‫resume() – המשך ההפעלה של הטראק הנוכחי אחרי פקודת השהיה.
  • seek() — מעבר למיקום ספציפי בטראק הנוכחי.
  • ‫release() – ניתוק החיבור בין האפליקציה למכשיר ההפעלה מרחוק.

אתם יכולים להשתמש בשיטות האלה כדי לצרף פעולות לרכיבי ה-UI להפעלה שאתם מספקים באפליקציה. רוב השיטות האלה גם מאפשרות לכם לכלול אובייקט קריאה חוזרת (callback) כדי שתוכלו לעקוב אחרי ההתקדמות של משימת ההפעלה או בקשת הבקרה.

במחלקה RemotePlaybackClient אפשר גם להוסיף לתור כמה קובצי מדיה להפעלה ולנהל את תור המדיה.

קוד לדוגמה

הדוגמאות Android BasicMediaRouter ו-MediaRouter ממחישות עוד יותר את השימוש ב-MediaRouter API.