البدء

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

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

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

إضافة ExoPlayer كعنصر تابع

إضافة وحدات ExoPlayer

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

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

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

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

حيث يمثّل 1.7.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، الذي يوفّر مجموعة من خيارات التخصيص. التعليمة البرمجية التالية هي أبسط مثال على إنشاء مثيل.

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

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

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

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

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

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

ربط مشغّل بمشهد

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

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

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

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

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

android:keepScreenOn="true"

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

ملء قائمة التشغيل وتجهيز مشغّل الفيديو

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

// 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()

// 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 استخدام قوائم التشغيل مباشرةً، لذا يمكن إعداد المشغّل باستخدام عناصر وسائط متعددة ليتم تشغيلها الواحدة تلو الأخرى:

// 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()

// 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 سرعة التشغيل وطبقة الصوت.

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

إزالة المشغّل

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