미디어 세션 사용

미디어 세션은 오디오 또는 동영상 플레이어와 상호작용하는 보편적인 방법을 제공합니다. 미디어가 앱에서 재생되고 있음을 Android에 알리면 재생 컨트롤을 앱에 위임할 수 있습니다. 미디어 세션과 통합하면 앱이 외부에서 미디어 재생을 알리고 외부 소스에서 재생 명령어를 수신할 수 있습니다. 이러한 소스는 실제 버튼 (예: 헤드셋 또는 TV 리모컨의 재생 버튼) 또는 간접적 명령어 (예: Google 어시스턴트에 '일시중지' 명령)일 수 있습니다. 그러면 미디어 세션은 이러한 명령어를 앱에 위임합니다. 앱은 명령어가 발생한 위치가 투명한 미디어 플레이어에 명령어를 적용합니다.

미디어 세션은 관리하는 플레이어와 함께 움직입니다. 미디어 세션 및 관련 플레이어를 소유한 활동이나 서비스의 onCreate() 메서드에서 미디어 세션을 만들고 초기화해야 합니다.

미디어 세션 초기화

새로 만든 미디어 세션에는 기능이 없습니다. 다음 단계에 따라 세션을 초기화해야 합니다.

  • 미디어 세션이 미디어 컨트롤러 및 미디어 버튼에서 콜백을 수신할 수 있도록 플래그를 설정합니다.
  • PlaybackStateCompat의 인스턴스를 만들고 초기화한 다음 세션에 할당합니다. 재생 상태는 세션 전체에서 변경되므로 재사용을 위해 PlaybackStateCompat.Builder를 캐시하는 것이 좋습니다.
  • MediaSessionCompat.Callback의 인스턴스를 만들고 세션에 할당합니다(콜백에 관한 자세한 내용은 아래 참조).

세션을 소유한 활동 또는 서비스onCreate() 메서드에서 미디어 세션을 만들고 초기화해야 합니다.

앱이 새로 초기화되거나 중지될 때 미디어 버튼이 작동하려면 PlaybackState에 미디어 버튼이 전송하는 인텐트와 일치하는 재생 작업이 포함되어야 합니다. 이러한 이유로 초기화 중에 ACTION_PLAY가 세션 상태에 할당됩니다. 자세한 내용은 미디어 버튼에 응답을 참고하세요.

재생 상태 및 메타데이터 유지 관리

미디어 세션의 상태를 나타내는 두 가지 클래스가 있습니다.

PlaybackStateCompat 클래스는 플레이어의 현재 작동 상태를 설명합니다. 여기에는 다음과 같은 콘텐츠가 포함됩니다.

  • 전송 상태(재생 중/일시중지/버퍼링 등의 플레이어 상태. getState() 참조)
  • 오류 코드 및 선택사항인 오류 메시지(해당되는 경우). (아래의 getErrorCode()를 참조하고 상태 및 오류를 읽어보세요.)
  • 플레이어 위치
  • 현재 상태에서 처리할 수 있는 유효한 컨트롤러 작업

MediaMetadataCompat 클래스는 재생 중인 자료를 설명합니다.

  • 아티스트, 앨범 및 트랙의 이름
  • 트랙 길이
  • 잠금 화면에 표시할 앨범 아트워크. 이미지는 최대 크기 320x320dp의 비트맵입니다(더 큰 경우 축소됨).
  • 아트워크의 더 큰 버전을 가리키는 ContentUris의 인스턴스

플레이어 상태와 메타데이터는 미디어 세션의 수명 동안 변경될 수 있습니다. 상태 또는 메타데이터가 변경될 때마다 각 클래스에 상응하는 빌더(PlaybackStateCompat.Builder() 또는 MediaMetadataCompat.Builder())를 사용한 다음 setPlaybackState() 또는 setMetaData()를 호출하여 새 인스턴스를 미디어 세션에 전달해야 합니다. 빈번한 작업으로 인한 전체 메모리 소비를 줄이려면 빌더를 한 번만 만들고 세션 수명 동안 재사용하는 것이 좋습니다.

상태 및 오류

PlaybackState세션의 재생 상태 (getState()) 및 필요한 경우 연결된 오류 코드 (getErrorCode())의 개별 값을 포함하는 객체입니다. 오류는 심각하거나 심각하지 않을 수 있습니다.

재생이 중단될 때마다 심각한 오류가 발생합니다. 전송 상태를 STATE_ERROR로 설정하고 setErrorMessage(int, CharSequence)와 관련된 오류를 지정합니다. 오류로 인해 재생이 차단되는 한 PlaybackState는 계속해서 STATE_ERROR 및 오류를 보고해야 합니다.

심각하지 않은 오류는 앱이 요청을 처리할 수 없지만 계속 재생할 수 있는 경우에 발생합니다. 전송은 '정상' 상태 (예: STATE_PLAYING)로 유지되지만 PlaybackState에는 오류 코드가 있습니다. 예를 들어 마지막 노래가 재생 중이고 사용자가 다음 노래로 건너뛰기를 요청하면 재생을 계속할 수 있지만, 오류 코드 ERROR_CODE_END_OF_QUEUE로 새 PlaybackState를 만든 다음 setPlaybackState()를 호출해야 합니다. 세션에 연결된 미디어 컨트롤러는 onPlaybackStateChanged() 콜백을 수신하고 무슨 일이 일어났는지 사용자에게 설명합니다. 심각하지 않은 오류는 발생 시점에 한 번만 보고해야 합니다. 다음에 세션 업데이트 시 PlaybackState는 심각하지 않은 동일한 오류를 다시 설정하지 않습니다(새 요청의 응답으로 오류가 발생하지 않는 한).

미디어 세션 잠금 화면

Android 4.0 (API 수준 14)부터 시스템은 미디어 세션의 재생 상태와 메타데이터에 액세스할 수 있습니다. 이 방식으로 잠금 화면에서 미디어 컨트롤과 아트워크가 표시됩니다. 동작은 Android 버전에 따라 다릅니다.

앨범 아트워크

Android 4.0 (API 수준 14)~Android 10 (API 수준 29)에서는 미디어 세션 메타데이터에 배경 비트맵이 포함된 경우에만 잠금 화면의 배경에 앨범 아트워크가 표시됩니다.

전송 컨트롤

Android 4.0(API 레벨 14)부터 Android 4.4(API 레벨 19)까지는 미디어 세션이 활성화되고 미디어 세션 메타데이터에 백그라운드 비트맵이 포함되면 잠금 화면에 전송 컨트롤이 자동으로 표시됩니다.

Android 5.0 (API 수준 21) 이상에서는 시스템이 잠금 화면에 전송 제어를 제공하지 않습니다. 대신 전송 컨트롤을 표시하려면 MediaStyle 알림을 사용해야 합니다.

맞춤 작업 추가

미디어 애플리케이션은 맞춤 작업(예: 좋아요, 좋아요, 30초 되감기)을 정의할 수 있습니다. 맞춤 작업은 완전히 새로운 동작을 구현해야 합니다. PlaybackStateCompat에 정의된 표준 전송 제어 작업 중 하나를 대체하는 데 맞춤 작업을 사용하지 마세요.

addCustomAction()로 맞춤 액션을 추가합니다. 다음 예는 '좋아요' 작업에 컨트롤을 추가하는 방법을 보여줍니다.

Kotlin

stateBuilder.addCustomAction(
        PlaybackStateCompat.CustomAction.Builder(
                CUSTOM_ACTION_THUMBS_UP,
                resources.getString(R.string.thumbs_up),
                thumbsUpIcon
        ).run {
            setExtras(customActionExtras)
            build()
        }
)

Java

stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
    CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
    .setExtras(customActionExtras)
    .build());

전체 예제는 유니버설 음악 플레이어를 참조하세요.

onCustomAction()으로 작업에 응답합니다.

Kotlin

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

Java

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

유니버설 음악 플레이어도 참조하세요.

미디어 세션 콜백

기본 미디어 세션 콜백 메서드는 onPlay(), onPause()onStop()입니다. 여기에서 플레이어를 제어하는 코드를 추가합니다.

런타임에(onCreate()에서) 세션의 콜백을 인스턴스화하고 설정하므로 앱에서 다른 플레이어를 사용하는 대체 콜백을 정의하고 기기 또는 시스템 수준에 따라 적절한 콜백/플레이어 조합을 선택할 수 있습니다. 앱의 나머지를 변경하지 않은 채 플레이어를 변경할 수 있습니다. 예를 들어 Android 4.1(API 레벨 16) 이상에서 실행할 경우 ExoPlayer를 사용하고 그 이전 시스템에서는 MediaPlayer를 사용할 수 있습니다.

콜백은 플레이어를 제어하고 미디어 세션 상태 전환을 관리하는 것 외에도 앱의 기능을 사용 설정 및 사용 중지하고 앱이 다른 앱 및 기기 하드웨어와 상호작용하는 방식을 제어합니다. 자세한 내용은 오디오 출력 제어를 참조하세요.

미디어 세션 콜백 메서드의 구현은 앱의 구조에 따라 다릅니다. 오디오 앱동영상 앱에서 콜백을 사용하는 방법을 설명하는 별도의 페이지를 참고하여 각 앱 종류에 콜백을 구현하는 방법을 설명합니다.