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

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

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

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

يحتوي 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 لسلسلة المحادثات الرئيسية للتطبيق. في جميع الحالات، يمكن استخدام Player.getApplicationLooper للاطّلاع على Looper من سلسلة المحادثات التي يجب الوصول إلى المشغّل من خلالها.

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

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

توفّر مكتبة 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.