به یک برنامه رسانه متصل شوید

دو روش برای اتصال به یک برنامه رسانه وجود دارد:

  1. MediaController
  2. MediaBrowser

MediaController

یک کنترل‌کننده رسانه با یک جلسه رسانه‌ای تعامل می‌کند تا پخش یک برنامه رسانه‌ای را پرس‌وجو و کنترل کند. در Media3، API MediaController رابط Player را پیاده‌سازی می‌کند. نمونه‌هایی از برنامه‌های کلاینت که از یک کنترل‌کننده رسانه استفاده می‌کنند عبارتند از:

یک کنترل‌کننده رسانه همچنین می‌تواند در یک برنامه رسانه‌ای مفید باشد، برای مثال اگر پخش‌کننده و جلسه رسانه در یک 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 کنترلر را به session داده شده متصل می‌کند. این کار به صورت غیرهمزمان انجام می‌شود، بنابراین باید منتظر نتیجه باشید و در صورت وجود از آن استفاده کنید.

کاتلین

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 به راهنمای رویدادهای Player مراجعه کنید.

رابط MediaController.Listener فراخوانی‌های اضافی برای رویدادها و دستورات سفارشی از MediaSession متصل تعریف می‌کند. به عنوان مثال، onCustomCommand() زمانی که session یک دستور سفارشی ارسال می‌کند، onAvailableSessionCommandsChanged() زمانی که session دستورات موجود session را تغییر می‌دهد یا onDisconnected() زمانی که کنترلر از session جدا شده است.

می‌توان هنگام ساخت کنترلر با استفاده از Builder یک MediaController.Listener تنظیم کرد:

کاتلین

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

جاوا

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 ، رها کنید.

کاتلین

MediaController.releaseFuture(controllerFuture)

جاوا

MediaController.releaseFuture(controllerFuture);

رها کردن کنترلر همچنان تمام دستورات در حال انتظار ارسال شده به جلسه را تحویل می‌دهد و فقط پس از مدیریت این دستورات یا پس از یک دوره زمانی مشخص، هر کدام که زودتر اتفاق بیفتد، از سرویس جلسه جدا می‌شود.

MediaBrowser

یک MediaBrowser بر اساس قابلیت‌های ارائه شده توسط MediaController ساخته شده است تا امکان مرور کتابخانه رسانه‌ای ارائه شده توسط MediaLibraryService یک برنامه رسانه‌ای را نیز فراهم کند.

ایجاد یک MediaBrowser

کاتلین

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

از یک MediaBrowser استفاده کنید

برای شروع مرور کتابخانه محتوای برنامه رسانه، ابتدا گره ریشه را با 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());

نمایش کنترل‌های پخش برای یک برنامه رسانه‌ای دیگر

هنگام نمایش کنترل‌های رابط کاربری با دکمه‌هایی برای یک برنامه رسانه‌ای دیگر، پیروی از تنظیمات دکمه رسانه‌ای اعلام‌شده توسط آن برنامه مهم است.

بهترین راه برای حل تنظیمات برنامه و محدودیت‌ها و الزامات رابط کاربری شما، استفاده از CommandButton.DisplayConstraints است. می‌توانید محدودیت‌ها و قیودی را که رابط کاربری شما می‌تواند انجام دهد تعریف کنید و متد resolve لیست مشخصی از دکمه‌ها را برای نمایش به همراه آیکون، موقعیت و عملکرد مورد نظر آنها ارائه می‌دهد.