출력 전환기

출력 전환기는 Android 13부터 콘텐츠의 로컬 재생과 원격 재생 간에 원활하게 전송할 수 있는 Cast SDK의 기능입니다. 전송자 앱이 콘텐츠가 재생되는 위치를 쉽고 빠르게 제어하도록 돕는 것이 목표입니다. 출력 전환기는 MediaRouter 라이브러리를 사용하여 휴대전화 스피커, 페어링된 블루투스 기기, 원격 Cast 지원 기기 간에 콘텐츠 재생을 전환합니다. 사용 사례는 다음과 같은 시나리오로 나눌 수 있습니다.

오디오 앱에서 출력 전환을 구현하는 방법을 알아보려면 아래 샘플을 다운로드하여 사용하세요. 샘플 실행 방법에 관한 안내는 포함된 README.md를 참고하세요.

샘플 다운로드

이 가이드에 설명된 단계에 따라 local-to-remote 및 remote-to-local을 지원하려면 출력 전환기를 사용 설정해야 합니다. 로컬 기기 스피커와 페어링된 블루투스 기기 간의 전송을 지원하는 데 필요한 추가 단계는 없습니다.

오디오 앱은 Google Cast SDK Developer Console의 수신기 앱 설정에서 오디오용 Google Cast를 지원하는 앱입니다.

출력 전환기 UI

출력 전환기는 사용 가능한 로컬 및 원격 기기와 함께 현재 기기 상태(기기가 선택되어 있는지, 연결 중인지, 현재 볼륨 수준)를 표시합니다. 현재 기기 외에 다른 기기가 있는 경우 다른 기기를 클릭하면 미디어 재생을 선택한 기기로 전송할 수 있습니다.

알려진 문제

  • 로컬 재생을 위해 생성된 미디어 세션은 Cast SDK 알림으로 전환할 때 닫히고 다시 생성됩니다.

진입점

미디어 알림

앱이 로컬 재생 (로컬 재생)을 위해 MediaSession를 사용하여 미디어 알림을 게시하면 미디어 알림의 오른쪽 상단에 콘텐츠가 현재 재생되고 있는 기기 이름 (예: 휴대전화 스피커)이 포함된 알림 칩이 표시됩니다. 알림 칩을 탭하면 출력 전환기 대화상자 시스템 UI가 열립니다.

볼륨 설정

출력 전환기 대화상자 시스템 UI는 기기의 실제 볼륨 버튼을 클릭하고 하단의 설정 아이콘을 탭한 다음 '<Cast Device>에서 <App Name> 재생>' 텍스트를 탭하여 트리거할 수도 있습니다.

단계 요약

기본 요건

  1. 기존 Android 앱을 AndroidX로 이전합니다.
  2. 출력 전환기에 필요한 최소 버전의 Android Sender SDK를 사용하도록 앱의 build.gradle을 업데이트합니다.
    dependencies {
      ...
      implementation 'com.google.android.gms:play-services-cast-framework:21.2.0'
      ...
    }
  3. 앱이 미디어 알림을 지원합니다.
  4. Android 13을 실행하는 기기

미디어 알림 설정

출력 전환기를 사용하려면 오디오동영상 앱에서 로컬 재생을 위한 미디어의 재생 상태와 컨트롤을 표시하는 미디어 알림을 만들어야 합니다. 이렇게 하려면 MediaSession를 만들고 MediaSession의 토큰으로 MediaStyle를 설정하고 알림에 미디어 컨트롤을 설정해야 합니다.

현재 MediaStyleMediaSession를 사용하지 않는 경우 아래 스니펫에서 설정 방법을 보여주며 오디오동영상 앱의 미디어 세션 콜백을 설정하는 방법에 관한 가이드를 확인할 수 있습니다.

Kotlin
// Create a media session. NotificationCompat.MediaStyle
// PlayerService is your own Service or Activity responsible for media playback.
val mediaSession = MediaSessionCompat(this, "PlayerService")

// Create a MediaStyle object and supply your media session token to it.
val mediaStyle = Notification.MediaStyle().setMediaSession(mediaSession.sessionToken)

// Create a Notification which is styled by your MediaStyle object.
// This connects your media session to the media controls.
// Don't forget to include a small icon.
val notification = Notification.Builder(this@PlayerService, CHANNEL_ID)
    .setStyle(mediaStyle)
    .setSmallIcon(R.drawable.ic_app_logo)
    .build()

// Specify any actions which your users can perform, such as pausing and skipping to the next track.
val pauseAction: Notification.Action = Notification.Action.Builder(
        pauseIcon, "Pause", pauseIntent
    ).build()
notification.addAction(pauseAction)
자바
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    // Create a media session. NotificationCompat.MediaStyle
    // PlayerService is your own Service or Activity responsible for media playback.
    MediaSession mediaSession = new MediaSession(this, "PlayerService");

    // Create a MediaStyle object and supply your media session token to it.
    Notification.MediaStyle mediaStyle = new Notification.MediaStyle().setMediaSession(mediaSession.getSessionToken());

    // Specify any actions which your users can perform, such as pausing and skipping to the next track.
    Notification.Action pauseAction = Notification.Action.Builder(pauseIcon, "Pause", pauseIntent).build();

    // Create a Notification which is styled by your MediaStyle object.
    // This connects your media session to the media controls.
    // Don't forget to include a small icon.
    String CHANNEL_ID = "CHANNEL_ID";
    Notification notification = new Notification.Builder(this, CHANNEL_ID)
        .setStyle(mediaStyle)
        .setSmallIcon(R.drawable.ic_app_logo)
        .addAction(pauseAction)
        .build();
}

또한 미디어 정보로 알림을 채우려면 미디어의 메타데이터 및 재생 상태MediaSession에 추가해야 합니다.

MediaSession에 메타데이터를 추가하려면 setMetaData()를 사용하고 MediaMetadataCompat.Builder()에 미디어의 관련 MediaMetadata 상수를 모두 제공합니다.

Kotlin
mediaSession.setMetadata(MediaMetadataCompat.Builder()
    // Title
    .putString(MediaMetadata.METADATA_KEY_TITLE, currentTrack.title)

    // Artist
    // Could also be the channel name or TV series.
    .putString(MediaMetadata.METADATA_KEY_ARTIST, currentTrack.artist)

    // Album art
    // Could also be a screenshot or hero image for video content
    // The URI scheme needs to be "content", "file", or "android.resource".
    .putString(
        MediaMetadata.METADATA_KEY_ALBUM_ART_URI, currentTrack.albumArtUri)
    )

    // Duration
    // If duration isn't set, such as for live broadcasts, then the progress
    // indicator won't be shown on the seekbar.
    .putLong(MediaMetadata.METADATA_KEY_DURATION, currentTrack.duration)

    .build()
)
자바
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    mediaSession.setMetadata(
        new MediaMetadataCompat.Builder()
        // Title
        .putString(MediaMetadata.METADATA_KEY_TITLE, currentTrack.title)

        // Artist
        // Could also be the channel name or TV series.
        .putString(MediaMetadata.METADATA_KEY_ARTIST, currentTrack.artist)

        // Album art
        // Could also be a screenshot or hero image for video content
        // The URI scheme needs to be "content", "file", or "android.resource".
        .putString(MediaMetadata.METADATA_KEY_ALBUM_ART_URI, currentTrack.albumArtUri)

        // Duration
        // If duration isn't set, such as for live broadcasts, then the progress
        // indicator won't be shown on the seekbar.
        .putLong(MediaMetadata.METADATA_KEY_DURATION, currentTrack.duration)

        .build()
    );
}

재생 상태를 MediaSession에 추가하려면 setPlaybackState()를 사용하고 PlaybackStateCompat.Builder()에 미디어와 관련된 모든 PlaybackStateCompat 상수를 모두 제공합니다.

Kotlin
mediaSession.setPlaybackState(
    PlaybackStateCompat.Builder()
        .setState(
            PlaybackStateCompat.STATE_PLAYING,

            // Playback position
            // Used to update the elapsed time and the progress bar.
            mediaPlayer.currentPosition.toLong(),

            // Playback speed
            // Determines the rate at which the elapsed time changes.
            playbackSpeed
        )

        // isSeekable
        // Adding the SEEK_TO action indicates that seeking is supported
        // and makes the seekbar position marker draggable. If this is not
        // supplied seek will be disabled but progress will still be shown.
        .setActions(PlaybackStateCompat.ACTION_SEEK_TO)
        .build()
)
자바
if (android.os.Build.VERSION.SDK_INT >= android.os.Build.VERSION_CODES.O) {
    mediaSession.setPlaybackState(
        new PlaybackStateCompat.Builder()
            .setState(
                 PlaybackStateCompat.STATE_PLAYING,

                // Playback position
                // Used to update the elapsed time and the progress bar.
                mediaPlayer.currentPosition.toLong(),

                // Playback speed
                // Determines the rate at which the elapsed time changes.
                playbackSpeed
            )

        // isSeekable
        // Adding the SEEK_TO action indicates that seeking is supported
        // and makes the seekbar position marker draggable. If this is not
        // supplied seek will be disabled but progress will still be shown.
        .setActions(PlaybackStateCompat.ACTION_SEEK_TO)
        .build()
    );
}

동영상 앱 알림 동작

백그라운드에서 로컬 재생을 지원하지 않는 동영상 앱이나 오디오 앱은 재생이 지원되지 않는 상황에서 미디어 명령어를 전송할 때 문제가 발생하지 않도록 미디어 알림에 관한 특정 동작을 취해야 합니다.

  • 미디어를 로컬에서 재생하고 앱이 포그라운드에 있을 때 미디어 알림을 게시합니다.
  • 로컬 재생을 일시중지하고 앱이 백그라운드에 있으면 알림을 닫습니다.
  • 앱이 포그라운드로 다시 이동하면 로컬 재생이 다시 시작되고 알림을 다시 게시해야 합니다.

AndroidManifest.xml에서 출력 전환기 사용 설정

출력 전환기를 사용 설정하려면 MediaTransferReceiver를 앱의 AndroidManifest.xml에 추가해야 합니다. 사용 설정되어 있지 않으면 기능이 사용 설정되지 않으며 Remote-to-local 기능 플래그도 유효하지 않습니다.

<application>
    ...
    <receiver
         android:name="androidx.mediarouter.media.MediaTransferReceiver"
         android:exported="true">
    </receiver>
    ...
</application>

MediaTransferReceiver는 시스템 UI가 있는 기기 간에 미디어 전송을 사용 설정하는 broadcast receiver입니다. 자세한 내용은 MediaTransferReceiver 참조를 확인하세요.

로컬에서 원격 간

사용자가 재생을 로컬에서 원격으로 전환하면 Cast SDK가 자동으로 전송 세션을 시작합니다. 그러나 앱은 로컬에서 원격로의 전환을 처리해야 합니다. 예를 들어 로컬 재생을 중지하고 Cast 기기에 미디어를 로드해야 합니다. 앱은 onSessionStarted()onSessionEnded() 콜백을 사용하여 전송 SessionManagerListener를 수신 대기하고 전송 SessionManager 콜백을 수신할 때 작업을 처리해야 합니다. 앱은 출력 전환기 대화상자가 열려 있고 포그라운드에 있지 않을 때 이러한 콜백이 여전히 활성 상태인지 확인해야 합니다.

백그라운드 전송을 위한 SessionManagerListener 업데이트

기존 Cast 환경에서는 앱이 포그라운드에 있을 때 이미 local-to-remote를 지원합니다. 일반적인 전송 환경은 사용자가 앱에서 전송 아이콘을 클릭하고 미디어를 스트리밍할 기기를 선택하면 시작됩니다. 이 경우 앱은 onCreate() 또는 onStart()에서 SessionManagerListener에 등록하고 앱 활동의 onStop() 또는 onDestroy()에서 리스너를 등록 취소해야 합니다.

출력 전환기를 사용한 전송의 새로운 환경에서는 앱이 백그라운드에 있을 때 전송을 시작할 수 있습니다. 이 기능은 백그라운드에서 재생할 때 알림을 게시하는 오디오 앱에 특히 유용합니다. 앱은 서비스의 onCreate()에서 SessionManager 리스너를 등록하고 서비스의 onDestroy()에서 등록을 취소할 수 있습니다. 이렇게 하면 앱이 백그라운드에 있을 때 항상 local-to-remote 콜백 (예: onSessionStarted)을 수신해야 합니다.

앱이 MediaBrowserService를 사용한다면 여기에 SessionManagerListener를 등록하는 것이 좋습니다.

Kotlin
class MyService : Service() {
    private var castContext: CastContext? = null
    protected fun onCreate() {
        castContext = CastContext.getSharedInstance(this)
        castContext
            .getSessionManager()
            .addSessionManagerListener(sessionManagerListener, CastSession::class.java)
    }

    protected fun onDestroy() {
        if (castContext != null) {
            castContext
                .getSessionManager()
                .removeSessionManagerListener(sessionManagerListener, CastSession::class.java)
        }
    }
}
자바
public class MyService extends Service {
  private CastContext castContext;

  @Override
  protected void onCreate() {
     castContext = CastContext.getSharedInstance(this);
     castContext
        .getSessionManager()
        .addSessionManagerListener(sessionManagerListener, CastSession.class);
  }

  @Override
  protected void onDestroy() {
    if (castContext != null) {
       castContext
          .getSessionManager()
          .removeSessionManagerListener(sessionManagerListener, CastSession.class);
    }
  }
}

이 업데이트를 통해 local-to-remote는 앱이 백그라운드에 있을 때 기존 전송과 동일하게 작동하며 블루투스 기기에서 Cast 기기로 전환하는 데 추가 작업이 필요하지 않습니다.

원격에서 로컬로

출력 전환기를 사용하면 원격 재생에서 휴대전화 스피커 또는 로컬 블루투스 기기로 전송할 수 있습니다. CastOptions에서 setRemoteToLocalEnabled 플래그를 true로 설정하여 사용 설정할 수 있습니다.

현재 발신자 기기가 여러 발신자와 기존 세션에 참여하고 앱에서 현재 미디어를 로컬로 전송할 수 있는지 확인해야 하는 경우 앱은 SessionTransferCallbackonTransferred 콜백을 사용하여 SessionState를 확인해야 합니다.

setRemoteToLocalEnabled 플래그 설정

CastOptions는 활성 전송 세션이 있을 때 출력 전환기 대화상자에 전송 타겟으로 휴대전화 스피커와 로컬 블루투스 기기를 표시하거나 숨기는 setRemoteToLocalEnabled를 제공합니다.

Kotlin
class CastOptionsProvider : OptionsProvider {
    fun getCastOptions(context: Context?): CastOptions {
        ...
        return Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
    }
}
자바
public class CastOptionsProvider implements OptionsProvider {
    @Override
    public CastOptions getCastOptions(Context context) {
        ...
        return new CastOptions.Builder()
            ...
            .setRemoteToLocalEnabled(true)
            .build()
  }
}

로컬에서 계속 재생

Remote-to-local을 지원하는 앱은 SessionTransferCallback를 등록하여 이벤트가 발생할 때 알림을 받아야 합니다. 이렇게 하면 미디어를 전송하고 로컬에서 계속 재생할 수 있도록 허용해야 하는지 확인할 수 있습니다.

CastContext#addSessionTransferCallback(SessionTransferCallback)를 사용하면 발신자가 로컬 재생으로 전송될 때 앱에서 SessionTransferCallback를 등록하고 onTransferredonTransferFailed 콜백을 수신 대기할 수 있습니다.

앱이 SessionTransferCallback를 등록 취소하면 앱은 더 이상 SessionTransferCallback를 수신하지 않습니다.

SessionTransferCallback는 기존 SessionManagerListener 콜백의 확장이며 onSessionEnded가 트리거된 후에 트리거됩니다. 따라서 원격에서 로컬로 콜백하는 순서는 다음과 같습니다.

  1. onTransferring
  2. onSessionEnding
  3. onSessionEnded
  4. onTransferred

출력 전환기는 앱이 백그라운드에 있고 전송 중일 때 미디어 알림 칩에서 열 수 있으므로 앱은 백그라운드 재생을 지원하는지에 따라 로컬로의 전송을 다르게 처리해야 합니다. 전송에 실패하면 오류가 발생할 때마다 onTransferFailed가 실행됩니다.

백그라운드 재생을 지원하는 앱

백그라운드에서 재생을 지원하는 앱 (일반적으로 오디오 앱)의 경우 Service를 사용하는 것이 좋습니다 (예: MediaBrowserService). 서비스는 앱이 포그라운드 또는 백그라운드에 있을 때 onTransferred 콜백을 수신 대기하고 로컬에서 재생을 재개해야 합니다.

Kotlin
class MyService : Service() {
    private var castContext: CastContext? = null
    private var sessionTransferCallback: SessionTransferCallback? = null
    protected fun onCreate() {
        castContext = CastContext.getSharedInstance(this)
        castContext.getSessionManager()
                   .addSessionManagerListener(sessionManagerListener, CastSession::class.java)
        sessionTransferCallback = MySessionTransferCallback()
        castContext.addSessionTransferCallback(sessionTransferCallback)
    }

    protected fun onDestroy() {
        if (castContext != null) {
            castContext.getSessionManager()
                       .removeSessionManagerListener(sessionManagerListener, CastSession::class.java)
            if (sessionTransferCallback != null) {
                castContext.removeSessionTransferCallback(sessionTransferCallback)
            }
        }
    }

    class MySessionTransferCallback : SessionTransferCallback() {
        fun onTransferring(@SessionTransferCallback.TransferType transferType: Int) {
            // Perform necessary steps prior to onTransferred
        }

        fun onTransferred(@SessionTransferCallback.TransferType transferType: Int,
                          sessionState: SessionState?) {
            if (transferType == SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
                // Remote stream is transferred to the local device.
                // Retrieve information from the SessionState to continue playback on the local player.
            }
        }

        fun onTransferFailed(@SessionTransferCallback.TransferType transferType: Int,
                             @SessionTransferCallback.TransferFailedReason transferFailedReason: Int) {
            // Handle transfer failure.
        }
    }
}
자바
public class MyService extends Service {
    private CastContext castContext;
    private SessionTransferCallback sessionTransferCallback;

    @Override
    protected void onCreate() {
        castContext = CastContext.getSharedInstance(this);
        castContext.getSessionManager()
                   .addSessionManagerListener(sessionManagerListener, CastSession.class);
        sessionTransferCallback = new MySessionTransferCallback();
        castContext.addSessionTransferCallback(sessionTransferCallback);
    }

    @Override
    protected void onDestroy() {
        if (castContext != null) {
            castContext.getSessionManager()
                       .removeSessionManagerListener(sessionManagerListener, CastSession.class);
            if (sessionTransferCallback != null) {
                castContext.removeSessionTransferCallback(sessionTransferCallback);
            }
        }
    }

    public static class MySessionTransferCallback extends SessionTransferCallback {
        public MySessionTransferCallback() {}

        @Override
        public void onTransferring(@SessionTransferCallback.TransferType int transferType) {
            // Perform necessary steps prior to onTransferred
        }

        @Override
        public void onTransferred(@SessionTransferCallback.TransferType int transferType,
                                  SessionState sessionState) {
            if (transferType==SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
                // Remote stream is transferred to the local device.
                // Retrieve information from the SessionState to continue playback on the local player.
            }
        }

        @Override
        public void onTransferFailed(@SessionTransferCallback.TransferType int transferType,
                                     @SessionTransferCallback.TransferFailedReason int transferFailedReason) {
            // Handle transfer failure.
        }
    }
}

백그라운드 재생을 지원하지 않는 앱

백그라운드 재생을 지원하지 않는 앱 (일반적으로 동영상 앱)의 경우 onTransferred 콜백을 수신 대기하고 앱이 포그라운드에 있으면 로컬에서 재생을 재개하는 것이 좋습니다.

앱이 백그라운드에 있는 경우 재생을 일시중지하고 SessionState에서 필요한 정보 (예: 미디어 메타데이터 및 재생 위치)를 저장해야 합니다. 앱이 백그라운드에서 포그라운드로 실행되는 경우 로컬 재생은 저장된 정보로 계속 진행되어야 합니다.

Kotlin
class MyActivity : AppCompatActivity() {
    private var castContext: CastContext? = null
    private var sessionTransferCallback: SessionTransferCallback? = null
    protected fun onCreate() {
        castContext = CastContext.getSharedInstance(this)
        castContext.getSessionManager()
                   .addSessionManagerListener(sessionManagerListener, CastSession::class.java)
        sessionTransferCallback = MySessionTransferCallback()
        castContext.addSessionTransferCallback(sessionTransferCallback)
    }

    protected fun onDestroy() {
        if (castContext != null) {
            castContext.getSessionManager()
                       .removeSessionManagerListener(sessionManagerListener, CastSession::class.java)
            if (sessionTransferCallback != null) {
                castContext.removeSessionTransferCallback(sessionTransferCallback)
            }
        }
    }

    class MySessionTransferCallback : SessionTransferCallback() {
        fun onTransferring(@SessionTransferCallback.TransferType transferType: Int) {
            // Perform necessary steps prior to onTransferred
        }

        fun onTransferred(@SessionTransferCallback.TransferType transferType: Int,
                          sessionState: SessionState?) {
            if (transferType == SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
                // Remote stream is transferred to the local device.

                // Retrieve information from the SessionState to continue playback on the local player.
            }
        }

        fun onTransferFailed(@SessionTransferCallback.TransferType transferType: Int,
                             @SessionTransferCallback.TransferFailedReason transferFailedReason: Int) {
            // Handle transfer failure.
        }
    }
}
자바
public class MyActivity extends AppCompatActivity {
  private CastContext castContext;
  private SessionTransferCallback sessionTransferCallback;

  @Override
  protected void onCreate() {
     castContext = CastContext.getSharedInstance(this);
     castContext
        .getSessionManager()
        .addSessionManagerListener(sessionManagerListener, CastSession.class);
     sessionTransferCallback = new MySessionTransferCallback();
     castContext.addSessionTransferCallback(sessionTransferCallback);
  }

  @Override
  protected void onDestroy() {
    if (castContext != null) {
       castContext
          .getSessionManager()
          .removeSessionManagerListener(sessionManagerListener, CastSession.class);
      if (sessionTransferCallback != null) {
         castContext.removeSessionTransferCallback(sessionTransferCallback);
      }
    }
  }

  public static class MySessionTransferCallback extends SessionTransferCallback {
    public MySessionTransferCallback() {}

    @Override
    public void onTransferring(@SessionTransferCallback.TransferType int transferType) {
        // Perform necessary steps prior to onTransferred
    }

    @Override
    public void onTransferred(@SessionTransferCallback.TransferType int transferType,
                               SessionState sessionState) {
      if (transferType==SessionTransferCallback.TRANSFER_TYPE_FROM_REMOTE_TO_LOCAL) {
        // Remote stream is transferred to the local device.

        // Retrieve information from the SessionState to continue playback on the local player.
      }
    }

    @Override
    public void onTransferFailed(@SessionTransferCallback.TransferType int transferType,
                                 @SessionTransferCallback.TransferFailedReason int transferFailedReason) {
      // Handle transfer failure.
    }
  }
}