وتتفاعل وحدة التحكم في الوسائط مع جلسة وسائط للاستعلام عن تشغيل تطبيق الوسائط والتحكم فيه. في Media3، تنفّذ واجهة برمجة التطبيقات
MediaController
واجهة Player
. تتضمن أمثلة تطبيقات العميل التي تستخدم
وحدة تحكم في الوسائط ما يلي:
- عناصر التحكّم في وسائط نظام Android
- التطبيق المصاحب لنظام التشغيل Android Wear OS
- Android Auto ونظام التشغيل Automotive
- المساعدات الصوتية، مثل مساعد Google
- تطبيق Media Controller Test
ويمكن الاستفادة من وحدة التحكّم في الوسائط أيضًا داخل تطبيق وسائط، مثلاً إذا كانت جلسة المشغّل وجلسة الوسائط معروضة في 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());