Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

管理音频焦点

两个或更多 Android 应用可以同时向同一输出流播放音频，系统会将所有音频混合在一起。虽然这在技术上令人印象深刻，但可能会让用户感到非常烦躁。为了避免所有音乐应用同时播放，Android 引入了音频焦点的概念。一次只能有一个应用获得音频焦点。

当您的应用需要输出音频时，它需要请求获得音频焦点，当它获得焦点时，就可以播放声音。不过，在获得音频焦点后，您可能无法一直保持该焦点，直到播放完毕。其他应用可以请求焦点，从而抢占您对音频焦点的控制权。如果发生这种情况，您的应用应暂停播放或降低音量，以便用户更轻松地听到新的音频源。

在 Android 12（API 级别 31）之前，音频焦点并非由系统管理。因此，虽然我们鼓励应用开发者遵守音频焦点指南，但如果应用在搭载 Android 11（API 级别 30）或更低版本的设备上失去音频焦点后仍继续大声播放，系统也无法阻止。不过，这种应用行为会导致用户体验不佳，并且通常会导致用户卸载行为不当的应用。

设计良好的音频应用应根据以下一般准则管理音频焦点：

在开始播放之前立即调用 requestAudioFocus()，并验证调用是否返回 AUDIOFOCUS_REQUEST_GRANTED。在媒体会话的 onPlay() 回调中调用 requestAudioFocus()。
当其他应用获得音频焦点时，停止或暂停播放，或降低音量。
当播放停止时（例如，当应用没有可播放的内容时），放弃音频焦点。如果用户暂停播放，但稍后可能会继续播放，则应用无需放弃音频焦点。
使用 AudioAttributes 描述应用正在播放的音频类型。例如，对于播放语音的应用，请指定 CONTENT_TYPE_SPEECH。

音频焦点的处理方式因运行的 Android 版本而异：

Android 12（API 级别 31）或更高版本: 音频焦点由系统管理。当另一个应用请求音频焦点时，系统会强制淡出某个应用的音频播放。系统还会在收到来电时将音频播放静音。
Android 8.0（API 级别 26）到 Android 11（API 级别 30）: 音频焦点不由系统管理，但包含从 Android 8.0（API 级别 26）开始引入的一些变更。
Android 7.1（API 级别 25）及更低版本: 音频焦点不由系统管理，应用使用 requestAudioFocus() 和 abandonAudioFocus() 管理音频焦点。

Android 12 及更高版本中的音频焦点

使用音频焦点的媒体或游戏应用在失去焦点后不应播放音频。在 Android 12（API 级别 31）及更高版本中，系统会强制执行此行为。当某个应用在另一个应用拥有焦点并正在播放时请求音频焦点，系统会强制正在播放的应用淡出。添加淡出效果后，从一个应用切换到另一个应用时，过渡会更加顺畅。

当满足以下条件时，就会出现这种淡出行为：

第一个应用（当前正在播放）满足以下所有条件：
- 应用具有 AudioAttributes.USAGE_MEDIA 或 AudioAttributes.USAGE_GAME 用途属性。
- 应用已成功通过 AudioManager.AUDIOFOCUS_GAIN 请求音频焦点。
- 应用未播放内容类型为 AudioAttributes.CONTENT_TYPE_SPEECH 的音频。
第二个应用使用 AudioManager.AUDIOFOCUS_GAIN 请求音频焦点。

满足这些条件后，音频系统会淡出第一个应用。淡出结束时，系统会通知第一个应用焦点丢失。应用的播放器会保持静音，直到应用再次请求音频焦点。

现有的音频焦点行为

您还应注意下面这些涉及切换音频焦点的其他情况。

自动降低音量

Android 8.0（API 级别 26）中引入了自动降低音量（暂时降低一个应用的音频音量，以便可以清楚地听到另一个应用的声音）。

通过让系统实现闪避，您无需在应用中实现闪避。

当音频通知从正在播放音频的应用夺取焦点时，也会出现自动降低音量的行为。通知播放的开头与降低音量坡道的结尾同步。

当满足以下条件时，就会出现自动降低音量的行为：

第一个应用（当前正在播放的应用）满足以下所有条件：
- 应用已成功请求音频焦点，并获得任何类型的焦点。
- 应用未播放内容类型为 AudioAttributes.CONTENT_TYPE_SPEECH 的音频。
- 应用未设置 AudioFocusRequest.Builder.setWillPauseWhenDucked(true)。
第二个应用使用 AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK 请求音频焦点。

满足这些条件后，当第二个应用获得焦点时，音频系统会闪避第一个应用的所有活跃播放器。当第二个应用放弃焦点时，系统会取消降低音量。第一个应用在失去焦点时不会收到通知，因此无需执行任何操作。

请注意，当用户正在收听语音内容时，系统不会自动降低音量，因为用户可能会错过部分节目。例如，行车路线的语音导航不会闪避。

来电时将当前播放的音频静音

有些应用无法正常运行，会在通话期间继续播放音频。这种情况会迫使用户找到并静音或退出违规应用，以便听到通话内容。为防止出现这种情况，系统可以在有来电时将其他应用的音频静音。当收到来电且应用满足以下条件时，系统会调用此功能：

应用具有 AudioAttributes.USAGE_MEDIA 或 AudioAttributes.USAGE_GAME 用途属性。
应用已成功请求音频焦点（任何焦点增益）并正在播放音频。

如果某个应用在通话过程中继续播放，其播放会静音，直到通话结束。不过，如果某个应用在通话期间开始播放，则该播放器不会静音，因为系统会假定用户是有意开始播放的。

Android 8.0 至 Android 11 中的音频焦点

从 Android 8.0（API 级别 26）开始，当您调用 requestAudioFocus() 时，必须提供 AudioFocusRequest 参数。AudioFocusRequest 包含有关应用的音频上下文和功能的信息。系统会使用这些信息自动管理音频焦点的获取和丢失。如需释放音频焦点，请调用 abandonAudioFocusRequest() 方法，该方法也接受 AudioFocusRequest 作为实参。在请求和放弃焦点时，使用同一个 AudioFocusRequest 实例。

如需创建 AudioFocusRequest，请使用 AudioFocusRequest.Builder。由于焦点请求必须始终指定请求类型，因此该类型包含在构建器的构造函数中。使用构建器的方法设置请求的其他字段。

FocusGain 字段为必需字段；所有其他字段均为可选字段。

方法	备注
`setFocusGain()`	每个请求中都必须包含此字段。它采用与 Android 8.0 之前版本中对 `requestAudioFocus()` 的调用所使用的 `durationHint` 相同的值：`AUDIOFOCUS_GAIN`、`AUDIOFOCUS_GAIN_TRANSIENT`、`AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` 或 `AUDIOFOCUS_GAIN_TRANSIENT_EXCLUSIVE`。
`setAudioAttributes()`	`AudioAttributes` 描述了应用的使用情形。当应用获得和失去音频焦点时，系统会查看这些属性。属性取代了音频流类型的概念。在 Android 8.0（API 级别 26）及更高版本中，除音量控制之外的任何操作的音频流类型均已废弃。在焦点请求中使用与音频播放器中相同的属性（如本表后面的示例所示）。首先使用 `AudioAttributes.Builder` 指定属性，然后使用此方法将属性分配给请求。如果未指定，`AudioAttributes` 默认为 `AudioAttributes.USAGE_MEDIA`。
`setWillPauseWhenDucked()`	当其他应用使用 `AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK` 请求焦点时，拥有焦点的应用通常不会收到 `onAudioFocusChange()` 回调，因为系统可以自行闪避。如果您需要暂停播放而不是降低音量，请调用 `setWillPauseWhenDucked(true)`，并创建和设置 `OnAudioFocusChangeListener`，如自动降低音量中所述。
`setAcceptsDelayedFocusGain()`	当焦点被其他应用锁定时，音频焦点请求可能会失败。此方法可实现延迟获得焦点：在焦点可用时异步获取焦点的能力。请注意，只有当您还在音频请求中指定 `AudioManager.OnAudioFocusChangeListener` 时，延迟获得焦点才有效，因为您的应用需要接收回调才能知道焦点已授予。
`setOnAudioFocusChangeListener()`	只有在请求中同时指定 `willPauseWhenDucked(true)` 或 `setAcceptsDelayedFocusGain(true)` 时，才需要 `OnAudioFocusChangeListener`。设置监听器的方法有两种：一种带有处理程序参数，另一种不带。处理程序是运行监听器的线程。如果您未指定处理程序，则系统会使用与主 `Looper` 关联的处理程序。

以下示例展示了如何使用 AudioFocusRequest.Builder 构建 AudioFocusRequest，以及如何请求和放弃音频焦点：

Kotlin

// initializing variables for audio focus and playback management
audioManager = getSystemService(Context.AUDIO_SERVICE) as AudioManager
focusRequest = AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN).run {
    setAudioAttributes(AudioAttributes.Builder().run {
        setUsage(AudioAttributes.USAGE_GAME)
        setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
        build()
    })
    setAcceptsDelayedFocusGain(true)
    setOnAudioFocusChangeListener(afChangeListener, handler)
    build()
}
val focusLock = Any()

var playbackDelayed = false
var playbackNowAuthorized = false

// requesting audio focus and processing the response
val res = audioManager.requestAudioFocus(focusRequest)
synchronized(focusLock) {
    playbackNowAuthorized = when (res) {
        AudioManager.AUDIOFOCUS_REQUEST_FAILED -> false
        AudioManager.AUDIOFOCUS_REQUEST_GRANTED -> {
            playbackNow()
            true
        }
        AudioManager.AUDIOFOCUS_REQUEST_DELAYED -> {
            playbackDelayed = true
            false
        }
        else -> false
    }
}

// implementing OnAudioFocusChangeListener to react to focus changes
override fun onAudioFocusChange(focusChange: Int) {
    when (focusChange) {
        AudioManager.AUDIOFOCUS_GAIN ->
            if (playbackDelayed || resumeOnFocusGain) {
                synchronized(focusLock) {
                    playbackDelayed = false
                    resumeOnFocusGain = false
                }
                playbackNow()
            }
        AudioManager.AUDIOFOCUS_LOSS -> {
            synchronized(focusLock) {
                resumeOnFocusGain = false
                playbackDelayed = false
            }
            pausePlayback()
        }
        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
            synchronized(focusLock) {
                // only resume if playback is being interrupted
                resumeOnFocusGain = isPlaying()
                playbackDelayed = false
            }
            pausePlayback()
        }
        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
            // ... pausing or ducking depends on your app
        }
    }
}

Java

// initializing variables for audio focus and playback management
audioManager = (AudioManager) Context.getSystemService(Context.AUDIO_SERVICE);
playbackAttributes = new AudioAttributes.Builder()
        .setUsage(AudioAttributes.USAGE_GAME)
        .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
        .build();
focusRequest = new AudioFocusRequest.Builder(AudioManager.AUDIOFOCUS_GAIN)
        .setAudioAttributes(playbackAttributes)
        .setAcceptsDelayedFocusGain(true)
        .setOnAudioFocusChangeListener(afChangeListener, handler)
        .build();
final Object focusLock = new Object();

boolean playbackDelayed = false;
boolean playbackNowAuthorized = false;

// requesting audio focus and processing the response
int res = audioManager.requestAudioFocus(focusRequest);
synchronized(focusLock) {
    if (res == AudioManager.AUDIOFOCUS_REQUEST_FAILED) {
        playbackNowAuthorized = false;
    } else if (res == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
        playbackNowAuthorized = true;
        playbackNow();
    } else if (res == AudioManager.AUDIOFOCUS_REQUEST_DELAYED) {
        playbackDelayed = true;
        playbackNowAuthorized = false;
    }
}

// implementing OnAudioFocusChangeListener to react to focus changes
@Override
public void onAudioFocusChange(int focusChange) {
    switch (focusChange) {
        case AudioManager.AUDIOFOCUS_GAIN:
            if (playbackDelayed || resumeOnFocusGain) {
                synchronized(focusLock) {
                    playbackDelayed = false;
                    resumeOnFocusGain = false;
                }
                playbackNow();
            }
            break;
        case AudioManager.AUDIOFOCUS_LOSS:
            synchronized(focusLock) {
                resumeOnFocusGain = false;
                playbackDelayed = false;
            }
            pausePlayback();
            break;
        case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT:
            synchronized(focusLock) {
                // only resume if playback is being interrupted
                resumeOnFocusGain = isPlaying();
                playbackDelayed = false;
            }
            pausePlayback();
            break;
        case AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK:
            // ... pausing or ducking depends on your app
            break;
        }
    }
}

自动降低音量

在 Android 8.0（API 级别 26）中，当其他应用使用 AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK 请求焦点时，系统可以降低和恢复音量，而无需调用应用的 onAudioFocusChange() 回调。

虽然自动闪避对于音乐和视频播放应用来说是可接受的行为，但在播放语音内容时（例如在有声读物应用中）却不实用。在这种情况下，应用应改为暂停。

如果您希望应用在收到降低音量请求时暂停播放而不是降低音量，请创建一个 OnAudioFocusChangeListener，并使用 onAudioFocusChange() 回调方法实现所需的暂停/恢复行为。调用 setOnAudioFocusChangeListener() 注册监听器，并调用 setWillPauseWhenDucked(true) 告知系统使用您的回调，而不是执行自动闪避。

延迟获取焦点

有时，系统无法授予音频焦点请求，因为焦点被其他应用“锁定”（例如在通话期间）。在这种情况下，requestAudioFocus() 会返回 AUDIOFOCUS_REQUEST_FAILED。发生这种情况时，您的应用不应继续播放音频，因为它没有获得焦点。

setAcceptsDelayedFocusGain(true) 方法，可让您的应用异步处理焦点请求。设置此标志后，在焦点锁定时发出的请求会返回 AUDIOFOCUS_REQUEST_DELAYED。当锁定音频焦点的条件不复存在时（例如，当通话结束时），系统会批准待处理的焦点请求，并调用 onAudioFocusChange() 来通知您的应用。

为了处理延迟获得焦点的情况，您必须创建一个 OnAudioFocusChangeListener，其中包含实现所需行为的 onAudioFocusChange() 回调方法，并通过调用 setOnAudioFocusChangeListener() 注册监听器。

Android 7.1 及更低版本中的音频焦点

调用 requestAudioFocus() 时，您必须指定时长提示，当前持有焦点并正在播放的另一个应用可能会遵循该提示：

如果您计划在可预见的未来播放音频（例如，播放音乐），并且您希望之前的音频焦点持有者停止播放，请请求永久音频焦点 (AUDIOFOCUS_GAIN)。
如果您预计只会播放很短时间的音频，并且希望上一个焦点持有者暂停播放，请请求暂时性焦点 (AUDIOFOCUS_GAIN_TRANSIENT)。
请求闪避瞬态焦点 (AUDIOFOCUS_GAIN_TRANSIENT_MAY_DUCK)，以指示您希望仅在短时间内播放音频，并且如果之前的焦点所有者“闪避”（降低）其音频输出，则可以继续播放。两个音频输出都会混入音频串流。“闪避”特别适合间歇性使用音频串流的应用，例如语音行车路线。

requestAudioFocus() 方法还需要一个 AudioManager.OnAudioFocusChangeListener。此监听器应在拥有媒体会话的同一 activity 或服务中创建。它会实现当其他应用获取或放弃音频焦点时您的应用收到的回调 onAudioFocusChange()。

以下代码段请求对 STREAM_MUSIC 流的永久音频焦点，并注册 OnAudioFocusChangeListener 以处理后续音频焦点更改。（响应音频焦点更改中讨论了更改监听器。）

Kotlin

audioManager = getSystemService(Context.AUDIO_SERVICE) as AudioManager
lateinit var afChangeListener AudioManager.OnAudioFocusChangeListener

...
// Request audio focus for playback
val result: Int = audioManager.requestAudioFocus(
        afChangeListener,
        // Use the music stream.
        AudioManager.STREAM_MUSIC,
        // Request permanent focus.
        AudioManager.AUDIOFOCUS_GAIN
)

if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
    // Start playback
}

Java

AudioManager audioManager = (AudioManager) context.getSystemService(Context.AUDIO_SERVICE);
AudioManager.OnAudioFocusChangeListener afChangeListener;

...
// Request audio focus for playback
int result = audioManager.requestAudioFocus(afChangeListener,
                             // Use the music stream.
                             AudioManager.STREAM_MUSIC,
                             // Request permanent focus.
                             AudioManager.AUDIOFOCUS_GAIN);

if (result == AudioManager.AUDIOFOCUS_REQUEST_GRANTED) {
    // Start playback
}

播放完毕后，请调用 abandonAudioFocus()。

Kotlin

audioManager.abandonAudioFocus(afChangeListener)

Java

// Abandon audio focus when playback complete
audioManager.abandonAudioFocus(afChangeListener);

此操作会通知系统，您不再需要焦点，并会取消注册关联的 OnAudioFocusChangeListener。如果您请求了瞬态焦点，此方法会通知已暂停或降低音量的应用，告知其可以继续播放或恢复音量。

响应音频焦点更改

当某个应用获得音频焦点后，它必须能够在其他应用请求音频焦点时释放该焦点。发生这种情况时，您的应用会收到对 AudioFocusChangeListener（您在应用调用 requestAudioFocus() 时指定）中的 onAudioFocusChange() 方法的调用。

传递给 onAudioFocusChange() 的 focusChange 参数表示正在发生的更改类型。它对应于获取焦点的应用所使用的时长提示。您的应用应做出适当响应。

暂时性失去焦点

如果焦点变化是暂时性的（AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK 或 AUDIOFOCUS_LOSS_TRANSIENT），您的应用应该降低音量（如果您不依赖自动降低音量）或暂停播放，但除此之外保持相同的状态。

在暂时失去音频焦点期间，您应继续监控音频焦点的变化，并准备好在重新获得焦点后恢复正常播放。当阻碍性应用放弃焦点时，您会收到回调 (AUDIOFOCUS_GAIN)。此时，您可以将音量恢复到正常水平或重新开始播放。

永久性失去焦点

如果音频焦点永久性丢失 (AUDIOFOCUS_LOSS)，则表示另一个应用正在播放音频。您的应用应立即暂停播放，因为它永远不会收到 AUDIOFOCUS_GAIN 回调。如需重新开始播放，用户必须执行明确的操作，例如在通知或应用界面中按下播放传输控件。

以下代码段演示了如何实现 OnAudioFocusChangeListener 及其 onAudioFocusChange() 回调。请注意，使用 Handler 可在永久失去音频焦点时延迟停止回调。

Kotlin

private val handler = Handler()
private val afChangeListener = AudioManager.OnAudioFocusChangeListener { focusChange ->
    when (focusChange) {
        AudioManager.AUDIOFOCUS_LOSS -> {
            // Permanent loss of audio focus
            // Pause playback immediately
            mediaController.transportControls.pause()
            // Wait 30 seconds before stopping playback
            handler.postDelayed(delayedStopRunnable, TimeUnit.SECONDS.toMillis(30))
        }
        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT -> {
            // Pause playback
        }
        AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
            // Lower the volume, keep playing
        }
        AudioManager.AUDIOFOCUS_GAIN -> {
            // Your app has been granted audio focus again
            // Raise volume to normal, restart playback if necessary
        }
    }
}

Java

private Handler handler = new Handler();
AudioManager.OnAudioFocusChangeListener afChangeListener =
  new AudioManager.OnAudioFocusChangeListener() {
    public void onAudioFocusChange(int focusChange) {
      if (focusChange == AudioManager.AUDIOFOCUS_LOSS) {
        // Permanent loss of audio focus
        // Pause playback immediately
        mediaController.getTransportControls().pause();
        // Wait 30 seconds before stopping playback
        handler.postDelayed(delayedStopRunnable,
          TimeUnit.SECONDS.toMillis(30));
      }
      else if (focusChange == AudioManager.AUDIOFOCUS_LOSS_TRANSIENT) {
        // Pause playback
      } else if (focusChange == AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK) {
        // Lower the volume, keep playing
      } else if (focusChange == AudioManager.AUDIOFOCUS_GAIN) {
        // Your app has been granted audio focus again
        // Raise volume to normal, restart playback if necessary
      }
    }
  };

处理程序使用如下所示的 Runnable：

Kotlin

private var delayedStopRunnable = Runnable {
    mediaController.transportControls.stop()
}

Java

private Runnable delayedStopRunnable = new Runnable() {
    @Override
    public void run() {
        getMediaController().getTransportControls().stop();
    }
};

为确保在用户重新开始播放时不会触发延迟停止，请调用 mHandler.removeCallbacks(mDelayedStopRunnable) 以响应任何状态更改。例如，在回调的 onPlay()、onSkipToNext() 等中调用 removeCallbacks()。在清理服务使用的资源时，您还应在服务的 onDestroy() 回调中调用此方法。

管理音频焦点 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Android 12 及更高版本中的音频焦点

现有的音频焦点行为

自动降低音量

来电时将当前播放的音频静音

Android 8.0 至 Android 11 中的音频焦点

Kotlin

Java

自动降低音量

延迟获取焦点

Android 7.1 及更低版本中的音频焦点

Kotlin

Java

Kotlin

Java

响应音频焦点更改

Kotlin

Java

Kotlin

Java

管理音频焦点