استخدام جلسة وسائط

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

يتم بث جلسة الوسائط إلى جانب المُشغِّل الذي تديره. يجب عليك إنشاء وإعداد جلسة وسائط بطريقة onCreate() للنشاط أو خدمة مالك جلسة الوسائط والمشغّل المرتبط بها.

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

لا تتضمّن جلسة الوسائط التي تم إنشاؤها حديثًا أي إمكانات. يجب تهيئة الجلسة بتنفيذ الخطوات التالية:

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

يجب إنشاء جلسة وسائط وإعدادها بالطريقة onCreate() في النشاط أو الخدمة التي تملك الجلسة.

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

الحفاظ على حالة التشغيل والبيانات الوصفية

هناك فئتان تمثلان حالة جلسة الوسائط.

تشير رسالة الأشكال البيانية PlaybackStateCompat تصف الحالة التشغيلية الحالية للمشغل. وتتضمّن المزايا ما يلي:

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

MediaMetadataCompat صف المادة قيد التشغيل:

  • اسم الفنان والألبوم والمقطع الصوتي
  • مدة المقطع الصوتي
  • صورة غلاف الألبوم لعرضها على شاشة القفل الصورة عبارة عن صورة نقطية بحجم أقصى 320×320 بكسل مستقل الكثافة (إذا كان أكبر، يتم تصغير حجم الصورة).
  • مثال على ContentUris يشير إلى نسخة أكبر من العمل الفني

قد تتغير حالة المشغّل والبيانات الوصفية على مدار فترة جلسة الوسائط. وفي كل مرة تتغير فيها الحالة أو البيانات الوصفية، يجب استخدام أداة الإنشاء المناسبة لكل صف، PlaybackStateCompat.Builder() أو MediaMetadataCompat.Builder()، ثم تمرير المثيل الجديد إلى جلسة الوسائط من خلال الاتصال setPlaybackState() أو setMetaData() لتقليل استهلاك الذاكرة بشكل عام من هذه العمليات المتكررة، من الجيد إنشاء أدوات الإنشاء مرة واحدة وإعادة استخدامها طوال مدة الجلسة.

الحالات والأخطاء

يُرجى العِلم أنّ PlaybackState هو كائن يحتوي على قيم منفصلة حالة تشغيل الجلسة (getState()) وعند الضرورة، رمز خطأ (getErrorCode()) مرتبط به. قد تكون الأخطاء فادحة أو غير فادحة:

عندما تتم مقاطعة التشغيل، سيظهر خطأ فادح: اضبط حالة النقل إلى STATE_ERROR وتحديد خطأ مرتبط بـ setErrorMessage(int, CharSequence). طالما أنّ تشغيل المحتوى محظور بسبب الخطأ، يجب أن يستمر تشغيل "PlaybackState". للإبلاغ عن STATE_ERROR والخطأ.

يحدث خطأ غير فادح عندما يتعذّر على تطبيقك معالجة أحد الطلبات، ولكن يمكنه مواصلة التشغيل: يظل النقل "عادي" (مثل STATE_PLAYING)، ولكن تتضمّن السمة PlaybackState رمز خطأ. على سبيل المثال، إذا تم تشغيل الأغنية الأخيرة وطلب المستخدم الانتقال إلى الأغنية التالية، يمكن متابعة التشغيل، ولكن يجب إنشاء PlaybackState جديدة تحتوي على رمز الخطأ ERROR_CODE_END_OF_QUEUE ثم الاتصال بـ setPlaybackState(). سيتم إرسال طلب معاودة الاتصال إلى وحدات التحكّم في الوسائط المرتبطة بالجلسة. onPlaybackStateChanged() واشرح للمستخدم ما حدث. يجب الإبلاغ عن الخطأ غير الفادح مرة واحدة فقط، وقت حدوثه. في المرة التالية التي تعدِّل فيها الجلسة PlaybackState، لا تضبط الخطأ غير الفادح نفسه مرة أخرى (ما لم يحدث الخطأ استجابةً لطلب جديد).

شاشات قفل جلسات تشغيل الوسائط

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

صور الألبوم

في إصدارات Android 4.0 (المستوى 14 من واجهة برمجة التطبيقات) إلى Android 10 (مستوى واجهة برمجة التطبيقات 29)، يتم استخدام الخلفية من شاشة القفل تعرض صورة الألبوم، ولكن فقط إذا كانت جلسة الوسائط البيانات الوصفية تتضمن صورة نقطية للخلفية.

عناصر التحكم في النقل

في إصدارات Android 4.0 (المستوى 14 لواجهة برمجة التطبيقات) إلى Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات)، عندما تكون جلسة الوسائط نشطة وتتضمّن البيانات الوصفية لجلسة الوسائط صورة نقطية للخلفية، تعرض شاشة القفل عناصر التحكم في النقل تلقائيًا.

في Android 5.0 (مستوى واجهة برمجة التطبيقات 21) أو الإصدارات الأحدث، لا يوفّر النظام النقل عناصر التحكم على شاشة القفل. بدلاً من ذلك، يجب عليك استخدام العلامة MediaStyle للإشعار لعرض ضوابط النقل.

إضافة إجراءات مخصّصة

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

يمكنك إضافة إجراءات مخصّصة باستخدام "addCustomAction()". يوضّح المثال التالي كيفية إضافة عنصر تحكّم لتنفيذ إجراء أعجبني:

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

راجع Universal Music Player للاطّلاع على مثال كامل.

يمكنك الردّ على الإجراء باستخدام onCustomAction().

Kotlin

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

Java

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

يُرجى أيضًا الاطّلاع على مشغّل الموسيقى Universal Music.

استدعاءات جلسة الوسائط

طرق معاودة الاتصال لجلسة الوسائط الرئيسية هي onPlay() وonPause() وonStop(). يمكنك هنا إضافة الرمز الذي يتحكّم في المشغّل.

بما أنّك تنشئ مثيلاً لمعاودة الاتصال بالجلسة وتضبطها في وقت التشغيل (في onCreate())، يمكن لتطبيقك تحديد عمليات معاودة الاتصال البديلة التي تستخدم مشغّلات مختلفة واختيار مجموعة معاودة الاتصال/المشغّل المناسبة بناءً على مستوى الجهاز و/أو النظام. يمكنك تغيير المشغّل بدون تغيير باقي محتوى التطبيق. على سبيل المثال، يمكنك استخدام ExoPlayer عند تشغيل Android 4.1 (المستوى 16 لواجهة برمجة التطبيقات) أو إصدار أحدث واستخدام MediaPlayer على الأنظمة السابقة.

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

يعتمد تنفيذ طرق معاودة الاتصال بجلسة الوسائط على بنية تطبيقك. راجع الصفحات المنفصلة التي توضح كيفية استخدام استدعاءات في تطبيقات المحتوى الصوتي أو وتطبيقات الفيديو توضح كيف يجب تنفيذ عمليات الاستدعاء لكل نوع من التطبيقات.