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

توفّر جلسات الوسائط طريقة شاملة للتفاعل مع مشغّل الصوت أو الفيديو. من خلال إعلام 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()). يمكن أن تكون الأخطاء فادحة أو غير فادحة:

Whenever playback is interrupted, you should generate a fatal error: Set the transport state to STATE_ERROR and specify an associated error with 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)، عندما تكون جلسة الوسائط نشطة وتتضمّن البيانات الوصفية لجلسة الوسائط صورة نقطية في الخلفية، تعرض شاشة القفل تلقائيًا عناصر التحكّم في النقل.

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

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

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

أضِف إجراءات مخصّصة باستخدام 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());

يمكنك الاطّلاع على مشغّل الموسيقى العالمي للحصول على مثال كامل.

يمكنك الردّ على الإجراء باستخدام 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)) {
        ...
    }
}

يمكنك أيضًا الاطّلاع على مشغّل الموسيقى العام.

عمليات معاودة الاتصال بجلسة الوسائط

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

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

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

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