ارائه محتوا با MediaLibraryService

برنامه های رسانه اغلب حاوی مجموعه ای از آیتم های رسانه ای هستند که در یک سلسله مراتب سازماندهی شده اند. به عنوان مثال، آهنگ های یک آلبوم یا قسمت های تلویزیونی در یک لیست پخش. این سلسله مراتب از آیتم های رسانه ای به عنوان کتابخانه رسانه ای شناخته می شود.

MediaLibraryService یک API استاندارد برای سرویس دهی و دسترسی به کتابخانه رسانه شما فراهم می کند. این می تواند مفید باشد، به عنوان مثال، هنگام افزودن پشتیبانی از Android Auto به برنامه رسانه خود، که رابط کاربری امن برای درایور خود را برای کتابخانه رسانه شما فراهم می کند.

یک MediaLibraryService بسازید

پیاده سازی MediaLibraryService شبیه اجرای MediaSessionService است، با این تفاوت که در متد onGetSession() باید به جای MediaSession یک MediaLibrarySession برگردانید.

class PlaybackService : MediaLibraryService() {
  var mediaLibrarySession: MediaLibrarySession? = null
  var callback: MediaLibrarySession.Callback = object : MediaLibrarySession.Callback {...}

  // If desired, validate the controller before returning the media library session
  override fun onGetSession(controllerInfo: MediaSession.ControllerInfo): MediaLibrarySession? =
    mediaLibrarySession

  // Create your player and media library session in the onCreate lifecycle event
  override fun onCreate() {
    super.onCreate()
    val player = ExoPlayer.Builder(this).build()
    mediaLibrarySession = MediaLibrarySession.Builder(this, player, callback).build()
  }

  // Remember to release the player and media library session in onDestroy
  override fun onDestroy() {
    mediaLibrarySession?.run { 
      player.release()
      release()
      mediaLibrarySession = null
    }
    super.onDestroy()
  }
}

class PlaybackService extends MediaLibraryService {
  MediaLibrarySession mediaLibrarySession = null;
  MediaLibrarySession.Callback callback = new MediaLibrarySession.Callback() {...};

  @Override
  public MediaLibrarySession onGetSession(MediaSession.ControllerInfo controllerInfo) {
    // If desired, validate the controller before returning the media library session
    return mediaLibrarySession;
  }

  // Create your player and media library session in the onCreate lifecycle event
  @Override
  public void onCreate() {
    super.onCreate();
    ExoPlayer player = new ExoPlayer.Builder(this).build();
    mediaLibrarySession = new MediaLibrarySession.Builder(this, player, callback).build();
  }

  // Remember to release the player and media library session in onDestroy
  @Override
  public void onDestroy() {
    if (mediaLibrarySession != null) {
      mediaLibrarySession.getPlayer().release();
      mediaLibrarySession.release();
      mediaLibrarySession = null;
    }
    super.onDestroy();
  }
}

به یاد داشته باشید که Service و مجوزهای مورد نیاز خود را در فایل مانیفست نیز اعلام کنید:

<service
    android:name=".PlaybackService"
    android:foregroundServiceType="mediaPlayback"
    android:exported="true">
    <intent-filter>
        <action android:name="androidx.media3.session.MediaSessionService"/>
    </intent-filter>
</service>

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<!-- For targetSdk 34+ -->
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />

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

MediaLibraryService API انتظار دارد که کتابخانه رسانه شما در قالب درختی، با یک گره ریشه واحد و گره‌های فرزند که ممکن است قابل پخش یا مرور بیشتر باشند، ساخته شود.

MediaLibrarySession API MediaSession را برای افزودن APIهای مرور محتوا گسترش می دهد. در مقایسه با فراخوان MediaSession ، MediaLibrarySession متدهایی مانند:

• onGetLibraryRoot() برای زمانی که یک کلاینت، MediaItem ریشه درخت محتوا را درخواست می کند
• onGetChildren() برای زمانی که مشتری از فرزندان یک MediaItem در درخت محتوا درخواست می کند
• onGetSearchResult() برای زمانی که یک کلاینت نتایج جستجو را از درخت محتوا برای یک پرس و جو داده شده درخواست می کند.

روش‌های برگشت تماس مربوطه شامل یک شی LibraryParams با سیگنال‌های اضافی در مورد نوع درخت محتوایی است که برنامه مشتری به آن علاقه دارد.

دکمه های فرمان برای آیتم های رسانه ای

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

دکمه های دستوری را در سمت جلسه تنظیم کنید

هنگام ساختن جلسه، یک برنامه جلسه مجموعه ای از دکمه های فرمان را که یک جلسه می تواند به عنوان دستورات سفارشی اداره کند، اعلام می کند:

val allCommandButtons =
  listOf(
    CommandButton.Builder(CommandButton.ICON_PLAYLIST_ADD)
      .setDisplayName(context.getString(R.string.add_to_playlist))
      .setDisplayName("Add to playlist")
      .setIconResId(R.drawable.playlist_add)
      .setSessionCommand(SessionCommand(COMMAND_PLAYLIST_ADD, Bundle.EMPTY))
      .setExtras(playlistAddExtras)
      .build(),
    CommandButton.Builder(CommandButton.ICON_RADIO)
      .setDisplayName(context.getString(R.string.radio_station))
      .setIconResId(R.drawable.radio)
      .setSessionCommand(SessionCommand(COMMAND_RADIO, Bundle.EMPTY))
      .setExtras(radioExtras)
      .build(),
    // possibly more here
  )

// Add all command buttons for media items supported by the session.
val session =
  MediaSession.Builder(context, player)
    .setCommandButtonsForMediaItems(allCommandButtons)
    .build()

ImmutableList<CommandButton> allCommandButtons =
    ImmutableList.of(
        new CommandButton.Builder(CommandButton.ICON_PLAYLIST_ADD)
            .setDisplayName("Add to playlist")
            .setIconUri(Uri.parse("http://www.example.com/icon/playlist_add"))
            .setSessionCommand(new SessionCommand(COMMAND_PLAYLIST_ADD, Bundle.EMPTY))
            .setExtras(playlistAddExtras)
            .build(),
        new CommandButton.Builder(CommandButton.ICON_RADIO)
            .setDisplayName("Radio station")
            .setIconUri(Uri.parse("http://www.example.com/icon/radio"))
            .setSessionCommand(new SessionCommand(COMMAND_RADIO, Bundle.EMPTY))
            .setExtras(radioExtras)
            .build());

// Add all command buttons for media items supported by the session.
MediaSession session =
    new MediaSession.Builder(context, player)
        .setCommandButtonsForMediaItems(allCommandButtons)
        .build();

هنگام ساخت یک آیتم رسانه، یک برنامه جلسه می‌تواند مجموعه‌ای از شناسه‌های فرمان پشتیبانی‌شده را اضافه کند که به دستورات جلسه دکمه‌های فرمانی که هنگام ساخت جلسه تنظیم شده‌اند، ارجاع می‌دهند:

val mediaItem =
  MediaItem.Builder()
    .setMediaMetadata(
      MediaMetadata.Builder()
        .setSupportedCommands(listOf(COMMAND_PLAYLIST_ADD, COMMAND_RADIO))
        .build())
    .build()

MediaItem mediaItem =
    new MediaItem.Builder()
        .setMediaMetadata(
            new MediaMetadata.Builder()
                .setSupportedCommands(ImmutableList.of(COMMAND_PLAYLIST_ADD, COMMAND_RADIO))
                .build())
        .build();

هنگامی که یک کنترلر یا مرورگر روش دیگری از Callback جلسه را متصل یا فراخوانی می‌کند، برنامه جلسه می‌تواند ControllerInfo ارسال شده به تماس برگشتی را بررسی کند تا حداکثر تعداد دکمه‌های دستوری را که یک کنترلر یا مرورگر می‌تواند نمایش دهد، دریافت کند. ControllerInfo ارسال شده به یک متد برگشت تماس، دریافت کننده ای را برای دسترسی راحت به این مقدار فراهم می کند. به طور پیش فرض مقدار روی 0 تنظیم شده است که نشان می دهد مرورگر یا کنترلر از این ویژگی پشتیبانی نمی کند:

override fun onGetItem(
  session: MediaLibrarySession,
  browser: MediaSession.ControllerInfo,
  mediaId: String,
): ListenableFuture<LibraryResult<MediaItem>> {

  val settableFuture = SettableFuture.create<LibraryResult<MediaItem>>()

  val maxCommandsForMediaItems = browser.maxCommandsForMediaItems
  scope.launch {
    loadMediaItem(settableFuture, mediaId, maxCommandsForMediaItems)
  }

  return settableFuture
}

@Override
public ListenableFuture<LibraryResult<MediaItem>> onGetItem(
    MediaLibraryService.MediaLibrarySession session, ControllerInfo browser, String mediaId) {

  SettableFuture<LibraryResult<MediaItem>> settableFuture = SettableFuture.create();

  int maxCommandsForMediaItems = browser.getMaxCommandsForMediaItems();
  loadMediaItemAsync(settableFuture, mediaId, maxCommandsForMediaItems);

  return settableFuture;
}

هنگام مدیریت یک اقدام سفارشی که برای یک آیتم رسانه ارسال شده است، برنامه جلسه می‌تواند شناسه مورد رسانه را از آرگومان‌هایی Bundle به onCustomCommand ارسال می‌کند دریافت کند:

override fun onCustomCommand(
  session: MediaSession,
  controller: MediaSession.ControllerInfo,
  customCommand: SessionCommand,
  args: Bundle,
): ListenableFuture<SessionResult> {
  val mediaItemId = args.getString(MediaConstants.EXTRA_KEY_MEDIA_ID)
  return if (mediaItemId != null)
    handleCustomCommandForMediaItem(controller, customCommand, mediaItemId, args)
  else handleCustomCommand(controller, customCommand, args)
}

@Override
public ListenableFuture<SessionResult> onCustomCommand(
    MediaSession session,
    ControllerInfo controller,
    SessionCommand customCommand,
    Bundle args) {
  String mediaItemId = args.getString(MediaConstants.EXTRA_KEY_MEDIA_ID);
  return mediaItemId != null
      ? handleCustomCommandForMediaItem(controller, customCommand, mediaItemId, args)
      : handleCustomCommand(controller, customCommand, args);
}

از دکمه های فرمان به عنوان مرورگر یا کنترلر استفاده کنید

در سمت MediaController ، یک برنامه می‌تواند حداکثر تعداد دکمه‌های فرمانی را که برای یک آیتم رسانه پشتیبانی می‌کند، هنگام ساخت MediaController یا MediaBrowser اعلام کند:

val browserFuture =
  MediaBrowser.Builder(context, sessionToken)
    .setMaxCommandsForMediaItems(3)
    .buildAsync()

ListenableFuture<MediaBrowser> browserFuture =
    new MediaBrowser.Builder(context, sessionToken)
        .setMaxCommandsForMediaItems(3)
        .buildAsync();

هنگامی که به جلسه وصل می شود، برنامه کنترلر می تواند دکمه های دستوری را که توسط آیتم رسانه پشتیبانی می شود و کنترل کننده فرمان در دسترس را توسط برنامه جلسه برای آنها اعطا می کند، دریافت کند:

val commandButtonsForMediaItem: List<CommandButton> =
  controller.getCommandButtonsForMediaItem(mediaItem)

ImmutableList<CommandButton> commandButtonsForMediaItem =
    controller.getCommandButtonsForMediaItem(mediaItem);

برای راحتی، MediaController می‌تواند دستورات سفارشی خاص مورد رسانه را با MediaController.sendCustomCommand(SessionCommand, MediaItem, Bundle) ارسال کند:

controller.sendCustomCommand(addToPlaylistButton.sessionCommand!!, mediaItem, Bundle.EMPTY)

controller.sendCustomCommand(
    checkNotNull(addToPlaylistButton.sessionCommand), mediaItem, Bundle.EMPTY);