استفاده از جلسه رسانه ای

جلسات رسانه راهی جهانی برای تعامل با پخش کننده صوتی یا تصویری را ارائه می دهند. با اطلاع دادن به Android که رسانه در یک برنامه در حال پخش است، کنترل های پخش را می توان به برنامه واگذار کرد. ادغام با جلسه رسانه به یک برنامه امکان می دهد پخش رسانه را به صورت خارجی تبلیغ کند و دستورات پخش را از منابع خارجی دریافت کند. این منابع می توانند دکمه های فیزیکی (مانند دکمه پخش روی هدست یا کنترل از راه دور تلویزیون) یا دستورات غیر مستقیم (مانند دستور "مکث" به دستیار Google) باشند. سپس جلسه رسانه این دستورات را به برنامه ای که آنها را در پخش کننده رسانه اعمال می کند، واگذار می کند و مشخص است که دستورات از کجا آمده اند.

یک جلسه رسانه در کنار پخش کننده ای که مدیریت می کند زندگی می کند. شما باید یک جلسه رسانه را در متد onCreate() از فعالیت یا سرویسی که دارای جلسه رسانه و پخش کننده مرتبط با آن است ایجاد و مقداردهی کنید.

جلسه رسانه ای را آغاز کنید

جلسه رسانه ای تازه ایجاد شده هیچ قابلیتی ندارد. شما باید جلسه را با انجام این مراحل مقداردهی اولیه کنید:

• پرچم‌ها را به‌گونه‌ای تنظیم کنید که جلسه رسانه بتواند از کنترل‌کننده‌های رسانه و دکمه‌های رسانه تماس‌های برگشتی دریافت کند.
• یک نمونه از PlaybackStateCompat ایجاد و مقداردهی اولیه کنید و آن را به جلسه اختصاص دهید. وضعیت پخش در طول جلسه تغییر می کند، بنابراین توصیه می کنیم PlaybackStateCompat.Builder را برای استفاده مجدد در حافظه پنهان ذخیره کنید.
• نمونه ای از MediaSessionCompat.Callback ایجاد کنید و آن را به جلسه اختصاص دهید (در ادامه در مورد تماس های برگشتی اطلاعات بیشتری کسب کنید).

شما باید یک جلسه رسانه را در متد onCreate() از اکتیویتی یا سرویسی که صاحب جلسه است ایجاد و مقداردهی کنید.

برای اینکه دکمه‌های رسانه زمانی که برنامه شما به‌تازگی مقداردهی اولیه (یا متوقف شده است) کار کند، PlaybackState آن باید دارای یک عملکرد پخش باشد که با هدفی که دکمه رسانه ارسال می‌کند مطابقت داشته باشد. به همین دلیل است که ACTION_PLAY در هنگام مقداردهی اولیه به حالت جلسه اختصاص داده می شود. برای اطلاعات بیشتر، به پاسخ به دکمه های رسانه مراجعه کنید.

وضعیت پخش و ابرداده را حفظ کنید

دو کلاس وجود دارد که وضعیت یک جلسه رسانه را نشان می دهد.

کلاس PlaybackStateCompat وضعیت عملیاتی فعلی پخش کننده را توصیف می کند. این شامل:

• وضعیت انتقال (این که آیا بازیکن در حال بازی/مکث/بافر کردن و غیره است. به getState() مراجعه کنید)
• یک کد خطا و پیام خطای اختیاری، در صورت لزوم. (به getErrorCode() مراجعه کنید و وضعیت ها و خطاها را در زیر بخوانید.)
• موقعیت بازیکن
• اقدامات کنترل کننده معتبری که در حالت فعلی قابل انجام است

کلاس MediaMetadataCompat موادی را که در حال پخش است توضیح می دهد:

• نام هنرمند، آلبوم و آهنگ
• مدت زمان آهنگ
• آثار هنری آلبوم برای نمایش در صفحه قفل. تصویر یک بیت مپ با حداکثر اندازه 320x320dp است (اگر بزرگتر باشد، کوچک شده است).
• نمونه ای از 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 4.0 (سطح API 14)، سیستم می‌تواند به وضعیت پخش و فراداده یک جلسه رسانه دسترسی داشته باشد. به این ترتیب صفحه قفل می تواند کنترل های رسانه و آثار هنری را نمایش دهد. این رفتار بسته به نسخه اندروید متفاوت است.

اثر هنری آلبوم

در اندروید 4.0 (سطح API 14) تا اندروید 10 (سطح API 29)، پس‌زمینه صفحه قفل آثار هنری آلبوم شما را نشان می‌دهد - اما تنها در صورتی که ابرداده جلسه رسانه شامل یک نقشه بیت پس‌زمینه باشد.

کنترل های حمل و نقل

در Android 4.0 (سطح API 14) تا Android 4.4 (سطح API 19)، هنگامی که یک جلسه رسانه فعال است و ابرداده جلسه رسانه شامل یک نقشه بیت پس‌زمینه است، صفحه قفل به طور خودکار کنترل‌های انتقال را نشان می‌دهد.

در Android نسخه 5.0 (سطح API 21) یا بالاتر، سیستم کنترل های حمل و نقل را در صفحه قفل ارائه نمی دهد. در عوض، باید از اعلان MediaStyle برای نمایش کنترل های حمل و نقل استفاده کنید.

افزودن اقدامات سفارشی

برنامه های کاربردی رسانه می توانند اقدامات سفارشی را تعریف کنند. برای مثال: شست بالا، لایک کردن، یا 30 ثانیه عقب رفتن. یک اقدام سفارشی باید رفتار کاملاً جدیدی را اجرا کند. از یک اقدام سفارشی برای جایگزینی یکی از اقدامات کنترل حمل و نقل استاندارد تعریف شده در 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());

برای مثال کامل به پخش کننده موسیقی جهانی مراجعه کنید.

شما با 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)) {
        ...
    }
}

همچنین به پخش کننده موسیقی جهانی مراجعه کنید.

تماس های جلسه رسانه ای

متدهای اصلی پاسخ به تماس جلسه رسانه عبارتند از onPlay() ، onPause() و onStop() . اینجاست که کدی را که پخش کننده شما را کنترل می کند اضافه می کنید.

از آنجایی که شما پاسخ تماس جلسه را در زمان اجرا نمونه‌سازی و تنظیم می‌کنید (در onCreate() )، برنامه شما می‌تواند فراخوان‌های جایگزینی را تعریف کند که از پخش‌کننده‌های مختلف استفاده می‌کنند و بسته به دستگاه و/یا سطح سیستم، ترکیب پاسخ به تماس/بازیکن مناسب را انتخاب کند. می توانید بدون تغییر بقیه برنامه، پخش کننده را تغییر دهید. به عنوان مثال، می‌توانید از ExoPlayer هنگام اجرا بر روی Android 4.1 (سطح API 16) یا بالاتر استفاده کنید و از MediaPlayer در سیستم‌های قبلی استفاده کنید.

علاوه بر کنترل پخش‌کننده و مدیریت انتقال وضعیت جلسه رسانه، تماس‌های برگشتی همچنین ویژگی‌های برنامه شما را فعال و غیرفعال می‌کنند و نحوه تعامل آن با سایر برنامه‌ها و سخت‌افزار دستگاه را کنترل می‌کنند. ( به کنترل خروجی صوتی مراجعه کنید).

اجرای روش‌های پاسخ به تماس جلسه رسانه به ساختار برنامه شما بستگی دارد. به صفحات جداگانه‌ای که نحوه استفاده از تماس‌های برگشتی را در برنامه‌های صوتی و برنامه‌های ویدیویی توضیح می‌دهند، مراجعه کنید، نحوه اجرای تماس‌های برگشتی را برای هر نوع برنامه توضیح دهید.