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

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

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

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

إنشاء MediaController

لإنشاء MediaController، ابدأ بإنشاء SessionToken للMediaSession المعنيّ. يمكن أن تكون طريقة onStart() في Activity أو Fragment مكانًا جيدًا لإجراء ذلك.

KotlinJava

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

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

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

KotlinJava

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

ملاحظة: يمكنك استخدام 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.

KotlinJava

MediaController.releaseFuture(controllerFuture)

MediaController.releaseFuture(controllerFuture);

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

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

تعتمد MediaBrowser على الإمكانات التي يوفرها MediaController لتمكين تصفح مكتبة الوسائط التي تقدمها إحدى الوسائط أيضًا MediaLibraryService للتطبيق.

KotlinJava

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

KotlinJava

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

KotlinJava

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