MediaLibraryService로 콘텐츠 제공

미디어 앱에는 계층 구조로 구성된 미디어 항목 모음이 포함되는 경우가 많습니다. 예를 들어 앨범의 노래 또는 재생목록의 TV 에피소드가 여기에 해당합니다. 이러한 미디어 항목의 계층 구조를 미디어 라이브러리라고 합니다.

그림 1: 미디어 라이브러리를 형성하는 미디어 항목 계층 구조의 예

MediaLibraryService는 미디어 라이브러리를 제공하고 액세스하는 표준화된 API를 제공합니다. 이는 미디어 라이브러리에 자체 운전자 안전 UI를 제공하는 미디어 앱에 Android Auto 지원을 추가할 때 유용할 수 있습니다.

MediaLibraryService 빌드

MediaLibraryService를 구현하는 것은 MediaSessionService를 구현하는 것과 비슷하지만 onGetSession() 메서드에서 MediaSession 대신 MediaLibrarySession를 반환해야 합니다.

Kotlin

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

참고: 기존 미디어 API를 사용하는 클라이언트와의 하위 호환성을 위해 intent-filter 요소에 <action android:name="android.media.browse.MediaBrowserService"/>를 추가로 포함할 수 있습니다.

MediaLibrarySession 사용

MediaLibraryService API는 미디어 라이브러리가 단일 루트 노드와 재생 또는 추가 탐색이 가능한 하위 노드로 구성된 트리 형식으로 되어 있을 것으로 예상합니다.

MediaLibrarySession는 MediaSession API를 확장하여 콘텐츠 탐색 API를 추가합니다. MediaSession 콜백에 비해 MediaLibrarySession 콜백에는 다음과 같은 메서드가 추가됩니다.

• 클라이언트가 콘텐츠 트리의 루트 MediaItem를 요청하는 경우 onGetLibraryRoot()
• onGetChildren() 클라이언트가 콘텐츠 트리에서 MediaItem의 하위 요소를 요청하는 경우
• onGetSearchResult() 클라이언트가 지정된 검색어에 대해 콘텐츠 트리에서 검색 결과를 요청하는 경우

관련 콜백 메서드에는 클라이언트 앱이 관심을 갖는 콘텐츠 트리의 유형에 관한 추가 신호가 포함된 LibraryParams 객체가 포함됩니다.

미디어 항목용 명령 버튼

세션 앱은 MediaMetadata에서 MediaItem에서 지원하는 명령어 버튼을 선언할 수 있습니다. 이렇게 하면 컨트롤러가 표시하고 항목의 맞춤 명령어를 세션에 편리하게 전송하는 데 사용할 수 있는 CommandButton 항목을 미디어 항목에 하나 이상 할당할 수 있습니다.

세션 측의 설정 명령어 버튼

세션을 빌드할 때 세션 앱은 세션이 맞춤 명령어로 처리할 수 있는 명령어 버튼 집합을 선언합니다.

Kotlin

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

참고: 미디어 알림을 통해 사용할 수 있는 Android 미디어 컨트롤은 미디어 항목에 명령어 버튼을 사용하지 않습니다. 맞춤 레이아웃을 사용하여 모바일의 Android 미디어 컨트롤에서 사용해야 하는 명령어 버튼을 선언합니다.

미디어 항목을 빌드할 때 세션 앱은 세션을 빌드할 때 설정된 명령어 버튼의 세션 명령어를 참조하는 지원되는 명령어 ID 집합을 추가할 수 있습니다.

Kotlin

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는 이 값에 편리하게 액세스할 수 있는 getter를 제공합니다. 기본적으로 값은 0으로 설정되며 이는 브라우저 또는 컨트롤러에서 이 기능을 지원하지 않음을 나타냅니다.

Kotlin

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;
}

미디어 항목에 대해 전송된 맞춤 작업을 처리할 때 세션 앱은 onCustomCommand에 전달된 인수 Bundle에서 미디어 항목 ID를 가져올 수 있습니다.

Kotlin

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를 빌드할 때 미디어 항목에 지원하는 최대 명령어 버튼 수를 선언할 수 있습니다.

Kotlin

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

자바

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

참고: 기본적으로 명령어 수는 0 (영)으로 설정되어 세션 앱에 해당 브라우저 또는 컨트롤러의 명령어 버튼을 광고하지 않도록 안내합니다.

세션에 연결되면 컨트롤러 앱은 미디어 항목에서 지원되고 컨트롤러에 세션 앱에서 부여한 사용 가능한 명령어가 있는 명령어 버튼을 수신할 수 있습니다.

Kotlin

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

자바

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

참고: 반환된 명령어 버튼은 세션에서 설정한 모든 버튼, 미디어 항목에 설정된 지원되는 명령어, 컨트롤러에서 사용할 수 있는 명령어의 교집합입니다.

편의를 위해 MediaController는 MediaController.sendCustomCommand(SessionCommand, MediaItem, Bundle)를 사용하여 미디어 항목별 맞춤 명령어를 보낼 수 있습니다.

Kotlin

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

Java

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