نظرة عامة على MediaRouter

لاستخدام إطار عمل MediaRouter في تطبيقك، يجب الحصول على مثيل لكائن MediaRouter وإرفاق كائن MediaRouter.Callback للاستماع إلى أحداث التوجيه. يمر المحتوى المُرسَل عبر مسار وسائط من خلال MediaRouteProvider المرتبط بالمسار (باستثناء بعض الحالات الخاصة، مثل جهاز إخراج يتضمّن بلوتوث). يقدّم الشكل 1 نظرة عامة على الفئات المستخدَمة لتوجيه المحتوى بين الأجهزة.

الشكل 1: نظرة عامة على فئات موجّه الوسائط الرئيسية التي تستخدمها التطبيقات

ملاحظة: إذا أردت أن يكون تطبيقك متوافقًا مع أجهزة Google Cast، عليك استخدام حزمة تطوير البرامج (SDK) لمنصّة Cast وإنشاء تطبيقك كجهاز مُرسِل للبث. اتّبِع التوجيهات الواردة في مستندات Cast بدلاً من استخدام إطار عمل MediaRouter مباشرةً.

زر مسار الوسائط

يجب أن تستخدم تطبيقات Android زر مسار الوسائط للتحكّم في توجيه الوسائط. يوفّر إطار عمل MediaRouter واجهة عادية للزر، ما يساعد المستخدمين في التعرّف على التوجيه واستخدامه عندما يكون متاحًا. يتم عادةً وضع زر مسار الوسائط على الجانب الأيسر من شريط الإجراءات في تطبيقك، كما هو موضّح في الشكل 2.

الشكل 2: زر مسار الوسائط في شريط الإجراءات

عندما يضغط المستخدم على زر مسار الوسائط، تظهر مسارات الوسائط المتاحة في قائمة كما هو موضّح في الشكل 3.

الشكل 3: قائمة بمسارات الوسائط المتاحة، تظهر بعد الضغط على زر مسار الوسائط.

اتّبِع الخطوات التالية لإنشاء زر مسار الوسائط:

  1. استخدام AppCompatActivity
  2. تحديد عنصر قائمة زر مسار الوسائط
  3. إنشاء MediaRouteSelector
  4. إضافة زر مسار الوسائط إلى شريط الإجراءات
  5. إنشاء طرق MediaRouter.Callback وإدارتها في مراحل نشاط نشاطك

يصف هذا القسم الخطوات الأربع الأولى. يصف القسم التالي طرق ردّ الاتصال.

استخدام AppCompatActivity

عند استخدام إطار عمل موجّه الوسائط في نشاط، يجب تمديد النشاط من AppCompatActivity واستيراد الحزمة androidx.appcompat.app. يجب إضافة مكتبات الدعم androidx.appcompat:appcompat وandroidx.mediarouter:mediarouter إلى مشروع تطوير تطبيقك. لمزيد من المعلومات حول إضافة مكتبات الدعم إلى مشروعك، يُرجى الاطّلاع على البدء في استخدام Android Jetpack.

تنبيه: تأكَّد من استخدام تنفيذ androidx لإطار عمل جهاز توجيه الوسائط. لا تستخدِم حزمة 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 للحصول على إرشادات حول دمج زر مسار الوسائط في تطبيقك.

عمليات معاودة الاتصال في MediaRouter

تتشارك جميع التطبيقات التي تعمل على الجهاز نفسه في مثيل MediaRouter واحد ومساراته (تتم فلترتها لكل تطبيق من خلال MediaRouteSelector الخاص بالتطبيق). يتواصل كل نشاط مع MediaRouter باستخدام طريقة التنفيذ الخاصة به لأساليب MediaRouter.Callback. يستدعي MediaRouter طرق رد الاتصال عندما يختار المستخدم مسارًا أو يغيّره أو يقطع اتصاله.

هناك عدة طرق في ردّ الاتصال يمكنك إلغاؤها لتلقّي معلومات عن أحداث التوجيه. كحد أدنى، يجب أن يتجاوز تنفيذ فئة MediaRouter.Callback onRouteSelected() و onRouteUnselected().

بما أنّ MediaRouter هو مورد مشترك، يحتاج تطبيقك إلى إدارة عمليات الاستدعاء في MediaRouter استجابةً لعمليات الاستدعاء في إحدى مراحل النشاط المعتادة:

  • عند إنشاء النشاط (onCreate(Bundle))، يمكنك الحصول على مؤشر إلى MediaRouter والاحتفاظ به طوال مدة استخدام التطبيق.
  • إرفاق عمليات الاستدعاء بـ MediaRouter عندما يصبح النشاط مرئيًا (onStart())، وفصلها عندما يكون مخفيًا (onStop()).

توضّح عيّنة التعليمات البرمجية التالية كيفية إنشاء عنصر ردّ الاتصال وحفظه، وكيفية الحصول على مثيل من MediaRouter، وكيفية إدارة عمليات ردّ الاتصال. يُرجى ملاحظة استخدام العلامة CALLBACK_FLAG_REQUEST_DISCOVERY عند إرفاق عمليات الاستدعاء في 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()
    }
    // ...
}

يوفّر إطار عمل موجّه الوسائط أيضًا فئة MediaRouteDiscoveryFragment التي تتولّى إضافة عمليات الاستدعاء وإزالتها لأي نشاط.

ملاحظة: إذا كنت تكتب تطبيقًا لتشغيل الموسيقى وتريد أن يشغّل التطبيق الموسيقى أثناء تشغيله في الخلفية، عليك إنشاء Service للتشغيل واستدعاء إطار عمل موجّه الوسائط من عمليات الاستدعاء في إحدى مراحل النشاط الخاصة بالخدمة.

التحكّم في مسار تشغيل عن بُعد

عند اختيار مسار تشغيل عن بُعد، يعمل تطبيقك كوحدة تحكّم عن بُعد. يتولّى الجهاز في الطرف الآخر من المسار جميع وظائف استرداد بيانات المحتوى وفك ترميزها وتشغيلها. تتواصل عناصر التحكّم في واجهة مستخدم تطبيقك مع جهاز الاستقبال باستخدام عنصر RemotePlaybackClient.

توفّر فئة RemotePlaybackClient طرقًا إضافية لإدارة تشغيل المحتوى. في ما يلي بعض طرق التشغيل الرئيسية من فئة RemotePlaybackClient:

  • ‫play(): لتشغيل ملف وسائط محدّد، يتم تحديده من خلال Uri
  • ‫pause(): لإيقاف المقطع الصوتي الذي يتم تشغيله حاليًا مؤقتًا
  • resume() — لمواصلة تشغيل المقطع الصوتي الحالي بعد أمر الإيقاف المؤقت
  • ‫seek(): للانتقال إلى موضع محدّد في المقطع الصوتي الحالي
  • ‫release(): لإلغاء الاتصال بين تطبيقك وجهاز التشغيل عن بُعد

يمكنك استخدام هذه الطرق لإرفاق الإجراءات بعناصر التحكّم في التشغيل التي توفّرها في تطبيقك. تتيح لك معظم هذه الطرق أيضًا تضمين عنصر استدعاء حتى تتمكّن من مراقبة مستوى تقدّم مهمة التشغيل أو طلب التحكّم.

تتيح فئة RemotePlaybackClient أيضًا وضع ملفات وسائط متعددة في قائمة انتظار لتشغيلها وإدارة قائمة انتظار الوسائط.

نموذج التعليمات البرمجية

يظهر استخدام MediaRouter API بشكل أكبر في نموذجَي Android BasicMediaRouter وMediaRouter.