التحكّم في الوسائط من خلال MediaSession

1. مقدمة

تاريخ آخر تعديل: 09‏/09‏/2020

ما هي مزايا إضافة MediaSession في ما يتعلّق بتشغيل الفيديو؟

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

إنّ توفير MediaSession من خلال تطبيقك له مزايا متعدّدة سيستفيد منها المستخدمون. في ما يلي بعض الأمثلة الرائعة.

مساعد Google

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

Android TV

في تجارب الشاشة الكبيرة، يمكن لتطبيق Android TV الاستفادة من أجهزة التحكّم عن بُعد التقليدية للمستخدمين الذين لديهم أجهزة تلفزيون تتيح ميزة HDMI-CEC. يتم توجيه الطلبات الصادرة عن أزرار التشغيل/الإيقاف المؤقت والتوقف والتقديم والترجيع إلى تطبيقك.

عناصر التحكّم في الوسائط على الشاشة

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

الوسائط في الخلفية

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

الحوسبة المحيطية

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

التطبيق الذي ستصممه

في هذا الدليل التعليمي حول الرموز البرمجية، ستوسّع نطاق نموذج Exoplayer الحالي لإضافة ميزة دعم جلسة الوسائط. سينفِّذ تطبيقك ما يلي:

• أن تعكس بشكل صحيح الحالة النشطة لجلسة الوسائط
• إعادة توجيه عناصر التحكّم في الوسائط إلى ExoPlayer
• تمرير البيانات الوصفية للعناصر في "قائمة المحتوى التالي" إلى جلسة الوسائط

ما ستتعرّف عليه

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

يركز هذا الدرس التطبيقي على حزمة تطوير البرامج MediaSession SDK. لا تتم مناقشة المفاهيم غير ذات الصلة ووحدات الرموز البرمجية، بما في ذلك تفاصيل حول تنفيذ ExoPlayer، ولكن يتم توفيرها لك لنسخها ولصقها بسهولة.

المتطلبات

• أحدث إصدار من "استوديو Android" (3.5 أو إصدار أحدث)
• معرفة أساسية بتطوير تطبيقات Android

2. الإعداد

ما هي نقطة البداية؟

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

الحصول على نموذج ExoPlayer

للبدء، لنبدأ بنموذج ExoPlayer. استنسِخ مستودع GitHub من خلال تشغيل الرمز البرمجي أدناه.

git clone https://github.com/google/ExoPlayer.git

فتح العرض التجريبي

في "استوديو Android"، افتح المشروع التجريبي الرئيسي ضمن demos/main.

سيطلب منك "استوديو Android" ضبط مسار حزمة SDK. ننصحك باتّباع الاقتراحات لتحديث أدوات IDE وحِزم SDK إذا واجهت أي مشاكل.

إذا طُلب منك استخدام أحدث إصدار من Gradle، يمكنك تثبيته.

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

3- إنشاء جلسة وسائط وإدارتها

إنشاء جلسة الوسائط

فتح "PlayerActivity.java" تنشئ هذه الفئة ExoPlayer وتدير وظائفه، مثل عرض الفيديو على الشاشة. في هذا النشاط، سنربط ExoPlayer بجلسة وسائط.

أدخِل الحقلَين التاليَين في أعلى الصف. سنستخدم هذه الحقول في جميع أقسام هذا المقالة.

private MediaSessionCompat mediaSession;
private MediaSessionConnector mediaSessionConnector;

ستحتاج إلى إضافة التبعية لمشروع "extension-mediasession" إلى build.gradle على مستوى الوحدة لـ "الوحدة: demo":

implementation project(path: ':extension-mediasession')

يُرجى العِلم أنّ Android Studio يمكنه مساعدتك في إضافة هذا العنصر التابع تلقائيًا إذا مررت مؤشر الماوس فوق الخطأ المتعلّق بحلّ MediaSessionConnector:

أخيرًا، يمكنك حلّ عمليات استيراد الصفوف من خلال إضافة ما يلي:

import android.support.v4.media.session.MediaSessionCompat;
import com.google.android.exoplayer2.ext.mediasession.MediaSessionConnector;

ملاحظة: في هذا الدليل التعليمي حول الرموز البرمجية، يشير مصطلح "جلسة الوسائط" إلى مثيل MediaSessionCompat. ينتمي هذا الصف إلى مكتبة media-compat، التي يُنصح بها لكتابة تطبيقات الوسائط.

عند إنشاء النشاط، سنحتاج إلى إنشاء جلسة وسائط ووصلة جلسة وسائط تعمل كوسيط بين جلسة الوسائط وExoPlayer.

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

private void initializePlayer() {
  if (player == null) {
    ...
    player = ...
    ...
    mediaSession = new MediaSessionCompat(this, "sample");
    mediaSessionConnector = new MediaSessionConnector(mediaSession);
    mediaSessionConnector.setPlayer(player);
  }
  ...
}

إلغاء جلسة الوسائط

يمكنك إلغاء حجز جلسة الوسائط عندما لا يعود هناك حاجة إليها. عند إصدار ExoPlayer في releasePlayer()، يمكننا أيضًا تضمين الرمز البرمجي التالي لإجراء ذلك:

private void releasePlayer() {
  if (mediaSession != null) {
    mediaSession.release();
  }
  ...
}

إدارة حالة جلسة الوسائط

بعد إنشاء جلسة الوسائط، علينا التأكّد من أنّ حالتها تظهر بشكل صحيح عندما يتفاعل المستخدم مع النشاط.

عندما يبدأ المستخدم النشاط، يجب أن تصبح جلسة الوسائط نشطة:

@Override
public void onStart() {
  ...
  if (mediaSession != null) {
    mediaSession.setActive(true);
  }
}

بما أنّ تطبيقنا لا يشغّل الوسائط في الخلفية، من الضروري التأكّد من أنّ جلسة الوسائط تصبح غير نشطة عندما يغادر المستخدم النشاط:

@Override
public void onStop() {
  super.onStop();
  if (mediaSession != null) {
    mediaSession.setActive(false);
  }
  ...
}

تحذير: قد يؤدي عدم ضبط جلسة وسائط على "غير نشطة" إلى ظهور نتائج غير مرغوب فيها للمستخدمين. على سبيل المثال، إذا تم إنهاء استخدام ExoPlayer عندما يخرج المستخدم من نشاط معيّن، قد يستمر عرض عناصر التحكّم في التشغيل غير القابلة للاستخدام على شاشة القفل الخاصة بالمستخدم.

ملاحظة: لمزيد من المعلومات حول آلية عمل وحدة التحكّم في الوسائط وجلسة الوسائط معًا، اطّلِع على الدليل الإجمالي لبنية تطبيقات الوسائط.

لننفِّذ العرض التجريبي

1. اربط جهاز Android أو ابدأ محاكيًا.
2. تأكَّد من اختيار "الإصدار التجريبي" لتشغيله من شريط أدوات "استوديو Android".
3. انقر على من شريط أدوات Android Studio.
4. بعد تشغيل التطبيق على جهازك، اختَر بث فيديو لتشغيله.
5. بعد بدء التشغيل، يمكنك استخدام أوامر adb التالية للتحكّم في جلسة الوسائط:

adb shell media dispatch pause
adb shell media dispatch play
adb shell media dispatch play-pause
adb shell media dispatch fast-forward
adb shell media dispatch rewind

ملاحظة: إذا كان جهازك لا يتيح استخدام هذه الأوامر، جرِّب استخدام محاكي.

6. يمكنك أيضًا الاطّلاع على كيفية رصد Android لجلسة الوسائط. على وجه الخصوص، يمكنك التحقّق من الإجراءات المتوافقة من خلال الاطّلاع على حقل الإجراء. الرقم الذي يظهر لك هنا هو تركيبة من أرقام تعريف الإجراءات، كما هو موضّح في عنصر PlaybackState. للاطّلاع على تشغيل جلسة الوسائط: adb shell dumpsys media_session
7. إذا كنت تستخدم جهازًا ماديًا مزوّدًا بميكروفون، حاوِل استدعاء "مساعد Google" وإصدار طلبات صوتية، مثل "إيقاف مؤقت". "استئناف". "تقديم سريع لمدة دقيقة واحدة"

عيّنة من ExoPlayer تعمل على Android TV

ملاحظة: قد لا تعمل الأوامر الصوتية من خلال "مساعد Google" إلا على Android TV أو إذا استمر تشغيل الوسائط في الخلفية مع بقاء جلسة الوسائط نشطة.

4. تضمين البيانات الوصفية للعناصر في قائمة المحتوى التالي

يمكننا الآن توسيع الميزات المتوافقة لجلسة الوسائط التي أنشأنا فيها MediaSessionConnector سابقًا في initializePlayer().

إضافة TimelineQueueNavigator

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

لتحقيق ذلك، سنحدّد TimelineQueueNavigator. حدِّد مكان إنشاء مثيل MediaSessionConnector في initializePlayer() وأضِف عملية تنفيذ TimelineQueueNavigator بعد تهيئة mediaSession.

mediaSessionConnector.setQueueNavigator(new TimelineQueueNavigator(mediaSession) {
  @Override
  public MediaDescriptionCompat getMediaDescription(Player player, int windowIndex) {
    return new MediaDescriptionCompat.Builder()
            .setTitle(player.getCurrentMediaItem().mediaMetadata.title)
            .setDescription("MediaDescription description for " + windowIndex)
            .setSubtitle("MediaDescription subtitle")
            .build();
  }
});

ملاحظة: في حال كان العنوان المقدَّم هنا فارغًا، لن يتمكّن "مساعد Google" من استخراج هذه المعلومات من MediaDescription.

يمكنك حلّ مشاكل استيراد الصفوف من خلال إضافة ما يلي:

import android.support.v4.media.MediaDescriptionCompat;
import com.google.android.exoplayer2.ext.mediasession.TimelineQueueNavigator;

يُرجى ملاحظة أنّ المَعلمة windowIndex تتطابق مع عنصر هذا الفهرس في قائمة التشغيل.

ملاحظة: يتم تحديد محتوى هذه "القائمة المتوفّرة" حسب مصدر الوسائط في المشغّل. في العرض التقديمي المقدَّم، يمكن اختيار مثال على قوائم التشغيل من نشاط اختيار العيّنات الذي يستخدم ConcatenatingMediaSource.

بعد إضافة بعض البيانات الوصفية، يمكنك اختبار ما إذا كان "مساعد Google" يفهم المحتوى الذي يتم تشغيله. أثناء تشغيل فيديو على Android TV، يمكنك استدعاء "مساعد Google" وسؤاله "ما هو الفيديو الذي يتم تشغيله؟"

5- تخصيص الإجراءات

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

تحديد الإجراءات المتاحة

جرِّب استخدام mediaSessionConnector.setEnabledPlaybackActions() لتخصيص الإجراءات التي تريد أن تتيحها جلسة الوسائط.

يُرجى العلم أنّ المجموعة الكاملة هي:

mediaSessionConnector.setEnabledPlaybackActions(
        PlaybackStateCompat.ACTION_PLAY_PAUSE
                | PlaybackStateCompat.ACTION_PLAY
                | PlaybackStateCompat.ACTION_PAUSE
                | PlaybackStateCompat.ACTION_SEEK_TO
                | PlaybackStateCompat.ACTION_FAST_FORWARD
                | PlaybackStateCompat.ACTION_REWIND
                | PlaybackStateCompat.ACTION_STOP
                | PlaybackStateCompat.ACTION_SET_REPEAT_MODE
                | PlaybackStateCompat.ACTION_SET_SHUFFLE_MODE
);

لنلقِ نظرة مرة أخرى على كيفية عرض هذه البيانات على المنصة:

1. كما في السابق، ابدأ تشغيل فيديو.
2. يمكنك استكشاف كيفية تعرّف Android على البيانات الوصفية من جلسة الوسائط من خلال تنفيذ ما يلي: adb shell dumpsys media_session
3. حدِّد موضع السطر الذي يحتوي على البيانات الوصفية وتأكَّد من أنّ العنوان والوصف مُدرَجان ومرتبطان بـ com.google.android.exoplayer2.demo/sample.

إضافة إجراءات إضافية

يمكننا توسيع جلسة الوسائط من خلال بعض الإجراءات الإضافية. في هذا القسم، سنضيف ميزة عرض الترجمة والشرح فقط.

إتاحة الترجمة والشرح

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

mediaSessionConnector.setCaptionCallback(new MediaSessionConnector.CaptionCallback() {
      @Override
      public void onSetCaptioningEnabled(Player player, boolean enabled) {
        Log.d("MediaSession", "onSetCaptioningEnabled: enabled=" + enabled);
      }

      @Override
      public boolean hasCaptions(Player player) {
        return true;
      }

      @Override
      public boolean onCommand(Player player, ControlDispatcher controlDispatcher, String command, Bundle extras, ResultReceiver cb) {
        return false;
      }
    }
);

أخيرًا، عليك حلّ أي عمليات استيراد غير متوفّرة.

يمكنك اختبار هذه الميزة من خلال تفعيل "مساعد Google" على Android TV وقول "تفعيل الترجمة والشرح". اطّلِع على Logcat للاطّلاع على الرسائل لمعرفة كيفية استدعاء هذا الرمز البرمجي.

ملاحظة: سيُعلم "مساعد Google" المستخدمين بأنّ مقاطع الترجمة والشرح غير متاحة عند عرض القيمة false من hasCaptions().

6- تهانينا

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

لقد حصلت على قدر هائل من الوظائف من خلال:

• إضافة جلسة وسائط
• ربط جلسات الوسائط بمثيل من ExoPlayer
• إضافة بيانات وصفية وإجراءات إضافية

لقد تعرّفت الآن على الخطوات الرئيسية المطلوبة لتحسين تطبيق الوسائط وتقديم تجربة أكثر تنوعًا للمستخدمين.

ملاحظة نهائية

تم إنشاء هذا الدرس التطبيقي حول الترميز استنادًا إلى نموذج من رمز ExoPlayer المصدر. ما مِن حاجة إلى استخدام ExoPlayer من المصدر، ويُنصح بدلاً من ذلك بسحب التبعيات الخاصة بـ ExoPlayer وMediaSessionConnector لتسهيل البقاء على اطّلاع بآخر الإصدارات.

لإجراء ذلك، ما عليك سوى استبدال تبعيات المشروع، مثل:

implementation project(modulePrefix + 'library-core')
implementation project(path: ':extension-mediasession')

لسحب البيانات من مستودعات Maven، مثل:

implementation 'com.google.android.exoplayer:exoplayer-core:2.+'
implementation 'com.google.android.exoplayer:extension-mediasession:2.+'

مستندات المرجع

• استخدام جلسة وسائط
• نظرة عامة على بنية تطبيقات الوسائط
• بنية المخطط الزمني في ExoPlayer
• دليل المطوّر لاستخدام ExoPlayer
• مرجع واجهة برمجة التطبيقات MediaSessionConnector في ExoPlayer