管理音频焦点

两个或多个 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）及更高版本中，系统会强制执行此行为。当一个应用在另一个应用具有焦点并正在播放时请求音频焦点时，系统会强制正在播放的应用淡出。淡出功能的添加为从一个应用切换到另一个应用提供了更平滑的过渡。

当满足以下条件时，会出现此淡出行为

1. 第一个正在播放的应用满足所有这些条件

   • 该应用具有 AudioAttributes.USAGE_MEDIA 或 AudioAttributes.USAGE_GAME 用途属性。
   • 该应用已成功使用 AudioManager.AUDIOFOCUS_GAIN 请求音频焦点。
   • 该应用没有使用 AudioAttributes.CONTENT_TYPE_SPEECH 内容类型播放音频。

2. 第二个应用使用 AudioManager.AUDIOFOCUS_GAIN 请求音频焦点。

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

现有的音频焦点行为

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

自动降低音量

自动降低音量（暂时降低一个应用的音频级别，以便另一个应用能够清晰地听到）是在 Android 8.0（API 级别 26）中引入的。

通过让系统实现降低音量，您不必在您的应用中实现降低音量。

当音频通知从正在播放的应用中获取焦点时，也会发生自动降低音量。通知播放的开始与降低音量斜坡的结束同步。

当满足以下条件时，会发生自动降低音量

1. 第一个正在播放的应用满足所有这些条件

   • 该应用已成功使用任何类型的 焦点获取 请求音频焦点。
   • 该应用没有使用 AudioAttributes.CONTENT_TYPE_SPEECH 内容类型播放音频。
   • 该应用没有设置 AudioFocusRequest.Builder.setWillPauseWhenDucked(true)。

2. 第二个应用使用 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 字段是必需的；所有其他字段都是可选的。

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

// 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
        }
    }
}

// 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。此监听器应在拥有你的媒体会话的相同活动或服务中创建。它实现了回调 onAudioFocusChange()，你的应用在其他应用获取或放弃音频焦点时会收到此回调。

以下代码片段请求在 STREAM_MUSIC 流上获得永久音频焦点，并注册一个 OnAudioFocusChangeListener 来处理后续的音频焦点变化。（变化监听器在 响应音频焦点变化 中进行了讨论。）

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
}

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()。

audioManager.abandonAudioFocus(afChangeListener)

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

这会通知系统你不再需要焦点，并注销关联的 OnAudioFocusChangeListener。如果你请求了瞬时焦点，这将通知暂停或降低音量的应用，它可以继续播放或恢复其音量。

响应音频焦点变化

当应用获取音频焦点时，它必须能够在另一个应用请求为自己获取音频焦点时释放它。发生这种情况时，你的应用会收到对 onAudioFocusChange() 方法的调用，该方法位于你在应用调用 requestAudioFocus() 时指定的 AudioFocusChangeListener 中。

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

瞬时失去焦点

如果焦点变化是瞬时的 (AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK 或 AUDIOFOCUS_LOSS_TRANSIENT)，你的应用应降低音量（如果你没有依赖 自动降低音量）或暂停播放，但在其他方面保持相同的状态。

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

永久失去焦点

如果音频焦点丢失是永久性的 (AUDIOFOCUS_LOSS)，则另一个应用正在播放音频。你的应用应立即暂停播放，因为它永远不会收到 AUDIOFOCUS_GAIN 回调。要重新开始播放，用户必须采取明确的操作，例如在通知或应用 UI 中按下播放传输控制。

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

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
        }
    }
}

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，它看起来像这样

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

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

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