إنشاء 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: إرجاع 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