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

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

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

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

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

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

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

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

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

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

تصف فئة PlaybackStateCompat الحالة التشغيلية الحالية للمشغّل. وتتضمّن المزايا ما يلي:

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

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

  • اسم الفنان والألبوم والمقطع الصوتي
  • مدة المقطع الصوتي
  • صورة غلاف الألبوم لعرضها على شاشة القفل هذه الصورة عبارة عن صورة نقطية بحجم أقصى يبلغ 320x320dp (إذا كانت أكبر، يتم تصغيرها).
  • مثال على 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 4.0 (المستوى 14 لواجهة برمجة التطبيقات) حتى Android 4.4 (المستوى 19 لواجهة برمجة التطبيقات)، عندما تكون جلسة وسائط نشطة وتتضمن البيانات الوصفية لجلسة الوسائط صورة نقطية في الخلفية، تعرض شاشة القفل تلقائيًا عناصر تحكم في النقل.

في الإصدار Android 5.0 (المستوى 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());

للاطلاع على مثال كامل، يُرجى الاطلاع على 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 Player.

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

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

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

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

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