סשנים של מדיה מספקים דרך אוניברסלית לאינטראקציה עם נגן אודיו או וידאו. כשמיידעים את Android שמדיה מופעלת באפליקציה, אפשר להעביר את רכיבי ה-UI להפעלה לאפליקציה. שילוב עם סשן המדיה מאפשר לאפליקציה לפרסם את הפעלת המדיה באופן חיצוני ולקבל פקודות הפעלה ממקורות חיצוניים. המקורות האלה יכולים להיות כפתורים פיזיים (כמו כפתור ההפעלה באוזניות או בשלט רחוק של טלוויזיה) או פקודות עקיפות (כמו הפקודה "pause" ל-Google Assistant). לאחר מכן, סשן המדיה מעביר את הפקודות האלה לאפליקציה, שמחילה אותן על נגן המדיה. לנגן המדיה לא משנה מה מקור הפקודות.
סשן מדיה פועל לצד הנגן שהוא מנהל. צריך ליצור סשן מדיה ולהפעיל אותו ב-method onCreate() של הפעילות או השירות שבבעלותם סשן המדיה והנגן שמשויך אליו.
הפעלת סשן המדיה
לסשן מדיה חדש שנוצר אין יכולות. כדי לאתחל את הסשן, צריך לבצע את הפעולות הבאות:
- מגדירים דגלים כדי שסשן המדיה יוכל לקבל קריאות חוזרות (callbacks) מבקרי מדיה ומכפתורי מדיה.
- יוצרים ומאתחלים מופע של
PlaybackStateCompatומקצים אותו לסשן. מצב ההפעלה משתנה במהלך הסשן, לכן מומלץ לשמור אתPlaybackStateCompat.Builderבמטמון לשימוש חוזר. - יוצרים מופע של
MediaSessionCompat.Callbackומקצים אותו לסשן (מידע נוסף על קריאות חוזרות מופיע בהמשך).
צריך ליצור ולאתחל סשן מדיה ב-method onCreate() של הפעילות או השירות שבבעלותם הסשן.
כדי שלחצני המדיה יפעלו כשהאפליקציה מאותחלת מחדש (או נעצרת), ה-PlaybackState שלה חייב להכיל פעולת הפעלה שתואמת ל-Intent שלחצן המדיה שולח. לכן ACTION_PLAY מוקצה למצב הסשן במהלך האתחול. מידע נוסף זמין במאמר תגובה ללחצני מדיה.
שמירה על מצב ההפעלה והמטא-נתונים
יש שתי מחלקות שמייצגות את המצב של סשן מדיה.
הכיתה PlaybackStateCompat מתארת את המצב התפעולי הנוכחי של הנגן. למשל:
- מצב ההעברה (אם הנגן פועל, מושהה, בטעינה וכו'.
מידע נוסף זמין במאמר
getState()) - קוד שגיאה והודעת שגיאה אופציונלית, אם רלוונטי. (ראו
getErrorCode()וקראו את הקטע מצבים ושגיאות בהמשך). - מיקום הנגן
- פעולות הבקר התקינות שאפשר לבצע במצב הנוכחי
הכיתה MediaMetadataCompat מתארת את החומר שמופעל:
- שם האומן, האלבום והטראק
- משך הטראק
- עטיפת האלבום שמוצגת במסך הנעילה. התמונה היא מפת סיביות (bitmap) בגודל מקסימלי של 320x320dp (אם היא גדולה יותר, היא מוקטנת).
- מופע של
ContentUrisשמפנה לגרסה גדולה יותר של הגרפיקה
המצב והמטא-נתונים של הנגן יכולים להשתנות במהלך סשן המדיה. בכל פעם שהמצב או המטא-נתונים משתנים, צריך להשתמש בכלי ה-builder המתאים לכל מחלקה, PlaybackStateCompat.Builder() או MediaMetadataCompat.Builder(), ואז להעביר את המכונה החדשה לסשן המדיה באמצעות קריאה ל-setPlaybackState() או ל-setMetaData(). כדי להפחית את צריכת הזיכרון הכוללת מהפעולות התכופות האלה, מומלץ ליצור את ה-builders פעם אחת ולהשתמש בהם שוב במהלך הסשן.
מצבים ושגיאות
שימו לב ש-PlaybackState הוא אובייקט שמכיל ערכים נפרדים למצב ההפעלה של הסשן (getState()) ובמקרה הצורך, קוד שגיאה משויך (getErrorCode()). השגיאות יכולות להיות קריטיות או לא קריטיות:
בכל פעם שההפעלה מופסקת, צריך ליצור שגיאה חמורה: מגדירים את מצב ההעברה ל-STATE_ERROR ומציינים שגיאה משויכת באמצעות setErrorMessage(int, CharSequence). כל עוד ההפעלה חסומה בגלל השגיאה, ה-PlaybackState צריך להמשיך לדווח על STATE_ERROR ועל השגיאה.
שגיאה לא קריטית מתרחשת כשהאפליקציה לא יכולה לטפל בבקשה, אבל יכולה להמשיך לפעול: הטרנספורט נשאר במצב "רגיל" (כמו STATE_PLAYING) אבל PlaybackState מכיל קוד שגיאה. לדוגמה, אם השיר האחרון מתנגן והמשתמש מבקש לדלג לשיר הבא, ההפעלה יכולה להימשך, אבל צריך ליצור PlaybackState חדש עם קוד השגיאה ERROR_CODE_END_OF_QUEUE ואז לקרוא ל-setPlaybackState(). ממשקי השליטה במדיה שמחוברים לסשן יקבלו את הקריאה החוזרת (callback) onPlaybackStateChanged() ויסבירו למשתמש מה קרה. צריך לדווח על שגיאה לא קריטית רק פעם אחת, כשהיא מתרחשת. בפעם הבאה שהסשן מעדכן את PlaybackState, אל תגדירו שוב את אותה שגיאה לא חמורה (אלא אם השגיאה קרתה בתגובה לבקשה חדשה).
מסכי נעילה של פעילות מדיה
החל מ-Android 4.0 (רמת API 14), המערכת יכולה לגשת למטא-נתונים ולמצב ההפעלה של סשן מדיה. ככה מסך הנעילה יכול להציג את ממשק השליטה במדיה ואת הגרפיקה. ההתנהגות משתנה בהתאם לגרסת Android.
עטיפות אלבומים
ב-Android מגרסה 4.0 (רמת API 14) ועד Android מגרסה 10 (רמת API 29), הרקע של מסך הנעילה מציג את עטיפת האלבום – אבל רק אם המטא-נתונים של סשן המדיה כוללים מפת סיביות (bitmap) של הרקע.
פקדי נסיעה
בגרסאות Android 4.0 (רמת API 14) עד Android 4.4 (רמת API 19), כשסשן מדיה פעיל והמטא-נתונים של סשן המדיה כוללים מפת סיביות ברקע, פקדי ההעברה מוצגים באופן אוטומטי במסך הנעילה.
ב-Android מגרסה 5.0 (רמת API 21) ואילך, המערכת לא מספקת פקדי העברה במסך הנעילה. במקום זאת, צריך להשתמש בהתראת MediaStyle כדי להציג את פקדי ההעברה.
הוספת פעולות בהתאמה אישית
אפליקציות מדיה יכולות להגדיר פעולות בהתאמה אישית, למשל: לייק, דיסלייק או הרצה אחורה של 30 שניות. פעולה בהתאמה אישית צריכה להטמיע התנהגות חדשה לגמרי. אל תשתמשו בפעולה מותאמת אישית כדי להחליף את אחת מפעולות הבקרה הרגילות של ההפעלה שמוגדרות ב-PlaybackStateCompat.
מוסיפים פעולות מותאמות אישית באמצעות addCustomAction(). בדוגמה הבאה אפשר לראות איך מוסיפים אמצעי בקרה לפעולת לייק:
Kotlin
stateBuilder.addCustomAction(
PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP,
resources.getString(R.string.thumbs_up),
thumbsUpIcon
).run {
setExtras(customActionExtras)
build()
}
)
Java
stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
.setExtras(customActionExtras)
.build());
אפשר לעיין בנגן מוזיקה אוניברסלי כדי לראות דוגמה מלאה.
אתם מגיבים לפעולה באמצעות onCustomAction().
Kotlin
override fun onCustomAction(action: String, extras: Bundle?) {
when(action) {
CUSTOM_ACTION_THUMBS_UP -> {
...
}
}
}
Java
@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
...
}
}
כדאי לעיין גם בנגן המוזיקה האוניברסלי.
קריאות חוזרות (callbacks) של סשן מדיה
שיטות הקריאה החוזרת העיקריות של סשן המדיה הן onPlay(), onPause() ו-onStop(). כאן מוסיפים את הקוד ששולט בנגן.
מכיוון שאתם יוצרים מופע ומגדירים את הקריאה החוזרת של הסשן בזמן הריצה (ב-onCreate()), האפליקציה יכולה להגדיר קריאות חוזרות חלופיות שמשתמשות בנגנים שונים, ולבחור את השילוב המתאים של קריאה חוזרת ונגן בהתאם למכשיר ולרמת המערכת. אפשר להחליף את הנגן בלי לשנות את שאר האפליקציה. לדוגמה, אפשר להשתמש ב-ExoPlayer כשמריצים את האפליקציה ב-Android 4.1 (רמת API 16) ומעלה, וב-MediaPlayer במערכות ישנות יותר.
בנוסף לשליטה בנגן ולניהול המעברים בין המצבים של סשן המדיה, פונקציות ה-callback גם מפעילות ומשביתות תכונות באפליקציה, ושולטות באופן שבו היא פועלת עם אפליקציות אחרות ועם החומרה של המכשיר. (שליטה בפלט האודיו).
ההטמעה של שיטות הקריאה החוזרת של סשן המדיה תלויה במבנה של האפליקציה. בדפים הנפרדים שמתארים איך להשתמש בקריאות חוזרות באפליקציות אודיו ובאפליקציות וידאו, מוסבר איך להטמיע את הקריאות החוזרות בכל סוג של אפליקציה.