هناك طريقتان للاتصال بتطبيق موسيقى:
MediaControllerMediaBrowser
MediaController
تتفاعل وحدة التحكّم في الوسائط مع جلسة وسائط للاستعلام عن تشغيل تطبيق وسائط والتحكّم فيه. في 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 المرتبط. وتتضمّن الأمثلة ما يلي:
onCustomCommand() عندما ترسل الجلسة أمرًا مخصّصًا،
onAvailableSessionCommandsChanged() عندما تغيّر الجلسة أوامر الجلسة المتاحة،
أو onDisconnected() عندما يتم فصل وحدة التحكّم
عن الجلسة.
يمكن ضبط MediaController.Listener عند إنشاء وحدة التحكّم باستخدام Builder:
Kotlin
val controllerFuture = MediaController.Builder(context, sessionToken) .setListener( object : MediaController.Listener { override fun onCustomCommand( controller: MediaController, command: SessionCommand, args: Bundle, ): ListenableFuture<SessionResult> { // Handle custom command. return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS)) } override fun onDisconnected(controller: MediaController) { // Handle disconnection. } } ) .buildAsync()
Java
ListenableFuture<MediaController> controllerFuture = new MediaController.Builder(context, sessionToken) .setListener( new MediaController.Listener() { @Override public ListenableFuture<SessionResult> onCustomCommand( MediaController controller, SessionCommand command, Bundle args) { // Handle custom command. return Futures.immediateFuture(new SessionResult(SessionResult.RESULT_SUCCESS)); } @Override public void onDisconnected(MediaController controller) { // Handle disconnection. } }) .buildAsync();
كما هو الحال مع المكوّنات الأخرى، تذكَّر إصدار MediaController عندما لا تكون هناك حاجة إليه، مثلاً في طريقة onStop() الخاصة بـ Activity أو Fragment.
Kotlin
MediaController.releaseFuture(controllerFuture)
Java
MediaController.releaseFuture(controllerFuture);
سيؤدي تحرير وحدة التحكّم إلى إرسال جميع الأوامر المعلّقة إلى الجلسة، ولن يتم إلغاء الربط من خدمة الجلسة إلا بعد معالجة هذه الأوامر أو بعد انتهاء مهلة زمنية، أيهما يحدث أولاً.
MediaBrowser
تستند MediaBrowser إلى الإمكانات التي توفّرها MediaController، كما تتيح تصفّح مكتبة الوسائط التي يوفّرها MediaLibraryService لتطبيق وسائط.
إنشاء MediaBrowser
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());
استخدام MediaBrowser
لبدء تصفّح مكتبة محتوى تطبيق الوسائط، عليك أولاً استرداد العقدة الجذرية باستخدام 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());
عرض عناصر التحكّم في التشغيل لتطبيق موسيقى آخر
عند عرض عناصر تحكّم في واجهة المستخدم تتضمّن أزرارًا لتطبيق وسائط آخر، من المهم اتّباع إعدادات أزرار الوسائط المحدّدة لهذا التطبيق.
لحلّ مشكلة الإعدادات المفضّلة للتطبيق مع القيود والمتطلبات الخاصة بواجهة المستخدم، استخدِم CommandButton.DisplayConstraints. يمكنك تحديد الحدود والقيود التي يمكن أن تنفّذها واجهة المستخدم، كما توفّر الطريقة resolve قائمة محددة بالأزرار التي سيتم عرضها مع الرمز والموضع والإجراء المقصود. إذا نقر المستخدم على أحد هذه الأزرار، يمكنك استخدام
CommandButton.executeAction لتفعيل الإجراء المرتبط في تطبيق الوسائط.
Kotlin
// Get media button preferences from media app val mediaButtonPreferences = controller.getMediaButtonPreferences() // Declare constraints of UI (example: limit overflow button to one) val displayConstraints = DisplayConstraints.Builder().setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1).build() // Resolve media app preferences with constraints val resolvedButtons = displayConstraints.resolve(mediaButtonPreferences, controller) // Display buttons in UI for (button in resolvedButtons) { generateUiButton( uiPosition = button.slots[0], icon = getIconRes(button.icon), onClick = { button.executeAction(controller) }, ) }
Java
// Get media button preferences from media app List<CommandButton> mediaButtonPreferences = controller.getMediaButtonPreferences(); // Declare constraints of UI (example: limit overflow button to one) DisplayConstraints displayConstraints = new DisplayConstraints.Builder() .setMaxButtonsForSlot(CommandButton.SLOT_OVERFLOW, 1) .build(); // Resolve media app preferences with constraints List<CommandButton> resolvedButtons = displayConstraints.resolve(mediaButtonPreferences, controller); // Display buttons in UI for (CommandButton button : resolvedButtons) { generateUiButton( /* uiPosition= */ button.slots.get(0), /* icon= */ getIconRes(button.icon), /* onClick= */ () -> button.executeAction(controller)); }