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

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

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

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

إضافة ExoPlayer كملحق

إضافة وحدات ExoPlayer

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

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

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

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

توفّر مكتبة ExoPlayer مجموعة من مكونات واجهة المستخدم المنشأة مسبقًا للوسائط التشغيل. وتشمل PlayerView، التي تضم PlayerControlView وSubtitleView وSurface لتحديد الفيديو المعروضة. يمكن تضمين PlayerView في تنسيق 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 باستخدام واجهة برمجة تطبيقات ExoPlayer setVideoSurfaceView وsetVideoTextureView وsetVideoSurfaceHolder و setVideoSurface طريقة على التوالي يمكن لطريقة 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.