출력 전환기

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

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

샘플 다운로드

이 가이드에서 다룬 단계를 사용하여 로컬 간에서 원격으로의 출력을 지원하도록 출력 전환기를 사용 설정해야 합니다. 로컬 기기 스피커와 페어링된 블루투스 기기 간의 전송을 지원하는 데 추가 단계가 필요하지 않습니다.

오디오 앱은 Google Cast SDK 개발자 콘솔의 수신기 앱 설정에서 오디오용 Google Cast를 지원하는 앱입니다.

출력 전환기 UI

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

알려진 문제

  • 로컬 재생용으로 생성된 미디어 세션은 Cast SDK 알림으로 전환할 때 닫혔다가 다시 생성됩니다.

진입점

미디어 알림

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

볼륨 설정

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

단계 요약

기본 요건

  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을 설정하고 알림의 미디어 컨트롤을 설정해야 합니다.

현재 MediaStyle 및 MediaSession를 사용하지 않는 경우 아래 스니펫을 통해 설정 방법을 확인할 수 있습니다. 가이드를 통해 오디오 및 동영상 앱의 미디어 세션 콜백을 설정할 수 있습니다.

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에서 출력 전환기 사용 설정

출력 전환기를 사용 설정하려면 앱의 AndroidManifest.xml에 MediaTransferReceiver를 추가해야 합니다. 그렇지 않은 경우 이 기능이 사용 설정되지 않으며 원격-로컬 기능 플래그도 무효화됩니다.

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

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

원격에서 원격으로

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

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

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

출력 전환을 사용하는 새로운 전송 환경을 사용하면 앱이 백그라운드에 있을 때 전송을 시작할 수 있습니다. 이 기능은 백그라운드에서 재생할 때 알림을 게시하는 오디오 앱에 특히 유용합니다. 앱은 서비스의 onCreate()에서 SessionManager 리스너를 등록하고 서비스의 onDestroy()에서 등록을 취소할 수 있습니다. 이렇게 하면 앱이 백그라운드에 있을 때 앱에서 항상 로컬-원격 원격 콜백 (예: 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);
    }
  }
}

이 업데이트를 통해 앱이 백그라운드에서 실행 중이고 블루투스 기기에서 Cast 기기로 전환하기 위한 추가 작업이 필요하지 않을 때 로컬-리모컨이 기존 전송과 동일하게 작동합니다.

원격에서 오프라인으로

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

현재 발신자 기기가 여러 세션에 기존 세션에 참여하고 앱에서 현재 미디어의 로컬 전송이 허용되는지 확인해야 하는 경우 앱은 SessionTransferCallback의 onTransferred 콜백을 사용하여 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()
  }
}

로컬에서 계속 재생

원격에서 로컬을 지원하는 앱은 이벤트가 발생할 때 알림을 받을 수 있도록 SessionTransferCallback를 등록해야 합니다. 그래야 미디어에서 전송 후 로컬로 재생을 계속할 수 있는지 확인할 수 있습니다.

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

앱이 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.
    }
  }
}
이전
가입 의도
다음
추가 기능