جلسه‌های رسانه روشی جهانی برای تعامل با پخش‌کننده صوتی یا ویدیویی ارائه می‌دهند. با اطلاع دادن به Android درباره اینکه رسانه درحال پخش در برنامه است، کنترل‌های بازپخش می‌تواند به برنامه واگذار شود. ادغام با جلسه رسانه به برنامه اجازه می‌دهد بازپخش رسانه را به‌صورت خارجی تبلیغ کند و فرمان‌های بازپخش را از منابع خارجی دریافت کند. این منابع می‌توانند دکمه‌های فیزیکی (مانند دکمه پخش در هدست یا کنترل از راه دور تلویزیون) یا فرمان‌های غیرمستقیم (مانند دستور «مکث» به «دستیار Google») باشند. سپس جلسه رسانه این فرمان‌ها را به برنامه‌ای واگذار می‌کند که آن‌ها را برای پخش‌کننده رسانه اعمال می‌کند، که برای آن شفاف است که فرمان‌ها از کجا منشأ گرفته‌اند.
جلسه رسانه در کنار پخش‌کننده‌ای که آن را مدیریت می‌کند قرار دارد. باید در روش onCreate() فعالیت یا سرویسی که مالک جلسه رسانه و پخش‌کننده مرتبط با آن است، جلسه رسانه ایجاد و مقداردهی اولیه کنید.
مقداردهی اولیه جلسه رسانه
جلسه رسانه تازه ایجادشده هیچ قابلیتی ندارد. باید با انجام این مراحل، جلسه را مقداردهی اولیه کنید:
- پرچم‌هایی تنظیم کنید تا جلسه رسانه بتواند از کنترل‌کننده‌های رسانه و دکمه‌های رسانه، فراخوان‌های برگشتی دریافت کند.
- نمونه‌ای از
PlaybackStateCompatایجاد و مقداردهی اولیه کنید و آن را به جلسه اختصاص دهید. وضعیت بازپخش درطول جلسه تغییر می‌کند، بنابراین توصیه می‌کنیمPlaybackStateCompat.Builderرا برای استفاده مجدد در حافظه پنهان ذخیره کنید. - نمونه‌ای از
MediaSessionCompat.Callbackایجاد کنید و آن را به جلسه اختصاص دهید (اطلاعات بیشتر درباره فراخوانی‌های برگشتی در زیر).
باید جلسه رسانه‌ای را در روش onCreate()
فعالیت یا سرویس مالک جلسه ایجاد و مقداردهی اولیه کنید.
برای اینکه دکمه‌های رسانه هنگام مقداردهی اولیه (یا توقف) برنامه شما کار کنند، PlaybackState آن باید حاوی یک کنش پخش مطابق با قصدی باشد که دکمه رسانه ارسال می‌کند. به‌همین دلیل است که ACTION_PLAY درطول مقداردهی اولیه به وضعیت جلسه اختصاص داده می‌شود. برای اطلاعات بیشتر، به پاسخ دادن به
دکمه‌های رسانه مراجعه کنید.
حفظ وضعیت بازپخش و فراداده
دو کلاس وجود دارد که وضعیت جلسه رسانه را نشان می‌دهد.
کلاس PlaybackStateCompat وضعیت عملیاتی فعلی پخش‌کننده را توصیف می‌کند. ازجمله:
- وضعیت انتقال (اینکه پخش‌کننده درحال پخش/ توقف موقت/ میان‌گیری و غیره است.
getState()را ببینید) - کد خطا و پیام خطای اختیاری، درصورت وجود. (
getErrorCode()را ببینید و وضعیت‌ها و خطاها را در زیر بخوانید.) - موقعیت پخش‌کننده
- کنش‌های معتبر کنترل‌کننده که می‌توانند در وضعیت فعلی انجام شوند
کلاس MediaMetadataCompat مطالبی را که درحال پخش است توصیف می‌کند:
- نام هنرمند، آلبوم، و قطعه
- مدت قطعه
- جلد آلبوم برای نمایش در صفحه قفل. تصویر بیت‌مپ با حداکثر اندازه ۳۲۰x۳۲۰dp است (اگر بزرگ‌تر باشد، کوچک می‌شود).
- نمونه‌ای از
ContentUrisکه به نسخه بزرگ‌تری از اثر هنری اشاره می‌کند
وضعیت پخش‌کننده و فراداده می‌تواند درطول عمر جلسه رسانه تغییر کند. هر بار که وضعیت یا فراداده تغییر می‌کند، باید از سازنده مربوطه برای هر کلاس، PlaybackStateCompat.Builder() یا MediaMetadataCompat.Builder()، استفاده کنید و سپس نمونه جدید را با فراخوانی setPlaybackState() یا setMetaData() به جلسه رسانه ارسال کنید. برای کاهش مصرف کلی حافظه از این عملیات‌های مکرر، ایده خوبی است که سازنده‌ها را یک‌بار ایجاد کنید و درطول عمر جلسه از آن‌ها دوباره استفاده کنید.
وضعیت‌ها و خطاها
توجه داشته باشید که PlaybackState شیئی است که حاوی مقادیر جداگانه‌ای برای
وضعیت بازپخش جلسه (getState()) و، درصورت لزوم،
کد خطای مرتبط (getErrorCode()) است. خطاها می‌توانند مهلک یا
غیرمهلک باشند:
هرگاه بازپخش قطع شد، باید خطای مهلکی ایجاد کنید: وضعیت انتقال را روی STATE_ERROR تنظیم کنید و خطای مرتبط را با setErrorMessage(int, CharSequence) مشخص کنید. تا زمانی که بازپخش به‌دلیل خطا مسدود شده است، PlaybackState باید همچنان STATE_ERROR و خطا را گزارش کند.
خطای غیرمهلک زمانی رخ می‌دهد که برنامه شما نمی‌تواند درخواستی را مدیریت کند، اما می‌تواند به پخش ادامه دهد: انتقال در حالت «عادی» (مانند STATE_PLAYING) باقی می‌ماند اما PlaybackState کد خطا را نگه می‌دارد. برای مثال، اگر آخرین آهنگ درحال پخش باشد و کاربر درخواست کند که به آهنگ بعدی برود، بازپخش می‌تواند ادامه یابد، اما باید PlaybackState جدیدی با کد خطای ERROR_CODE_END_OF_QUEUE ایجاد کنید و سپس setPlaybackState() را فراخوانی کنید. «کنترل‌کننده‌های رسانه»
متصل به جلسه، فراخوان برگشتی را دریافت خواهند کرد
onPlaybackStateChanged() و به کاربر توضیح دهید چه اتفاقی افتاده است. خطای غیرمهلک باید فقط یک‌بار و در زمان وقوع گزارش شود. دفعه بعد که جلسه PlaybackState را به‌روزرسانی می‌کند، همان خطای غیرمهلک را دوباره تنظیم نکنید (مگر اینکه خطا در پاسخ به درخواست جدیدی رخ داده باشد).
صفحه قفل جلسه رسانه
از Android نسخه ۴.۰ (سطح میانای برنامه‌سازی کاربردی ۱۴) به بعد، سیستم می‌تواند به فراداده و وضعیت بازپخش جلسه رسانه دسترسی داشته باشد. به این صورت صفحه قفل می‌تواند کنترل‌های رسانه و کار هنری را نمایش دهد. این رفتار بسته به نسخه Android متفاوت است.
جلد آلبوم
در Android نسخه ۴.۰ (سطح میانای برنامه‌سازی کاربردی ۱۴) تا Android نسخه ۱۰ (سطح میانای برنامه‌سازی کاربردی ۲۹)، پس‌زمینه صفحه قفل، جلد آلبوم شما را نمایش می‌دهد - اما فقط درصورتی‌که فراداده جلسه رسانه شامل نقشه بیتی پس‌زمینه باشد.
کنترل‌های حمل‌ونقل
در Android نسخه ۴.۰ (سطح API ۱۴) تا Android نسخه ۴.۴ (سطح API ۱۹)، وقتی جلسه رسانه فعال است و فراداده جلسه رسانه شامل نقشه بیتی پس‌زمینه است، صفحه قفل به‌طور خودکار کنترل‌های انتقال را نمایش می‌دهد.
در Android نسخه ۵.۰ (سطح میانای برنامه‌سازی کاربردی ۲۱) یا بالاتر، سیستم کنترل‌های انتقال را در صفحه قفل ارائه نمی‌دهد. درعوض، باید از اعلان MediaStyle برای نمایش کنترل‌های انتقال استفاده کنید.
افزودن کنش‌های سفارشی
برنامه‌های رسانه می‌توانند کنش‌های سفارشی تعریف کنند؛ برای مثال: رأی موافق، پسندیدن، یا ۳۰ ثانیه عقب بردن. کنش سفارشی باید رفتار کاملاً جدیدی را اجرا کند. از کنش سفارشی برای جایگزین کردن یکی از کنش‌های کنترل حمل‌ونقل استاندارد تعریف‌شده در PlaybackStateCompat استفاده نکنید.
با addCustomAction() کنش‌های سفارشی اضافه کنید. مثال زیر نشان می‌دهد
چگونه کنترلی برای کنش رأی موافق اضافه کنید:
کاتلین
stateBuilder.addCustomAction(
PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP,
resources.getString(R.string.thumbs_up),
thumbsUpIcon
).run {
setExtras(customActionExtras)
build()
}
)
جاوا
stateBuilder.addCustomAction(new PlaybackStateCompat.CustomAction.Builder(
CUSTOM_ACTION_THUMBS_UP, resources.getString(R.string.thumbs_up), thumbsUpIcon)
.setExtras(customActionExtras)
.build());
برای مشاهده نمونه کامل، به Universal Music Player مراجعه کنید.
با onCustomAction() به کنش پاسخ می‌دهید.
کاتلین
override fun onCustomAction(action: String, extras: Bundle?) {
when(action) {
CUSTOM_ACTION_THUMBS_UP -> {
...
}
}
}
جاوا
@Override
public void onCustomAction(@NonNull String action, Bundle extras) {
if (CUSTOM_ACTION_THUMBS_UP.equals(action)) {
...
}
}
همچنین Universal Music Player را ببینید.
پاسخ تماس‌های جلسه رسانه
روش‌های اصلی فراخوانی جلسه رسانه عبارت‌اند از onPlay()، onPause()، و
onStop(). اینجا جایی است که کدی را که پخش‌کننده شما را کنترل می‌کند اضافه می‌کنید.
ازآنجایی‌که شما در زمان اجرا (در
onCreate()) نمونه‌سازی می‌کنید و فراخوان برگشتی جلسه را تنظیم می‌کنید، برنامه‌تان می‌تواند فراخوان‌های برگشتی جایگزینی را تعریف کند که از پخش‌کننده‌های مختلف استفاده می‌کنند و ترکیب مناسبی از فراخوان برگشتی و پخش‌کننده را بسته به دستگاه و سطح سیستم انتخاب کنند. می‌توانید پخش‌کننده را بدون تغییر دادن بقیه برنامه تغییر دهید. برای مثال، می‌توانید از ExoPlayer هنگام اجرا در Android 4.1 (سطح میانای برنامه‌سازی کاربردی ۱۶) یا بالاتر استفاده کنید و از MediaPlayer در سیستم‌های قدیمی‌تر استفاده کنید.
علاوه‌بر کنترل پخش‌کننده و مدیریت انتقال‌های حالت جلسه رسانه، برگشت‌های فراخوانی همچنین ویژگی‌های برنامه شما را فعال و غیرفعال می‌کنند و نحوه تعامل آن با برنامه‌های دیگر و سخت‌افزار دستگاه را کنترل می‌کنند. (کنترل خروجی صدا را ببینید).
پیاده‌سازی روش‌های فراخوانی جلسه رسانه به ساختار برنامه شما بستگی دارد. صفحه‌های جداگانه‌ای را که نحوه استفاده از فراخوانی‌ها را در برنامه‌های صوتی و برنامه‌های ویدیویی شرح می‌دهند ببینید، این صفحه‌ها نحوه پیاده‌سازی فراخوانی‌ها را برای هر نوع برنامه شرح می‌دهند.