سخت‌سازی صدای پس‌زمینه

از Android 17 به بعد، چارچوب صوتی محدودیت‌هایی را بر تعاملات صوتی پس‌زمینه، ازجمله بازپخش صدا، درخواست‌های تمرکز صوتی، و میاناهای برنامه‌سازی کاربردی تغییر میزان صدا اعمال می‌کند تا اطمینان حاصل شود که این تغییرات به‌طور عمدی توسط کاربر شروع شده‌اند.

همه برنامه‌هایی که در Android 17 اجرا می‌شوند و این تعامل‌های صوتی پس‌زمینه‌ای را دارند باید فعالیت نمایان داشته باشند یا باید سرویس پیش‌زمینه‌ای را اجرا کنند که از نوع SHORT_SERVICE نباشد. این موضوع صرف‌نظر از اینکه برنامه سطح میانای برنامه‌سازی کاربردی ۳۷ را هدف قرار دهد یا نه، اعمال می‌شود.

اگر برنامه‌ای Android 17 (سطح میانای برنامه‌سازی کاربردی ۳۷) را هدف‌یابی کند، محدودیت دیگری وجود دارد. اگر برنامه در پس‌زمینه درحال اجرا است، برنامه باید سرویس پیش‌زمینه‌ای را اجرا کند که قابلیت‌های درحال استفاده (WIU) داشته باشد. (اگر سرویس پیش‌زمینه‌ای در پاسخ به عملیاتی که کاربر شروع کرده است یا زمانی که برنامه برای کاربر قابل‌مشاهده است شروع شود، قابلیت‌های WIU به آن اعطا می‌شود.) بااین‌حال، اگر به برنامه اجازه زنگ دقیق اعطا شده باشد و برنامه درحال ایجاد تغییرات در جاری‌سازی‌های صوتی دارای مشخصه USAGE_ALARM باشد، از الزام قابلیت‌های WIU صرف‌نظر می‌شود.

اگر برنامه تلاش کند میاناهای برنامه‌سازی کاربردی صوتی را فراخوانی کند درحالی‌که برنامه در چرخه حیات معتبری نباشد، میاناهای برنامه‌سازی کاربردی بازپخش صدا و تغییر میزان صدا بدون ایجاد استثنا یا ارائه پیام خطا، بی‌صدا ناموفق می‌شوند. میانای برنامه‌سازی کاربردی تمرکز صوتی با کد نتیجه AUDIOFOCUS_REQUEST_FAILED ناموفق بود.

چرا این تغییر را ایجاد می‌کنیم

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

• برنامه‌هایی که بدون سرویس پیش‌زمینه‌ای صدا پخش می‌کنند ممکن است متوقف شوند. وقتی برنامه درنهایت از حالت ثابت خارج می‌شود، پخش صدا را به‌طور غیرمنتظره ازسر می‌گیرد، که ممکن است ساعت‌ها بعد باشد.
• برنامه‌هایی که صدا را بدون سرویس پیش‌زمینه‌ای پخش می‌کنند با محدودیت‌های اجرای مختلفی مواجه می‌شوند که منجر به عملکرد نامنظم صدا می‌شود.
• بازپخش از چرخه حیات فعالیت جدا شده است که می‌تواند منجر به نشت جلسه بازپخش یا نشت رویدادهای تمرکز شود که بدون هیچ راهی برای توقف بازپخش توسط کاربر ادامه می‌یابد.

توسعه‌دهندگان را تشویق می‌کنیم برنامه‌هایشان را آزمایش کنند و اگر موارد استفاده عمدی از صدا تحت تأثیر منفی قرار گرفته است، درباره تغییر رفتار بازخورد ارائه دهند. لطفاً هرگونه مشکل را بااستفاده از این ردیاب مشکل سازگاری برنامه Android 17 گزارش کنید.

شناسایی موارد استفاده از صدای پس‌زمینه تحت‌تأثیر قرارگرفته

پیاده‌سازی بازپخش صوتی‌تان را ممیزی کنید و مشخص کنید که آیا برنامه‌تان قصد دارد عملکرد تعامل صوتی پس‌زمینه را حتی در شرایط مشروط ارائه دهد یا نه.

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

اگر برنامه‌تان عملکرد VOIP ارائه می‌دهد، ازجمله برنامه‌های تماس تصویری، پس باید ازقبل الزامات معرفی‌شده برای بازپخش را برآورده کند (معمولاً ازطریق استفاده از میاناهای برنامه‌سازی کاربردی مخابراتی توصیه‌شده) تا بتواند صدا را با موفقیت ضبط کند، بنابراین بعید است تحت تأثیر قرار گیرد.

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

سناریوهای صدای پس‌زمینه که احتمالاً تحت تأثیر قرار می‌گیرند

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

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

روال‌های مطلوب برای صدای پس‌زمینه برای کاهش تأثیر

• از مؤلفه MediaSessionService کتابخانه jetpack media3 برای مدیریت بازپخش صدای پس‌زمینه استفاده کنید.

  اگر این کار را انجام دهید، احتمالاً برنامه‌تان تحت‌تأثیر سخت‌سازی پس‌زمینه قرار نخواهد گرفت، زیرا کتابخانه به مدیریت چرخه حیات بازپخش کمک می‌کند.

• اگر از کتابخانه media3 استفاده نمی‌کنید، باید به‌صورت دستی mediaPlayback FGS را شروع کنید. اگر ممکن است صدای پس‌زمینه پخش شود، همیشه وقتی برنامه در پیش‌زمینه است، سرویس پیش‌زمینه را شروع کنید.

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

  با انجام این کار، سرویس پیش‌زمینه‌ای با قابلیت‌های WIU شروع می‌شود.

• mediaPlayback FGS را درطول خرابی‌های گذرا که کمتر از ۱۰ دقیقه طول می‌کشد فعال نگه دارید.

  اگر برنامه شما دچار خرابی گذرا شود، مثلاً مشکلی در میان‌گیری به‌دلیل فعالیت شبکه، یا وقفه گذرا و موردانتظاری مثل AUDIOFOCUS_LOSS_TRANSIENT وجود داشته باشد، هدف پخش باید ادامه یابد. بنابراین، FGS شما باید فعال بماند.

• سرویس پیش‌زمینه‌ای را در پایان بازپخش متوقف کنید و بازپخش را فقط درصورتی بازراه‌اندازی کنید که کاربر صریحاً بازپخش را ازسر بگیرد.

  درصورت وجود سیگنال دائمی برای پایان دادن به بازپخش (برای مثال، محتوا بدون پخش خودکار تکمیل شده است، AUDIOFOCUS_LOSS، رویداد توقف از UMO، یا رویداد کلید رسانه) یا خرابی غیرقابل‌بازیابی، برنامه‌تان باید تعامل صوتی را متوقف کند، سرویس پیش‌زمینه‌ای را متوقف کند، و جلسه رسانه را پایان دهد. انجام همه این کارها با مفهوم «پایان» تعامل صوتی پس‌زمینه موردنظر کاربر مطابقت دارد. پس‌از انجام این کار، برنامه‌تان دیگر قابلیت‌های تعامل صوتی پس‌زمینه را ندارد.

  متعاقباً، اگر کاربر صریحاً بازپخش را ازسر بگیرد، برای مثال ازطریق رابط کاربری برنامه شما یا ازطریق دکمه پخش Universal Media Object، هدف شروع بازپخش صدا باید برگردد، که منجر به شروع FGS جدیدی می‌شود.

• رفتار بازپخش صدا را با فرمان‌های پوسته adb آزمایش کنید.

درحال آزمایش تغییرات

می‌توانید با اجرای فرمان ADB زیر، مطابقت برنامه‌تان را در برنامه‌هایی که Android 17 یا بالاتر دارند (از نسخه بتا ۳ شروع می‌شود) آزمایش کنید:

adb shell cmd audio set-enable-hardening <enable|disable|throw>

این فرمان گزینه‌های زیر را دارد:

• enable: همه محدودیت‌های تقویت صوتی را برای همه برنامه‌ها فعال می‌کند. الزام سرویس‌های پیش‌زمینه‌ای WIU صرف‌نظر از اینکه برنامه Android 17 (سطح میانای برنامه‌سازی کاربردی 37) را هدف قرار دهد یا نه، اعمال می‌شود. علاوه‌براین، این الزام حتی اگر برنامه درحال ایجاد تغییرات در جریان‌های زنگ هشدار باشد و اجازه زنگ هشدار دقیق را داشته باشد، اعمال می‌شود.

• disable: همه محدودیت‌های مقاوم‌سازی صوتی را غیرفعال می‌کند.

• throw: همه محدودیت‌های سخت‌سازی صوتی را برای همه برنامه‌ها فعال می‌کند، مثل enable. علاوه‌براین، این پرچم خرابی‌های بلند را فعال می‌کند و IllegalStateException را برای تعاملات میزان صدا و تمرکز ایجاد می‌کند. برای بازپخش صدا، روش نوشتن به‌طور مداوم کد خطا برمی‌گرداند. برای حالت‌های بازپخش بدون نوشتن صریح، برنامه ازکار می‌افتد.

از adb dumpsys audio یا logcat استفاده کنید تا تشخیص دهید که آیا برنامه به‌دلیل اجرای سخت‌سازی صوتی با خرابی‌های بی‌صدا مواجه شده است یا نه. اگر این اتفاق افتاده باشد، ورودی‌ای با پیشوند AudioHardening و نام بسته شما وجود خواهد داشت. اگر پیام حاوی level: full باشد، برنامه‌تان درحال اجرای سرویس پیش‌زمینه‌ای است، اما این سرویس قابلیت «درحین استفاده» را ندارد. اگر پیام حاوی level: partial باشد، برنامه‌تان اصلاً سرویس پیش‌زمینه‌ای اجرا نمی‌کند.

آشنایی با FGS با قابلیت «درحال استفاده»

به‌طور کلی، سرویس‌های پیش‌زمینه‌ای (FGS) باید زمانی راه‌اندازی شوند که برنامه در پیش‌زمینه باشد تا عملیات شروع‌شده توسط کاربر را گسترش دهند. در برخی موارد خاص، برنامه‌ها مجازند سرویس پیش‌زمینه‌ای را درحالی‌که برنامه در پس‌زمینه است راه‌اندازی کنند. بااین‌حال، این سرویس‌های پیش‌زمینه‌ای معمولاً قابلیت‌های «درحال استفاده» (WIU) را دریافت نمی‌کنند.

WIU به‌عنوان یک دروازه امنیتی عمل می‌کند و مانع از آن می‌شود که FGS شروع‌شده از پس‌زمینه در رفتارهای حساس خاصی شرکت کند، به‌ویژه زمانی که کاربر ممکن است از فعالیت برنامه آگاه نباشد. این حالت از دسترسی برنامه به داده‌های حساس مانند مکان، دوربین، یا میکروفون جلوگیری می‌کند و از Android 17 به بعد، میاناهای برنامه‌سازی کاربردی صوتی را که معمولاً به بافت واسط کاربر قابل‌مشاهده نیاز دارند نیز مسدود می‌کند.

در اینجا مرجع مفیدی ارائه شده است:

• «سرویس پیش‌زمینه» استاندارد: سرویس‌هایی که وقتی برنامه نمایان است یا قابلیت راه‌اندازی فعالیت پس‌زمینه به آن اعطا شده است شروع می‌شوند، دسترسی «درحال استفاده» به آن‌ها اعطا می‌شود.
• FGS شروع‌شده در پس‌زمینه (BFSL): اکثر آن‌ها دسترسی WIU را اعطا نمی‌کنند. استثناهای اصلی که WIU را اعطا می‌کنند، تعاملاتی هستند که شامل قصد صریح کاربر می‌شوند، برای مثال، کلیک‌های اعلان، تعاملات ابزاره، یا رویدادهای کلید رسانه از یک دستگاه خارجی.
• سرویس پیش‌زمینه‌ای شروع‌شده توسط سیستم: اگر سرویس‌های پیش‌زمینه‌ای توسط نمایندگی سرور سیستم (برای مثال، از کتابخانه Telecom jetpack) یا توسط اتصال‌های سیستم که نشان‌دهنده وضعیت پیش‌زمینه ارتقایافته برای انجام عملکرد اختصاصی (مانند VoiceInteractionService) هستند شروع شوند، دسترسی «درحال استفاده» به آن‌ها اعطا می‌شود.

در محدودیت‌های شروع سرویس پیش‌زمینه‌ای از پس‌زمینه بیشتر بخوانید.

فهرست کامل میاناهای برنامه‌سازی کاربردی صوتی تحت‌تأثیر قرارگرفته

عملکرد صوتی	نتیجه	میاناهای برنامه‌سازی کاربردی تحت‌تأثیر قرارگرفته
بازپخش پیام صوتی	بازپخش بی‌صدا است هیچ استثنایی وجود ندارد، هیچ پیام خطایی ازسوی هیچ میانای برنامه‌سازی کاربردی ارائه نشده است	AudioTrack.write() (NDK) AAudioStream_write ‫OpenSL ES برای Android هر کتابخانه رسانه‌ای سمت کارخواه که بازپخش را مدیریت می‌کند، مثل media3،‏ Exoplayer، و Oboe، نیز ممکن است تحت‌تأثیر قرار بگیرد.
درخواست اولویت صوتی	بازگشتی‌ها AUDIOFOCUS_REQUEST_FAILED تأثیری بر بازپخش صدای برنامه‌های دیگر ندارد، تمرکز به‌دست نیامده است	AudioManager.requestAudioFocus()
میاناهای برنامه‌سازی کاربردی میزان صدا و حالت زنگ	تأثیری بر حالت زنگ یا میزان صدا ندارد (فراخوانی روش بی‌صدا نادیده گرفته می‌شود) هیچ استثنایی وجود ندارد، هیچ پیام خطایی توسط هیچ میانای برنامه‌سازی کاربردی ارائه نشده است	AudioManager.setStreamVolume() AudioManager.setStreamMute() AudioManager.adjustStreamVolume() AudioManager.adjustVolume() AudioManager.adjustSuggestedStreamVolume() AudioManager.setRingerMode()