البدء

يتطلب بدء استخدام ExoPlayer تنفيذ الخطوات التالية:

  1. أضِف ExoPlayer كعنصر تابع لمشروعك.
  2. أنشِئ مثيلاً لـ ExoPlayer.
  3. ربط المشغّل بطريقة عرض (لإخراج الفيديو وإدخال المستخدم)
  4. يجب إعداد المشغّل باستخدام MediaItem لتشغيل المحتوى.
  5. ارفع إصبعك عن الشاشة عند الانتهاء.

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

إضافة ExoPlayer كتبعية

لاستخدام ExoPlayer في تطبيقك، أضِف الوحدات المطلوبة وفعِّل دعم Java 8.

إضافة وحدات ExoPlayer

أسهل طريقة لبدء استخدام AndroidX Media3 هي إضافة تبعيات gradle على المكتبات التي تحتاجها في ملف build.gradle الخاص بوحدة تطبيقك.

على سبيل المثال، للاعتماد على ExoPlayer مع ميزة تشغيل DASH ومكوّنات واجهة المستخدم، يمكنك إضافة تبعيات على الوحدات على النحو التالي:

Kotlin

implementation("androidx.media3:media3-exoplayer:1.11.1")
implementation("androidx.media3:media3-exoplayer-dash:1.11.1")
implementation("androidx.media3:media3-ui:1.11.1")
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

أنيق

implementation "androidx.media3:media3-exoplayer:1.11.1"
implementation "androidx.media3:media3-exoplayer-dash:1.11.1"
implementation "androidx.media3:media3-ui:1.11.1"
implementation("androidx.media3:media3-ui-compose-material3:1.11.1")

حيث يمثّل 1.11.1 الإصدار المفضّل لديك (يمكن العثور على أحدث إصدار من خلال الاطّلاع على ملاحظات الإصدار). يجب أن تكون جميع الوحدات من الإصدار نفسه.

تحتوي AndroidX Media3 على وحدات مكتبة تعتمد على مكتبات خارجية لتوفير وظائف إضافية. يتوفّر بعضها من مستودع Maven، بينما يجب إنشاء البعض الآخر يدويًا. تصفَّح دليل المكتبات واطّلِع على ملفات README الفردية للحصول على التفاصيل.

يمكنك الاطّلاع على مزيد من المعلومات حول وحدات المكتبة المتاحة في صفحة Google Maven AndroidX Media.

تفعيل Java 8

إذا لم تكن ميزة Java 8 مفعَّلة، عليك تفعيلها على الأقل في جميع ملفات build.gradle التي تعتمد على ExoPlayer، وذلك من خلال إضافة ما يلي إلى قسم android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

إنشاء المشغّل

يمكنك إنشاء مثيل ExoPlayer باستخدام ExoPlayer.Builder، والذي يوفر مجموعة من خيارات التخصيص. الرمز التالي هو أبسط مثال على إنشاء مثيل.

Kotlin

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

Java

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

ملاحظة حول سلاسل المحادثات

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

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

لمزيد من المعلومات حول نموذج سلاسل المحادثات في ExoPlayer، يُرجى الاطّلاع على قسم "نموذج سلاسل المحادثات" في ExoPlayer Javadoc.

ربط المشغّل بطريقة عرض

توفّر مكتبة media3-ui مجموعة من عناصر واجهة المستخدم المُعدّة مسبقًا لتشغيل الوسائط. وتشمل هذه الفئات PlayerView التي تتضمّن PlayerControlView وSubtitleView وSurface يتم عرض الفيديو عليها. يمكن تضمين PlayerView في ملف xml الخاص بتنسيق تطبيقك. على سبيل المثال، لربط المشغّل بالعرض:

Kotlin

// Bind the player to the view.
playerView.player = player

Java

// Bind the player to the view.
playerView.setPlayer(player);

يُعدّ استخدام مكوّنات واجهة المستخدم المُعدّة مسبقًا في Media3 اختياريًا. بالنسبة إلى تطبيقات الفيديو التي تستخدم واجهة المستخدم الخاصة بها، يمكن ضبط الهدف SurfaceView أو TextureView أو SurfaceHolder أو Surface باستخدام طرق setVideoSurfaceView وsetVideoTextureView وsetVideoSurfaceHolder وsetVideoSurface في المشغّل على التوالي. يمكن استخدام دالة الاستدعاء Listener.onCues لتلقّي الترجمة والشرح التي يجب عرضها أثناء التشغيل، ويمكن استخدام setImageOutput لتلقّي الصور التي تم فك ترميزها.

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

android:keepScreenOn="true"

إذا كان تطبيقك يستخدم Jetpack Compose لواجهة المستخدم، يمكنك استخدام الدالة المركّبة Player من مكتبة media3-ui-compose-material3. يعرض Player الفيديو ويتضمّن قيمًا معبأة تلقائيًا لمواضع عناصر التحكّم في التشغيل. لإرفاق عنصر androidx.media3.common.Player بدالة مركّبة androidx.media3.ui.compose.material3.Player، ما عليك سوى تمريره كوسيطة:

// Bind the player to the composable.
Player(player = player)

يمكنك الاطّلاع على مزيد من المعلومات حول استخدام مكوّنات واجهة مستخدم Media3 وتخصيصها في صفحة واجهة المستخدم.

تعبئة قائمة التشغيل وإعداد المشغّل

في ExoPlayer، يتم تمثيل كل ملف وسائط من خلال MediaItem. لتشغيل ملف وسائط، عليك إنشاء MediaItem مطابق وإضافته إلى المشغّل، ثم إعداد المشغّل واستدعاء play لبدء التشغيل:

Kotlin

// Build the media item.
val mediaItem = MediaItem.fromUri(videoUri)
// Set the media item to be played.
player.setMediaItem(mediaItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media item.
MediaItem mediaItem = MediaItem.fromUri(videoUri);
// Set the media item to be played.
player.setMediaItem(mediaItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

يتيح ExoPlayer استخدام قوائم التشغيل مباشرةً، لذا من الممكن إعداد المشغّل باستخدام ملفات وسائط متعددة ليتم تشغيلها واحدًا تلو الآخر:

Kotlin

// Build the media items.
val firstItem = MediaItem.fromUri(firstVideoUri)
val secondItem = MediaItem.fromUri(secondVideoUri)
// Add the media items to be played.
player.addMediaItem(firstItem)
player.addMediaItem(secondItem)
// Prepare the player.
player.prepare()
// Start the playback.
player.play()

Java

// Build the media items.
MediaItem firstItem = MediaItem.fromUri(firstVideoUri);
MediaItem secondItem = MediaItem.fromUri(secondVideoUri);
// Add the media items to be played.
player.addMediaItem(firstItem);
player.addMediaItem(secondItem);
// Prepare the player.
player.prepare();
// Start the playback.
player.play();

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

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

بعد إعداد المشغّل، يمكن التحكّم في التشغيل من خلال استدعاء الطرق على المشغّل. في ما يلي بعض الطرق الأكثر شيوعًا:

  • يؤدي الضغط على play وpause إلى بدء التشغيل وإيقافه مؤقتًا.
  • تتيح السمة seekTo البحث داخل الوسائط.
  • تتيح لك الأزرار hasPrevious وhasNext وprevious وnext التنقّل في قائمة التشغيل.
  • يتحكّم setRepeatMode في ما إذا كان سيتم تكرار الوسائط وكيفية تكرارها.
  • يتحكّم "setShuffleModeEnabled" في الترتيب العشوائي لقائمة التشغيل.
  • يضبط "setPlaybackParameters" سرعة التشغيل ودرجة الصوت.
  • تعمل السمة setScrubbingModeEnabled على تحسين المشغّل لعمليات البحث المتكررة أثناء سحب المستخدم لشريط التمرير. لمعرفة التفاصيل، يُرجى الاطّلاع على وضع التصفية.

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

تحرير اللاعب

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