Output Switcher הוא תכונה ב-Cast SDK שמאפשרת העברה חלקה בין הפעלה מקומית לבין הפעלה מרחוק של תוכן החל מ-Android 13. המטרה היא לעזור לאפליקציות של השולחים לשלוט בקלות ובמהירות במיקום שבו התוכן מופעל.
מתג המעבר למכשיר אחר משתמש בספרייה MediaRouter
כדי להעביר את הפעלת התוכן בין הרמקול של הטלפון, מכשירי Bluetooth מותאמים ומכשירים מרחוק שתומכים ב-Cast. אפשר לפצל את התרחישים לדוגמה לתרחישים הבאים:
הורידו את הדוגמה הבאה והשתמשו בה כדי ללמוד איך להטמיע את Output Switcher באפליקציית האודיו. עיינו ב-README.md המצורף לקבלת הוראות להפעלת הדוגמה.
יש להפעיל את מתג המעבר למכשיר אחר כדי לתמוך מרחוק בתקשורת המקומית ובמרחוק לאזור באמצעות השלבים שמפורטים במדריך הזה. אין צורך לבצע פעולות נוספות כדי להעביר בין הרמקולים של המכשיר המקומי למכשירי Bluetooth מותאמים.
אפליקציות אודיו הן אפליקציות שתומכות ב-Google Cast for Audio בהגדרות אפליקציית המקבל ב-Google Cast SDK Console
ממשק המשתמש של מתג המעבר למכשיר אחר
במתג המעבר למכשיר אחר מוצגים המכשירים המקומיים והמכשירים המרוחקים שזמינים, וגם את מצבי המכשיר הנוכחיים, כולל רמת עוצמת הקול הנוכחית – אם המכשיר נבחר ומחובר. אם יש מכשירים אחרים בנוסף למכשיר הנוכחי, לחיצה על המכשיר האחר תאפשר לכם להעביר את הפעלת המדיה למכשיר שנבחר.
בעיות מוכרות
- סשנים של מדיה שנוצרו להפעלה מקומית יבוטלו וייצרו מחדש כשתעברו להתראה של Cast SDK.
נקודות כניסה
התראה של מדיה
אם אפליקציה מפרסמת התראת מדיה עם MediaSession
להפעלה מקומית (הפעלה מקומית), בפינה השמאלית העליונה של ההתראה במדיה מוצג צ'יפ של התראה עם שם המכשיר (למשל רמקול הטלפון) שהתוכן מופעל כרגע. הקשה על צ'יפ ההתראה פותחת את ממשק המשתמש של מערכת הדו-שיח של 'מתג המעבר למכשיר'.
הגדרות עוצמת הקול
אפשר להפעיל את ממשק המשתמש של מערכת הדו-שיח של Output Switcher גם על-ידי לחיצה על לחצני עוצמת הקול הפיזיים במכשיר, הקשה על סמל ההגדרות בחלק התחתון והקשה על הטקסט "Play <App Name> on <Cast Device>" (הפעלת שם האפליקציה).
סיכום השלבים
- עמידה בדרישות המוקדמות
- מפעילים את מתג המעבר למכשיר אחר בקובץ AndroidManifest.xml
- עדכון של SessionManagerListener להעברה ברקע
- הגדרת הסימון setRemoteToLocalEnabled
- המשך ההפעלה באופן מקומי
דרישות מוקדמות
- העברת אפליקציה קיימת ל-Android אל AndroidX.
- צריך לעדכן את
build.gradle
של האפליקציה כך שתשתמש בגרסה המינימלית הנדרשת של Android Sender SDK עבור Output Switcher:dependencies { ... implementation 'com.google.android.gms:play-services-cast-framework:21.2.0' ... }
- האפליקציה תומכת בהתראות על מדיה.
- מכשיר עם Android 13.
הגדרה של התראות מדיה
כדי להשתמש במתג המעבר למכשיר אחר, אפליקציות אודיו ווידאו נדרשות ליצור התראת מדיה כדי להציג את סטטוס ההפעלה ואת הפקדים של המדיה להפעלה מקומית. כדי לעשות את זה צריך ליצור MediaSession
, להגדיר את ה-MediaStyle
עם האסימון של MediaSession
ולהגדיר את לחצני המדיה בהתראה.
אם אתם לא משתמשים כרגע ב-MediaStyle
וב-MediaSession
, קטע הקוד שבהמשך מראה איך להגדיר אותם, ויש מדריכים זמינים להגדרת הקריאות החוזרות (callbacks) של סשן מדיה באפליקציות אודיו ווידאו:
// 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()
ומספקים את כל הקבועים הרלוונטיים של MediaMetadata
למדיה ב-MediaMetadataCompat.Builder()
.
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
למדיה ב-PlaybackStateCompat.Builder()
.
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. האפליקציות צריכות להאזין להעברה (cast)
SessionManagerListener
,
באמצעות הקריאות החוזרות
onSessionStarted()
ו-onSessionEnded()
ולבצע את הפעולה כשמקבלים את הקריאות החוזרות
של ה-Cast
SessionManager
. האפליקציות צריכות להבטיח שהקריאות החוזרות (callback) האלה עדיין פעילות כשתיבת הדו-שיח Output Switcher נפתחת והאפליקציה לא בחזית.
עדכון של sessionManagerListener עבור העברה ברקע
בגרסה הקודמת של Cast, כבר יש תמיכה במעבר בין חנויות מקומיות לשלט רחוק כשהאפליקציה פועלת בחזית. חוויה אופיינית של הפעלת Cast מתחילה כשמשתמשים לוחצים על סמל ההעברה באפליקציה ובוחרים מכשיר לשידור מדיה. במקרה כזה, האפליקציה צריכה
להירשם ב-SessionManagerListener
,
ב-onCreate()
או
onStart()
ולבטל את רישום המאזינים ב-
onStop()
או ב-onDestroy()
מתוך הפעילות של האפליקציה.
בחוויית ההעברה (cast) החדשה באמצעות מתג המעבר למכשיר אחר, אפליקציות יכולות להתחיל לבצע העברה כשהן פועלות ברקע. היא שימושית במיוחד לאפליקציות אודיו שמפרסמות התראות גם בזמן ההפעלה שלהן ברקע. אפליקציות יכולות לרשום את המאזינים ל-SessionManager
ב-onCreate()
של השירות, ולבטל את הרישום ב-onDestroy()
של השירות. כך, האפליקציות תמיד צריכות לקבל את הקריאה החוזרת (callback) מהמיקום המקומי לרשת (כמו 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); } } }
בעקבות העדכון הזה, העברה מקומית מרחוק פועלת כמו העברה רגילה כשהאפליקציה פועלת ברקע, ולא נדרשת מאמץ נוסף כדי לעבור ממכשירי Bluetooth למכשירי Cast.
מרחוק ליעד מקומי
מתג המעבר למכשיר אחר מאפשר לעבור מהפעלה מרחוק לרמקול של הטלפון או למכשיר Bluetooth המקומי. אפשר להפעיל את זה על ידי הגדרת הדגל setRemoteToLocalEnabled
לערך true
ב-CastOptions
.
במקרים שבהם המכשיר השולח הנוכחי מצטרף לסשן קיים עם מספר שולחים והאפליקציה צריכה לבדוק אם אפשר להעביר את המדיה הנוכחית באופן מקומי, אפליקציות צריכות להשתמש בקריאה החוזרת (callback) של onTransferred
של SessionTransferCallback
כדי לבדוק את SessionState
.
הגדרת הסימון setremoteToLocalEnabled
השדה CastOptions
מספק setRemoteToLocalEnabled
כדי להציג או להסתיר את הרמקול של הטלפון ואת מכשירי ה-Bluetooth המקומיים כיעדים להעברה אל בתיבת הדו-שיח של 'כלי למעבר בין מכשירים', כשיש סשן 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
שלה ולהאזין לקריאות חוזרות (callback) של onTransferred
ו-onTransferFailed
כשהשולח מועבר להפעלה מקומית.
אחרי שהאפליקציה מבטלת את הרישום של SessionTransferCallback
, האפליקציה לא תקבל יותר
SessionTransferCallback
.
SessionTransferCallback
הוא תוסף של הקריאות החוזרות (callback) הקיימות ב-SessionManagerListener
, ומופעל אחרי ההפעלה של onSessionEnded
. לכן, הסדר של הקריאות החוזרות מרחוק לאזור המקומי הוא:
onTransferring
onSessionEnding
onSessionEnded
onTransferred
מכיוון שאפשר לפתוח את מתג המעבר למכשיר אחר באמצעות צ'יפ של התראות מדיה
כשהאפליקציה פועלת ברקע ובהפעלת Cast, האפליקציות צריכות לטפל בהעברה
למקומי באופן שונה, בהתאם לתמיכה שלהן בהפעלה ברקע או לא. במקרה של העברה שנכשלה, 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. } } }
אפליקציות שלא תומכות בהפעלה ברקע
באפליקציות שלא תומכות בהפעלה ברקע (בדרך כלל אפליקציות וידאו), מומלץ להאזין לקריאה החוזרת (callback) של 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. } } }