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

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

Все приложения, работающие на Android 17 и имеющие подобные фоновые аудиовзаимодействия, должны иметь видимое действие или запускать службу переднего плана, не относящуюся к типу SHORT_SERVICE . Это относится как к приложениям, ориентированным на API уровня 37, так и к приложениям, использующим его.

Если приложение ориентировано на Android 17 (уровень API 37), существует дополнительное ограничение. Если приложение работает в фоновом режиме, оно должно запускать службу переднего плана, обладающую возможностями управления во время использования (WIU). (Службе переднего плана предоставляются возможности WIU, если она запускается в ответ на операцию, инициированную пользователем, или когда приложение видно пользователю.) Однако требование к возможностям WIU отменяется, если приложению предоставлено точное разрешение на будильник , и оно вносит изменения в аудиопотоки, имеющие атрибут USAGE_ALARM .

Если приложение пытается вызвать 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 можно на приложениях, работающих под управлением Android 17 или выше (начиная с бета-версии 3), выполнив следующую команду ADB:

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

Эта команда имеет следующие параметры:

• enable : Включает все ограничения на защиту звука для всех приложений. Требование к фоновым службам WIU применяется независимо от того, ориентировано ли приложение на Android 17 (уровень API 37). Кроме того, это требование соблюдается, даже если приложение вносит изменения в потоки будильников и имеет точно такое же разрешение на будильник.

• disable : Отключает все ограничения на усиление защиты звука.

• throw : Включает все ограничения на усиление звука для всех приложений, как и enable . Кроме того, этот флаг включает сбои при воспроизведении громких звуков, генерируя исключение IllegalStateException при взаимодействии с громкостью и фокусом. При воспроизведении звука метод write постоянно возвращает код ошибки. В режимах воспроизведения без явной записи приложение аварийно завершает работу.

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

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

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

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

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

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

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

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