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

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

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

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

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

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

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

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

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

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

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

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

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

  • اسم الفنان والألبوم والمقطع الصوتي
  • مدة المسار
  • صورة غلاف الألبوم معروضة على شاشة القفل هذه الصورة عبارة عن صورة نقطية بحجم أقصى يبلغ 320x320 بكسل مستقل الكثافة (إذا كان حجمها أكبر، فسيتم تصغيرها).
  • مثيل 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 ثانية. ومن المفترض أن يؤدي الإجراء المخصّص إلى تنفيذ سلوك جديد تمامًا. لا تستخدِم إجراءً مخصّصًا لاستبدال أحد الإجراءات العادية للتحكم في النقل المحدّدة في التشغيلStateCompat.

يمكنك إضافة إجراءات مخصّصة باستخدام "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 على الأنظمة القديمة.

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

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