미디어 버튼에 응답

미디어 버튼은 블루투스 헤드셋의 일시중지/재생 버튼 등 Android 기기 및 기타 주변기기에서 볼 수 있는 하드웨어 버튼입니다. 사용자가 미디어 버튼을 누르면 Android는 KeyEvent를 생성하는데, 여기에는 버튼을 식별하는 키 코드가 포함되어 있습니다. 미디어 버튼 KeyEvents의 키 코드는 KEYCODE_MEDIA로 시작하는 상수입니다(예: KEYCODE_MEDIA_PLAY).

앱은 다음의 우선순위에 따라 세 가지 경우에 미디어 버튼 이벤트를 처리할 수 있어야 합니다.

  • 앱의 UI 활동이 표시되는 경우
  • UI 활동이 숨겨져 있고 앱의 미디어 세션이 활성 상태인 경우
  • UI 활동이 숨겨져 있고 앱의 미디어 세션이 비활성 상태이며 다시 시작해야 하는 경우

포그라운드 활동에서 미디어 버튼 처리

포그라운드 활동은 onKeyDown() 메서드에서 미디어 버튼 키 이벤트를 수신합니다. 실행 중인 Android 버전에 따라 시스템에서 이벤트를 미디어 컨트롤러로 라우팅하는 두 가지 방법이 있습니다.

  • Android 5.0 (API 수준 21) 이상을 실행 중이면 FLAG_HANDLES_MEDIA_BUTTONS MediaBrowserCompat.ConnectionCallback.onConnected를 호출합니다. 그러면 미디어 컨트롤러의 dispatchMediaButtonEvent()가 자동으로 호출되어 키 코드를 미디어 세션 콜백으로 변환합니다.
  • Android 5.0 (API 수준 21) 이전 버전에서는 이벤트를 직접 처리하도록 onKeyDown()를 수정해야 합니다. 자세한 내용은 활성 미디어 세션에서 미디어 버튼 처리를 참조하세요. 다음 코드 스니펫은 키 코드를 가로채고 dispatchMediaButtonEvent()를 호출하는 방법을 보여줍니다. 이벤트가 처리되었음을 나타내려면 true를 반환해야 합니다.

    Kotlin

        fun onKeyDown(keyCode: Int, event: KeyEvent): Boolean {
            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
                return super.onKeyDown(keyCode, event)
            }
            when (keyCode) {
                KeyEvent.KEYCODE_MEDIA_PLAY -> {
                    yourMediaController.dispatchMediaButtonEvent(event)
                    return true
                }
            }
            return super.onKeyDown(keyCode, event)
        }
        

    Java

        @Override
        boolean onKeyDown(int keyCode, KeyEvent event) {
                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP) {
                  return super.onKeyDown(keyCode, event);
                }
                switch (keyCode) {
                  case KeyEvent.KEYCODE_MEDIA_PLAY:
                          yourMediaController.dispatchMediaButtonEvent(event);
                          return true;
                }
                return super.onKeyDown(keyCode, event);
        }
        

미디어 세션 찾기

포그라운드 활동이 이벤트를 처리하지 않는 경우 Android는 이벤트를 처리할 수 있는 미디어 세션을 찾으려고 시도합니다. Android의 실행 버전에 따라 미디어 세션을 검색하는 방법에는 두 가지가 있습니다.

  • Android 8.0 (API 수준 26) 이상을 실행하는 경우 시스템은 로컬에서 오디오를 재생한 MediaSession이 있는 마지막 앱을 찾으려고 합니다. 세션이 여전히 활성 상태이면 Android에서 이벤트를 직접 세션에 보냅니다. 세션이 활성 상태가 아니고 미디어 버튼 수신기가 있는 경우 Android는 이벤트를 수신기에 전송합니다. 그러면 세션이 다시 시작되어 이벤트를 수신할 수 있습니다. 자세한 내용은 미디어 버튼을 사용하여 비활성 미디어 세션 다시 시작을 참조하세요. 세션에 미디어 버튼 수신기가 없으면 시스템에서 미디어 버튼 이벤트를 삭제하고 아무 일도 일어나지 않습니다. 로직은 다음 다이어그램과 같습니다.

  • Android 8.0 (API 수준 26) 이전 버전에서는 시스템에서 활성 미디어 세션으로 이벤트를 전송하려고 합니다. 활성 미디어 세션이 여러 개 있는 경우 Android는 중지된 미디어 세션이 아니라 재생 (버퍼링/연결)을 준비 중이거나 재생 중이거나 일시중지된 미디어 세션을 선택하려고 합니다. 자세한 내용은 활성 미디어 세션에서 미디어 버튼 처리를 참고하세요. 활성 세션이 없으면 Android는 가장 최근에 활성화된 세션으로 이벤트를 전송하려고 합니다. 자세한 내용은 미디어 버튼을 사용하여 비활성 미디어 세션 다시 시작을 참조하세요. 다음 다이어그램은 로직을 보여줍니다.

활성 미디어 세션에서 미디어 버튼 처리

Android 5.0 (API 수준 21) 이상에서 Android는 onMediaButtonEvent()를 호출하여 미디어 버튼 이벤트를 자동으로 활성 미디어 세션에 전달합니다. 기본적으로 이 콜백은 KeyEvent를 키 코드와 일치하는 적절한 미디어 세션 콜백 메서드로 변환합니다.

Android 5.0 (API 수준 21) 이전 버전에서는 Android가 ACTION_MEDIA_BUTTON 작업으로 인텐트를 브로드캐스트하여 미디어 버튼 이벤트를 처리합니다. 이러한 인텐트를 가로채려면 앱에서 BroadcastReceiver를 등록해야 합니다. MediaButtonReceiver 클래스는 이 목적을 위해 특별히 설계되었습니다. 이는 Android media-compat 라이브러리에 있는 편의 클래스로, ACTION_MEDIA_BUTTON를 처리하고 수신 인텐트를 적절한 MediaSessionCompat.Callback 메서드 호출로 변환합니다.

MediaButtonReceiver는 수명이 짧은 BroadcastReceiver로, 수신되는 인텐트를 미디어 세션을 관리하는 서비스에 전달합니다. Android 5.0 이전 시스템에서 미디어 버튼을 사용하려면 MEDIA_BUTTON 인텐트 필터를 사용하여 매니페스트에 MediaButtonReceiver를 포함해야 합니다.

<receiver android:name="android.support.v4.media.session.MediaButtonReceiver" >
   <intent-filter>
     <action android:name="android.intent.action.MEDIA_BUTTON" />
   </intent-filter>
 </receiver>

BroadcastReceiver는 인텐트를 서비스에 전달합니다. 인텐트를 파싱하고 미디어 세션의 콜백을 생성하려면 서비스의 onStartCommand()MediaButtonReceiver.handleIntent() 메서드를 포함합니다. 그러면 키 코드가 적절한 세션 콜백 메서드로 변환됩니다.

Kotlin

private val mediaSessionCompat: MediaSessionCompat = ...

override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
    MediaButtonReceiver.handleIntent(mediaSessionCompat, intent)
    return super.onStartCommand(intent, flags, startId)
}

Java

private MediaSessionCompat mediaSessionCompat = ...;

 public int onStartCommand(Intent intent, int flags, int startId) {
   MediaButtonReceiver.handleIntent(mediaSessionCompat, intent);
   return super.onStartCommand(intent, flags, startId);
 }

미디어 버튼을 사용하여 비활성 미디어 세션 다시 시작

Android는 마지막 활성 미디어 세션을 식별할 수 있는 경우 ACTION_MEDIA_BUTTON 인텐트를 manifest에 등록된 구성요소(예: 서비스 또는 BroadcastReceiver)로 보내 세션을 다시 시작하려고 합니다.

그러면 앱은 UI가 보이지 않는 동안 재생을 다시 시작할 수 있습니다(대부분의 오디오 앱이 그러함).

MediaSessionCompat 사용 시 이 동작이 자동으로 사용 설정됩니다. Android 프레임워크의 MediaSession 또는 지원 라이브러리 24.0.0~25.1.1을 사용하는 경우 setMediaButtonReceiver를 호출하여 미디어 버튼이 비활성 미디어 세션을 다시 시작하도록 해야 합니다.

null 미디어 버튼 수신기를 설정하여 Android 5.0 (API 수준 21) 이상에서 이 동작을 사용 중지할 수 있습니다.

Kotlin

// Create a MediaSessionCompat
mediaSession = MediaSessionCompat(context, LOG_TAG)
mediaSession.setMediaButtonReceiver(null)

Java

// Create a MediaSessionCompat
mediaSession = new MediaSessionCompat(context, LOG_TAG);
mediaSession.setMediaButtonReceiver(null);

미디어 버튼 핸들러 맞춤설정

onMediaButtonEvent()의 기본 동작은 키 코드를 추출하고 미디어 세션의 현재 상태 및 지원되는 작업 목록을 사용하여 어떤 메서드를 호출할지를 결정합니다. 예를 들어 KEYCODE_MEDIA_PLAYonPlay()를 호출합니다.

모든 앱에서 일관된 미디어 버튼 환경을 제공하려면 기본 동작을 사용하고 특정 목적을 위해서만 벗어나야 합니다. 미디어 버튼에 맞춤 처리가 필요한 경우 콜백의 onMediaButtonEvent() 메서드를 재정의하고, intent.getParcelableExtra(Intent.EXTRA_KEY_EVENT)를 사용하여 KeyEvent를 추출하고, 이벤트를 직접 처리하고, true를 반환합니다.

요약

모든 Android 버전에서 미디어 버튼 이벤트를 올바르게 처리하려면 미디어 세션을 만들 때 FLAG_HANDLES_MEDIA_BUTTONS를 지정해야 합니다.

또한 지원하려는 Android 버전에 따라 다음 요구사항도 충족해야 합니다.

Android 5.0 이상에서 실행하는 경우:

  • 미디어 컨트롤러 onConnected() 콜백에서 MediaControllerCompat.setMediaController()를 호출합니다.
  • 미디어 버튼이 비활성 세션을 다시 시작하도록 하려면 setMediaButtonReceiver()를 호출하고 PendingIntent를 전달하여 동적으로 MediaButtonReceiver를 만듭니다.

Android 5.0 이전의 시스템에서 실행하는 경우:

  • 미디어 버튼 처리를 위해 활동의 onKeyDown()을 재정의합니다.
  • 앱의 manifest에 추가하여 정적으로 MediaButtonReceiver를 생성합니다.