输出切换器是 Cast SDK 的一项功能,从 Android 13 开始,可在本地和远程内容播放之间实现流畅转换。目的是帮助发送方应用轻松快速地控制内容的播放位置。输出切换器使用 MediaRouter
库在手机扬声器、配对的蓝牙设备和支持 Cast 的远程设备之间切换内容播放。用例可分解为以下场景:
下载并使用 CastVideos-android 示例应用,了解如何在应用中实现输出切换器。
您应按照本指南中介绍的步骤启用输出切换器,以支持本地到远程、远程到本地和远程到远程切换。无需执行任何其他步骤即可支持在本地设备音箱和已配对的蓝牙设备之间进行传输。
输出切换器界面
输出切换器会显示可用的本地和远程设备,以及当前设备状态,包括设备是否处于已选择、正在连接和当前音量等状态。如果除了当前设备之外还有其他设备,点击“其他设备”可将媒体播放转移到所选设备。
已知问题
- 切换到 Cast SDK 通知时,系统会关闭为本地播放创建的媒体会话,并重新创建这些会话。
入口点
媒体通知
如果应用使用 MediaSession
发布媒体通知以进行本地播放(在本地播放),则媒体通知的右上角会显示一个通知条状标签,其中包含当前播放内容所用的设备名称(例如手机扬声器)。点按通知条状标签会打开输出切换器对话框系统界面。
音量设置
您还可以通过以下方式触发输出切换器对话框系统界面:点击设备上的实体音量按钮,点按底部的设置图标,然后点按“在 <Cast 设备> 上播放 <应用名称>”文本。
步骤摘要
- 确保满足前提条件
- 在 AndroidManifest.xml 中启用输出切换器
- 更新了适用于后台投放的 SessionManagerListener
- 添加了对 Remote-to-Remote 的支持
- 设置 setRemoteToLocalEnabled 标志
- 在本地继续播放
前提条件
- 将现有的 Android 应用迁移到 AndroidX。
- 更新应用的
build.gradle
,以使用输出切换器的最低要求 Android Sender SDK 版本:dependencies { ... implementation 'com.google.android.gms:play-services-cast-framework:21.2.0' ... }
- 应用支持媒体通知。
- 搭载 Android 13 的设备。
设置媒体通知
如需使用输出切换器,音频和视频应用必须创建媒体通知,以显示其媒体的播放状态和控件,以便在本地播放。这需要创建 MediaSession
、使用 MediaSession
的令牌设置 MediaStyle
,并在通知上设置媒体控件。
如果您目前不使用 MediaStyle
和 MediaSession
,请参阅以下代码段,了解如何进行设置。此外,您还可以参阅有关为音频和视频应用设置媒体会话回调的指南:
// 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
常量。
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
常量。
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
。如果未启用,则该功能将无法启用,并且“远程到本地”功能标志也将无效。
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
MediaTransferReceiver
是一个广播接收器,可在具有系统界面的设备之间实现媒体传输。如需了解详情,请参阅 MediaTransferReceiver 参考文档。
本地到远程
当用户将播放模式从本地切换为远程时,Cast SDK 会自动启动 Cast 会话。不过,应用需要处理从本地切换到远程的操作,例如停止本地播放并在 Cast 设备上加载媒体。应用应使用 onSessionStarted()
和 onSessionEnded()
回调监听 Cast SessionManagerListener
,并在收到 Cast SessionManager
回调时处理操作。当打开输出切换器对话框且应用不在前台时,应用应确保这些回调仍处于有效状态。
更新了适用于后台投放的 SessionManagerListener
旧版 Cast 体验在应用处于前台时已支持本地到远程投放。典型的 Cast 体验始于用户点击应用中的 Cast 图标并选择用于流式传输媒体的设备。在这种情况下,应用需要在 onCreate()
或 onStart()
中注册 SessionManagerListener
,并在应用 activity 的 onStop()
或 onDestroy()
中取消注册监听器。
借助使用输出切换器投放内容的新体验,应用可以在后台开始投放内容。对于在后台播放时发布通知的音频应用,这尤其有用。应用可以在服务的 onCreate()
中注册 SessionManager
监听器,并在服务的 onDestroy()
中取消注册。当应用在后台运行时,应用应始终接收本地到远程回调(例如 onSessionStarted
)。
如果应用使用 MediaBrowserService
,建议在其中注册 SessionManagerListener
。
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.Builder
提供了 setRemoteToLocalEnabled
,用于在有有效 Cast 会话时,在输出切换器对话框中显示或隐藏手机扬声器和本地蓝牙设备作为转接目标。
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
触发后触发。远程到本地回调的顺序如下:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
由于当应用在后台投放时,媒体通知条状标签可以打开输出切换器,因此应用需要根据是否支持后台播放来不同地处理对本地的传输。如果传输失败,onTransferFailed
将在发生错误时随时触发。
支持后台播放的应用
对于支持在后台播放的应用(通常是音频应用),建议使用 Service
(例如 MediaBrowserService
)。服务应监听 onTransferred
回调,并在应用位于前台或后台时在本地恢复播放。
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
中的必要信息(例如媒体元数据和播放位置)。当应用从后台切换到前台时,本地播放应继续使用存储的信息。
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. } } }
远程到远程
输出切换器支持使用流式扩展功能将音频应用扩展到多个支持投放的音箱设备。
音频应用是指在 Google Cast SDK 开发者控制台的“接收器应用”设置中支持 Google Cast for Audio 的应用
使用音箱进行流式扩展
使用输出切换器的音频应用能够在 Cast 会话期间使用流式扩展功能将音频扩展到多个支持 Cast 的音箱设备。
Cast 平台支持此功能,如果应用使用的是默认界面,则无需进行任何进一步更改。如果使用自定义界面,应用应更新界面以反映应用正在投放到组。
如需在流式扩展期间获取新的展开式群组名称,请使用 CastSession#addCastListener
注册 Cast.Listener
。然后,在 onDeviceNameChanged
回调期间调用 CastSession#getCastDevice()
。
class MyActivity : Activity() { private var mCastSession: CastSession? = null private lateinit var mCastContext: CastContext private lateinit var mSessionManager: SessionManager private val mSessionManagerListener: SessionManagerListener<CastSession> = SessionManagerListenerImpl() private val mCastListener = CastListener() private inner class SessionManagerListenerImpl : SessionManagerListener<CastSession?> { override fun onSessionStarting(session: CastSession?) {} override fun onSessionStarted(session: CastSession?, sessionId: String) { addCastListener(session) } override fun onSessionStartFailed(session: CastSession?, error: Int) {} override fun onSessionSuspended(session: CastSession?, reason Int) { removeCastListener() } override fun onSessionResuming(session: CastSession?, sessionId: String) {} override fun onSessionResumed(session: CastSession?, wasSuspended: Boolean) { addCastListener(session) } override fun onSessionResumeFailed(session: CastSession?, error: Int) {} override fun onSessionEnding(session: CastSession?) {} override fun onSessionEnded(session: CastSession?, error: Int) { removeCastListener() } } private inner class CastListener : Cast.Listener() { override fun onDeviceNameChanged() { mCastSession?.let { val castDevice = it.castDevice val deviceName = castDevice.friendlyName // Update UIs with the new cast device name. } } } private fun addCastListener(castSession: CastSession) { mCastSession = castSession mCastSession?.addCastListener(mCastListener) } private fun removeCastListener() { mCastSession?.removeCastListener(mCastListener) } override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) mCastContext = CastContext.getSharedInstance(this) mSessionManager = mCastContext.sessionManager mSessionManager.addSessionManagerListener(mSessionManagerListener, CastSession::class.java) } override fun onDestroy() { super.onDestroy() mSessionManager.removeSessionManagerListener(mSessionManagerListener, CastSession::class.java) } }
public class MyActivity extends Activity { private CastContext mCastContext; private CastSession mCastSession; private SessionManager mSessionManager; private SessionManagerListener<CastSession> mSessionManagerListener = new SessionManagerListenerImpl(); private Cast.Listener mCastListener = new CastListener(); private class SessionManagerListenerImpl implements SessionManagerListener<CastSession> { @Override public void onSessionStarting(CastSession session) {} @Override public void onSessionStarted(CastSession session, String sessionId) { addCastListener(session); } @Override public void onSessionStartFailed(CastSession session, int error) {} @Override public void onSessionSuspended(CastSession session, int reason) { removeCastListener(); } @Override public void onSessionResuming(CastSession session, String sessionId) {} @Override public void onSessionResumed(CastSession session, boolean wasSuspended) { addCastListener(session); } @Override public void onSessionResumeFailed(CastSession session, int error) {} @Override public void onSessionEnding(CastSession session) {} @Override public void onSessionEnded(CastSession session, int error) { removeCastListener(); } } private class CastListener extends Cast.Listener { @Override public void onDeviceNameChanged() { if (mCastSession == null) { return; } CastDevice castDevice = mCastSession.getCastDevice(); String deviceName = castDevice.getFriendlyName(); // Update UIs with the new cast device name. } } private void addCastListener(CastSession castSession) { mCastSession = castSession; mCastSession.addCastListener(mCastListener); } private void removeCastListener() { if (mCastSession != null) { mCastSession.removeCastListener(mCastListener); } } @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); mCastContext = CastContext.getSharedInstance(this); mSessionManager = mCastContext.getSessionManager(); mSessionManager.addSessionManagerListener(mSessionManagerListener, CastSession.class); } @Override protected void onDestroy() { super.onDestroy(); mSessionManager.removeSessionManagerListener(mSessionManagerListener, CastSession.class); } }
测试远程到远程
如需测试此功能,请执行以下操作: