تنفيذ التحكم اللاسلكي

يستند تنفيذ التحكّم في الراديو إلى MediaSession و MediaBrowse، ما يتيح لتطبيقات الوسائط ومساعدات الصوت التحكّم في الراديو. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إنشاء تطبيقات وسائط للسيارات على developer.android.com.

يتم توفير تنفيذ شجرة تصفُّح الوسائط في مكتبة car-broadcastradio-support في packages/apps/Car/libs. تحتوي هذه المكتبة أيضًا على إضافات لبرنامج Selector من أجل التحويل من عنوان URL والعكس. ننصحك باستخدام هذه المكتبة لإنشاء شجرة التصفّح المرتبطة عند تنفيذ تطبيقات الراديو.

أداة تبديل مصادر الوسائط

لتوفير انتقال سلس بين التطبيق المخصّص للراديو والتطبيقات الأخرى المعروضة في الوسائط، تحتوي مكتبة car-media-common على فئات يجب دمجها في تطبيق الراديو. يمكن تضمين MediaAppSelectorWidget في ملف XML الخاص بتطبيق الراديو (الرمز والقائمة المنسدلة المستخدَمة في الوسائط المرجعية وتطبيقات الراديو):

<com.android.car.media.common.MediaAppSelectorWidget
    android:id="@+id/app_switch_container"
    android:layout_width="@dimen/app_switch_widget_width"
    android:layout_height="wrap_content"
    android:background="@drawable/app_item_background"
    android:gravity="center" />

يشغِّل التطبيق المصغّر هذا AppSelectionFragment الذي يعرض قائمة بمصادر الوسائط التي يمكن التبديل إليها. إذا أردت استخدام واجهة مستخدم مختلفة عن الواجهة المقدَّمة، يمكنك إنشاء تطبيق مصغّر مخصّص لتشغيل AppSelectionFragment عندما يجب عرض التبديل.

AppSelectionFragment newFragment = AppSelectionFragment.create(widget,
            packageName, fullScreen);
    newFragment.show(mActivity.getSupportFragmentManager(), null);

يتوفّر نموذج لتنفيذ تطبيق الراديو المرجعي، والذي يمكن العثور عليه في packages/apps/Car/Radio.

مواصفات التحكّم التفصيلية

توفّر واجهة MediaSession (من خلال MediaSession.Callback) آليات التحكّم في برنامج الراديو الذي يتم تشغيله حاليًا:

• onPlay، onStop. كتم صوت تشغيل الراديو أو إزالته
• onPause. الإيقاف المؤقت مع تغيير السرعة الزمنية (إذا كان ذلك متاحًا)
• onPlayFromMediaId. تشغيل أي محتوى من مجلد بمستوى أعلى على سبيل المثال، "تشغيل راديو FM" أو "تشغيل الراديو".
• onPlayFromUri. تشغيل تردد محدّد على سبيل المثال، "تشغيل 88.5 FM".
• onSkipToNext، onSkipToPrevious. انتقِل إلى محطة يليها أو محطة سابقة.
• onSetRating. إضافة تطبيقات إلى "التطبيقات المفضّلة" أو إزالتها منها

يعرِض MediaBrowser MediaItem قابل للضبط على مستوى ثلاثة أنواع من الأدلة ذات المستوى الأعلى:

• (اختياري) البرامج (المحطات). يُستخدَم هذا الوضع عادةً في أجهزة الراديو المزودة بموجّهَين للإشارة إلى جميع محطات الراديو القابلة للضبط في الموقع الجغرافي للمستخدم.
• الأماكن المفضّلة: برامج إذاعية تمت إضافتها إلى قائمة "المفضلة"، قد يكون بعضها غير متاح (خارج نطاق الاستقبال).
• قنوات النطاق جميع القنوات التي يمكن استخدامها في المنطقة الحالية (87.9، 88.1، 88.3، 88.5، 88.7، 88.9، 89.1 وما إلى ذلك) لكلّ مجموعة موسيقية دليل من المستوى الأعلى منفصل.

الشكل 2. بنية شجرة MediaBrowserService

كل عنصر في كل من هذه المجلدات (AM/FM/Programs) هو عنصر MediaItem يحتوي على عنوان URL يمكن استخدامه مع MediaSession لضبط الإعدادات. كل مجلد على المستوى الأعلى (AM/FM/Programs) هو عنصر وسائط يتضمّن معرّف وسائط يمكن استخدامه مع MediaSession لبدء التشغيل، ويعود ذلك إلى تقدير المصنّع الأصلي للجهاز. على سبيل المثال، "تشغيل راديو FM" و"تشغيل راديو AM" و"تشغيل راديو" هي طلبات بحث غير محدّدة للراديو تستخدم ‎mediaId لإرسالها إلى تطبيق الراديو الخاص بصانع الجهاز الأصلي. ويعود الأمر إلى تطبيق الراديو لتحديد المحتوى الذي سيتم تشغيله من الطلب العام وmediaId.

MediaSession

بما أنّه لا يمكن إيقاف البث مؤقتًا، فإنّ إجراءات التشغيل والإيقاف المؤقت والإيقاف لا تنطبق دائمًا على المحتوى الصوتي. في الراديو، يكون الإجراء "إيقاف" مرتبطًا بكتم صوت البث بينما يكون الإجراء "تشغيل" مرتبطًا بإزالة كتم الصوت.

توفّر بعض أجهزة ضبط البثّ الإذاعي (أو التطبيقات) إمكانية إيقاف البثّ مؤقتًا عن طريق تخزين المحتوى مؤقتًا ثم إعادة تشغيله لاحقًا. في هذه الحالات، استخدِم onPause.

يهدف التشغيل من إجراءات mediaId وURI إلى ضبط محطة يتم جلبها من واجهة MediaBrowser. mediaId هي سلسلة عشوائية يوفّرها تطبيق الراديو لفرض قيمة فريدة (كي يشير معرّف معيّن إلى عنصر واحد فقط) وثابتة (كي يكون للعنصر المعيّن المعرّف نفسه خلال الجلسة بأكملها) لتحديد محطة معيّنة. سيكون معرّف الموارد المنتظم (URI) من مخطّط محدّد جيدًا. بعبارة أخرى، هو شكل من أشكال ProgramSelector تم تحويله إلى عنوان URL. على الرغم من أنّ ذلك يحافظ على سمة التفرد، ليس من الضروري أن يكون ثابتًا، على الرغم من أنّه يمكن أن يتغيّر عندما تنتقل المحطة إلى تردد مختلف.

لا يتم استخدام onPlayFromSearch عن قصد. تقع على عاتق العميل (التطبيق المصاحب) مسؤولية اختيار نتيجة بحث من شجرة MediaBrowser. سيؤدي نقل هذه المسؤولية إلى تطبيق الراديو إلى زيادة التعقيد، وسيتطلب عقودًا رسمية حول كيفية ظهور طلبات البحث عن السلاسل، وسيؤدي إلى تجربة مستخدم غير متكافئة على منصات الأجهزة المختلفة.

ملاحظة: لا يحتوي تطبيق الراديو على معلومات إضافية قد تكون مفيدة للبحث عن اسم محطة غير معروض للعميل من خلال واجهة MediaBrowser.

يعتمد التخطّي إلى المحطة التالية أو السابقة على السياق الحالي:

• عند ضبط تطبيق على محطة من قائمة "المفضلة"، يمكن للتطبيق الانتقال إلى المحطة التالية من قائمة "المفضلة".
• قد يؤدي الاستماع إلى محطة من قائمة البرامج إلى ضبط الإعدادات على المحطة التالية المتاحة، والتي يتم ترتيبها حسب رقم القناة.
• قد يؤدي الاستماع إلى قناة عشوائية إلى ضبط القناة الفعلية التالية، حتى في حال عدم توفّر إشارة بث.

يعالج تطبيق الراديو هذه الإجراءات.

معالجة الأخطاء

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

يجب أن يعالج تطبيق الراديو هذه الإجراءات وتنفيذها أو ضبط حالة خطأ. إذا لم يكن تنفيذ الأمر Play فوريًا، يجب تغيير حالة التشغيل إلى STATE_CONNECTING (في حال ضبط القنوات مباشرةً) أو STATE_SKIPPING_TO_PREVIOUS أو NEXT أثناء تنفيذ الأمر.

على العميل مشاهدة PlaybackState والتأكّد من أنّ الجلسة غيّرت البرنامج الحالي إلى البرنامج المطلوب أو تم إدخاله في حالة الخطأ. يجب ألا تتجاوز مدة STATE_CONNECTING 30 ثانية. ومع ذلك، من المفترض أن يكون ضبط التردد مباشرةً على تردد AM/FM معيّن أسرع بكثير.

إضافة العناصر المفضّلة وإزالتها

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

على عكس الإعدادات المُسبقة القديمة، يفترض هذا النموذج قائمة "المفضّلة" غير المرتبة وغير المحدودة، عندما تم تخصيص كل مفضّل محفوظ لمكان رقمي (عادةً من 1 إلى 6). ونتيجةً لذلك، ستكون الأنظمة المستندة إلى الإعدادات المُسبَقة غير متوافقة مع تشغيل onSetRating.

يتمثل الحدّ الأقصى لواجهة برمجة التطبيقات MediaSession API في أنّه لا يمكن إضافة أو إزالة سوى المحطة التي يتمّ ضبطها حاليًا. على سبيل المثال، يجب اختيار العناصر أولاً قبل إزالتها. هذا قيد على برنامج MediaBrowser فقط، مثل تطبيق مصاحب. ولا يتم فرض قيود مماثلة على تطبيق الراديو. هذا الجزء اختياري عندما لا يتيح التطبيق ميزة "العناصر المفضّلة".

MediaBrowser

للتعبير عن الترددات أو أسماء القنوات المادية (عند ضبط التردد على قناة عشوائية مناسبة لتكنولوجيا راديو معيّنة) الصالحة لمنطقة معيّنة، يتم إدراج جميع القنوات الصالحة (الترددات) لكل نطاق. في منطقة الولايات المتحدة، يشمل ذلك 101 قناة FM في النطاق من 87.8 إلى 108.0 ميغاهرتز (باستخدام فاصل 0.2 ميغاهرتز) و117 قناة AM في النطاق من 530 إلى 1700 كيلوهرتز (باستخدام فاصل 10 كيلوهرتز). وبما أنّ الراديو بدقة عالية يستخدم مساحة القناة نفسها، لا يتم عرضه بشكل منفصل.

قائمة البرامج الإذاعية المتاحة حاليًا ليست مُفصَّلة، وبالتالي لا تسمح بتطبيق تصاميم عرض معيّنة، مثل التجميع حسب مجموعة البث الصوتي المباشر (DAB).

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

لتحديد المجلدات على المستوى الأعلى، يتم تطبيق الآلية نفسها المستخدَمة في البلوتوث. وهذا يعني أنّ حِزمة Extras الخاصة بالعنصر MediaDescription تحتوي على حقل خاص بالمعدّل، تمامًا مثلما تفعل البلوتوث مع EXTRA_BT_FOLDER_TYPE. في ما يتعلّق بالإذاعة البثّية، يؤدّي ذلك إلى تحديد الحقول الجديدة التالية في واجهة برمجة التطبيقات العامة:

• EXTRA_BCRADIO_FOLDER_TYPE = "android.media.extra.EXTRA_BCRADIO_FOLDER_TYPE". إحدى القيم التالية:
  • BCRADIO_FOLDER_TYPE_PROGRAMS = 1. البرامج المتاحة حاليًا
  • BCRADIO_FOLDER_TYPE_FAVORITES = 2. الإعدادات المفضّلة
  • BCRADIO_FOLDER_TYPE_BAND = 3. جميع القنوات المادية لفرقة معيّنة

  ما مِن حاجة إلى تحديد أيّ حقول بيانات وصفية مخصّصة خاصة بالراديو، لأنّ كل البيانات ذات الصلة تتوافق مع مخطّط MediaBrowser.MediaItem الحالي:

  • اسم البرنامج (RDS PS، اسم خدمة DAB) MediaDescription.getTitle.
  • تردد FM: عنوان URL (راجِع ProgramSelector) أو MediaDescription.getTitle (إذا كان الإدخال في مجلد BROADCASTRADIO_FOLDER_TYPE_BAND).
  • المعرّفات الخاصة بالراديو (RDS PI وDAB SId) تم تحليل MediaDescription.getMediaUri إلى ProgramSelector.

  لا يلزم عادةً جلب تردد FM لإدخال في البرنامج الحالي أو قائمة "المفضلة" (لأنّه من المفترض أن يعمل العميل على معرّفات الوسائط). ومع ذلك، إذا ظهرت الحاجة إلى ذلك (على سبيل المثال، لأغراض العرض)، سيكون متوفّرًا في عنوان URL ويمكن تحليله إلى ProgramSelector. ومع ذلك، لا يُنصح باستخدام عنوان URL لاختيار العناصر ضمن الجلسة الحالية. للاطّلاع على التفاصيل، يُرجى مراجعة ProgramSelector.

  لتجنُّب المشاكل المتعلّقة بالأداء أو ببرنامج ربط البيانات، يجب أن توفّر خدمة MediaBrowser ميزة تقسيم الصفحات:

  • EXTRA_PAGE
  • EXTRA_PAGE_SIZE
  • مَعلمات إضافية لـ subscribe()

  ملاحظة: يتم تطبيق تقسيم الصفحات تلقائيًا في onLoadChildren() بدون معالجة الخيارات.

  قد تحتوي الإدخالات ذات الصلة من جميع أنواع القوائم (القنوات الأوّلية والبرامج التي تم العثور عليها والمفضّلة) على معرّفات mediaId مختلفة (يعود الأمر إلى تطبيق الراديو، وستكون مكتبة الدعم مختلفة). تختلف عناوين URL (بتنسيق ProgramSelector) بين القنوات والبرامج الأوّلية التي يتم العثور عليها في معظم الحالات (باستثناء FM بدون RDS)، ولكنّها تكون متطابقة في معظم الأحيان بين البرامج التي يتم العثور عليها والبرامج المفضّلة (باستثناء، على سبيل المثال، عند تعديل AF).

  إنّ توفُّر معرّفات mediaId مختلفة للعناصر من أنواع مختلفة من القوائم يجعل من المُمكن اتخاذ إجراءات مختلفة بشأنها. يمكنك التنقّل في قائمة "المفضّلة" أو قائمة "جميع البرامج" على onSkipToNext، استنادًا إلى مجلد MediaItem الذي تم اختياره مؤخرًا (راجِع MediaSession).

  إجراءات اللحن الخاص

  تتيح قائمة البرامج للمستخدمين ضبط التردد على محطة معيّنة، ولكن لا تسمح لهم بتقديم طلبات عامة مثل "ضبط التردد على FM"، ما قد يؤدي إلى ضبط التردد على محطة تم الاستماع إليها مؤخرًا على نطاق FM.

  لتمكين هذه الإجراءات، تم ضبط علامة FLAG_PLAYABLE في بعض الأدلة ذات المستوى الأعلى (بالإضافة إلى FLAG_BROWSABLE للمجلدات).

  الإجراء	نغمات تناسب	كيفية إصدار التذكرة
  تشغيل الراديو	أي قناة راديو	startService(ACTION_PLAY_BROADCASTRADIO) أو playFromMediaId(MediaBrowser.getRoot())
  Play FM	أي قناة FM	يمكنك التشغيل من mediaId نطاق FM.

  يحدد التطبيق البرنامج الذي يتم ضبطه، وعادةً ما يكون ذلك القناة التي تم ضبطها مؤخرًا من القائمة المحدّدة. لمعرفة التفاصيل حول ACTION_PLAY_BROADCASTRADIO، يُرجى الاطّلاع على النوايا العامة للتشغيل.

  اكتشاف الخدمات والربط بها

  يمكن أن يعثر PackageManager مباشرةً على MediaBrowserService التي تعرِض شجرة البث الإذاعي. لإجراء ذلك، يمكنك استدعاء resolveService باستخدام النية ACTION_PLAY_BROADCASTRADIO (راجِع النوايا العامة للتشغيل) ومربّع الاختيار MATCH_SYSTEM_ONLY. للعثور على جميع الخدمات التي توفّر خدمة الراديو (قد يكون هناك أكثر من خدمة واحدة، مثل AM/FM وخدمات الأقمار الصناعية المنفصلة)، استخدِم queryIntentServices.

  تعالج الخدمة التي تم حلّها أيضًا النية android.media.browse.MediaBrowserService bind. يتم التحقّق من ذلك من خلال GTS.

  للاتصال بخدمة MediaBrowserService المحدّدة، أنشئ مثيل MediaBrowser لمكوّن خدمة معيّن وconnect. بعد إنشاء الاتصال، يمكن الحصول على معرّف MediaSession من خلال getSessionToken.

  يمكن لتطبيق "راديو Google" حظر حِزم العملاء المسموح لها بالاتصال في تنفيذ onGetRoot لخدمتهم. من المفترض أن يسمح التطبيق لتطبيقات النظام بالاتصال بدون إضافة التطبيقات إلى القائمة البيضاء. لمعرفة التفاصيل حول القائمة المسموح بها، يُرجى الاطّلاع على مقالة قبول حزمة تطبيق "مساعد Google" وتوقيعه.

  إذا تم تثبيت تطبيق خاص بالمصدر (مثل تطبيق راديو) على جهاز لا يتيح استخدام هذا المصدر، سيظل التطبيق يعرّف نفسه على أنّه يعالج ACTION_PLAY_BROADCASTRADIO النية، ولكن لن تحتوي شجرة MediaBrowser على علامات خاصة بالراديو. وبالتالي، على العميل الذي يريد التحقّق مما إذا كان مصدر معيّن متوفّرًا على جهاز ما، تنفيذ ما يلي:

  1. التعرّف على خدمة الراديو (الاتصال على resolveService للحصول على ACTION_PLAY_BROADCASTRADIO)
  2. أنشئ MediaBrowser ثم اربط حسابك به.
  3. حدِّد مدى توفّر MediaItem باستخدام EXTRA_BCRADIO_FOLDER_TYPE الإضافية.

  ملاحظة: في معظم الحالات، على العميل فحص كل شجرات MediaBrowser المتاحة لرصد جميع المصادر المتاحة لجهاز معيّن.

  أسماء النطاقات

  يتم تمثيل قائمة النطاقات من خلال مجموعة من الأدلة ذات المستوى الأعلى التي تم ضبط علامة نوع المجلد فيها على BCRADIO_FOLDER_TYPE_BAND. عناوين MediaItem هي سلاسل مترجَمة تمثّل أسماء الفرق الموسيقية. في معظم الحالات، سيكون المحتوى مطابقًا للترجمة الإنجليزية، ولكن لا يمكن للعميل الاعتماد على هذا الافتراض.

  لتوفير آلية ثابتة للبحث عن نطاقات معيّنة، تتم إضافة علامة إضافية لمجلدات النطاقات، EXTRA_BCRADIO_BAND_NAME_EN. هذا هو اسم النطاق غير المُعرَّب، ويمكن أن يأخذ إحدى القيم المحدَّدة مسبقًا التالية فقط:

  • AM
  • FM
  • DAB

  إذا لم تكن الفرقة مُدرَجة في هذه القائمة، يجب عدم ضبط علامة اسم الفرقة. ومع ذلك، إذا كان النطاق مُدرَجًا في القائمة، يجب أن يكون لديه مجموعة علامات. لا يُدرِج راديو HD نطاقات منفصلة لأنّه يستخدم الوسيط الأساسي نفسه المستخدَم في بثّ AM/FM.

  نوايا اللعب العامة

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

  • android.car.intent.action.PLAY_BROADCASTRADIO
  • ‫android.car.intent.action.PLAY_AUDIOCD: CD-DA أو CD-Text
  • android.car.intent.action.PLAY_DATADISC: قرص بيانات ضوئي مثل CD/DVD، ولكن ليس CD-DA (قد يكون قرص CD بوضع مختلط)
  • android.car.intent.action.PLAY_AUX: بدون تحديد مَنفذ AUX
  • android.car.intent.action.PLAY_BLUETOOTH
  • android.car.intent.action.PLAY_USB: بدون تحديد جهاز USB
  • android.car.intent.action.PLAY_LOCAL: مساحة تخزين الوسائط المحلية (ذاكرة فلاش مدمجة)

  تم اختيار النية لاستخدامها في الأمر العام للتشغيل، لأنّها تحلّ مشكلتَين في آنٍ واحد: الأمر العام للتشغيل نفسه واكتشاف الخدمة. من المزايا الإضافية لوجود هذا الإجراء إمكانية تنفيذ هذا الإجراء البسيط بدون فتح جلسة MediaBrowser.

  إنّ اكتشاف الخدمة هو المشكلة الأكثر أهمية التي يتم حلّها باستخدام هذه النوايا. بهذه الطريقة، يكون إجراء اكتشاف الخدمة سهلًا وواضحًا (راجِع الاكتشاف وربط الخدمة).

  لتسهيل تنفيذ بعض التطبيقات، هناك طريقة بديلة لإصدار أمر Play هذا (يجب أن ينفذه تطبيق الراديو أيضًا): إصدار playFromMediaId باستخدام معرّف الجذر للعقدة الجذر (يُستخدَم كمعرّف الوسائط). على الرغم من أنّه ليس من المفترض أن يكون العقدة الجذر قابلة للتشغيل، فإنّ rootId هو سلسلة عشوائية يمكن استخدامها كـ mediaId. ومع ذلك، ليس مطلوبًا من العملاء فهم هذه التفاصيل الدقيقة.

  ProgramSelector

  على الرغم من أنّ mediaId كافٍ لاختيار قناة من MediaBrowserService، إلا أنّه يصبح مرتبطًا بجلسة معيّنة وغير متّسق بين مقدّمي الخدمة. في بعض الحالات، قد يحتاج العميل إلى مؤشر مطلق (مثل معدّل تكرار مطلق) للحفاظ عليه بين الجلسات والأجهزة.

  في عصر البثّ الإذاعي الرقمي، لا يكفي التردد وحده لضبط محطة إذاعية معيّنة. لذلك، استخدِم الزر ProgramSelector للضبط على قناة تناظرية أو رقمية. يتألّف ProgramSelector من جزأين:

  • المعرّف الأساسي: معرّف فريد وثابت لمحطة إذاعة معيّنة لا يتغيّر ولكن قد لا يكون كافيًا لضبط هذه المحطة على سبيل المثال، رمز RDS PI، الذي يمكن ترجمته إلى علامة النداء في الولايات المتحدة
  • المعرّفات الثانوية: معرّفات إضافية مفيدة لضبط تردد تلك المحطة (على سبيل المثال، التردد)، وقد تتضمّن معرّفات من تقنيات راديو أخرى على سبيل المثال، قد تتضمّن محطة DAB بثًا احتياطيًا تمثيليًا.

  لتفعيل ProgramSelector لكي يلائم الحل المستنِد إلى MediaBrowser أو MediaSession، حدِّد مخطّطًا لمعرّف الموارد المنتظم (URI) لتسلسله. يتم تعريف المخطّط على النحو التالي:

  broadcastradio://program/<primary ID type>/<primary ID>?
  <secondary ID type>=<secondary ID>&<secondary ID type>=<secondary ID>

  في هذا المثال، الجزء الخاص بالمعرّفات الثانوية (بعد علامة الاستفهام (?)) هو اختياري ويمكن إزالته لتوفير معرّف ثابت لاستخدامه كـ mediaId. مثلاً:

  • broadcastradio://program/RDS_PI/1234?AMFM_FREQUENCY=88500&AMFM_FREQUENCY=103300
  • broadcastradio://program/AMFM_FREQUENCY/102100
  • broadcastradio://program/DAB_SID_EXT/14895264?RDS_PI=1234

  يقدّم جزء السلطة (المعروف أيضًا باسم المضيف) من program بعض المساحة لإضافة مزيد من program في المستقبل. يتم تحديد سلاسل أنواع المعرّفات بدقة كأسماء لها في تعريف IdentifierType في HAL 2.x، ويكون تنسيق القيمة عددًا عشريًا أو سداسيًا عشريًا (مع البادئة 0x).

  يتم تمثيل جميع المعرّفات الخاصة بالمورّدين باستخدام البادئة VENDOR_. على سبيل المثال، VENDOR_0 لرمز VENDOR_START و VENDOR_1 لرمز VENDOR_START زائد 1. إنّ معرّفات الموارد المنتظمة هذه خاصة بجهاز الراديو الذي تم إنشاؤها عليه ولا يمكن نقلها بين الأجهزة التي تصنعها شركات تصنيع أصلية مختلفة.

  يجب إسناد عناوين URL هذه إلى كل عنصر MediaItem ضمن مجلدات radio ذات المستوى الأعلى. بالإضافة إلى ذلك، يجب أن تتوافق MediaSession مع كل من playFromMediaId وplayFromUri. ومع ذلك، فإنّ عنوان URL مخصّص في الأساس لاستخراج ملف البث المرئي والصوتي (مثل تردد FM) وتخزينه بشكل دائم. لا يمكن ضمان توفّر عنوان URL لجميع عناصر الوسائط (على سبيل المثال، عندما يكون نوع معرّف الأساسي غير متوافق بعد مع إطار العمل). من ناحية أخرى، يعمل رقم تعريف الوسائط دائمًا. لا يُنصح بأن يستخدم العملاء معرّف الموارد المتّصل (URI) لاختيار العناصر من جلسة MediaBrowser الحالية. استخدِم playFromMediaId بدلاً من ذلك. ومع ذلك، فإنّه ليس اختياريًا للتطبيق الذي يعرض المحتوى، ويتم حجز معرّفات الموارد المنتظمة غير المتوفّرة للحالات التي تتضمّن أسبابًا وجيهة.

  استخدَم التصميم الأوّلي فاصلة واحدة بدلاً من تسلسل :// بعد جزء المخطّط. ومع ذلك، لا يتوافق الخيار الأول مع android.net.Uri لمراجع معرّفات الموارد المنتظمة (URI) التسلسلية المطلقة.

  أنواع المصادر الأخرى

  يمكن التعامل مع مصادر الصوت الأخرى بالطريقة نفسها. على سبيل المثال، الإدخال الإضافي و مشغّل أقراص الصوت المضغوط

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

  قرص صوتي

  يشبه هذا النوع من الأقراص أقراص Audio CD من حيث أنّ التطبيق الذي يعرض هذه الأقراص يعرض MediaBrowser بتسجيل واحد قابل للتصفّح (أو أكثر، إذا كان النظام يحتوي على مشغّل أقراص CD)، والذي سيحتوي بدوره على جميع الأغاني في قرص CD معيّن. إذا لم يكن لدى النظام معرفة بالمقاطع الصوتية على كل قرص مضغوط (على سبيل المثال، عند إدخال كل الأقراص في علبة في وقت واحد وعدم قراءتها كلها)، سيكون MediaItem للقرص بأكمله هو PLAYABLE فقط، وليس BROWSABLE بالإضافة إلى PLAYABLE. إذا لم يكن هناك قرص في خانة معيّنة، لن يكون العنصر PLAYABLE ولا BROWSABLE (ولكن يجب أن تكون كل خانة متوفّرة دائمًا في الشجرة).

  

  الشكل 3. بنية شجرة القرص الصوتي المضغوط

  سيتم وضع علامة على هذه الإدخالات بطريقة مشابهة لتلك المُستخدَمة في مجلدات البث الإذاعي، وستتضمّن حقولًا إضافية أخرى محدّدة في MediaDescription API:

  • ‫EXTRA_CD_TRACK: لكل MediaItem على قرص صوتي، رقم المقطع الصوتي بالاستناد إلى 1
  • EXTRA_CD_DISK: رقم القرص بالترتيب من 1

  بالنسبة إلى النظام المزوّد بميزة CD-Text والقرص المتوافق، سيحتوي العنصر MediaItem من المستوى الأعلى على عنوان القرص. وبالمثل، سيحتوي MediaItems للمقاطع الصوتية على عنوان المقطع الصوتي.

  الإدخال الإضافي

  يعرض التطبيق الذي يقدّم إدخالًا مساعدًا شجرة MediaBrowser تتضمّن إدخالًا واحدًا (أو أكثر، عند توفّر منافذ متعددة) يمثّل منفذ AUX. تأخذ MediaSession المعنيّة mediaId وتبدّل إلى هذا المصدر بعد تلقّي طلب playFromMediaId.

  

  الشكل 4. بنية شجرة AUX

  سيحتوي كل إدخال AUX MediaItem على حقل إضافي EXTRA_AUX_PORT_NAME تم ضبطه على الاسم غير المترجَم للمنفذ بدون عبارة "AUX". على سبيل المثال، سيتم ضبط "AUX 1" على "1"، و"AUX front" على "front"، و "AUX" على سلسلة فارغة. في اللغات غير الإنجليزية، ستظل علامة name هي السلسلة الإنجليزية نفسها. من غير المحتمل أن يكون الأمر كذلك، لأنّه بالنسبة إلى EXTRA_BCRADIO_BAND_NAME_EN، تحدّد الشركة المصنّعة للجهاز القيم ولا يتم تحديدها وفقًا لقائمة محدّدة مسبقًا.

  إذا كان الجهاز قادرًا على رصد الأجهزة المتصلة بمنفذ AUX، يجب أن يضع الجهاز علامة على MediaItem على أنّه PLAYABLE، فقط في حال اتصال الإدخال. من المفترض أن يظل الجهاز مدرَجًا (ولكن ليس PLAYABLE) إذا لم يتم توصيل أي جهاز بمنفذ هذا. إذا لم يكن الجهاز مزوّدًا بهذه الميزة، يجب ضبط MediaItem دائمًا على PLAYABLE.

  الحقول الإضافية

  حدِّد الحقول التالية:

  • EXTRA_CD_TRACK = "android.media.extra.CD_TRACK"
  • EXTRA_CD_DISK = "android.media.extra.CD_DISK"
  • EXTRA_AUX_PORT_NAME = "android.media.extra.AUX_PORT_NAME"

  على العميل مراجعة عناصر MediaItems من المستوى الأعلى التي تحتوي على الحقل EXTRA_CD_DISK أو EXTRA_AUX_PORT_NAME إضافيًا.

  أمثلة تفصيلية

  تتناول الأمثلة التالية بنية شجرة MediaBrowser لأنواع المصادر التي تشكل جزءًا من هذا التصميم.

  Broadcast radio MediaBrowserService (handles ACTION_PLAY_BROADCASTRADIO):

  • المحطات (قابلة للتصفّح)EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_PROGRAMS
    • معرّف الموارد المنتظم (URI) لقناة BBC One (قابلة للتشغيل): broadcastradio://program/RDS_PI/1234?AMFM_FREQUENCY=90500
    • معرّف الموارد المنتظم (URI) لقناة ABC 88.1 (القابلة للتشغيل): broadcastradio://program/RDS_PI/5678?AMFM_FREQUENCY=88100
    • معرّف الموارد المنتظم (URI) لقناة ABC 88.1 HD1 (قابلة للتشغيل): broadcastradio://program/HD_STATION_ID_EXT/158241DEADBEEF?AMFM_FREQUENCY=88100&RDS_PI=5678
    • معرّف الموارد المنتظم (URI) لقناة ABC 88.1 HD2 (قابلة للتشغيل): broadcastradio://program/HD_STATION_ID_EXT/158242DEADBEFE
    • ‎90.5 FM (قابلة للتشغيل) - FM بدون RDSURI: broadcastradio://program/AMFM_FREQUENCY/90500
    • ‎620 AM (playable) URI: broadcastradio://program/AMFM_FREQUENCY/620
    • معرّف الموارد المنتظم (URI) لقناة BBC One (قابلة للتشغيل): broadcastradio://program/DAB_SID_EXT/1E24102?RDS_PI=1234
  • القنوات المفضّلة (قابلة للتصفّح والتشغيل)EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_FAVORITES
    • معرّف الموارد المنتظم (URI) لقناة BBC One (قابلة للتشغيل): broadcastradio://program/RDS_PI/1234?AMFM_FREQUENCY=101300
    • BBC Two (لا يمكن تشغيله)معرّف الموارد المنتظم (URI): broadcastradio://program/RDS_PI/1300?AMFM_FREQUENCY=102100
  • AM (قابلة للتصفح والتشغيل): EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_BANDEXTRA_BCRADIO_BAND_NAME_EN="AM"
    • معرّف الموارد المنتظم (URI) لبثّ المحتوى بدقة 530 AM: broadcastradio://program/AMFM_FREQUENCY/530
    • معرّف الموارد المنتظم (URI) لبث الفيديو بدقة 540p (قابل للتشغيل): broadcastradio://program/AMFM_FREQUENCY/540
    • معرّف الموارد المنتظم (URI) لمحتوى 550 AM (قابل للتشغيل): broadcastradio://program/AMFM_FREQUENCY/550
  • FM (قابلة للتصفّح والتشغيل): EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_BANDEXTRA_BCRADIO_BAND_NAME_EN="FM"
    • 87.7 FM (قابلة للتشغيل) معرّف الموارد المنتظم (URI): broadcastradio://program/AMFM_FREQUENCY/87700
    • 87.9 FM (قابلة للتشغيل) معرّف الموارد المنتظم (URI): broadcastradio://program/AMFM_FREQUENCY/87900
    • ‎88.1 FM (playable) URI: broadcastradio://program/AMFM_FREQUENCY/88100
  • DAB (قابلة للتشغيل): EXTRA_BCRADIO_FOLDER_TYPE=BCRADIO_FOLDER_TYPE_BANDEXTRA_BCRADIO_BAND_NAME_EN="DAB"

  Audio CD MediaBrowserService (المعروف باسم ACTION_PLAY_AUDIOCD):

  • القرص 1 (قابل للتشغيل) EXTRA_CD_DISK=1
  • القرص 2 (قابل للتصفّح والتشغيل) EXTRA_CD_DISK=2
    • المسار 1 (قابل للتشغيل) EXTRA_CD_TRACK=1
    • المقطع الصوتي 2 (قابل للتشغيل) EXTRA_CD_TRACK=2
  • قرص الموسيقى الخاص بي (قابل للتصفّح والتشغيل) EXTRA_CD_DISK=3
    • All By Myself (playable) EXTRA_CD_TRACK=1
    • Reise, Reise (playable) EXTRA_CD_TRACK=2
  • خانة فارغة 4 (لا يمكن تشغيلها) EXTRA_CD_DISK=4

  ‫AUX MediaBrowserService (المعروف باسم ACTION_PLAY_AUX):

  • منفذ AUX الأمامي (قابل للتشغيل) EXTRA_AUX_PORT_NAME="front"
  • منفذ AUX في الخلف (قابل للتشغيل) EXTRA_AUX_PORT_NAME="rear"