إنشاء DefaultPreloadManager وإعداده

توضّح هذه الصفحة كيفية إنشاء DefaultPreloadManager، والذي يحمّل مسبقًا محتوى الوسائط لتطبيقك استنادًا إلى الاستراتيجية التي تختارها.

تتيح لك أدوات إدارة التحميل المُسبق المستندة إلى الفئة المجرّدة BasePreloadManager ترتيب المحتوى حسب المعايير التي تختارها. يشرح هذا المستند كيفية استخدام الفئة المشتقة DefaultPreloadManager، حيث يتم ترتيب كل ملف وسائط برقم صحيح يمثّل موقعه في قائمة (على سبيل المثال، موضعه في لوحة عرض دوّارة للفيديوهات). يعطي مدير التحميل المُسبق الأولوية لتحميل العناصر بناءً على مدى قربها من العنصر الذي يشغّله المستخدم حاليًا. بهذه الطريقة، إذا انتقل المستخدم إلى عنصر آخر، يمكن أن يبدأ تشغيل العنصر الجديد على الفور.

هناك ثلاث خطوات لإنشاء مثيل من DefaultPreloadManager:

• حدِّد TargetPreloadStatusControl يمكن لمدير التحميل المُسبَق الاستعلام عنه لمعرفة ما إذا كان ملف الوسائط جاهزًا للتحميل ومقدار التحميل.
• أنشئ أداة الإنشاء التي ستستخدمها لإنشاء مدير التحميل المُسبَق، ولإنشاء عناصر ExoPlayer في تطبيقك.
• استخدِم أداة الإنشاء لإنشاء مدير التحميل المُسبَق من خلال استدعاء طريقة build() الخاصة بأداة الإنشاء.

إنشاء عنصر تحكّم في حالة التحميل المُسبَق المستهدَفة

عند إنشاء DefaultPreloadManager.Builder، عليك تمرير عنصر التحكّم في حالة التحميل المُسبَق المستهدَف الذي تحدّده. ينفّذ هذا العنصر واجهة TargetPreloadStatusControl. عندما يستعد مدير التحميل المُسبق لتحميل الوسائط مسبقًا، يستدعي الأسلوب getTargetPreloadStatus() الخاص بعنصر التحكّم في الحالة لتحديد ما إذا كان سيتم إعداد المحتوى أو تحميله أو تخزينه مؤقتًا لملف وسائط. يؤدي التحميل إلى تحميل بيانات الوسائط مسبقًا مباشرةً في ذاكرة التخزين المؤقت في المشغّل، ما يجعلها جاهزة للتشغيل الفوري، بينما يؤدي التخزين المؤقت إلى حفظ بيانات الوسائط في ذاكرة تخزين مؤقت للقرص الدائم لتوفير ذاكرة المشغّل. يمكن أن يردّ عنصر التحكّم في الحالة بأحد رموز الحالة التالية:

• STAGE_SPECIFIED_RANGE_LOADED: يجب أن يحمّل مدير التحميل المُسبَق المحتوى من موضع البدء المحدّد وللمدة المحدّدة (بالملي ثانية) في المخزن المؤقت في الذاكرة للمشغّل.
• ‫STAGE_SPECIFIED_RANGE_CACHED: على مدير التحميل المُسبَق تخزين المحتوى مؤقتًا من موضع البدء المحدّد وللمدة المحدّدة (بالملي ثانية) في ذاكرة التخزين المؤقت للقرص.
• ‫STAGE_TRACKS_SELECTED: يجب أن يحمّل مدير التحميل المُسبَق معلومات المقطع الصوتي للمحتوى ويعالجها، ثم يختار المقاطع الصوتية. يجب ألا يبدأ مدير التحميل المُسبق في تحميل المحتوى بعد.
• STAGE_SOURCE_PREPARED: يجب أن يُعدّ مدير التحميل المُسبق مصدر المحتوى. على سبيل المثال، إذا كانت البيانات الوصفية للمحتوى في ملف بيان منفصل، قد يجلب مدير التحميل المُسبق هذا البيان ويحلّله.
• ‫null: يجب ألا يحمّل مدير التحميل المُسبَق أي محتوى أو بيانات وصفية لملف الوسائط هذا.

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

• الفهرس n+1 (ملف الوسائط التالي): يتم تحميل 3000 ملي ثانية (3 ثوانٍ) من موضع البدء التلقائي
• الفهرس n-1 (ملف الوسائط السابق): يتم تحميل 1000 ملي ثانية (ثانية واحدة) من موضع البدء التلقائي
• ملفات الوسائط الأخرى في النطاق من n-2 إلى n+2: زرّ Return PreloadStatus.TRACKS_SELECTED
• ملفات الوسائط الأخرى في النطاق من n-4 إلى n+4: زرّ Return PreloadStatus.SOURCE_PREPARED
• بالنسبة إلى جميع ملفات الوسائط الأخرى، يتم عرض null

class MyTargetPreloadStatusControl(var currentPlayingIndex: Int = 0) :
  TargetPreloadStatusControl<Int, DefaultPreloadManager.PreloadStatus> {

  override fun getTargetPreloadStatus(index: Int): DefaultPreloadManager.PreloadStatus {
    if (index - currentPlayingIndex == 1) { // next track
      // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
      // suggest loading 3000ms from the default start position
      return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
    } else if (index - currentPlayingIndex == -1) { // previous track
      // return a PreloadStatus that is labelled by STAGE_SPECIFIED_RANGE_LOADED and
      // suggest loading 3000ms from the default start position
      return DefaultPreloadManager.PreloadStatus.specifiedRangeLoaded(3000L)
    } else if (abs(index - currentPlayingIndex) == 2) {
      // return a PreloadStatus that is labelled by STAGE_TRACKS_SELECTED
      return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_TRACKS_SELECTED
    } else if (abs(index - currentPlayingIndex) <= 4) {
      // return a PreloadStatus that is labelled by STAGE_SOURCE_PREPARED
      return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_SOURCE_PREPARED
    }
    return DefaultPreloadManager.PreloadStatus.PRELOAD_STATUS_NOT_PRELOADED
  }
}
PreloadManagerCreate.kt

نقاط رئيسية حول الرمز

• ستمرّر مثيلاً من MyTargetPreloadStatusControl إلى أداة إنشاء مدير التحميل المُسبَق عند إنشائه.
• يحتوي currentPlayingIndex على فهرس ملف الوسائط الذي يتم تشغيله حاليًا. وتتمثل مهمة التطبيق في إبقاء هذه القيمة محدّثة.
• عندما يصبح مدير التحميل المُسبق جاهزًا لتحميل المحتوى، يستدعي getTargetPreloadStatus ويمرّر معلومات الترتيب التي حدّدتها لملف الوسائط المقابل. في حالة DefaultPreloadManager، تكون معلومات الترتيب هذه عددًا صحيحًا، يحدد موضع العنصر في لوحة عرض دوّارة. تختار الطريقة الرمز الذي سيتم عرضه من خلال مقارنة هذا الفهرس مع فهرس العنصر المحدّد حاليًا.

إنشاء مدير التحميل المُسبَق

لإنشاء مدير التحميل المُسبَق، تحتاج إلى DefaultPreloadManager.Builder. يتم ضبط أداة الإنشاء هذه باستخدام السياق الحالي وعنصر التحكّم في حالة التحميل المُسبق المستهدَف للتطبيق. يمكنك إنشاء مدير تحميل مسبق بجميع الإعدادات التلقائية.

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder = DefaultPreloadManager.Builder(context, targetPreloadStatusControl)
val preloadManager = preloadManagerBuilder.build()
PreloadManagerCreate.kt

توفّر أداة الإنشاء أيضًا طرق ضبط يمكنك استخدامها لضبط المكوّنات المخصّصة لمدير التحميل المُسبَق.

على سبيل المثال، يمكنك تخصيص إجمالي وحدات البايت الاحتياطية المستهدَفة لجميع مصادر الوسائط التي يتم تحميلها مسبقًا في DefaultPreloadManager، بحيث لا تتجاوز البيانات التي تم تحميلها مسبقًا هذا الحدّ. يمكنك ضبط هذا الحدّ باستخدام setPlayerTargetBufferBytes(String, int) في DefaultLoadControl.Builder مخصّص يحمل اسم المشغّل "preload" وتمرير هذه النسخة إلى أداة إنشاء مدير التحميل المُسبَق:

val targetPreloadStatusControl = MyTargetPreloadStatusControl()
val preloadManagerBuilder = DefaultPreloadManager.Builder(context, targetPreloadStatusControl)

preloadManagerBuilder.setLoadControl(
  DefaultLoadControl.Builder()
    .setPlayerTargetBufferBytes("preload", 128 * 1024 * 1024) // 128 MiB
    .build()
)
val preloadManager = preloadManagerBuilder.build()
PreloadManagerCreate.kt

على الرغم من أنّ طرق الضبط في أداة الإنشاء اختيارية بشكل أساسي للتخصيص، إذا أردت تخزين أي ملفات وسائط مؤقتًا على القرص، عليك ضبط أداة الإنشاء باستخدام Cache من خلال استدعاء setCache(). في حال عدم ضبط أي ذاكرة تخزين مؤقت، ستؤدي محاولة تخزين ملفات الوسائط مؤقتًا إلى ظهور الخطأ IllegalStateException.

إنشاء ExoPlayer لتشغيل ملف الوسائط الذي تم تحميله مسبقًا

بالإضافة إلى استخدام أداة الإنشاء لإنشاء مدير التحميل المُسبق، ستستخدمها أيضًا لإنشاء عناصر ExoPlayer التي يستخدمها تطبيقك لتشغيل المحتوى، لكي يشارك ExoPlayer المكوّنات بشكل صحيح مع مدير التحميل المُسبق. لا يزال بإمكانك ضبط الإعدادات الخاصة بالتشغيل لـ ExoPlayer من خلال تمرير مثيل ExoPlayer.Builder مع ضبط هذه الإعدادات.

// Direct creation
val exoPlayer = preloadManagerBuilder.buildExoPlayer()

// Creation with custom playback specific configurations
val skipSilenceExoPlayerBuilder = ExoPlayer.Builder(context).setSkipSilenceEnabled(true)
val skipSilenceExoPlayer = preloadManagerBuilder.buildExoPlayer(skipSilenceExoPlayerBuilder)
PreloadManagerCreate.kt