الربط بتطبيق وسائط

يتفاعل جهاز التحكّم في الوسائط مع جلسة وسائط للاستعلام عن تشغيل تطبيق وسائط والتحكّم فيه. في Media3، تنفِّذ واجهة برمجة التطبيقات MediaController واجهة Player. ومن أمثلة تطبيقات العميل التي تستخدم وحدة تحكُّم في الوسائط ما يلي:

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

إنشاء MediaController

لإنشاء MediaController، ابدأ بإنشاء SessionToken للMediaSession المعنيّ. يمكن أن تكون طريقة onStart() في Activity أو Fragment مكانًا جيدًا لإجراء ذلك.

Kotlin

val sessionToken = 
  SessionToken(context, ComponentName(context, PlaybackService::class.java))

Java

SessionToken sessionToken = 
  new SessionToken(context, new ComponentName(context, PlaybackService.class));

يؤدي استخدام هذا العنصر SessionToken لإنشاء MediaController بعد ذلك إلى ربط وحدة التحكّم بالجلسة المحدّدة. يتم ذلك بشكل غير متزامن، لذا عليك الانتظار إلى أن تظهر النتيجة واستخدامها عند توفّرها.

Kotlin

val controllerFuture =
  MediaController.Builder(context, sessionToken).buildAsync()
controllerFuture.addListener({
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaController> controllerFuture =
  new MediaController.Builder(context, sessionToken).buildAsync();
controllerFuture.addListener(() -> {
  // MediaController is available here with controllerFuture.get()
}, MoreExecutors.directExecutor());

استخدام MediaController

ينفِّذ MediaController الواجهة Player، لذا يمكنك استخدام الأوامر المحددة في الواجهة للتحكّم في تشغيل MediaSession المرتبطة. وهذا يعني أنّ استدعاء play() على MediaController سيؤدي إلى إرسال الأمر إلى MediaSession المتصل، والذي سيفوض بعد ذلك الأمر إلى Player الأساسي.

وبالمثل، يمكنك إضافة Player.Listener إلى وحدة التحكّم للانتباه إلى التغييرات في حالة Player. راجِع دليل أحداث اللاعبين لمزيد من التفاصيل حول استخدام Player.Listener. تحدِّد واجهة MediaController.Listener وظائف استدعاء إضافية للأحداث والأوامر الواردة منMediaSession المتصل، مثل onAvailableSessionCommandsChanged() عندما تغيِّر جلسة الوسائط أوامر الجلسة المتاحة وonDisconnected() عندما يتم فصل وحدة التحكّم عن الجلسة.

كما هو الحال مع المكوّنات الأخرى، احرص على إزالة MediaController عندما لم تعُد مطلوبة، مثل طريقة onStop() في Activity أو Fragment.

Kotlin

MediaController.releaseFuture(controllerFuture)

Java

MediaController.releaseFuture(controllerFuture);

سيظلّ تحرير وحدة التحكّم يُرسِل جميع الأوامر التي في انتظار المعالجة المُرسَلة إلى الجلسة، ولن يتم إلغاء الربط بخدمة الجلسة إلا بعد معالجة هذه الأوامر أو بعد فترة مهلة، أيهما يحدث أولاً.

إنشاء MediaBrowser واستخدامه

تستند MediaBrowser إلى الإمكانات التي يوفّرها MediaController لتفعيل تصفُّح مكتبة الوسائط التي يوفّرهاMediaLibraryService في تطبيق الوسائط.

Kotlin

val browserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
browserFuture.addListener({
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor())

Java

ListenableFuture<MediaBrowser> browserFuture =
  new MediaBrowser.Builder(context, sessionToken).buildAsync();
browserFuture.addListener(() -> {
  // MediaBrowser is available here with browserFuture.get()
}, MoreExecutors.directExecutor());

لبدء تصفُّح مكتبة محتوى تطبيق الوسائط، عليك أولاً استرداد العقدة الجذر باستخدام getLibraryRoot():

Kotlin

// Get the library root to start browsing the library tree.
val rootFuture = mediaBrowser.getLibraryRoot(/* params= */ null)
rootFuture.addListener({
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor())

Java

// Get the library root to start browsing the library tree.
ListenableFuture<LibraryResult<MediaItem>> rootFuture =
  mediaBrowser.getLibraryRoot(/* params= */ null);
rootFuture.addListener(() -> {
  // Root node MediaItem is available here with rootFuture.get().value
}, MoreExecutors.directExecutor());

يمكنك بعد ذلك التنقّل في مكتبة الوسائط من خلال استرداد العناصر الفرعية لملف MediaItem في المكتبة باستخدام getChildren(). على سبيل المثال، لاسترداد العناصر الفرعية للعُقدة الجذر MediaItem:

Kotlin

// Get the library root to start browsing the library tree.
val childrenFuture = 
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Int.MAX_VALUE, null)
childrenFuture.addListener({
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor())

Java

ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> childrenFuture =
  mediaBrowser.getChildren(rootMediaItem.mediaId, 0, Integer.MAX_VALUE, null);
childrenFuture.addListener(() -> {
  // List of children MediaItem nodes is available here with
  // childrenFuture.get().value
}, MoreExecutors.directExecutor());