البدء

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

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

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

إضافة ExoPlayer كاعتمادية

إضافة وحدات ExoPlayer

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

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

Kotlin

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

أنيق

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

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

يتضمّن 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()
HelloWorld.kt

Java

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

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

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

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

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

ربط المشغّل بعرض

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

Kotlin

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

Java

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

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

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

android:keepScreenOn="true"

يمكنك الاطّلاع على مزيد من المعلومات عن استخدام مكوّنات واجهة مستخدم 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()
HelloWorld.kt

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();
HelloWorld.java

يتيح 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()
HelloWorld.kt

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();
HelloWorld.java

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

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

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

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

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

إيقاف المشغّل

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