Der Ausgabewechsel ist eine Funktion des Cast SDK, die ab Android 13 die nahtlose Übertragung von Inhalten zwischen der lokalen und der Remote-Wiedergabe ermöglicht. Ziel ist es, Absender-Apps dabei zu helfen, schnell und einfach zu steuern, wo die Inhalte wiedergegeben werden.
Die Ausgabeauswahl verwendet die Bibliothek MediaRouter, um die Inhaltswiedergabe zwischen dem Smartphone-Lautsprecher, gekoppelten Bluetooth-Geräten und für Google Cast optimierten Remote-Geräten zu wechseln. Anwendungsfälle können in die folgenden Szenarien unterteilt werden:
Laden Sie das folgende Beispiel herunter und verwenden Sie es als Referenz, um die Ausgabeauswahl in Ihrer Audio-App zu implementieren. Eine Anleitung zum Ausführen des Beispiels finden Sie in der enthaltenen Datei README.md.
Die Ausgabeauswahl muss aktiviert sein, damit die beiden in dieser Anleitung beschriebenen Schritte von Lokal zu Remote und Remote-zu-Lokal unterstützt werden. 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 Empfänger-App-Einstellungen in der Google Cast SDK-Entwicklerkonsole unterstützen.
Benutzeroberfläche des Ausgabewechsels
Die Ausgabeauswahl zeigt die verfügbaren lokalen und Remote-Geräte sowie den aktuellen Gerätestatus an, einschließlich der aktuellen Lautstärke, wenn das Gerät ausgewählt ist, eine Verbindung herstellt. Wenn es neben dem aktuellen Gerät weitere Geräte gibt, können Sie die Medienwiedergabe durch Klicken auf ein anderes Gerät auf das ausgewählte Gerät übertragen.
Bekannte Probleme
- Für die lokale Wiedergabe erstellte Mediensitzungen werden geschlossen und neu erstellt, wenn zur Cast SDK-Benachrichtigung gewechselt wird.
Einstiegspunkte
Medienbenachrichtigung
Wenn eine App eine Medienbenachrichtigung mit MediaSession für die lokale Wiedergabe bereitstellt, wird in der oberen rechten Ecke der Medienbenachrichtigung ein Benachrichtigungs-Chip mit dem Namen des Geräts (z. B. Telefonlautsprecher) angezeigt, auf dem der Inhalt gerade wiedergegeben wird. Durch Tippen auf den Benachrichtigungs-Chip wird die System-UI des Dialogfelds „Ausgabeauswahl“ geöffnet.
Lautstärkeeinstellungen
Sie können die System-UI des Dialogfelds für die Ausgabeauswahl auch öffnen, indem Sie auf die physischen Lautstärketasten am Gerät, unten auf das Symbol für die Einstellungen und dann auf den Text „Play <App Name >“ (<App-Name > auf<Cast-Gerät> abspielen) tippen.
Zusammenfassung der Schritte
- Voraussetzungen erfüllen
- Ausgabeauswahl in AndroidManifest.xml aktivieren
- SessionManagerListener für das Hintergrundstreaming aktualisieren
- Flag „setRemoteToLocalEnabled“ festlegen
- Wiedergabe lokal fortsetzen
Voraussetzungen
- Migrieren Sie Ihre bestehende Android-App zu AndroidX.
- Aktualisieren Sie die
build.gradleIhrer App so, dass die erforderliche Mindestversion des Android Sender SDK für die Ausgabeauswahl verwendet wird: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
Wenn Sie die Ausgabeauswahl verwenden möchten, müssen die Audio- und Video-Apps eine Medienbenachrichtigung erstellen, um den Wiedergabestatus und Steuerelemente für die lokale Wiedergabe anzuzeigen. Dazu müssen Sie ein MediaSession erstellen, den MediaStyle mit dem Token des MediaSession festlegen und die Mediensteuerelemente für die Benachrichtigung festlegen.
Wenn Sie MediaStyle und MediaSession derzeit nicht verwenden, zeigt das folgende Snippet, wie sie eingerichtet werden. Außerdem sind Anleitungen zum Einrichten der Mediensitzungs-Callbacks für Audio- und Video-Apps 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();
}
Außerdem musst du die Metadaten und den Wiedergabestatus der Medien zu MediaSession hinzufügen, um die Benachrichtigung mit Informationen zu deinen Medien zu füllen.
Wenn Sie dem MediaSession Metadaten hinzufügen möchten, verwenden Sie setMetaData() und geben Sie alle relevanten MediaMetadata-Konstanten für Ihre Medien im 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 den Wiedergabestatus zur MediaSession hinzuzufügen, und gib alle relevanten PlaybackStateCompat-Konstanten für deine Medien im PlaybackStateCompat.Builder() 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()
);
}
Verhalten von Video-App-Benachrichtigungen
Video-Apps oder Audio-Apps, die keine lokale Wiedergabe im Hintergrund unterstützen, sollten ein spezielles Verhalten für Medienbenachrichtigungen haben, um Probleme beim Senden von Medienbefehlen in Situationen zu vermeiden, in denen die Wiedergabe nicht unterstützt wird:
- Die Medienbenachrichtigung posten, wenn Medien lokal abgespielt werden und die App im Vordergrund ausgeführt wird.
- Pausiere die lokale Wiedergabe und schließe die Benachrichtigung, wenn die App im Hintergrund ausgeführt wird.
- Wenn die App wieder in den Vordergrund wechselt, sollte die lokale Wiedergabe fortgesetzt und die Benachrichtigung noch einmal gepostet werden.
Ausgabeauswahl in AndroidManifest.xml aktivieren
Zum Aktivieren der Ausgabeauswahl muss MediaTransferReceiver dem AndroidManifest.xml der Anwendung hinzugefügt werden. Ist dies nicht der Fall, wird die Funktion nicht aktiviert und das Flag der Remote-zu-Lokal-Funktion ist ebenfalls ungültig.
<application>
...
<receiver
android:name="androidx.mediarouter.media.MediaTransferReceiver"
android:exported="true">
</receiver>
...
</application>
Der MediaTransferReceiver ist ein Broadcast-Empfänger, der die Medienübertragung zwischen Geräten mit System-UI ermöglicht. Weitere Informationen finden Sie in der Referenz zu MediaTransferReceiver.
Von Lokal zu Remote
Wenn der Nutzer von „Lokal“ zu „Remote“ wechselt, startet das Cast SDK die Streamingsitzung automatisch. Die Apps müssen jedoch den Wechsel von der lokalen zur Remote-Version übernehmen, z. B. müssen sie die lokale Wiedergabe stoppen und die Medien auf das Übertragungsgerät laden. Apps sollten den Cast-SessionManagerListener mit den onSessionStarted()- und onSessionEnded()-Callbacks überwachen und die Aktion verarbeiten, wenn sie die Cast-CallbacksSessionManager empfangen. Apps sollten dafür sorgen, dass diese Callbacks noch aktiv sind, wenn das Dialogfeld „Ausgabeauswahl“ geöffnet wird und sich die App nicht im Vordergrund befindet.
SessionManagerListener für Hintergrundstreaming aktualisieren
Die Legacy-Übertragung unterstützt bereits die lokale Übertragung von Remote-Verbindungen, 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 beim SessionManagerListener in onCreate() oder onStart() registrieren und die Registrierung des Listeners in onStop() oder onDestroy() der App-Aktivität aufheben.
Dank der neuen Funktion des Streamens über den Ausgabeauswahl-Switcher können Apps bereits im Hintergrund streamen. Dies ist besonders nützlich für Audio-Apps, die bei der Wiedergabe im Hintergrund Benachrichtigungen posten. Anwendungen können die SessionManager-Listener im onCreate() des Dienstes registrieren und in onDestroy() des Dienstes ihre Registrierung aufheben. Auf diese Weise sollten Anwendungen immer die Lokal-zu-Remote-Callbacks (z. B. onSessionStarted) erhalten, wenn sie im Hintergrund ausgeführt wird.
Wenn die App MediaBrowserService verwendet, wird empfohlen, 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 Lokal-zu-Remote-Streaming genauso wie das herkömmliche Streamen, wenn die App im Hintergrund ausgeführt wird und für den Wechsel von Bluetooth- zu Übertragungsgeräten kein zusätzlicher Aufwand erforderlich ist.
Von Remote zu Lokal
Der Ausgabewechsel bietet die Möglichkeit, von der Remote-Wiedergabe auf den Lautsprecher des Smartphones oder ein lokales Bluetooth-Gerät zu übertragen. Setzen Sie dazu das Flag setRemoteToLocalEnabled für CastOptions auf true.
Wenn das aktuelle Sendergerät einer vorhandenen 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
CastOptions stellt ein setRemoteToLocalEnabled bereit, mit dem der Lautsprecher des Smartphones und lokale Bluetooth-Geräte als Ziele für die Übertragung im Dialogfeld zur Ausgabeauswahl ein- oder ausgeblendet werden, wenn eine Streamingsitzung aktiv ist.
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 unterstützen, sollten die SessionTransferCallback registrieren, um beim Eintreten des Ereignisses benachrichtigt zu werden. So können sie prüfen, ob Medien die lokale Übertragung und Fortsetzung der Wiedergabe ermöglichen.
Mit CastContext#addSessionTransferCallback(SessionTransferCallback) kann eine App ihre SessionTransferCallback registrieren und auf onTransferred- und onTransferFailed-Callbacks warten, wenn ein Absender zur lokalen Wiedergabe weitergeleitet wird.
Nachdem die App ihre SessionTransferCallback-Registrierung aufgehoben hat, erhält die App keine SessionTransferCallbacks mehr.
SessionTransferCallback ist eine Erweiterung der vorhandenen SessionManagerListener-Callbacks und wird ausgelöst, nachdem onSessionEnded ausgelöst wurde. Daher sieht die Reihenfolge der Remote-zu-Lokal-Callbacks so aus:
onTransferringonSessionEndingonSessionEndedonTransferred
Da die Ausgabeauswahl über den Benachrichtigungs-Chip für Medien geöffnet werden kann, wenn die App im Hintergrund läuft und gestreamt wird, müssen Apps die Übertragung in ein lokales Netzwerk unterschiedlich verarbeiten, je nachdem, ob sie die Hintergrundwiedergabe unterstützen oder nicht. Bei einer fehlgeschlagenen Übertragung wird onTransferFailed jederzeit 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), empfiehlt sich die Verwendung eines Service (z. B. MediaBrowserService). Die Dienste sollten den onTransferred-Callback abhören 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 die Hintergrundwiedergabe nicht unterstützen
Bei Apps, die keine Hintergrundwiedergabe unterstützen (in der Regel Video-Apps), empfiehlt es sich, den onTransferred-Callback anzuhören und die Wiedergabe lokal fortzusetzen, wenn sich die App im Vordergrund befindet.
Wenn die App im Hintergrund ausgeführt wird, sollte sie die Wiedergabe anhalten und die erforderlichen Informationen aus SessionState speichern (z.B. Medienmetadaten und Wiedergabeposition). 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.
}
}
}