عرض المحتوى باستخدام MediaLibraryService

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

الشكل 1: أمثلة على التسلسلات الهرميّة لملفّات الوسائط التي تشكّل مكتبة وسائط.

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

إنشاء MediaLibraryService

يشبه تنفيذ MediaLibraryService تنفيذ MediaSessionService، باستثناء أنّه في طريقة onGetSession()، يجب عرض MediaLibrarySession بدلاً من MediaSession.

Kotlin

class PlaybackService : MediaLibraryService() {
  var mediaLibrarySession: MediaLibrarySession? = null
  var callback: MediaLibrarySession.Callback = object : MediaLibrarySession.Callback {...}

  // If desired, validate the controller before returning the media library session
  override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaLibrarySession? =
    mediaLibrarySession

  // Create your player and media library session in the onCreate lifecycle event
  override fun onCreate() {
    super.onCreate()
    val player = ExoPlayer.Builder(this).build()
    mediaLibrarySession = MediaLibrarySession.Builder(this, player, callback).build()
  }

  // Remember to release the player and media library session in onDestroy
  override fun onDestroy() {
    mediaLibrarySession?.run { 
      player.release()
      release()
      mediaLibrarySession = null
    }
    super.onDestroy()
  }
}

Java

class PlaybackService extends MediaLibraryService {
  MediaLibrarySession mediaLibrarySession = null;
  MediaLibrarySession.Callback callback = new MediaLibrarySession.Callback() {...};

  @Override
  public MediaLibrarySession onGetSession(MediaSession.ControllerInfo controllerInfo) {
    // If desired, validate the controller before returning the media library session
    return mediaLibrarySession;
  }

  // Create your player and media library session in the onCreate lifecycle event
  @Override
  public void onCreate() {
    super.onCreate();
    ExoPlayer player = new ExoPlayer.Builder(this).build();
    mediaLibrarySession = new MediaLibrarySession.Builder(this, player, callback).build();
  }

  // Remember to release the player and media library session in onDestroy
  @Override
  public void onDestroy() {
    if (mediaLibrarySession != null) {
      mediaLibrarySession.getPlayer().release();
      mediaLibrarySession.release();
      mediaLibrarySession = null;
    }
    super.onDestroy();
  }
}

يُرجى أيضًا تقديم بيان عن Service والأذونات المطلوبة في ملف البيان:

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<!-- For targetSdk 34+ -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

ملاحظة: لضمان التوافق مع الإصدارات القديمة من واجهات برمجة التطبيقات للوسائط، يمكنك أيضًا تضمين <action android:name="android.media.browse.MediaBrowserService"/> في عنصر intent-filter.

استخدام MediaLibrarySession

تتوقع واجهة برمجة التطبيقات MediaLibraryService أن تكون مكتبة الوسائط منضمّنة في ملف بتنسيق شجرة، مع عقدة جذر واحدة وعقد فرعية قد تكون قابلة للتشغيل أو قابلة للتصفّح بشكل أكبر.

تُوسّع واجهة برمجة التطبيقات MediaLibrarySession واجهة برمجة التطبيقات MediaSession API لإضافة واجهات برمجة تطبيقات لتصفّح المحتوى. مقارنةً بأسلوب MediaSession ردّ الاتصال، يضيف أسلوبMediaLibrarySession ردّ الاتصال طُرقًا مثل:

• onGetLibraryRoot() للحالات التي يطلب فيها العميل الجذر MediaItem لشجرة محتوى
• ‫onGetChildren() للحالات التي يطلب فيها العميل عناصر MediaItem في شجرة المحتوى
• onGetSearchResult() لحالات طلب العميل لنتائج البحث من شجرة المحتوى لطلب بحث معيّن

ستتضمّن طرق الاستدعاء ذات الصلة عنصر LibraryParams يتضمّن إشارات إضافية حول نوع شجرة المحتوى التي يهتم بها تطبيق العميل.