Усиление фонового звука

Начиная с Android 17, аудиофреймворк вводит ограничения на фоновые взаимодействия со звуком, включая воспроизведение аудио, запросы на фокусировку на аудио и API изменения громкости , чтобы гарантировать, что эти изменения инициируются пользователем осознанно.

Если разработчик приложения намерен управлять звуком без видимой активности, он должен убедиться, что в приложении есть служба переднего плана (не типа SHORT_SERVICE ), запущенная с возможностью использования во время работы (WIU). Служба переднего плана получает возможность использования WIU, если она запускается в ответ на событие MediaSessionEvent или когда приложение видно пользователю.

Если приложение пытается вызвать API для работы со звуком, находясь вне допустимого жизненного цикла, API воспроизведения звука и изменения громкости завершаются с ошибкой без генерации исключения или предоставления сообщения об ошибке. API фокусировки звука завершается с кодом ошибки AUDIOFOCUS_REQUEST_FAILED .

Цель введения этих ограничений — уменьшить количество непреднамеренных фоновых сбоев в работе звука. Вот несколько примеров:

• Приложения, воспроизводящие аудио без запущенной фоновой службы, могут зависнуть. Когда приложение наконец разблокируется, оно неожиданно возобновит воспроизведение аудио, возможно, через несколько часов.
• Приложения, воспроизводящие аудио без фоновой службы, сталкивались с различными ограничениями при запуске, что приводило к прерывистому звучанию.
• Воспроизведение, оторванное от жизненного цикла активности, может привести к утечке сеанса воспроизведения или утечке событий фокуса, которые продолжаются без возможности остановить воспроизведение для пользователя.

Мы призываем разработчиков тестировать свои приложения и предоставлять обратную связь по поводу изменений в поведении, если какие-либо сценарии использования звука негативно затрагиваются. Пожалуйста, сообщайте о любых проблемах, используя этот трекер проблем совместимости приложений Android 17 .

Определите затронутые сценарии использования фонового аудио.

Проведите аудит реализации воспроизведения звука и определите, планирует ли ваше приложение предоставлять функциональность взаимодействия со звуком в фоновом режиме даже при определенных условиях.

Если ваше приложение предназначено только для воспроизведения звука или использования аудио API во время отображения действия, видимого пользователю, включая режим «картинка в картинке» (PiP) , то ни одно из этих изменений на него не повлияет.

Если ваше приложение предоставляет функциональность VoIP, включая приложения для видеозвонков, то оно уже должно соответствовать требованиям, предъявляемым к воспроизведению (как правило, за счет использования рекомендуемых телекоммуникационных API ) для успешной записи звука, и поэтому вряд ли это повлияет на него.

Если ваше приложение предназначено для продолжения воспроизведения аудио при выключенном экране или при полном закрытии пользователем окна, что чаще всего встречается в приложениях для потоковой передачи музыки или подкастов, то ваше приложение считается предоставляющим фоновую аудиофункциональность и должно соответствовать новым требованиям.

Сценарии фонового звука, которые могут оказать влияние

Если ваше приложение не следует модели продолжения аудиовзаимодействия, инициированного во время работы приложения или в ответ на явный запрос пользователя, то, скорее всего, функциональность вашего приложения будет незаметно отключена.

Например, если ваше приложение запускает службу переднего плана в ответ на BOOT_COMPLETE и пытается взаимодействовать со звуком, эта попытка будет подавлена.

Рекомендации по использованию фонового звука для минимизации негативного воздействия

• Используйте компонент MediaSessionService из библиотеки media3 jetpack для управления фоновым воспроизведением звука.

  В этом случае ваше приложение, скорее всего, не пострадает от усиления защиты в фоновом режиме, поскольку библиотека помогает управлять жизненным циклом воспроизведения.

• Если вы не используете библиотеку media3, вам потребуется вручную запустить службу mediaPlayback FGS. Всегда запускайте службу переднего плана, пока приложение находится на переднем плане, если возможно воспроизведение фонового звука.

  Например, если ваше приложение предназначено для потоковой передачи видео и обычно работает только на переднем плане, но предоставляет пользователю возможность продолжить воспроизведение при выключенном экране, то при срабатывании триггера воспроизведения, инициированного пользователем, ваше приложение все равно должно запустить службу переднего плана.

  Это гарантирует запуск службы переднего плана с возможностями WIU.

• Поддерживайте активность функции mediaPlayback FGS во время кратковременных сбоев продолжительностью менее 10 минут.

  Если в вашем приложении произойдёт временный сбой, например, проблема с буферизацией из-за сетевой активности, или ожидается временное прерывание, такое как AUDIOFOCUS_LOSS_TRANSIENT , попытка воспроизведения должна продолжиться. Таким образом, ваша система FGS должна оставаться активной.

• Остановите службу переднего плана по окончании воспроизведения и возобновите воспроизведение только в том случае, если пользователь явно запросит возобновление воспроизведения.

  В случае получения постоянного сигнала о завершении воспроизведения (например, контент завершен без автовоспроизведения, событие AUDIOFOCUS_LOSS , событие паузы от UMO или событие нажатия медиа-клавиши) или неустранимой ошибки, ваше приложение должно прекратить аудиовзаимодействие, остановить службу переднего плана и завершить медиасессию. Выполнение всех этих действий соответствует представлению пользователя о «завершении» желаемого фонового аудиовзаимодействия. После этого ваше приложение больше не будет обладать возможностями фонового аудиовзаимодействия.

  Впоследствии, если пользователь явно возобновит воспроизведение, например, через пользовательский интерфейс вашего приложения или с помощью кнопки воспроизведения Universal Media Object, намерение начать воспроизведение аудио должно вернуться, что приведет к запуску нового FGS.

• Проверьте работу воспроизведения звука с помощью команд оболочки adb.

Тестирование изменений на Android 16 и Android 17.

Эта функция уже реализована на уровне «предупреждения» начиная с Android 16. Это означает, что приложения могут использовать adb shell cmd audio set-enable-hardening для ручной проверки принудительного включения защиты от копирования в фоновом режиме.

Чтобы включить принудительное применение на устройствах под управлением Android 16, выполните следующую команду:

adb shell cmd audio set-enable-hardening 1

Чтобы отключить принудительное применение правил на устройствах под управлением Android 17, выполните следующую команду:

adb shell cmd audio set-enable-hardening 0

Мы также рекомендуем использовать logcat или команду adb adb dumpsys audio чтобы определить, возникали ли в приложении скрытые сбои из-за мер по усилению защиты звука. Если да, то в журнале появится запись с префиксом AudioHardening , указывающим на имя вашего пакета.

Понимание работы системы FGS в процессе эксплуатации.

Как правило, службы переднего плана (FGS) должны запускаться, когда приложение находится на переднем плане, для продления выполнения операций, инициированных пользователем. В некоторых конкретных случаях приложениям разрешается запускать службу переднего плана, когда приложение находится в фоновом режиме. Однако этим службам переднего плана обычно не предоставляются возможности использования во время работы (WIU).

WIU выступает в роли защитного механизма — он предотвращает выполнение FGS, запущенным в фоновом режиме, определенных важных действий, о которых пользователь может не знать. Он предотвращает доступ приложения к конфиденциальным данным, таким как местоположение, камера или микрофон, а начиная с Android 17, также блокирует аудио API, которые обычно требуют видимого контекста пользовательского интерфейса.

Вот полезная справочная информация:

• Стандартный FGS: Сервисам, запущенным во время видимости приложения или получившим разрешение на запуск в фоновом режиме, предоставляется доступ WIU.
• Фоновый запуск FGS (BFSL): В большинстве случаев доступ к WIU не предоставляется. Основные исключения , предоставляющие доступ к WIU, — это взаимодействия, связанные с явным намерением пользователя, например, нажатия на уведомления, взаимодействие с виджетами или события нажатия мультимедийных клавиш на внешнем устройстве.
• Система запуска FGS: FGS, запущенная с использованием делегирования системного сервера (например, с помощью библиотеки Telecom jetpack), получает доступ к WIU.

Подробнее читайте в разделе «Ограничения на запуск фоновой службы из фонового режима» .

Полный список затронутых аудио API

Аудиофункция	Результат	Затронутые API
Воспроизведение аудио	Воспроизведение прекращается. Никаких исключений, никаких сообщений об ошибке не предоставляется ни одним API.	AudioTrack.write() (NDK) AAudioStream_write OpenSL ES для Android Это также может затронуть любые клиентские медиатеки, управляющие воспроизведением, такие как media3, Exoplayer и Oboe.
Запрос на фокусировку звука	Возвращает AUDIOFOCUS_REQUEST_FAILED Не влияет на воспроизведение звука в других приложениях, фокус не перехватывается.	AudioManager.requestAudioFocus()
API для регулировки громкости и режима звонка	Не влияет на режим звонка или громкость (вызов метода молча игнорируется). Никаких исключений, никаких сообщений об ошибке не предоставляется ни одним API.	AudioManager.setStreamVolume() AudioManager.setStreamMute() AudioManager.adjustStreamVolume() AudioManager.adjustVolume() AudioManager.adjustSuggestedStreamVolume() AudioManager.setRingerMode()