جلسه‌های رسانه روشی جهانی برای تعامل با پخش‌کننده صوتی یا تصویری ارائه می‌دهند. با اطلاع دادن به Android درباره اینکه رسانه درحال پخش شدن در برنامه است، کنترل‌های بازپخش را می‌توان به برنامه واگذار کرد. ادغام با جلسه رسانه به برنامه امکان می‌دهد بازپخش رسانه را به‌صورت خارجی تبلیغ کند و فرمان‌های بازپخش را از منابع خارجی دریافت کند. این منابع می‌توانند دکمه‌های فیزیکی (مانند دکمه پخش در هدست یا کنترل از راه دور تلویزیون) یا فرمان‌های غیرمستقیم (مانند دستور «مکث» به «دستیار Google») باشند. سپس جلسه رسانه این فرمان‌ها را به برنامه‌ای واگذار می‌کند که آن‌ها را برای پخش‌کننده رسانه اعمال می‌کند، و برای پخش‌کننده رسانه مشخص است که فرمان‌ها از کجا منشأ گرفته‌اند.
جلسه رسانه در کنار پخش‌کننده‌ای که آن را مدیریت می‌کند قرار دارد. باید در روش onCreate() فعالیت یا سرویسی که مالک جلسه رسانه و پخش‌کننده مرتبط با آن است، جلسه رسانه ایجاد و مقداردهی اولیه کنید.
مقداردهی اولیه جلسه رسانه
جلسه رسانه تازه ایجادشده هیچ قابلیتی ندارد. باید با انجام این مراحل، جلسه را مقداردهی اولیه کنید:
- پرچم‌هایی تنظیم کنید تا جلسه رسانه بتواند از کنترل‌کننده‌های رسانه و دکمه‌های رسانه بازخوانی دریافت کند.
- نمونه‌ای از
PlaybackStateCompatایجاد و مقداردهی اولیه کنید و آن را به جلسه اختصاص دهید. وضعیت بازپخش درطول جلسه تغییر می‌کند، بنابراین توصیه می‌کنیمPlaybackStateCompat.Builderرا برای استفاده مجدد در حافظه نهان ذخیره کنید. - نمونه‌ای از
MediaSessionCompat.Callbackایجاد کنید و آن را به جلسه اختصاص دهید (اطلاعات بیشتر درباره فراخوانی‌های برگشتی در زیر).
باید جلسه رسانه را در روش onCreate()
فعالیت
یا سرویس مالک جلسه ایجاد و مقداردهی اولیه کنید.
برای اینکه دکمه‌های رسانه وقتی برنامه‌تان به‌تازگی مقداردهی اولیه (یا متوقف) شده است کار کنند، PlaybackState آن باید حاوی کنش پخشی باشد که با قصدی که دکمه رسانه ارسال می‌کند مطابقت داشته باشد. به همین دلیل است که ACTION_PLAY درطول مقداردهی اولیه به وضعیت جلسه اختصاص داده می‌شود. برای اطلاعات بیشتر، به پاسخ دادن به دکمه‌های رسانه مراجعه کنید.
حفظ وضعیت بازپخش و فراداده
دو کلاس وجود دارد که وضعیت جلسه رسانه را نشان می‌دهد.
کلاس
PlaybackStateCompat
وضعیت عملیاتی فعلی پخش‌کننده را توصیف می‌کند. ازجمله:
- وضعیت انتقال (اینکه پخش‌کننده درحال پخش/توقف موقت/میان‌گیری و غیره است.
getState()را ببینید) - کد خطا و پیام خطای اختیاری، درصورت وجود. (
getErrorCode()را ببینید و وضعیت‌ها و خطاها را در زیر بخوانید.) - موقعیت پخش‌کننده
- کنش‌های کنترل‌کننده معتبر که می‌توانند در وضعیت فعلی انجام شوند
کلاس MediaMetadataCompat
مطلبی را که درحال پخش است توصیف می‌کند:
- نام هنرمند، آلبوم، و قطعه
- مدت قطعه
- جلد آلبوم برای نمایش در صفحه قفل. تصویر یک نقشه بیتی با حداکثر اندازه ۳۲۰×۳۲۰ پیکسل مستقل از تراکم است (اگر بزرگ‌تر باشد، کوچک‌تر می‌شود).
- نمونه‌ای از
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 5.0 (سطح میانای برنامه‌سازی کاربردی ۲۱) یا بالاتر، سیستم کنترل‌های انتقال را در صفحه قفل ارائه نمی‌دهد. درعوض، باید از اعلان 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()) نمونه‌سازی می‌کنید و فراخوان برگشتی جلسه را تنظیم می‌کنید، برنامه‌تان می‌تواند فراخوان‌های برگشتی جایگزینی را تعریف کند که از پخش‌کننده‌های مختلف استفاده می‌کنند و ترکیب فراخوان برگشتی/پخش‌کننده مناسب را بسته به دستگاه و/یا سطح سیستم انتخاب کند. می‌توانید پخش‌کننده را بدون تغییر دادن بقیه برنامه تغییر دهید. برای مثال، می‌توانید هنگام اجرا در Android 4.1 (سطح میانای برنامه‌سازی کاربردی ۱۶) یا بالاتر از ExoPlayer استفاده کنید و در سیستم‌های قدیمی‌تر از MediaPlayer استفاده کنید.
علاوه‌بر کنترل پخش‌کننده و مدیریت انتقال‌های وضعیت جلسه رسانه، تماس‌های برگشتی همچنین ویژگی‌های برنامه شما را فعال و غیرفعال می‌کنند و نحوه تعامل آن با برنامه‌های دیگر و سخت‌افزار دستگاه را کنترل می‌کنند. (کنترل خروجی صوتی را ببینید).
پیاده‌سازی روش‌های فراخوانی برگشتی جلسه رسانه به ساختار برنامه شما بستگی دارد. صفحه‌های جداگانه‌ای را که نحوه استفاده از فراخوانی‌های برگشتی را در برنامه‌های صوتی و برنامه‌های ویدیویی شرح می‌دهند ببینید، این صفحه‌ها نحوه پیاده‌سازی فراخوانی‌های برگشتی را برای هر نوع برنامه شرح می‌دهند.