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

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

• عناصر التحكّم في وسائط نظام Android
• التطبيق المصاحب لنظام التشغيل Android Wear OS
• Android Auto ونظام التشغيل Automotive
• المساعدات الصوتية، مثل مساعد Google
• تطبيق Media Controller Test

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

إنشاء MediaController

لإنشاء MediaController، ابدأ بإنشاء SessionToken للسمة MediaSession المقابلة. قد تكون طريقة onStart() لـ Activity أو Fragment خيارًا مناسبًا لهذا الغرض.

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

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

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

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

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.

MediaController.releaseFuture(controllerFuture)

MediaController.releaseFuture(controllerFuture);

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

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

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

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

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

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

// 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())

// 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:

// 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())

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());