音频属性

音频播放器支持定义音频系统如何处理指定来源的导向、音量和焦点决策的属性。应用可以将属性附加到音频播放（例如流式传输服务播放的音乐或新电子邮件通知）上，然后将音频源的属性传递给框架，此时音频系统会使用这些属性做出混音决策并将系统状态通知给应用。

在 Android 4.4 及更早版本中，框架仅使用音频流类型做出混音决策。不过，基于流类型做出这些决策过于受限，无法在多个应用和设备上产生优质输出。例如，在移动设备上，某些应用（例如 Google 地图）基于 STREAM_MUSIC 流类型播放驾驶方向；但是，在采用投影仪模式（例如 Android Auto）的移动设备上，应用不能将驾驶方向与其他媒体流混合在一起播放。

应用可以使用音频属性 API 为音频系统提供有关特定音频源的详细信息，包括用法（播放来源的原因）、内容类型（播放来源的类型）、标志（来源的播放方式）以及上下文（Android 9 中的新变化）。语法如下所示： 

AudioAttributes {
    mUsage
    mContentType
    mSource
    mFlags
    mTags / mFormattedTags / mBundle    (key value pairs)
}
  • 用法。指定播放来源的原因，并控制导向、焦点和音量决策。
  • 内容类型。指定播放来源的类型（音乐、电影、语音、发音、未知）。
  • 上下文。提取到 Audio HAL 的用法值。
  • 标记。指定来源的播放方式。 包括对可听性强制执行（一些国家/地区要求发出相机快门提示音）和硬件音频/视频同步的支持。

对于动态处理，应用必须区分电影、音乐和语音内容。关于数据本身的信息也可能非常重要，例如响度和峰值采样值。

使用属性

用法指定了在何种上下文中使用相关流类型，并提供有关播放相应声音的原因以及该声音用法的信息。用法信息比流类型信息更丰富，并且可让平台或导向策略优化音量或导向决策。

为任何实例提供以下用法值之一：

  • USAGE_UNKNOWN
  • USAGE_MEDIA
  • USAGE_VOICE_COMMUNICATION
  • USAGE_VOICE_COMMUNICATION_SIGNALLING
  • USAGE_ALARM
  • USAGE_NOTIFICATION
  • USAGE_NOTIFICATION_TELEPHONY_RINGTONE
  • USAGE_NOTIFICATION_COMMUNICATION_REQUEST
  • USAGE_NOTIFICATION_COMMUNICATION_INSTANT
  • USAGE_NOTIFICATION_COMMUNICATION_DELAYED
  • USAGE_NOTIFICATION_EVENT
  • USAGE_ASSISTANCE_ACCESSIBILITY
  • USAGE_ASSISTANCE_NAVIGATION_GUIDANCE
  • USAGE_ASSISTANCE_SONIFICATION
  • USAGE_GAME
  • USAGE_VIRTUAL_SOURCE
  • USAGE_ASSISTANT

音频属性用法值是互斥的。有关示例，请参阅 USAGE_MEDIA 和 USAGE_ALARM 定义；有关例外情况，请参阅 AudioAttributes.Builder 定义。

内容类型

内容类型定义了声音是什么，并指明内容的常规类别，如电影、语音或提示音/铃声。音频框架使用内容类型信息来选择性地配置音频处理后块。尽管提供内容类型是可选的，但只要内容类型已知，您就应该包含类型信息，例如针对电影流式传输服务使用 CONTENT_TYPE_MOVIE，或针对音乐播放应用使用 CONTENT_TYPE_MUSIC。

为任何实例提供以下内容类型值之一：

  • CONTENT_TYPE_UNKNOWN（默认）
  • CONTENT_TYPE_MOVIE
  • CONTENT_TYPE_MUSIC
  • CONTENT_TYPE_SONIFICATION
  • CONTENT_TYPE_SPEECH

音频属性内容类型值是互斥的。有关内容类型的详细信息，请参阅音频属性 API。

上下文

Android 中的每段声音都由相应的应用和生成声音的原因来识别；Android 设备会使用这些信息来确定如何呈现声音。在 Android 8.x 及更低版本中，应用可以使用旧版流类型（如 AudioSystem.STREAM_MUSIC）或 AudioAttributes 报告生成声音的原因。在 Android 9 中，AudioAttributes.usage 值在 HAL 级别被提取为上下文。

HAL 音频上下文 AudioAttributes 用法
MUSIC MEDIA
VOICE_COMMAND USAGE_ASSISTANT
NAVIGATION ASSISTANCE_NAVIGATION_GUIDANCE
CALL VOICE_COMMUNICATION
RINGTONE NOTIFICATION_RINGTONE
NOTIFICATION NOTIFICATION
ALARM ALARM
SYSTEM_SOUND ASSISTANCE_SONIFICATION
UNKNOWN UNKNOWN

您可以为任何实例提供以下 CONTEXT_NUMBER 值之一：

  • MUSIC_CONTEXT // 音乐播放
  • NAVIGATION_CONTEXT // 导航路线
  • VOICE_COMMAND_CONTEXT // 语音指令会话
  • CALL_RING_CONTEXT // 语音呼叫响铃
  • CALL_CONTEXT // 语音通话
  • ALARM_CONTEXT // Android 闹钟铃声
  • NOTIFICATION_CONTEXT // 通知
  • SYSTEM_SOUND_CONTEXT // 用户交互声音（按钮点击声音等）

标志

标志会指定音频框架如何对音频播放应用效果。请为一个实例提供以下一个或多个标志：

  • FLAG_AUDIBILITY_ENFORCED。向系统发出请求，以确保声音的可听性。用于满足旧版 STREAM_SYSTEM_ENFORCED 的需求（如强制要求发出相机快门提示音）。
  • HW_AV_SYNC。向系统发出请求，以选择支持硬件 A/V 同步的输出流。

音频属性标志是非专有的（可以组合使用）。如需详细了解这些标记，请参阅音频属性 API。

示例

在以下示例中，AudioAttributes.Builder 定义了将由一个新的 AudioTrack 实例使用的 AudioAttributes： 

AudioTrack myTrack = new AudioTrack(
  new AudioAttributes.Builder()
 .setUsage(AudioAttributes.USAGE_MEDIA)
    .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
    .build(),
  myFormat, myBuffSize, AudioTrack.MODE_STREAM, mySession);

兼容性

应用开发者在为 Android 5.0 或更高版本创建或更新应用时，应使用音频属性。不过，应用并非必须要利用这些属性；它们可以仅处理旧版流类型，或一直不知道属性（即，对其播放的内容一无所知的常规媒体播放器）。

在此类情况下，框架通过自动将旧版音频流类型转换为音频属性，保持对旧设备和 Android 版本的向后兼容性。不过，框架不会针对各个设备、制造商或 Android 版本强制要求或保证具备这种映射。

兼容性映射：

Android 5.0 及更高版本 Android 4.4 及更早版本
CONTENT_TYPE_SPEECH
USAGE_VOICE_COMMUNICATION 		STREAM_VOICE_CALL
CONTENT_TYPE_SONIFICATION
USAGE_ASSISTANCE_SONIFICATION 		STREAM_SYSTEM
CONTENT_TYPE_SONIFICATION
USAGE_NOTIFICATION_RINGTONE 		STREAM_RING
CONTENT_TYPE_MUSIC
USAGE_UNKNOWN
USAGE_MEDIA
USAGE_GAME
USAGE_ASSISTANCE_ACCESSIBILITY
USAGE_ASSISTANCE_NAVIGATION_GUIDANCE 		STREAM_MUSIC
CONTENT_TYPE_SONIFICATION
USAGE_ALARM 		STREAM_ALARM
CONTENT_TYPE_SONIFICATION
USAGE_NOTIFICATION
USAGE_NOTIFICATION_COMMUNICATION_REQUEST
USAGE_NOTIFICATION_COMMUNICATION_INSTANT
USAGE_NOTIFICATION_COMMUNICATION_DELAYED
USAGE_NOTIFICATION_EVENT 		STREAM_NOTIFICATION
CONTENT_TYPE_SPEECH (@hide) STREAM_BLUETOOTH_SCO
FLAG_AUDIBILITY_ENFORCED (@hide) STREAM_SYSTEM_ENFORCED
CONTENT_TYPE_SONIFICATION
USAGE_VOICE_COMMUNICATION_SIGNALLING 		(@hide) STREAM_DTMF

已弃用的流类型

Android 9 弃用了以下用于汽车的流类型：

  • STREAM_DEFAULT
  • STREAM_VOICE_CALL
  • STREAM_SYSTEM
  • STREAM_RING
  • STREAM_MUSIC
  • STREAM_ALARM
  • STREAM_NOTIFICATION
  • STREAM_BLUETOOTH_SCO
  • STREAM_SYSTEM_ENFORCED
  • STREAM_DTMF
  • STREAM_TTS
  • STREAM_ACCESSIBILITY

有关详情，请参阅汽车音频。