재생 컨트롤 사용 설정

Android Auto 및 Android Automotive OS (AAOS)에서 미디어 재생을 사용 설정하려면 미디어 세션을 등록하고 콜백 메서드를 처리하여 재생 컨트롤을 구현하세요. 이 페이지에서는 다음 방법에 대해 설명합니다.

• 미디어 브라우저 서비스에 MediaSessionCompat 객체를 등록합니다.

• MediaSessionCompat.Callback 메서드를 구현하여 사용자 재생 요청에 응답합니다.

• 표준 및 맞춤 재생 작업을 구성합니다.

• 미디어 세션의 초기 재생 상태를 설정합니다.

• 오디오 형식을 나타내는 아이콘을 추가합니다.

• 활성 상태로 재생 중인 미디어 항목에서 링크를 만듭니다.

Android Auto와 AAOS는 서비스의 MediaSessionCompat를 통해 재생 컨트롤 명령어를 전송합니다. 세션을 등록하고 연결된 콜백 메서드를 구현해야 합니다.

미디어 세션 등록

미디어 브라우저 서비스의 onCreate 메서드에서 MediaSessionCompat 인스턴스를 만든 다음 setSessionToken을 호출하여 미디어 세션을 등록합니다. 이 코드 스니펫은 미디어 세션을 만들고 등록하는 방법을 보여줍니다.

override fun onCreate() {
    super.onCreate()
    ...
    // Start a new MediaSession.
    val session = MediaSessionCompat(this, "session tag").apply {
        // Set a callback object that implements MediaSession.Callback
        // to handle play control requests.
        setCallback(MyMediaSessionCallback())
    }
    sessionToken = session.sessionToken
    ...
}

public void onCreate() {
    super.onCreate();
    ...
    // Start a new MediaSession.
    MediaSessionCompat session = new MediaSessionCompat(this, "session tag");
    setSessionToken(session.getSessionToken());

    // Set a callback object that implements MediaSession.Callback
    // to handle play control requests.
    session.setCallback(new MyMediaSessionCallback());
    ...
}

미디어 세션 객체를 만들 때 재생 컨트롤 요청을 처리하는 데 사용되는 콜백 객체를 설정합니다. 이 콜백 객체는 앱의 MediaSessionCompat.Callback 클래스 구현을 제공하여 만듭니다. 다음 섹션에서는 이 객체를 구현하는 방법을 설명합니다.

재생 명령어 구현

사용자가 앱에서 미디어 항목의 재생을 요청하면 Android Automotive OS와 Android Auto는 앱의 미디어 브라우저 서비스에서 가져온 MediaSessionCompat 객체의 MediaSessionCompat.Callback 클래스를 사용합니다. 사용자가 재생을 일시중지하거나 다음 트랙으로 건너뛰는 등 콘텐츠 재생을 제어하려는 경우 Android Auto 및 Android Automotive OS는 콜백 객체의 메서드 중 하나를 호출합니다.

콘텐츠 재생을 처리하려면 앱에서 추상 MediaSessionCompat.Callback 클래스를 확장하고 앱에서 지원하는 메서드를 구현해야 합니다.

앱에서 제공하는 콘텐츠 유형에 적합한 각 콜백 메서드를 구현합니다.

onPrepare

미디어 소스가 변경되면 AAOS가 이 메서드를 호출합니다.

onPlay

사용자가 특정 항목을 선택하지 않고 재생을 선택하면 호출됩니다. 앱은 기본 콘텐츠를 재생해야 합니다. 또는 onPause로 재생이 일시중지된 경우 재생을 재개합니다.

onPlayFromMediaId

사용자가 특정 항목 재생을 선택하면 호출됩니다. 이 메서드는 콘텐츠 계층 구조의 미디어 항목에 미디어 브라우저 서비스가 할당한 ID를 수신합니다.

onPlayFromSearch

사용자가 검색어에서 재생을 선택하면 호출됩니다. 앱에서는 전달된 검색 문자열에 근거하여 적절한 선택을 해야 합니다.

onPause

사용자가 재생 일시중지를 선택하면 호출됩니다.

onSkipToNext

사용자가 다음 항목으로 건너뛰기를 선택하면 호출됩니다.

onSkipToPrevious

사용자가 이전 항목으로 건너뛰기를 선택하면 호출됩니다.

onStop

사용자가 재생 중지를 선택하면 호출됩니다. 앱에서 이러한 메서드를 재정의하여 선택한 결과를 제공하세요. 앱에서 목적을 지원하지 않으면 메서드를 구현할 필요가 없습니다. 예를 들어 앱에서 스포츠 방송과 같은 라이브 스트림을 재생한다면 onSkipToNext를 구현하지 않아도 됩니다. 대신 onSkipToNext의 기본 구현을 사용하세요.

앱에 특별한 로직이 있어야 자동차 스피커를 통해 콘텐츠를 재생할 수 있는 것은 아닙니다. 앱이 콘텐츠 재생 요청을 수신하면 사용자의 휴대전화 스피커나 헤드폰을 통해 콘텐츠를 재생하는 것과 동일한 방식으로 오디오를 재생합니다. Android Auto와 AAOS는 오디오 콘텐츠를 자동차 시스템으로 자동 전송하여 자동차 스피커를 통해 재생합니다.

오디오 콘텐츠 재생에 관한 자세한 내용은 미디어 플레이어 개요, 오디오 앱 개요, ExoPlayer 개요를 참고하세요.

표준 재생 작업 설정

Android Auto와 AAOS는 PlaybackStateCompat 객체에서 사용 설정된 작업에 기반하여 재생 컨트롤을 표시합니다. 기본적으로 앱에서는 다음 작업을 지원해야 합니다.

• ACTION_PLAY
• ACTION_PAUSE
• ACTION_STOP
• ACTION_PLAY_FROM_MEDIA_ID
• ACTION_PLAY_FROM_SEARCH

앱에서는 앱 콘텐츠와 관련이 있다면 다음 작업을 추가로 지원할 수 있습니다.

• ACTION_SKIP_TO_PREVIOUS
• ACTION_SKIP_TO_NEXT

또한 사용자에게 표시할 재생 대기열을 선택적으로 만들 수 있습니다. 이렇게 하려면 setQueue 및 setQueueTitle 메서드를 호출하고 ACTION_SKIP_TO_QUEUE_ITEM 작업을 사용 설정하고 콜백 onSkipToQueueItem을 정의합니다.

또한 재생 중인 음악을 알려주는 표시기인 지금 재생 중 아이콘에 대한 지원을 추가합니다. 이렇게 하려면 setActiveQueueItemId 메서드를 호출하고 재생목록에서 재생 중인 항목의 ID를 전달합니다. 재생목록이 변경될 때마다 setActiveQueueItemId를 업데이트해야 합니다.

Android Auto 및 AAOS는 사용 설정된 각 작업과 재생 목록의 버튼을 표시합니다. 사용자가 이 버튼을 클릭하면 시스템은 MediaSessionCompat.Callback에서 상응하는 콜백을 호출합니다.

사용하지 않는 공간 예약

Android Auto와 AAOS는 ACTION_SKIP_TO_PREVIOUS 및 ACTION_SKIP_TO_NEXT 작업을 위해 UI에 공간을 예약합니다. 앱에서 이러한 기능 중 하나를 지원하지 않는 경우 Android Auto와 AAOS에서는 이 공간을 사용하여 개발자가 만드는 맞춤 작업을 표시합니다.

이 공간을 맞춤 작업으로 채우고 싶지 않다면 앱에서 해당 기능을 지원하지 않을 때마다 Android Auto와 AAOS에서 공백을 비워 둘 수 있도록 이 공간을 예약할 수 있습니다.

이렇게 하려면 예약된 함수에 상응하는 상수가 포함된 추가 번들로 setExtras 메서드를 호출하세요. SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_NEXT는 ACTION_SKIP_TO_NEXT에 상응하고 SESSION_EXTRAS_KEY_SLOT_RESERVATION_SKIP_TO_PREV는 ACTION_SKIP_TO_PREVIOUS에 상응합니다. 이러한 상수를 번들에서 키로 사용하고 부울 true를 값으로 사용합니다.

초기 PlaybackState 설정

Android Auto와 AAOS가 미디어 브라우저 서비스와 통신할 때 미디어 세션은 PlaybackStateCompat를 사용하여 콘텐츠 재생 상태를 전달합니다.

AAOS 또는 Android Auto가 미디어 브라우저 서비스에 연결될 때 앱에서 자동으로 음악 재생을 시작해서는 안 됩니다. 대신 Android Auto 및 AAOS를 사용하여 자동차의 상태 또는 사용자 작업을 기반으로 재생을 재개하거나 시작하세요.

이 작업을 실행하려면 미디어 세션의 초기 PlaybackStateCompat를 STATE_STOPPED, STATE_PAUSED, STATE_NONE 또는 STATE_ERROR로 설정하세요.

Android Auto와 AAOS 내의 미디어 세션은 운전하는 동안에만 지속되므로 사용자는 이러한 세션을 자주 시작하거나 중지합니다. 주행 간의 원활한 환경을 촉진하려면 사용자의 이전 세션 상태를 추적하여 미디어 앱에서 재개 요청을 수신할 때 사용자가 중단된 부분부터 자동으로 시작할 수 있도록 하세요(예: 마지막으로 재생한 미디어 항목, PlaybackStateCompat, 재생목록).

맞춤 재생 작업 추가

맞춤 재생 작업을 추가하면 미디어 앱에서 지원하는 추가 작업을 표시할 수 있습니다. 공간이 있는 경우 (예약은 하지 않음) Android는 전송 컨트롤에 맞춤 작업을 추가합니다. 그렇지 않은 경우에는 맞춤 작업이 더보기 메뉴에 표시됩니다. Android는 PlaybackStateCompat에 추가된 순서대로 맞춤 작업을 표시합니다.

맞춤 작업을 사용하여 표준 작업과는 다른 동작을 제공합니다. 표준 작업을 대체하거나 복제하는 데 사용하지 마세요.

맞춤 작업을 추가하려면 PlaybackStateCompat.Builder 클래스의 addCustomAction 메서드를 사용하세요. 이 코드 스니펫은 '무선 채널 시작'에 맞춤 작업을 추가하는 방법을 보여줍니다.

val customActionExtras = Bundle()
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO)

stateBuilder.addCustomAction(
    PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon // or R.drawable.media3_icon_radio
    ).run {
        setExtras(customActionExtras)
        build()
    }
)

Bundle customActionExtras = new Bundle();
customActionExtras.putInt(
  androidx.media3.session.MediaConstants.EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT,
  androidx.media3.session.CommandButton.ICON_RADIO);

stateBuilder.addCustomAction(
    new PlaybackStateCompat.CustomAction.Builder(
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA,
        resources.getString(R.string.start_radio_from_media),
        startRadioFromMediaIcon) // or R.drawable.media3_icon_radio
    .setExtras(customActionExtras)
    .build());

이 메서드의 자세한 예는 GitHub의 범용 Android 뮤직 플레이어 샘플 앱에서 setCustomAction 메서드를 참고하세요. 맞춤 작업을 만든 후 미디어 세션은 onCustomAction 메서드를 재정의하여 작업에 응답할 수 있습니다.

이 코드 스니펫은 앱이 '무선 채널 시작' 작업에 응답할 수 있는 방법을 보여줍니다.

override fun onCustomAction(action: String, extras: Bundle?) {
    when(action) {
        CUSTOM_ACTION_START_RADIO_FROM_MEDIA -> {
            ...
        }
    }
}

@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
    if (CUSTOM_ACTION_START_RADIO_FROM_MEDIA.equals(action)) {
        ...
    }
}

자세한 내용은 GitHub의 범용 Android 뮤직 플레이어 샘플 앱에서 onCustomAction 메서드를 참고하세요.

맞춤 작업 아이콘 만들기

개발자가 만드는 각 맞춤 작업에는 아이콘이 필요합니다.

해당 아이콘의 설명이 CommandButton.ICON_ 상수 중 하나와 일치하면 맞춤 작업의 추가 정보에 있는 EXTRAS_KEY_COMMAND_BUTTON_ICON_COMPAT 키의 정수 값을 설정합니다. 지원되는 시스템에서 이렇게 하면 CustomAction.Builder에 전달된 아이콘 리소스가 재정의되어 시스템 구성요소가 작업과 기타 재생 작업을 일관되게 렌더링할 수 있습니다.

아이콘 리소스도 지정해야 합니다. 자동차의 앱은 다양한 화면 크기와 밀도에서 실행될 수 있으므로 개발자가 제공하는 아이콘은 벡터 드로어블이어야 합니다. 벡터 드로어블을 사용하여 세부정보 손실 없이 애셋을 확장합니다. 벡터 드로어블은 해상도가 낮을 때 가장자리와 모서리를 픽셀 경계에 맞출 수 있습니다.

맞춤 작업이 스테이트풀 (재생 설정을 사용 설정 또는 사용 중지하는 경우)이면 여러 상태에 다양한 아이콘을 제공하여 사용자가 작업을 선택할 때 변경사항을 확인할 수 있도록 합니다.

사용 중지된 작업에 대체 아이콘 스타일 제공

현재 컨텍스트에서 맞춤 작업을 사용할 수 없는 경우 맞춤 작업 아이콘을 작업이 사용 중지되었음을 나타내는 대체 아이콘으로 바꾸세요.

오디오 형식 표시

재생 중인 미디어가 특수 오디오 형식을 사용한다고 나타내려면 이 기능을 지원하는 자동차에서 렌더링되는 아이콘을 지정하면 됩니다. 현재 재생 중인 미디어 항목의 추가 항목 번들에서 KEY_CONTENT_FORMAT_TINTABLE_LARGE_ICON_URI 및 KEY_CONTENT_FORMAT_TINTABLE_SMALL_ICON_URI를 설정할 수 있습니다 (MediaSession.setMetadata에 전달됨). 두 추가 항목을 모두 설정하여 다양한 레이아웃을 수용해야 합니다.

또한 KEY_IMMERSIVE_AUDIO 추가 항목을 설정하여 자동차 OEM에 이 오디오가 몰입형 오디오임을 알릴 수 있으며 자동차 OEM은 몰입형 콘텐츠를 방해할 수 있는 오디오 효과를 적용할지 결정할 때 매우 주의해야 합니다.

현재 재생 중인 항목에서 링크 추가

재생 중인 미디어 항목을 구성하여 자막, 설명 또는 둘 다를 다른 미디어 항목으로 연결되도록 할 수 있습니다. 이를 통해 사용자가 관련 항목으로 빠르게 이동할 수 있습니다. 예를 들어 동일한 아티스트의 다른 노래나 팟캐스트의 다른 에피소드 등으로 이동할 수 있습니다. 자동차에서 이 기능을 지원하는 경우 사용자는 링크를 탭하여 해당 콘텐츠를 탐색할 수 있습니다.

링크를 추가하려면 KEY_SUBTITLE_LINK_MEDIA_ID 메타데이터(자막에서 연결) 또는 KEY_DESCRIPTION_LINK_MEDIA_ID (설명에서 연결)를 구성합니다. 자세한 내용은 해당 메타데이터 필드의 참조 문서를 확인하세요.