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

نصيحة: يمكنك أيضًا البدء من خلال العمل من خلال الدرس التطبيقي حول الترميز ExoPlayer.

في حالات الاستخدام البسيطة، يتألف بدء استخدام 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.3.1")
implementation("androidx.media3:media3-exoplayer-dash:1.3.1")
implementation("androidx.media3:media3-ui:1.3.1")

رائع

implementation "androidx.media3:media3-exoplayer:1.3.1"
implementation "androidx.media3:media3-exoplayer-dash:1.3.1"
implementation "androidx.media3:media3-ui:1.3.1"

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

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

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

تفعيل دعم Java 8

إذا لم يتم التفعيل من قبل، يجب تفعيل دعم Java 8 في جميع ملفات build.gradle التي تعتمد على ExoPlayer، من خلال إضافة ما يلي إلى قسم android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

تفعيل Multidex

إذا كان حجم minSdkVersion في Gradle 20 أو أقل، يجب تفعيل Multidex لمنع حدوث أخطاء الإصدار.

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

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

Kotlin

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

Java

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

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

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

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

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

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

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

وتوفر مكتبة ExoPlayer مجموعة من مكونات واجهة المستخدم التي تم إنشاؤها مسبقًا لتشغيل الوسائط. وتشمل هذه الأنواع 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);

يمكنك أيضًا استخدام PlayerControlView كمكون مستقل، وهو مفيد لحالات استخدام الصوت فقط.

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

تعبئة قائمة التشغيل وتحضير المشغّل

في 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();

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

ملاحظة: تحوّل Media3 ExoPlayer عناصر الوسائط إلى MediaSource مثيلات تحتاج إليها داخليًا. يمكنك الاطّلاع على مزيد من المعلومات عن هذه العملية وكيفية تخصيصها على صفحة مصادر الوسائط. يمكنك تقديم MediaSource مباشرةً للّاعب باستخدام ExoPlayer.setMediaSource(s) وExoPlayer.addMediaSource(s).

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

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

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

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

حرر المشغّل

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