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

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

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

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

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

إضافة وحدات ExoPlayer

إنّ أسهل طريقة لبدء استخدام AndroidX Media3 هي إضافة درجات اعتمادية إلى المكتبات التي تحتاج إليها في ملف 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، بينما يجب إنشاء البعض الآخر يدويًا. يمكنك تصفُّح دليل المكتبات والاطّلاع على الملفات الشخصية الفردية للحصول على التفاصيل.

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

تشغيل دعم Java 8

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

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

تفعيل ميزة الوسائط المتعددة

إذا كانت قيمة minSdkVersion في Gradle 20 أو أقل، عليك تفعيل ميزة الوسائط المتعددة لمنع حدوث أخطاء في الإصدار.

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

يمكنك إنشاء مثيل 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.

لمزيد من المعلومات حول نموذج سلاسل المحادثات في 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();

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

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

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

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

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

ارفع إصبعك عن المشغّل.

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