미디어 버튼에 응답

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

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

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

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

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

  • Android 5.0(API 레벨 21) 이상을 실행 중인 경우 FLAG_HANDLES_MEDIA_BUTTONSMediaBrowserCompat.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)
        }

    자바

            @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 인텐트 필터를 사용하여 manifest에 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)
    }

자바

    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)

자바

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

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

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

모든 앱에서 일관된 미디어 버튼 환경을 제공하려면 기본 동작을 사용하되 특별한 목적을 위해서만 예외를 적용해야 합니다. 미디어 버튼에 맞춤 처리가 필요한 경우 콜백의 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를 생성합니다.