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

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

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

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

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

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

تفعيل ميزة "التوافق مع Java 8"

إذا لم يكن مفعّلاً، عليك تفعيل دعم Java 8 في جميع build.gradle الملفات التي تعتمد على ExoPlayer، وذلك عن طريق إضافة ما يلي إلى قسم android:

compileOptions {
  targetCompatibility JavaVersion.VERSION_1_8
}

تفعيل حزمة multidex

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

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

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

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

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

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

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

// 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 لبدء التشغيل:

// 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.