بالنسبة إلى حالات الاستخدام البسيطة، يتألف بدء استخدام ExoPlayer
من تنفيذ الخطوات التالية:
- أضف ExoPlayer كتبعية لمشروعك.
- إنشاء مثيل
ExoPlayer
- إرفاق المشغّل بطريقة عرض (لإخراج الفيديو وإدخال المستخدم)
- يمكنك إعداد المشغّل باستخدام
MediaItem
للّعب. - ارفع إصبعك عن المشغّل عند الانتهاء.
في ما يلي توضيح مفصَّل لهذه الخطوات. للاطّلاع على مثال كامل، يمكنك الرجوع إلى
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
.