إنشاء تطبيق مشغّل وسائط أساسي باستخدام Media3 ExoPlayer

تحدِّد Jetpack Media3 واجهة Player توضِّح الوظائف الأساسية لتشغيل ملفات الفيديو والصوت. ExoPlayer هو التنفيذ التلقائي لهذه الواجهة في Media3. ننصحك باستخدام ExoPlayer، لأنّه يقدّم مجموعة كاملة من الميزات التي تغطي معظم حالات الاستخدام المتعلّقة بتشغيل المحتوى، ويمكن تعديله للتعامل مع أيّ حالات استخدام إضافية قد تكون لديك. يزيل ExoPlayer أيضًا التجزئة في الأجهزة ونظام التشغيل لكي يعمل الرمز البرمجي بشكلٍ منتظم في جميع مكونات Android المتكاملة. يتضمّن ExoPlayer ما يلي:

• إتاحة قوائم التشغيل
• إتاحة مجموعة متنوعة من تنسيقات البث التدريجي والمكيّف
• إتاحة إدراج الإعلانات من جهة العميل والخادم على حدّ سواء
• إتاحة تشغيل المحتوى المحمي بإدارة الحقوق الرقمية

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

الخطوات الأولى

للبدء، أضِف تبعية على وحدات ExoPlayer وواجهة المستخدم والوحدات الشائعة في Jetpack Media3:

implementation "androidx.media3:media3-exoplayer:1.5.0"
implementation "androidx.media3:media3-ui:1.5.0"
implementation "androidx.media3:media3-common:1.5.0"

استنادًا إلى حالة الاستخدام، قد تحتاج أيضًا إلى وحدات إضافية من Media3، مثل exoplayer-dash لتشغيل أحداث البث بتنسيق DASH.

احرص على استبدال 1.5.0 بالإصدار المفضّل من المكتبة. يمكنك الرجوع إلى ملاحظات الإصدار للاطّلاع على أحدث إصدار.

إنشاء مشغّل وسائط

باستخدام Media3، يمكنك استخدام عملية التنفيذ المضمّنة Player لواجهة ExoPlayer، أو يمكنك إنشاء عملية التنفيذ المخصّصة الخاصة بك.

إنشاء ExoPlayer

في ما يلي أبسط طريقة لإنشاء مثيل ExoPlayer:

val player = ExoPlayer.Builder(context).build()

ExoPlayer player = new ExoPlayer.Builder(context).build();

يمكنك إنشاء مشغّل الوسائط في طريقة onCreate() لدورة حياة Activity أو Fragment أو Service حيث يكون مضمّنًا.

يتضمّن Builder مجموعة من خيارات التخصيص التي قد تهمّك، مثل:

• setAudioAttributes() لضبط معالجة أولوية الصوت
• setHandleAudioBecomingNoisy() لضبط سلوك التشغيل عند فصل جهاز إخراج الصوت
• setTrackSelector() لضبط اختيار المسار

توفّر Media3 PlayerView مكوّن واجهة مستخدم يمكنك تضمينه فيملف تنسيق تطبيقك. يتضمّن هذا المكوّن PlayerControlView لعناصر التحكّم في التشغيل وSubtitleView لعرض الترجمة والشرح وSurface لعرض الفيديو.

تحضير المشغّل

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

يجب عدم تنفيذ هذه الخطوات قبل أن يكون التطبيق في المقدّمة. إذا كان المشغِّل في وضع Activity أو Fragment، يعني ذلك أنّه يتم إعداده في onStart()method lifecycle (طريقة دورة حياة) على المستوى 24 من واجهة برمجة التطبيقات والإصدارات الأحدث أو onResume()method lifecycle (طريقة دورة الحياة) على المستوى 23 من واجهة برمجة التطبيقات والإصدارات الأقدم. بالنسبة إلى اللاعب الذي يلعب في Service، يمكنك إعداده في onCreate().

التحكّم في المشغّل

بعد تجهيز المشغّل، يمكنك التحكّم في التشغيل من خلال استدعاء طُرق على المشغّل، مثل:

• play() وpause() لبدء التشغيل وإيقافه مؤقتًا
• seekTo() للتقديم إلى موضع في ملف الوسائط الحالي
• seekToNextMediaItem() وseekToPreviousMediaItem() للتنقّل في قائمة التشغيل

سيتم تعديل مكونات واجهة المستخدم، مثل PlayerView أو PlayerControlView، وفقًا لذلك عند ربطها بمشغّل.

تحرير اللاعب

يمكن أن يتطلّب التشغيل موارد محدودة، مثل برامج فك ترميز الفيديو، لذا من المهمّ استدعاء release() في مشغّلك لإخلاء الموارد عندما لا يكون المشغّل مطلوبًا بعد الآن.

إذا كان مشغّل الوسائط في وضع Activity أو Fragment، يمكنك بدء تشغيله في onStop()method lifecycle (طريقة دورة الحياة) على المستوى 24 من واجهة برمجة التطبيقات والإصدارات الأحدث أو onPause()method (طريقة) على المستوى 23 من واجهة برمجة التطبيقات والإصدارات الأقدم. بالنسبة إلى لاعب في Service، يمكنك إصداره في onDestroy().

إدارة التشغيل باستخدام جلسة وسائط

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

لاستخدام جلسات الوسائط، أضِف عنصرًا تابعًا لمكوّن "جلسة Media3":

implementation "androidx.media3:media3-session:1.5.0"

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

يمكنك إنشاء MediaSession بعد بدء تشغيل مشغّل على النحو التالي:

val player = ExoPlayer.Builder(context).build()
val mediaSession = MediaSession.Builder(context, player).build()

ExoPlayer player = new ExoPlayer.Builder(context).build();
MediaSession mediaSession = new MediaSession.Builder(context, player).build();

تُزامن Media3 تلقائيًا حالة Player مع حالة MediaSession. يعمل هذا الإجراء مع أي عملية تنفيذ Player، بما في ذلك ExoPlayer أو CastPlayer أو تنفيذ مخصّص.

منح عناصر التحكّم لعملاء آخرين

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

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

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

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

تشغيل الوسائط في الخلفية

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

تنفيذ MediaSessionService

أنشئ فئة تمثّل MediaSessionService وأنشئ مثيلًا لمحاولة MediaSession في طريقة دورة حياة onCreate().

class PlaybackService : MediaSessionService() {
    private var mediaSession: MediaSession? = null

    // Create your Player and MediaSession in the onCreate lifecycle event
    override fun onCreate() {
        super.onCreate()
        val player = ExoPlayer.Builder(this).build()
        mediaSession = MediaSession.Builder(this, player).build()
    }

    // Remember to release the player and media session in onDestroy
    override fun onDestroy() {
        mediaSession?.run {
            player.release()
            release()
            mediaSession = null
        }
        super.onDestroy()
    }
}

public class PlaybackService extends MediaSessionService {
    private MediaSession mediaSession = null;

    @Override
    public void onCreate() {
        super.onCreate();
        ExoPlayer player = new ExoPlayer.Builder(this).build();
        mediaSession = new MediaSession.Builder(this, player).build();
    }

    @Override
    public void onDestroy() {
        mediaSession.getPlayer().release();
        mediaSession.release();
        mediaSession = null;
        super.onDestroy();
    }
}

في ملف البيان، يجب أن تتضمّن فئة Service فلتر هدف MediaSessionService وتطلب الإذن FOREGROUND_SERVICE لتشغيل خدمة تعمل في المقدّمة:

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

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

// This example always accepts the connection request
override fun onGetSession(
    controllerInfo: MediaSession.ControllerInfo
): MediaSession? = mediaSession

@Override
public MediaSession onGetSession(MediaSession.ControllerInfo controllerInfo) {
  // This example always accepts the connection request
  return mediaSession;
}

الاتصال بواجهة المستخدم

بما أنّ جلسة الوسائط متوفّرة الآن في Service منفصل عن Activity أو Fragment حيث يتوفّر واجهة مستخدم المشغّل، يمكنك استخدام MediaController لربط الجلستين معًا. في طريقة onStart() من Activity أو Fragment مع واجهة المستخدم، أنشئ SessionToken لـ MediaSession، ثم استخدِم SessionToken لإنشاء MediaController. يتم إنشاء MediaController بشكل غير متزامن.

override fun onStart() {
  val sessionToken = SessionToken(this, ComponentName(this, PlaybackService::class.java))
  val controllerFuture = MediaController.Builder(this, sessionToken).buildAsync()
  controllerFuture.addListener(
    {
        // Call controllerFuture.get() to retrieve the MediaController.
        // MediaController implements the Player interface, so it can be
        // attached to the PlayerView UI component.
        playerView.setPlayer(controllerFuture.get())
      },
    MoreExecutors.directExecutor()
  )
}

@Override
public void onStart() {
  SessionToken sessionToken =
    new SessionToken(this, new ComponentName(this, PlaybackService.class));
  ListenableFuture<MediaController> controllerFuture =
    new MediaController.Builder(this, sessionToken).buildAsync();
  controllerFuture.addListener(() -> {
    // Call controllerFuture.get() to retrieve the MediaController.
    // MediaController implements the Player interface, so it can be
    // attached to the PlayerView UI component.
    playerView.setPlayer(controllerFuture.get());
  }, MoreExecutors.directExecutor())
}

تُنفِّذ MediaController واجهة Player، لذا يمكنك استخدام METHODS نفسها، مثل play() وpause() للتحكّم في التشغيل. على غرار المكونات الأخرى، تذكَّر تحرير MediaController عندما لا يعود مطلوبًا، مثل طريقة onStop() لدورة حياة Activity، من خلال استدعاء MediaController.releaseFuture().

نشر إشعار

يجب أن تنشر الخدمات التي تعمل في المقدّمة إشعارًا عندما تكون نشطة. سينشئ MediaSessionService تلقائيًا MediaStyle إشعارًا لك على شكل MediaNotification. لتقديم إشعار مخصّص، أنشئ MediaNotification.Provider باستخدام DefaultMediaNotificationProvider.Builder أو من خلال إنشاء عملية تنفيذ مخصّصة لواجهة مقدّم الخدمة. أضِف موفّر الخدمة إلى MediaSession باستخدام setMediaNotificationProvider.

الإعلان عن مكتبة المحتوى

يستند MediaLibraryService إلى MediaSessionService من خلال السماح لتطبيقات العميل بتصفّح محتوى الوسائط الذي يوفّره تطبيقك. تنفِّذ تطبيقات العميل MediaBrowser للتفاعل مع MediaLibraryService.

يشبه تنفيذ MediaLibraryService تنفيذ MediaSessionService، باستثناء أنّه في onGetSession() يجب عرض MediaLibrarySession بدلاً من MediaSession. مقارنةً بملف MediaSession.Callback، يتضمّن ملف MediaLibrarySession.Callback مزيدًا من الخطوات التي تسمح لأحد عملاء المتصفّح بالتنقّل في المحتوى الذي تقدّمه خدمة مكتبتك.

على غرار MediaSessionService، يجب تقديم بيان عن MediaLibraryService في بيان التطبيق وطلب إذن FOREGROUND_SERVICE لتشغيل خدمة تعمل في المقدّمة:

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaLibraryService"/>
        <action android:name="android.media.browse.MediaBrowserService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

يتضمّن المثال أعلاه فلتر أهداف لكل من MediaLibraryService وMediaBrowserService القديم، وذلك للتوافق مع الإصدارات القديمة. يتيح فلتر الأهداف الإضافي لتطبيقات العملاء التي تستخدم واجهة برمجة التطبيقات MediaBrowserCompat التعرّف على Service.

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

إنشاء MediaLibrarySession

تُوسّع واجهة برمجة التطبيقات MediaLibrarySession واجهة برمجة التطبيقات MediaSession API لإضافة واجهات برمجة تطبيقات لتصفّح المحتوى. مقارنةً بأسلوب MediaSession ردّ الاتصال، يضيف أسلوبMediaLibrarySession ردّ الاتصال طُرقًا مثل:

• onGetLibraryRoot() للحالات التي يطلب فيها العميل الجذر MediaItem لشجرة محتوى
• ‫onGetChildren() للحالات التي يطلب فيها العميل عناصر MediaItem في شجرة المحتوى
• onGetSearchResult() لحالات طلب العميل لنتائج البحث من شجرة المحتوى لطلب بحث معيّن

ستتضمّن طرق الاستدعاء ذات الصلة عنصر LibraryParams يتضمّن إشارات إضافية حول نوع شجرة المحتوى التي يهتم بها تطبيق العميل.