后台音频强化

从 Android 17 开始，音频框架对后台音频互动（包括音频播放、音频焦点请求和音量更改 API）强制执行限制，以确保这些更改是由用户有意发起的。

如果应用开发者打算在没有可见 activity 的情况下控制音频，则应确保应用具有使用 “使用时”(WIU) 功能启动的前台服务（不是 SHORT_SERVICE 类型）。如果前台服务是在响应 MediaSessionEvent 时启动，或者在应用对用户可见时启动，则会获得 WIU 功能。

如果应用尝试在应用处于无效生命周期时调用音频 API，则音频播放和音量更改 API 会静默失败，而不会抛出异常或提供失败消息。音频焦点 API 失败，结果代码为 AUDIOFOCUS_REQUEST_FAILED。

引入这些限制的目的是减少意外的后台音频 bug 体验。部分示例如下：

• 如果应用在没有前台服务的情况下播放音频，则可能会被冻结。当应用最终解除冻结时，它会意外地恢复音频播放，这可能会在数小时后发生。
• 在没有前台服务的情况下播放音频的应用会面临各种运行时限制，从而导致音频播放效果不流畅。
• 播放与 activity 生命周期分离，这可能会导致播放会话或焦点事件泄漏，并且用户无法停止播放。

我们建议开发者测试其应用，并针对任何受到有意音频使用情形负面影响的行为变更提供反馈。 请使用此 Android 17 应用兼容性问题跟踪器报告任何问题。

确定受影响的后台音频使用情形

审核音频播放实现，并确定您的应用是否打算即使在条件性情况下也提供后台音频互动功能。

如果您的应用仅在显示用户可见的 activity 时（包括使用画中画 (PiP) 模式）打算播放音频或利用音频 API，则不会受到任何这些更改的影响。

如果您的应用提供 VOIP 功能（包括视频通话应用），那么它必须已经满足针对播放引入的要求（通常通过利用推荐的 telecom API），才能成功录制音频，因此不太可能受到影响。

如果您的应用打算在屏幕关闭或用户完全关闭您的 activity 时继续播放音频（这在音乐流式传输应用或播客应用中最为常见），则您的应用会被视为提供后台音频功能，并且必须满足新要求。

可能会受到影响的后台音频使用场景

如果您的应用不遵循在应用打开时或响应明确的用户触发器时继续音频互动的模式，则很可能会静默抑制应用的功能。

例如，如果您的应用响应 BOOT_COMPLETE 而启动前台服务并尝试与音频互动，则该应用会被抑制。

可减轻影响的最佳后台音频实践

• 使用 media3 Jetpack 库的 MediaSessionService 组件来管理后台音频播放。

  如果您这样做，由于该库有助于管理播放生命周期，因此您的应用不太可能受到后台强化功能的影响。

• 如果您未使用 media3 库，则需要手动启动 mediaPlayback FGS。如果可能会出现后台音频，请务必在应用处于前台时启动前台服务。

  例如，如果您的应用是视频流应用，通常仅在前台运行，但包含在屏幕关闭时继续播放的用户操作，那么当用户启动播放触发器时，您的应用仍应启动前台服务。

  这样做可确保前台服务以 WIU 功能启动。

• 在持续时间不到 10 分钟的短暂故障期间，保持 mediaPlayback FGS 处于有效状态。

  如果您的应用出现暂时性故障（例如因网络活动而导致缓冲出现问题），或者出现预期的暂时性中断（例如 AUDIOFOCUS_LOSS_TRANSIENT），则播放意图应继续。因此，您的 FGS 应保持有效状态。

• 在播放结束时停止前台服务，并且仅在用户明确恢复播放时才重新开始播放。

  如果出现永久性结束播放信号（例如，内容已播放完毕且未自动播放、出现 AUDIOFOCUS_LOSS、来自 UMO 的暂停事件或媒体键事件）或无法恢复的故障，您的应用应停止音频互动、停止前台服务并结束媒体会话。所有这些操作都与用户对“完成”所需后台音频互动的概念相符。完成此操作后，您的应用将不再具备后台音频互动功能。

  随后，如果用户明确恢复播放（例如通过您的应用界面或通过通用媒体对象播放按钮），则启动音频播放的 intent 应返回，从而导致 FGS 重新启动。

• 使用 adb shell 命令测试音频播放行为。

在 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) 必须在应用位于前台时启动，以延长用户发起的运行时间。在某些特定情况下，应用可以在后台运行时启动前台服务。不过，这些前台服务通常不会被授予“使用期间”功能。

WIU 充当安全门，可防止从后台启动的 FGS 在用户可能不知道应用活动的情况下执行某些敏感行为。它会阻止应用访问位置信息、摄像头或麦克风等敏感数据，并且从 Android 17 开始，它还会阻止通常需要可见界面上下文的音频 API。

以下是方便实用的参考信息：

• 标准 FGS：在应用可见时启动或被授予后台活动启动功能的服务会被授予 WIU 访问权限。
• 后台启动的 FGS (BFSL)：大多数不授予 WIU 访问权限。授予 WIU 的主要例外情况是涉及明确用户意图的互动，例如通知点击、微件互动或来自外部设备的媒体键事件。
• 系统启动 FGS：使用 system-server 委托（例如，通过使用 Telecom Jetpack 库）启动的 FGS 会被授予 WIU 访问权限。

如需了解详情，请参阅与从后台启动前台服务相关的限制。

受影响的音频 API 的完整列表

音频功能	结果	受影响的 API
音频播放	播放已静音 没有任何 API 提供异常或失败消息	AudioTrack.write() (NDK) AAudioStream_write 面向 Android 的 OpenSL ES 任何管理播放的客户端媒体库（例如 media3、Exoplayer 和 Oboe）也可能会受到影响。
音频焦点请求	返回 AUDIOFOCUS_REQUEST_FAILED 对其他应用的音频播放没有影响，未获取焦点	AudioManager.requestAudioFocus()
音量和响铃模式 API	对铃声模式或音量没有影响（方法调用会被静默忽略） 没有任何 API 提供异常或失败消息	AudioManager.setStreamVolume() AudioManager.setStreamMute() AudioManager.adjustStreamVolume() AudioManager.adjustVolume() AudioManager.adjustSuggestedStreamVolume() AudioManager.setRingerMode()