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

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

ملاحظة: يمكنك استخدام ContextCompat.getMainExecutor() بدلاً من MoreExecutors.directExecutor(). في حال تشغيل خدمتك في عملية أخرى غير واجهة المستخدم.

ملاحظة: يجب أن تشتمل التطبيقات التي تستهدف المستوى 30 من حزمة تطوير البرامج (SDK) أو الإصدارات الأحدث على عنصر <queries>. في ملف البيان للربط بـ MediaSessionService على تطبيق مختلف (أو نفس العنصر). راجِع مستوى عرض الحِزم. الدليل للحصول على مزيد من التفاصيل.

استخدام MediaController

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

ملاحظة: تعمل وحدة التحكّم في الوسائط على تنفيذ واجهة 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());