שימוש בסשן מדיה

פעילויות מדיה מספקות דרך אוניברסלית לאינטראקציה עם אודיו או וידאו נגן. אם מיידעים את Android על כך שמדיה מופעלת באפליקציה, אפשר להפעיל ניתן להעניק הרשאה לשימוש בפקדים באפליקציה. שילוב עם הפעלת המדיה מאפשר אפליקציה לפרסום הפעלת מדיה באופן חיצוני ולקבל פקודות הפעלה ממקורות חיצוניים. המקורות האלה יכולים להיות לחצנים פיזיים (כמו לחצן ההפעלה) באוזניות או בשלט הרחוק של הטלוויזיה) או פקודות עקיפות (כמו הוראה ל"השהיה" אל Google Assistant). לאחר מכן, סשן המדיה יאציל את הסמכויות האלה פקודות לאפליקציה שמחילות אותם על נגן המדיה שעבורו שקוף מהמקור הפקודות.

סשן מדיה פעיל לצד הנגן שהוא מנהל. אתם צריכים ליצור ומאתחלים סשן מדיה בשיטה onCreate() של הפעילות, או השירות שבבעלותו סשן המדיה והנגן המשויך אליו.

אתחול הסשן של המדיה

לסשן מדיה חדש אין יכולות. כדי לאתחל את הסשן, צריך לבצע את השלבים הבאים:

מגדירים סימונים כדי שסשן המדיה יוכל לקבל התקשרות חזרה מבקרי מדיה ומלחצני מדיה.
יוצרים ומפעילים מכונה של PlaybackStateCompat ומקצים אותו לסשן. מצב ההפעלה משתנה במהלך הסשן, לכן מומלץ לשמור במטמון את PlaybackStateCompat.Builder לשימוש חוזר.
צריך ליצור מכונה של MediaSessionCompat.Callback ולהקצות אותו לסשן (מידע נוסף על קריאות חוזרות (callback) מופיע בהמשך).

עליך ליצור ולהפעיל סשן מדיה באמצעות השיטה onCreate() של פעילות או השירות שהוא הבעלים של הסשן.

כדי שלחצני המדיה יפעלו כשהאפליקציה שלך מופעלת לאחרונה (או מפסיקה), הPlaybackState שלה צריך מכילים פעולת הפעלה שתואמת לכוונה שלחצן המדיה שולח. הדבר למה ACTION_PLAY הוקצה למצב הסשן במהלך באתחול. מידע נוסף זמין במאמר תגובה למדיה לחצנים.

שומרים על מצב ההפעלה ועל המטא-נתונים

יש שני מחלקות שמייצגות את המצב של סשן מדיה.

PlaybackStateCompat מתאר את המצב התפעולי הנוכחי של הנגן. התכונות כוללות:

מצב ההעברה (האם הנגן מופעל, מושהה או בתהליך אגירת נתונים וכו'. מידע נוסף זמין בgetState())
קוד שגיאה והודעת שגיאה אופציונלית, אם רלוונטי. (יש לעיין בgetErrorCode() ולקרוא מצבים ושגיאות שבהמשך).
מיקום הנגן
הפעולות החוקיות של נאמני מידע שניתן לטפל בהן במצב הנוכחי

MediaMetadataCompat class מתאר את התוכן המושמע:

שם האומן, האלבום והטראק
משך הזמן של הטראק
גרפיקה של אלבום שתוצג במסך הנעילה. התמונה היא מפת סיביות (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), הרקע של מסך הנעילה מציג את עטיפת האלבום, אבל רק אם סשן המדיה מטא-נתונים כוללים מפת סיביות של רקע.

אמצעי בקרה להעברה

ב-Android 4.0 (רמת API 14) עד Android 4.4 (רמת API 19), כשסשן מדיה פעיל והמטא-נתונים של סשן המדיה כוללים מפת סיביות של רקע, מסך הנעילה מציג באופן אוטומטי את פקדי התעבורה.

ב-Android 5.0 (רמת API 21) ואילך המערכת לא מספקת העברה הפקדים במסך הנעילה. במקום זאת, צריך להשתמש ב-MediaStyle. התראה כדי להציג את אמצעי הבקרה לתעבורה.

הוספת פעולות מותאמות אישית

אפליקציות מדיה יכולות להגדיר פעולות מותאמות אישית; לדוגמה: לייק, לייק או הרצה 30 שניות אחורה. פעולה מותאמת אישית צריכה להטמיע התנהגות חדשה לגמרי. מומלץ לא להשתמש בפעולה מותאמת אישית כדי להחליף אחת מהפעולות הרגילות של בקרת התעבורה מוגדר ב PlayStateCompat.

הוספת פעולות מותאמות אישית עם 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());

דוגמה מלאה זמינה ב-Universal Music Player.

התגובה שלך לפעולה היא 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)) {
        ...
    }
}

ראה גם את Universal Music Player.

קריאות חוזרות (callback) בסשנים של מדיה

שיטות הקריאה החוזרת (callback) העיקריות של סשן מדיה הן onPlay(), onPause() ו-onStop(). כאן מוסיפים את הקוד ששולט בנגן.

מכיוון שאתם יוצרים ומגדירים את הקריאה החוזרת של הסשן בזמן הריצה (ב-onCreate()), האפליקציה יכולה להגדיר קריאות חוזרות (callback) חלופיות שמשתמשות בנגנים שונים, ולבחור את השילוב המתאים של קריאה חוזרת (callback) ונגן, בהתאם לרמת המכשיר ו/או המערכת. אפשר להחליף את הנגן בלי לבצע שינויים בשאר האפליקציות באפליקציה. לדוגמה, אפשר להשתמש ב-ExoPlayer כשמריצים אותו ב-Android 4.1 (API ברמה 16) ומעלה, ולהשתמש ב-MediaPlayer במערכות קודמות.

מלבד שליטה בנגן וניהול המעברים בין המצבים של סשנים במדיה, קריאות חוזרות (callback) גם מפעילים ומשביתים תכונות של האפליקציה ושולטים באופן שבו היא מקיימת אינטראקציה עם אפליקציות אחרות ועם חומרת המכשיר. (למידע נוסף, ראו שליטה בפלט האודיו).

היישום של שיטות הקריאה החוזרת (callback) של סשן במדיה תלוי במבנה האפליקציה שלכם. לקרוא את הדפים הנפרדים שמתארים איך להשתמש בקריאות חוזרות (callback) אפליקציות אודיו וגם אפליקציות וידאו, תיאור האופן שבו יש להטמיע את הקריאות החוזרות לכל סוג אפליקציה.