تفعيل عنصر التحكّم في التشغيل

لتفعيل تشغيل الوسائط في Android Auto ونظام التشغيل Android Automotive ‏ (AAOS)، يجب تنفيذ عناصر التحكّم في التشغيل من خلال تسجيل جلسة وسائط والتعامل مع طرق معاودة الاتصال الخاصة بها. توضّح هذه الصفحة كيفية تنفيذ ما يلي:

• تسجيل عنصر MediaSessionCompat في خدمة متصفّح الوسائط

• تنفيذ طرق MediaSessionCompat.Callback للردّ على طلبات تشغيل المستخدم

• ضبط إجراءات التشغيل العادية والمخصّصة

• ضبط حالة التشغيل الأولية لجلسة الوسائط

• إضافة رموز للإشارة إلى تنسيق الصوت

• إنشاء روابط من عناصر الوسائط التي يتم تشغيلها حاليًا

يرسل Android Auto وAAOS أوامر التحكّم في التشغيل من خلال MediaSessionCompat لخدمتك. عليك تسجيل جلسة وتنفيذ طرق معاودة الاتصال المرتبطة بها.

تسجيل جلسة وسائط

في طريقة onCreate لخدمة متصفّح الوسائط، أنشِئ مثيلاً من MediaSessionCompat، ثم استخدِم setSessionToken لتسجيل جلسة الوسائط. يوضّح مقتطف الرمز البرمجي التالي كيفية إنشاء جلسة وسائط وتسجيلها:

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

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

تنفيذ أوامر التشغيل

عندما يطلب المستخدم تشغيل عنصر وسائط من تطبيقك، يستخدِم Android Automotive OS وAndroid Auto فئة MediaSessionCompat.Callback من عنصر MediaSessionCompat في تطبيقك الذي حصلوا عليه من خدمة متصفّح الوسائط في تطبيقك. عندما يريد المستخدم التحكّم في تشغيل المحتوى، مثل إيقاف التشغيل مؤقتًا أو الانتقال إلى المقطع التالي، يستدعي Android Auto وAndroid Automotive OS إحدى طرق عنصر معاودة الاتصال.

للتعامل مع تشغيل المحتوى، يجب أن يوسّع تطبيقك فئة MediaSessionCompat.Callback المجرّدة وينفّذ الطرق التي يتيحها.

نفِّذ كل طريقة من طرق معاودة الاتصال هذه التي تتناسب مع نوع المحتوى الذي يقدّمه تطبيقك:

onPrepare

يستدعي AAOS هذه الطريقة عند تغيير مصدر الوسائط.

onPlay

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

onPlayFromMediaId

يتم استدعاء هذه الطريقة عندما يختار المستخدم تشغيل عنصر معيّن. تتلقّى الطريقة المعرّف الذي خصّصته خدمة متصفّح الوسائط لعنصر الوسائط في التسلسل الهرمي للمحتوى.

onPlayFromSearch

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

onPause

يتم استدعاء هذه الطريقة عندما يختار المستخدم إيقاف التشغيل مؤقتًا.

onSkipToNext

يتم استدعاء هذه الطريقة عندما يختار المستخدم الانتقال إلى العنصر التالي.

onSkipToPrevious

يتم استدعاء هذه الطريقة عندما يختار المستخدم الانتقال إلى العنصر السابق.

onStop

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

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

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

ضبط إجراءات التشغيل العادية

يعرض Android Auto وAAOS عناصر التحكّم في التشغيل استنادًا إلى الإجراءات المفعّلة في عنصر PlaybackStateCompat. يجب أن يتيح تطبيقك الإجراءات التالية تلقائيًا:

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

يمكن أن يتيح تطبيقك بالإضافة إلى ذلك الإجراءات التالية إذا كانت ذات صلة بمحتوى التطبيق:

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

بالإضافة إلى ذلك، يمكنك اختياريًا إنشاء قائمة تشغيل لعرضها للمستخدم. لإجراء ذلك، استخدِم الطريقتَين setQueue وsetQueueTitle، وفعِّل الإجراء ACTION_SKIP_TO_QUEUE_ITEM، وحدِّد معاودة الاتصال onSkipToQueueItem.

أضِف أيضًا إمكانية استخدام رمز يتم التشغيل الآن، وهو مؤشر للمحتوى الذي يتم تشغيله. لإجراء ذلك، استخدِم الطريقة setActiveQueueItemId ومرِّر معرّف العنصر الذي يتم تشغيله في قائمة الانتظار. عليك تعديل setActiveQueueItemId كلما حدث تغيير في صفّ.

يعرض Android Auto وAAOS أزرارًا لكل إجراء مفعّل بالإضافة إلى قائمة التشغيل. عندما ينقر المستخدمون على هذه الأزرار، يستدعي النظام الـ معاودة الاتصال المقابلة من MediaSessionCompat.Callback.

حجز مساحة غير مستخدَمة

يحجز Android Auto وAAOS مساحة في واجهة المستخدم للإجراءَين ACTION_SKIP_TO_PREVIOUS وACTION_SKIP_TO_NEXT. إذا كان تطبيقك لا يتيح إحدى هاتَين الوظيفتَين، يستخدِم Android Auto وAAOS المساحة لعرض أي إجراءات مخصّصة تنشئها.

إذا كنت لا تريد ملء هذه المساحات بإجراءات مخصّصة، يمكنك حجزها حتى يترك Android Auto وAAOS المساحة فارغة عندما لا يتيح تطبيقك الوظيفة المقابلة.

لإجراء ذلك، استخدِم الطريقة setExtras مع حزمة إضافات تحتوي على ثوابت تتوافق مع الوظائف المحجوزة. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT يتوافق مع ACTION_SKIP_TO_NEXT، و SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV يتوافق مع ACTION_SKIP_TO_PREVIOUS. استخدِم هذه الثوابت كمفاتيح في الحزمة، واستخدِم القيمة المنطقية true كقيم.

ضبط PlaybackState الأولي

أثناء تواصل Android Auto وAAOS مع خدمة متصفّح الوسائط ، تُبلِغ جلسة الوسائط بحالة تشغيل المحتوى باستخدام PlaybackStateCompat.

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

لإجراء ذلك، اضبط PlaybackStateCompat لجلسة الوسائط على STATE_STOPPED أو STATE_PAUSED أو STATE_NONE أو STATE_ERROR.

لا تستمر جلسات الوسائط في Android Auto وAAOS إلا طوال مدة الرحلة، لذا يبدأ المستخدمون هذه الجلسات ويوقفونها بشكل متكرّر. لتعزيز تجربة سلسة بين الرحلات، تتبَّع حالة الجلسة السابقة للمستخدم، حتى يتمكّن المستخدم تلقائيًا من استئناف التشغيل من حيث توقّف عندما يتلقّى تطبيق الوسائط طلبًا بالاستئناف. على سبيل المثال، آخر ملف وسائط تم تشغيله وPlaybackStateCompat وقائمة الانتظار.

إضافة إجراءات تشغيل مخصّصة

يمكنك إضافة إجراءات تشغيل مخصّصة لعرض إجراءات إضافية يتيحها تطبيق الوسائط. إذا كانت المساحة تسمح بذلك (ولم تحجزها)، يضيف Android الإجراءات المخصّصة إلى عناصر التحكّم في النقل. بخلاف ذلك، تظهر الإجراءات المخصّصة في قائمة المزيد. يعرض Android الإجراءات المخصّصة بالترتيب الذي تضيفها به إلى PlaybackStateCompat.

استخدِم الإجراءات المخصّصة لتوفير سلوك مختلف عن الإجراءات العادية. لا تستخدِمها لاستبدال الإجراءات العادية أو تكرارها.

لإضافة إجراءات مخصّصة، استخدِم الـ addCustomAction في الـ PlaybackStateCompat.Builder. يوضّح مقتطف الرمز البرمجي التالي كيفية إضافة إجراء مخصّص إلى "بدء قناة راديو":

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

للحصول على مثال أكثر تفصيلاً لهذه الطريقة، يُرجى الاطّلاع على setCustomAction الطريقة في نموذج تطبيق Universal Android Music Player على GitHub. بعد إنشاء الإجراء المخصّص، يمكن أن تستجيب جلسة الوسائط للإجراءات من خلال إلغاء الطريقة onCustomAction.

يوضّح مقتطف الرمز البرمجي التالي كيفية استجابة تطبيقك لإجراء "بدء قناة راديو":

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

لمزيد من المعلومات، يُرجى الاطّلاع على الطريقة onCustomAction في نموذج تطبيق Universal Android Music Player على GitHub.

إنشاء رموز للإجراءات المخصّصة

يتطلّب كل إجراء مخصّص تنشئه رمزًا.

إذا كان وصف هذا الرمز يتطابق مع أحد CommandButton.ICON_ الثوابت، اضبط القيمة العددية للمفتاح EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT للإضافات الخاصة بالإجراء المخصّص. في الأنظمة المتوافقة، يؤدي ذلك إلى إلغاء مصدر الرمز الذي تم تمريره إلى CustomAction.Builder، ما يسمح لمكوّنات النظام بعرض الإجراء والإجراءات الأخرى للتشغيل بشكل متّسق.

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

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

تقديم أنماط رموز بديلة للإجراءات التي تم إيقافها

عندما يكون إجراء مخصّص غير متاح للسياق الحالي، استبدِل رمز الإجراء المخصّص برمز بديل يوضّح أنّ الإجراء غير مفعّل.

الإشارة إلى تنسيق الصوت

للإشارة إلى أنّ الوسائط التي يتم تشغيلها تستخدِم تنسيقًا صوتيًا خاصًا، يمكنك تحديد رموز يتم عرضها في السيارات التي تتيح هذه الميزة. يمكنك ضبط KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI وKEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI في حزمة الإضافات لعنصر الوسائط الذي يتم تشغيله حاليًا (الذي تم تمريره إلى MediaSession.setMetadata). اضبط كلتا الإضافتَين لاستيعاب التنسيقات المختلفة.

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

إضافة روابط من العنصر الذي يتم تشغيله حاليًا

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

لإضافة روابط، اضبط البيانات الوصفية KEY_SUBTITLE_LINK_MEDIA_ID (للربط من العنوان الفرعي) أو KEY_DESCRIPTION_LINK_MEDIA_ID (للربط من الوصف). لمزيد من التفاصيل، يُرجى الاطّلاع على المستندات المرجعية لحقول البيانات الوصفية هذه.