Die Ausgabeauswahl ist eine Funktion des Cast SDK, die eine nahtlose Übertragung zwischen der lokalen und der Remote-Wiedergabe von Inhalten ab Android 13 ermöglicht. So können Absender-Apps einfach und schnell steuern, wo die Inhalte wiedergegeben werden.
Die Ausgabeauswahl nutzt die Bibliothek MediaRouter
, um die Inhaltswiedergabe zwischen dem Smartphone-Lautsprecher, den gekoppelten Bluetooth-Geräten und den für Google Cast optimierten Remote-Geräten umzuschalten. Anwendungsfälle können in die folgenden Szenarien unterteilt werden:
Laden Sie das folgende Beispiel herunter und verwenden Sie es als Referenz zur Implementierung des Output Switchers in Ihrer Audio-App. Eine Anleitung zur Ausführung des Beispiels finden Sie in der enthaltenen README.md.
Die Ausgabeauswahl sollte aktiviert werden, um Lokal-zu-Remote und Remote-zu-Lokal mithilfe der in dieser Anleitung beschriebenen Schritte zu unterstützen. Für die Übertragung zwischen den lokalen Lautsprechern und den gekoppelten Bluetooth-Geräten sind keine weiteren Schritte erforderlich.
Audio-Apps sind Apps, die Google Cast für Audio in den Einstellungen der Receiver App in der Google Cast SDK Developer Console unterstützen.
Benutzeroberfläche für die Ausgabeauswahl
In der Ausgabeauswahl werden die verfügbaren lokalen und Remote-Geräte sowie der aktuelle Gerätestatus angezeigt, einschließlich der aktuellen Lautstärke und ob das ausgewählte Gerät eine Verbindung herstellt. Wenn es neben dem aktuellen Gerät noch weitere Geräte gibt, kannst du die Medienwiedergabe auf das ausgewählte Gerät übertragen, indem du auf ein anderes Gerät klickst.
Bekannte Probleme
- Mediensitzungen, die für die lokale Wiedergabe erstellt wurden, werden beim Wechsel zur Cast SDK-Benachrichtigung geschlossen und neu erstellt.
Einstiegspunkte
Medienbenachrichtigung
Wenn eine App eine Medienbenachrichtigung mit MediaSession
für die lokale Wiedergabe (lokal wiedergegeben) sendet, wird in der oberen rechten Ecke der Medienbenachrichtigung ein Benachrichtigungs-Chip mit dem Gerätenamen (z. B. Telefonlautsprecher) angezeigt, auf dem der Inhalt gerade wiedergegeben wird. Durch Tippen auf den Benachrichtigungs-Chip wird die
System-UI des Dialogfelds "Ausgabewechsel" geöffnet.
Lautstärkeeinstellungen
Die System-UI des Dialogfelds „Ausgabeauswahl“ kann auch durch Klicken auf die physischen Lautstärketasten auf dem Gerät, Tippen auf das Symbol „Einstellungen“ unten und „Play <App Name> on <Cast Device>“ (<App-Name> auf <Cast-Gerät> wiedergeben) aktiviert werden.
Zusammenfassung der Schritte
- Voraussetzungen erfüllen
- Ausgabewechsel in AndroidManifest.xml aktivieren
- SessionManagerListener für das Streamen im Hintergrund aktualisieren
- Flag „setRemoteToLocalEnabled“ festlegen
- Wiedergabe lokal fortsetzen
Voraussetzungen
- Migriere deine bestehende Android-App zu AndroidX.
- Aktualisiere die
build.gradle
deiner App, um die mindestens erforderliche Version des Android Sender SDK für den Ausgabewechsel zu verwenden:dependencies { ... implementation 'com.google.android.gms:play-services-cast-framework:21.2.0' ... }
- Die App unterstützt Medienbenachrichtigungen.
- Gerät mit Android 13.
Medienbenachrichtigungen einrichten
Zur Verwendung der Ausgabeauswahl müssen Audio- und Video-Apps eine Medienbenachrichtigung erstellen, in der der Wiedergabestatus und die Steuerelemente für ihre Medien für die lokale Wiedergabe angezeigt werden. Dazu musst du eine MediaSession
erstellen, den MediaStyle
mit dem Token von MediaSession
festlegen und die Mediensteuerelemente für die Benachrichtigung festlegen.
Wenn Sie MediaStyle
und MediaSession
derzeit nicht verwenden, sehen Sie im Snippet unten, wie sie eingerichtet werden. Für die Einrichtung der Callbacks für Mediensitzungen für Audio- und Video-Apps sind Leitfäden verfügbar:
// 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(); }
Damit in die Benachrichtigung Informationen zu deinen Medien eingefügt werden, musst du die Metadaten und den Wiedergabestatus des Mediums zu MediaSession
hinzufügen.
Wenn Sie dem MediaSession
Metadaten hinzufügen möchten, verwenden Sie setMetaData()
und geben Sie alle relevanten MediaMetadata
-Konstanten für Ihre Medien in der MediaMetadataCompat.Builder()
an.
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() ); }
Verwende setPlaybackState()
, um dem MediaSession
den Wiedergabestatus hinzuzufügen. Gib in der PlaybackStateCompat.Builder()
alle relevanten PlaybackStateCompat
-Konstanten für deine Medien an.
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() ); }
App-Benachrichtigungsverhalten
Video-Apps oder Audio-Apps, die die lokale Wiedergabe im Hintergrund nicht unterstützen, sollten ein bestimmtes Verhalten für Medienbenachrichtigungen verhalten, um Probleme beim Senden von Medienbefehlen zu vermeiden, wenn die Wiedergabe nicht unterstützt wird:
- Poste die Medienbenachrichtigung, wenn Medien lokal wiedergegeben werden und die App im Vordergrund ausgeführt wird.
- Die lokale Wiedergabe pausieren und die Benachrichtigung schließen, wenn die App im Hintergrund läuft.
- Wenn die App in den Vordergrund zurückwechselt, sollte die lokale Wiedergabe fortgesetzt und die Benachrichtigung erneut gepostet werden.
Ausgabeauswahl in AndroidManifest.xml aktivieren
Zum Aktivieren der Ausgabeauswahl muss der MediaTransferReceiver
dem AndroidManifest.xml
der Anwendung hinzugefügt werden. Andernfalls wird die Funktion nicht aktiviert und das Flag für die Remote-zu-Local-Funktion ist ebenfalls ungültig.
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
Der MediaTransferReceiver
ist ein Übertragungsempfänger, der die Medienübertragung zwischen Geräten mit System-UI ermöglicht. Weitere Informationen finden Sie in der Referenz zu MediaTransferReceiver.
Lokal-zu-Remote
Wenn der Nutzer die Wiedergabe von der lokalen Wiedergabe zu der Remote-Wiedergabe wechselt, startet das Cast SDK automatisch die Cast-Sitzung. Apps müssen jedoch für den Wechsel von lokal zu ferngesteuert sein. Beispielsweise müssen sie die lokale Wiedergabe beenden und die Medien auf das Übertragungsgerät laden. Apps sollten das Cast-Signal SessionManagerListener
über die onSessionStarted()
- und onSessionEnded()
-Callbacks erfassen und die Aktion beim Empfang der Cast-SessionManager
-Callbacks verarbeiten. Apps sollten sicherstellen, dass diese Callbacks noch aktiv sind, wenn das Dialogfeld für die Ausgabeauswahl geöffnet wird und die App nicht im Vordergrund ausgeführt wird.
SessionManagerListener für das Streamen im Hintergrund aktualisieren
Das alte Streamen unterstützt die Lokal-zu-Remote-Verbindung bereits, wenn die App im Vordergrund ausgeführt wird. Ein typisches Streaming beginnt, wenn Nutzer in der App auf das Cast-Symbol klicken und ein Gerät zum Streamen von Medien auswählen. In diesem Fall muss sich die Anwendung bei SessionManagerListener
in onCreate()
oder onStart()
registrieren und die Registrierung des Listeners in onStop()
oder onDestroy()
der Anwendungsaktivität aufheben.
Dank der neuen Übertragung über die Ausgabeauswahl können Apps mit dem Streamen beginnen, wenn sie sich im Hintergrund befinden. Dies ist besonders nützlich für Audio-Apps, die Benachrichtigungen senden, während sie im Hintergrund laufen. Anwendungen können die SessionManager
-Listener in der onCreate()
des Dienstes registrieren und die Registrierung im onDestroy()
des Dienstes aufheben. Auf diese Weise sollten Anwendungen immer die Local-zu-Remote-Callbacks (z. B. onSessionStarted
) empfangen, wenn sie im Hintergrund ausgeführt wird.
Wenn die Anwendung MediaBrowserService
verwendet, wird empfohlen, die SessionManagerListener
dort zu registrieren.
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); } } }
Nach diesem Update funktioniert das Streamen von der lokalen Verbindung zum Remote-Gerät genauso wie beim herkömmlichen Streamen, wenn die App im Hintergrund ausgeführt wird. Für den Wechsel von Bluetooth-Geräten zu Übertragungsgeräten ist kein zusätzlicher Aufwand erforderlich.
Remote-zu-Lokal
Die Ausgabeauswahl ermöglicht die Übertragung von der Remote-Wiedergabe auf den Telefonlautsprecher oder das lokale Bluetooth-Gerät. Setzen Sie dazu das Flag setRemoteToLocalEnabled
für CastOptions
auf true
.
Wenn das aktuelle Absendergerät einer bestehenden Sitzung mit mehreren Absendern beitritt und die App prüfen muss, ob die aktuellen Medien lokal übertragen werden dürfen, sollten Apps den onTransferred
-Callback von SessionTransferCallback
verwenden, um SessionState
zu prüfen.
Flag „setRemoteToLocalEnabled“ festlegen
Die CastOptions
bietet eine setRemoteToLocalEnabled
zum Ein- oder Ausblenden des Smartphone-Lautsprechers und lokaler Bluetooth-Geräte als Ziele für die Weiterleitung im Dialogfeld „Ausgabeauswahl“, wenn eine aktive Streaming-Sitzung läuft.
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() } }
Wiedergabe lokal fortsetzen
Apps, die Remote-zu-Lokal-Verbindungen unterstützen, sollten die SessionTransferCallback
registrieren, um über das Ereignis benachrichtigt zu werden. So können sie prüfen, ob Medien übertragen werden und die Wiedergabe lokal fortsetzen können.
Mit CastContext#addSessionTransferCallback(SessionTransferCallback)
kann eine App ihre SessionTransferCallback
registrieren und auf onTransferred
- und onTransferFailed
-Callbacks warten, wenn ein Sender zur lokalen Wiedergabe weitergeleitet wird.
Nachdem die App ihre SessionTransferCallback
abgemeldet hat, erhält sie keine SessionTransferCallback
s mehr.
SessionTransferCallback
ist eine Erweiterung der vorhandenen SessionManagerListener
-Callbacks und wird ausgelöst, nachdem onSessionEnded
ausgelöst wurde. Die Reihenfolge der Remote-zu-Lokal-Callbacks lautet daher:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
Da die Ausgabeauswahl über den Medienbenachrichtigungs-Chip geöffnet werden kann, wenn die App im Hintergrund ausgeführt wird und Daten überträgt, müssen die Apps die Übertragung an die lokale Umgebung unterschiedlich verarbeiten, je nachdem, ob sie die Hintergrundwiedergabe unterstützen oder nicht. Bei einer fehlgeschlagenen Übertragung wird onTransferFailed
immer ausgelöst, wenn der Fehler auftritt.
Apps, die die Hintergrundwiedergabe unterstützen
Für Apps, die die Wiedergabe im Hintergrund unterstützen (in der Regel Audio-Apps), wird die Verwendung einer Service
(z. B. MediaBrowserService
) empfohlen. Die Dienste sollten den onTransferred
-Callback erfassen und die Wiedergabe lokal fortsetzen, sowohl wenn die App im Vordergrund als auch im Hintergrund ausgeführt wird.
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. } } }
Apps, die keine Hintergrundwiedergabe unterstützen
Bei Apps, die keine Hintergrundwiedergabe unterstützen (in der Regel Video-Apps), empfiehlt es sich, auf den onTransferred
-Callback zu achten und die Wiedergabe lokal fortzusetzen, wenn sich die App im Vordergrund befindet.
Wenn die App im Hintergrund ausgeführt wird, sollte sie die Wiedergabe pausieren und die erforderlichen Informationen aus SessionState
(z.B. Medienmetadaten und Wiedergabeposition) speichern. Wenn die App im Hintergrund im Vordergrund ausgeführt wird, sollte die lokale Wiedergabe mit den gespeicherten Informationen fortgesetzt werden.
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. } } }