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

تتفاعل وحدة التحكم في الوسائط مع جلسة وسائط للاستعلام عن الوسائط والتحكم فيها لتشغيل التطبيق. في 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());