סשנים של מדיה מספקים דרך אוניברסלית לאינטראקציה עם נגן אודיו או וידאו. ב-Media3, נגן ברירת המחדל הוא המחלקה ExoPlayer
, שמטמיעה את הממשק Player
. חיבור סשן המדיה לנגן מאפשר לאפליקציה לפרסם הפעלת מדיה באופן חיצוני ולקבל פקודות הפעלה ממקורות חיצוניים.
הפקודות יכולות להגיע מלחצנים פיזיים, כמו לחצן ההפעלה באוזניות או בשלט הרחוק של הטלוויזיה. הן יכולות להגיע גם מאפליקציות לקוח עם נגן מדיה, למשל הוראה ל-Google Assistant להשהות את ההפעלה. הסשן במדיה מקצה את הפקודות האלה לנגן של אפליקציית המדיה.
מתי כדאי לבחור סשן מדיה
כשמטמיעים את MediaSession
, המשתמשים יכולים לשלוט בהפעלה:
- דרך האוזניות שלהם. לעיתים קרובות יש לחצנים או אינטראקציות מגע שהמשתמש יכול לבצע באוזניות כדי להפעיל או להשהות מדיה או לעבור לטראק הבא או הקודם.
- על ידי דיבור אל Google Assistant. דפוס נפוץ הוא לומר "Ok Google, pause" כדי להשהות כל מדיה שפועלת כרגע במכשיר.
- דרך שעון Wear OS. כך קל יותר לגשת לפקדי ההפעלה הנפוצים ביותר כשצופים בטלפון.
- באמצעות פקדי המדיה. בקרוסלה הזו מוצגים הפקדים של כל סשן מדיה פעיל.
- ב-טלוויזיה. מאפשרת לבצע פעולות באמצעות לחצני הפעלה פיזיים, לשלוט בהפעלה בפלטפורמה ולנהל את צריכת החשמל (לדוגמה, אם הטלוויזיה, פס האודיו או מקלט ה-A/V נכבים או שהקלט משתנה, ההפעלה אמורה להיפסק באפליקציה).
- וכל תהליך חיצוני אחר שצריכים להשפיע על ההפעלה.
זה שימושי בהרבה תרחישי שימוש. במיוחד מומלץ להשתמש ב-MediaSession
במקרים הבאים:
- אתם צופים בסטרימינג של תוכן וידאו ארוך, כמו סרטים או טלוויזיה בשידור חי.
- אתם משדרים בסטרימינג תוכן אודיו ארוך, כמו פודקאסטים או פלייליסטים של מוזיקה.
- אתם מפתחים אפליקציית טלוויזיה.
עם זאת, לא כל תרחישי לדוגמה מתאימים ל-MediaSession
. כדאי להשתמש רק ב-Player
במקרים הבאים:
- אתם מציגים תוכן קצר, שבו חשובה מאוד ההתעניינות והאינטראקציה של המשתמשים.
- אין סרטון פעיל אחד, למשל המשתמש גולל ברשימה ומספר סרטונים מוצגים במסך בו-זמנית.
- אתם מפעילים סרטון מבוא או הסבר חד-פעמי, שאתם מצפים שהמשתמש יצפה בו באופן פעיל.
- התוכן שלכם רגיש לפרטיות ואתם לא רוצים שתהליכים חיצוניים יקבלו גישה למטא-נתוני המדיה (לדוגמה, מצב פרטי בדפדפן)
אם תרחיש השימוש שלכם לא תואם לאף אחד מהתרחישים שמפורטים למעלה, כדאי לשקול אם אתם מסכימים שההפעלה באפליקציה תמשיך גם כשהמשתמש לא מעורב באופן פעיל בתוכן. אם התשובה היא כן, מומלץ לבחור באפשרות MediaSession
. אם התשובה היא 'לא', מומלץ להשתמש ב-Player
במקום זאת.
יצירת סשן מדיה
סשן מדיה נמצא לצד הנגן שהוא מנהל. אפשר ליצור סשן מדיה באמצעות אובייקט Context
ואובייקט Player
. צריך ליצור ולהפעיל סשן מדיה לפי הצורך, למשל באמצעות שיטת מחזור החיים onStart()
או onResume()
של Activity
או Fragment
, או באמצעות השיטה onCreate()
של Service
שבבעלותו סשן המדיה והנגן המשויך אליו.
כדי ליצור סשן מדיה, צריך לאתחל את Player
ולספק אותו ל-MediaSession.Builder
באופן הבא:
Kotlin
val player = ExoPlayer.Builder(context).build() val mediaSession = MediaSession.Builder(context, player).build()
Java
ExoPlayer player = new ExoPlayer.Builder(context).build(); MediaSession mediaSession = new MediaSession.Builder(context, player).build();
טיפול אוטומטי במצבים
ספריית Media3 מעדכנת באופן אוטומטי את סשן המדיה בהתאם למצב הנגן. לכן, אין צורך לטפל באופן ידני במיפוי מהנגן לסשן.
זוהי סטייה מהגישה הקודמת, שבה צריך ליצור ולתחזק PlaybackStateCompat
בנפרד מהנגן עצמו, למשל כדי לציין שגיאות.
מזהה סשן ייחודי
כברירת מחדל, MediaSession.Builder
יוצר סשן עם מחרוזת ריקה בתור מזהה הסשן. זה מספיק אם האפליקציה מתכוונת ליצור רק מופע אחד של סשן, וזה המצב הנפוץ ביותר.
אם אפליקציה רוצה לנהל מספר מופעים של סשנים בו-זמנית, היא צריכה לוודא שמזהה הסשן של כל סשן הוא ייחודי. אפשר להגדיר את מזהה הסשן בזמן היצירה שלו באמצעות MediaSession.Builder.setId(String id)
.
אם IllegalStateException
גורם לקריסה של האפליקציה עם הודעת השגיאה IllegalStateException: Session ID must be unique. ID=
, סביר להניח שסשן נוצר באופן בלתי צפוי לפני שמכונה שנוצרה בעבר עם אותו מזהה שוחררה. כדי למנוע הדלפה של סשנים עקב שגיאת תכנות, מקרים כאלה מזוהים ומקבלים הודעה על ידי הפעלת חריגה.
הענקת שליטה ללקוחות אחרים
סשן המדיה הוא המפתח לשליטה בהפעלה. היא מאפשרת לנתב פקודות ממקורות חיצוניים לנגן שמפעיל את המדיה. המקורות האלה יכולים להיות לחצנים פיזיים, כמו לחצן ההפעלה באוזניות או בשלט הרחוק של הטלוויזיה, או פקודות עקיפות כמו "השהיה" ב-Google Assistant. כמו כן, כדאי להעניק גישה למערכת Android כדי להקל על בקרת ההתראות ומסך הנעילה, או לשעון Wear OS כדי שתוכלו לשלוט בהפעלה מהמסך של השעון. לקוחות חיצוניים יכולים להשתמש בנגן מדיה כדי להנפיק פקודות הפעלה לאפליקציית המדיה. הפקודות האלה מתקבלות בסשן המדיה, שמעביר אותן בסופו של דבר לנגן המדיה.
כשאמצעי בקרה עומד להתחבר לסשן המדיה, מתבצעת קריאה ל-method onConnect()
. אתם יכולים להשתמש ב-ControllerInfo
שסופק כדי להחליט אם לאשר או לדחות את הבקשה. דוגמה לאישור בקשת חיבור מופיעה בקטע הצהרה על הפקודות הזמינות.
אחרי החיבור, הבקר יכול לשלוח לסשן פקודות הפעלה. לאחר מכן, הסשן מעביר את הפקודות האלה לנגן. פקודות ההפעלה והפלייליסט שהוגדרו בממשק Player
מטופלות באופן אוטומטי על ידי הסשן.
שיטות אחרות של קריאה חוזרת מאפשרות לטפל, למשל, בבקשות לפקודות הפעלה בהתאמה אישית ולשינוי הפלייליסט).
הקריאות החוזרות האלה כוללות באופן דומה אובייקט ControllerInfo
, כך שאפשר לשנות את אופן התגובה לכל בקשה בנפרד.
שינוי הפלייליסט
סשן מדיה יכול לשנות ישירות את הפלייליסט של הנגן שלו, כפי שמוסבר במדריך של ExoPlayer לפלייליסטים.
בנוסף, אמצעי הבקרה יכולים לשנות את הפלייליסט אם COMMAND_SET_MEDIA_ITEM
או COMMAND_CHANGE_MEDIA_ITEMS
זמינים לאמצעי הבקרה.
כשמוסיפים פריטים חדשים לפלייליסט, הנגן בדרך כלל דורש מכונות MediaItem
עם מזהה URI מוגדר כדי שאפשר יהיה להפעיל אותם. כברירת מחדל, פריטים חדשים שנוספו מועברים אוטומטית ל-methods של שחקן כמו player.addMediaItem
, אם מוגדר להם URI.
אם רוצים להתאים אישית את המכונות של MediaItem
שנוספו לנגן, אפשר לבטל את onAddMediaItems()
.
צריך לבצע את השלב הזה אם רוצים לתמוך בבקשות מדיה של בקרי מדיה ללא URI מוגדר. במקום זאת, בדרך כלל מוגדר ב-MediaItem
אחד או יותר מהשדות הבאים כדי לתאר את המדיה המבוקשת:
MediaItem.id
: מזהה כללי שמזהה את המדיה.MediaItem.RequestMetadata.mediaUri
: URI של בקשה שעשוי להשתמש בסכימה בהתאמה אישית, ולא בהכרח שניתן להפעיל אותו ישירות בנגן.MediaItem.RequestMetadata.searchQuery
: שאילתת חיפוש טקסטואלית, למשל מ-Google Assistant.MediaItem.MediaMetadata
: מטא-נתונים מובְנים כמו 'שם' או 'אומן'.
כדי לקבל אפשרויות נוספות להתאמה אישית של פלייליסטים חדשים לגמרי, אפשר גם לשנות את הערך של onSetMediaItems()
כדי להגדיר את הפריט והמיקום של ההתחלה בפלייליסט. לדוגמה, אפשר להרחיב פריט בודד שנבקש לפלייליסט שלם ולהורות לנגן להתחיל במדד של הפריט שנבקש במקור. הטמעה לדוגמה של onSetMediaItems()
עם התכונה הזו מופיעה באפליקציית הדגמה של הסשן.
ניהול של פריסה בהתאמה אישית ופקודות בהתאמה אישית
בקטעים הבאים מוסבר איך לפרסם לאפליקציות לקוח פריסה בהתאמה אישית של לחצני פקודות בהתאמה אישית, ולהעניק הרשאה למכשירי הבקרה לשלוח את הפקודות בהתאמה אישית.
הגדרת פריסה מותאמת אישית של הסשן
כדי לציין לאפליקציות הלקוח אילו אמצעי בקרה על ההפעלה אתם רוצים להציג למשתמש, מגדירים את פריסת הסשן בהתאמה אישית כשאתם יוצרים את MediaSession
בשיטה onCreate()
של השירות.
Kotlin
override fun onCreate() { super.onCreate() val likeButton = CommandButton.Builder() .setDisplayName("Like") .setIconResId(R.drawable.like_icon) .setSessionCommand(SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING)) .build() val favoriteButton = CommandButton.Builder() .setDisplayName("Save to favorites") .setIconResId(R.drawable.favorite_icon) .setSessionCommand(SessionCommand(SAVE_TO_FAVORITES, Bundle())) .build() session = MediaSession.Builder(this, player) .setCallback(CustomMediaSessionCallback()) .setCustomLayout(ImmutableList.of(likeButton, favoriteButton)) .build() }
Java
@Override public void onCreate() { super.onCreate(); CommandButton likeButton = new CommandButton.Builder() .setDisplayName("Like") .setIconResId(R.drawable.like_icon) .setSessionCommand(new SessionCommand(SessionCommand.COMMAND_CODE_SESSION_SET_RATING)) .build(); CommandButton favoriteButton = new CommandButton.Builder() .setDisplayName("Save to favorites") .setIconResId(R.drawable.favorite_icon) .setSessionCommand(new SessionCommand(SAVE_TO_FAVORITES, new Bundle())) .build(); Player player = new ExoPlayer.Builder(this).build(); mediaSession = new MediaSession.Builder(this, player) .setCallback(new CustomMediaSessionCallback()) .setCustomLayout(ImmutableList.of(likeButton, favoriteButton)) .build(); }
הצהרת פקודות נגן ופקודות בהתאמה אישית שזמינות
אפליקציות מדיה יכולות להגדיר פקודות בהתאמה אישית, למשל לשימוש בפריסה בהתאמה אישית. לדוגמה, יכול להיות שתרצו להטמיע לחצנים שמאפשרים למשתמש לשמור פריט מדיה ברשימת הפריטים המועדפים. הפקודה MediaController
שולחת פקודות בהתאמה אישית וה-MediaSession.Callback
מקבל אותן.
אתם יכולים להגדיר אילו פקודות מותאמות אישית של סשן יהיו זמינות ל-MediaController
כשהוא יתחבר לסשן המדיה שלכם. אפשר לעשות זאת על ידי שינוי של MediaSession.Callback.onConnect()
. מגדירים ומחזירים את קבוצת הפקודות הזמינות כשמאשרים בקשת חיבור מ-MediaController
בשיטת ה-callback onConnect
:
Kotlin
private inner class CustomMediaSessionCallback: MediaSession.Callback { // Configure commands available to the controller in onConnect() override fun onConnect( session: MediaSession, controller: MediaSession.ControllerInfo ): MediaSession.ConnectionResult { val sessionCommands = ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon() .add(SessionCommand(SAVE_TO_FAVORITES, Bundle.EMPTY)) .build() return AcceptedResultBuilder(session) .setAvailableSessionCommands(sessionCommands) .build() } }
Java
class CustomMediaSessionCallback implements MediaSession.Callback { // Configure commands available to the controller in onConnect() @Override public ConnectionResult onConnect( MediaSession session, ControllerInfo controller) { SessionCommands sessionCommands = ConnectionResult.DEFAULT_SESSION_COMMANDS.buildUpon() .add(new SessionCommand(SAVE_TO_FAVORITES, new Bundle())) .build(); return new AcceptedResultBuilder(session) .setAvailableSessionCommands(sessionCommands) .build(); } }
כדי לקבל בקשות של פקודות בהתאמה אישית מ-MediaController
, צריך לשנות את השיטה onCustomCommand()
ב-Callback
.
Kotlin
private inner class CustomMediaSessionCallback: MediaSession.Callback { ... override fun onCustomCommand( session: MediaSession, controller: MediaSession.ControllerInfo, customCommand: SessionCommand, args: Bundle ): ListenableFuture<SessionResult> { if (customCommand.customAction == SAVE_TO_FAVORITES) { // Do custom logic here saveToFavorites(session.player.currentMediaItem) return Futures.immediateFuture( SessionResult(SessionResult.RESULT_SUCCESS) ) } ... } }
Java
class CustomMediaSessionCallback implements MediaSession.Callback { ... @Override public ListenableFuture<SessionResult> onCustomCommand( MediaSession session, ControllerInfo controller, SessionCommand customCommand, Bundle args ) { if(customCommand.customAction.equals(SAVE_TO_FAVORITES)) { // Do custom logic here saveToFavorites(session.getPlayer().getCurrentMediaItem()); return Futures.immediateFuture( new SessionResult(SessionResult.RESULT_SUCCESS) ); } ... } }
אפשר לעקוב אחרי רכיב הבקרה של המדיה ששולח את הבקשה באמצעות המאפיין packageName
של האובייקט MediaSession.ControllerInfo
שמועברים לשיטות Callback
. כך תוכלו להתאים אישית את התנהגות האפליקציה בתגובה לפקודה מסוימת, אם היא מגיעה מהמערכת, מהאפליקציה שלכם או מאפליקציות לקוח אחרות.
עדכון פריסה מותאמת אישית לאחר אינטראקציה של משתמש
אחרי טיפול בפקודה מותאמת אישית או בכל אינטראקציה אחרת עם הנגן, כדאי לעדכן את הפריסה שמוצגת בממשק המשתמש של הבקר. דוגמה אופיינית היא לחצן החלפת מצב שמשנה את הסמל שלו אחרי הפעלת הפעולה שמשויכת ללחצן הזה. כדי לעדכן את הפריסה, אפשר להשתמש ב-MediaSession.setCustomLayout
:
Kotlin
val removeFromFavoritesButton = CommandButton.Builder() .setDisplayName("Remove from favorites") .setIconResId(R.drawable.favorite_remove_icon) .setSessionCommand(SessionCommand(REMOVE_FROM_FAVORITES, Bundle())) .build() mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton))
Java
CommandButton removeFromFavoritesButton = new CommandButton.Builder() .setDisplayName("Remove from favorites") .setIconResId(R.drawable.favorite_remove_icon) .setSessionCommand(new SessionCommand(REMOVE_FROM_FAVORITES, new Bundle())) .build(); mediaSession.setCustomLayout(ImmutableList.of(likeButton, removeFromFavoritesButton));
התאמה אישית של ההתנהגות של פקודת ההפעלה
כדי להתאים אישית את ההתנהגות של פקודה שהוגדרה בממשק Player
, כמו play()
או seekToNext()
, צריך לעטוף את Player
ב-ForwardingPlayer
.
Kotlin
val player = ExoPlayer.Builder(context).build() val forwardingPlayer = object : ForwardingPlayer(player) { override fun play() { // Add custom logic super.play() } override fun setPlayWhenReady(playWhenReady: Boolean) { // Add custom logic super.setPlayWhenReady(playWhenReady) } } val mediaSession = MediaSession.Builder(context, forwardingPlayer).build()
Java
ExoPlayer player = new ExoPlayer.Builder(context).build(); ForwardingPlayer forwardingPlayer = new ForwardingPlayer(player) { @Override public void play() { // Add custom logic super.play(); } @Override public void setPlayWhenReady(boolean playWhenReady) { // Add custom logic super.setPlayWhenReady(playWhenReady); } }; MediaSession mediaSession = new MediaSession.Builder(context, forwardingPlayer).build();
מידע נוסף על ForwardingPlayer
זמין במדריך של ExoPlayer בנושא התאמה אישית.
זיהוי הבקר המבקש של פקודת נגן
כשהקריאה ל-method Player
מגיעה מ-MediaController
, אפשר לזהות את מקור המקור עם MediaSession.controllerForCurrentRequest
ולקבל את ה-ControllerInfo
בשביל הבקשה הנוכחית:
Kotlin
class CallerAwareForwardingPlayer(player: Player) : ForwardingPlayer(player) { override fun seekToNext() { Log.d( "caller", "seekToNext called from package ${session.controllerForCurrentRequest?.packageName}" ) super.seekToNext() } }
Java
public class CallerAwareForwardingPlayer extends ForwardingPlayer { public CallerAwareForwardingPlayer(Player player) { super(player); } @Override public void seekToNext() { Log.d( "caller", "seekToNext called from package: " + session.getControllerForCurrentRequest().getPackageName()); super.seekToNext(); } }
תגובה ללחיצה על לחצני מדיה
לחצני מדיה הם לחצני חומרה שקיימים במכשירי Android ובמכשירים היקפיים אחרים, כמו לחצן ההפעלה וההשהיה באוזניות Bluetooth. כשאירועי לחצני המדיה מגיעים לסשן, Media3 מטפל בהם ומפעיל את השיטה המתאימה Player
בנגן הסשן.
אפליקציה יכולה לשנות את התנהגות ברירת המחדל על ידי שינוי הערך של MediaSession.Callback.onMediaButtonEvent(Intent)
. במקרה כזה, האפליקציה יכולה/צריכה לטפל בכל הפרטים הספציפיים של ה-API בעצמה.
טיפול בשגיאות ודיווח עליהן
יש שני סוגי שגיאות שסשן פולט ומדווח לנאמני מידע. שגיאות קטלניות מדווחות על כשל טכני בהפעלה של נגן הסשן, שמפריע להפעלה. שגיאות קטלניות מדווחות למסוף באופן אוטומטי כשהן מתרחשות. שגיאות לא חמורות הן שגיאות לא טכניות או שגיאות מדיניות שלא מפריעות להפעלה, ונשלחות לנאמני מידע על ידי האפליקציה באופן ידני.
שגיאות קריטיות בהפעלה
הנגן מדווח על שגיאת הפעלה קריטית לסשן, ואז הוא מדווח לבקרים כדי לבצע קריאה דרך Player.Listener.onPlayerError(PlaybackException)
ו-Player.Listener.onPlayerErrorChanged(@Nullable PlaybackException)
.
במקרה כזה, מצב ההפעלה מועבר ל-STATE_IDLE
ו-MediaController.getPlaybackError()
יחזיר את הערך PlaybackException
שגרם למעבר. אמצעי בקרה יכול לבדוק את PlayerException.errorCode
כדי לקבל מידע על הסיבה לשגיאה.
כדי לבצע יכולת פעולה הדדית, שגיאה חמורה משוכפלת ל-PlaybackStateCompat
של הסשן בפלטפורמה. לשם כך, מעבירים את המצב ל-STATE_ERROR
ומגדירים את קוד השגיאה וההודעה בהתאם ל-PlaybackException
.
התאמה אישית של שגיאה קריטית
כדי לספק למשתמש מידע מקומי ומשמעותי, תוכלו להתאים אישית את קוד השגיאה, הודעת השגיאה והתוספות לשגיאה של שגיאת הפעלה חמורה באמצעות ForwardingPlayer
כשיוצרים את הסשן:
Kotlin
val forwardingPlayer = ErrorForwardingPlayer(player) val session = MediaSession.Builder(context, forwardingPlayer).build()
Java
Player forwardingPlayer = new ErrorForwardingPlayer(player); MediaSession session = new MediaSession.Builder(context, forwardingPlayer).build();
הנגן המעביר רושם Player.Listener
לנגן עצמו ומיירט קריאות חוזרות (callback) שמדווחות על שגיאה. לאחר מכן, המערכת מעבירה את הערך המותאם אישית של PlaybackException
למאזינים שרשומים בנגן ההעברה. כדי שהפעולה הזו תפעל, הנגן המעביר מבטל את ההגדרות של Player.addListener
ו-Player.removeListener
כדי לקבל גישה למאזינים, שבאמצעותם הוא יכול לשלוח קוד שגיאה, הודעה או פרטים נוספים בהתאמה אישית:
Kotlin
class ErrorForwardingPlayer(private val context: Context, player: Player) : ForwardingPlayer(player) { private val listeners: MutableList<Player.Listener> = mutableListOf() private var customizedPlaybackException: PlaybackException? = null init { player.addListener(ErrorCustomizationListener()) } override fun addListener(listener: Player.Listener) { listeners.add(listener) } override fun removeListener(listener: Player.Listener) { listeners.remove(listener) } override fun getPlayerError(): PlaybackException? { return customizedPlaybackException } private inner class ErrorCustomizationListener : Player.Listener { override fun onPlayerErrorChanged(error: PlaybackException?) { customizedPlaybackException = error?.let { customizePlaybackException(it) } listeners.forEach { it.onPlayerErrorChanged(customizedPlaybackException) } } override fun onPlayerError(error: PlaybackException) { listeners.forEach { it.onPlayerError(customizedPlaybackException!!) } } private fun customizePlaybackException( error: PlaybackException, ): PlaybackException { val buttonLabel: String val errorMessage: String when (error.errorCode) { PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW -> { buttonLabel = context.getString(R.string.err_button_label_restart_stream) errorMessage = context.getString(R.string.err_msg_behind_live_window) } // Apps can customize further error messages by adding more branches. else -> { buttonLabel = context.getString(R.string.err_button_label_ok) errorMessage = context.getString(R.string.err_message_default) } } val extras = Bundle() extras.putString("button_label", buttonLabel) return PlaybackException(errorMessage, error.cause, error.errorCode, extras) } override fun onEvents(player: Player, events: Player.Events) { listeners.forEach { it.onEvents(player, events) } } // Delegate all other callbacks to all listeners without changing arguments like onEvents. } }
Java
private static class ErrorForwardingPlayer extends ForwardingPlayer { private final Context context; private List<Player.Listener> listeners; @Nullable private PlaybackException customizedPlaybackException; public ErrorForwardingPlayer(Context context, Player player) { super(player); this.context = context; listeners = new ArrayList<>(); player.addListener(new ErrorCustomizationListener()); } @Override public void addListener(Player.Listener listener) { listeners.add(listener); } @Override public void removeListener(Player.Listener listener) { listeners.remove(listener); } @Nullable @Override public PlaybackException getPlayerError() { return customizedPlaybackException; } private class ErrorCustomizationListener implements Listener { @Override public void onPlayerErrorChanged(@Nullable PlaybackException error) { customizedPlaybackException = error != null ? customizePlaybackException(error, context) : null; for (int i = 0; i < listeners.size(); i++) { listeners.get(i).onPlayerErrorChanged(customizedPlaybackException); } } @Override public void onPlayerError(PlaybackException error) { for (int i = 0; i < listeners.size(); i++) { listeners.get(i).onPlayerError(checkNotNull(customizedPlaybackException)); } } private PlaybackException customizePlaybackException( PlaybackException error, Context context) { String buttonLabel; String errorMessage; switch (error.errorCode) { case PlaybackException.ERROR_CODE_BEHIND_LIVE_WINDOW: buttonLabel = context.getString(R.string.err_button_label_restart_stream); errorMessage = context.getString(R.string.err_msg_behind_live_window); break; // Apps can customize further error messages by adding more case statements. default: buttonLabel = context.getString(R.string.err_button_label_ok); errorMessage = context.getString(R.string.err_message_default); break; } Bundle extras = new Bundle(); extras.putString("button_label", buttonLabel); return new PlaybackException(errorMessage, error.getCause(), error.errorCode, extras); } @Override public void onEvents(Player player, Events events) { for (int i = 0; i < listeners.size(); i++) { listeners.get(i).onEvents(player, events); } } // Delegate all other callbacks to all listeners without changing arguments like onEvents. } }
שגיאות לא קטלניות
אפליקציה יכולה לשלוח שגיאות לא קטלניות שלא נובעות מחריגה טכנית לכל הבקרים או לבקר ספציפי:
Kotlin
val sessionError = SessionError( SessionError.ERROR_SESSION_AUTHENTICATION_EXPIRED, context.getString(R.string.error_message_authentication_expired), ) // Sending a nonfatal error to all controllers. mediaSession.sendError(sessionError) // Interoperability: Sending a nonfatal error to the media notification controller to set the // error code and error message in the playback state of the platform media session. mediaSession.mediaNotificationControllerInfo?.let { mediaSession.sendError(it, sessionError) }
Java
SessionError sessionError = new SessionError( SessionError.ERROR_SESSION_AUTHENTICATION_EXPIRED, context.getString(R.string.error_message_authentication_expired)); // Sending a nonfatal error to all controllers. mediaSession.sendError(sessionError); // Interoperability: Sending a nonfatal error to the media notification controller to set the // error code and error message in the playback state of the platform media session. ControllerInfo mediaNotificationControllerInfo = mediaSession.getMediaNotificationControllerInfo(); if (mediaNotificationControllerInfo != null) { mediaSession.sendError(mediaNotificationControllerInfo, sessionError); }
שגיאה לא קטלנית שנשלחת למתג ההתראות של המדיה עוברת רפליקה ל-PlaybackStateCompat
של סשן הפלטפורמה. כך, רק קוד השגיאה והודעת השגיאה מוגדרים ב-PlaybackStateCompat
בהתאם, בעוד ש-PlaybackStateCompat.state
לא משתנה ל-STATE_ERROR
.
קבלת שגיאות לא קטלניות
MediaController
מקבל שגיאה לא קריטית על ידי הטמעת MediaController.Listener.onError
:
Kotlin
val future = MediaController.Builder(context, sessionToken) .setListener(object : MediaController.Listener { override fun onError(controller: MediaController, sessionError: SessionError) { // Handle nonfatal error. } }) .buildAsync()
Java
MediaController.Builder future = new MediaController.Builder(context, sessionToken) .setListener( new MediaController.Listener() { @Override public void onError(MediaController controller, SessionError sessionError) { // Handle nonfatal error. } });