Audio attributes

Audio players support attributes that define how the audio system handles routing, volume, and focus decisions for the specified source. Applications can attach attributes to an audio playback (such as music played by a streaming service or a notification for a new email) then pass the audio source attributes to the framework, where the audio system uses the attributes to make mixing decisions and to notify applications about the state of the system.

Note: Applications can also attach attributes to an audio recording (such as audio captured in a video recording), but this functionality is not exposed in the public API.

In Android 4.4 and earlier, the framework made mixing decisions using only the audio stream type. However, basing such decisions on stream type was too limiting to produce quality output across multiple applications and devices. For example, on a mobile device, some applications (i.e. Google Maps) played driving directions on the STREAM_MUSIC stream type; however, on mobile devices in projection mode (i.e. Android Auto), applications cannot mix driving directions with other media streams.

Using the Audio Attribute API, applications provide the audio system with detailed information about a specific audio source, including usage (why the source is playing), content type (what the source is playing), flags (how the source should be played), and contexts (new in Android 9). Syntax:

AudioAttributes {
    mUsage
    mContentType
    mSource
    mFlags
    mTags / mFormattedTags / mBundle    (key value pairs)
}

• Usage. Specifies why the source is playing and controls routing, focus, and volume decisions.
• Content type. Specifies what the source is playing (music, movie, speech, sonification, unknown).
• Context. Usage values abstracted to the Audio HAL.
• Flags. Specifies how the source should be played. Includes support for audibility enforcement (camera shutter sounds required in some countries) and hardware audio/video synchronization.

For dynamics processing, applications must distinguish between movie, music, and speech content. Information about the data itself may also matter, such as loudness and peak sample value.

Use attributes

Usage specifies the context in which the stream is used, providing information about why the sound is playing and what the sound is used for. Usage information is more expressive than a stream type and allows platforms or routing policies to refine volume or routing decisions.

Supply one of the following usage values for any instance:

• 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

Audio attribute usage values are mutually exclusive. For examples, refer to USAGE_MEDIA and USAGE_ALARM definitions; for exceptions, refer to the AudioAttributes.Builder definition.

Content type

Content type defines what the sound is and expresses the general category of the content such as movie, speech, or beep/ringtone. The audio framework uses content type information to selectively configure audio post-processing blocks. While supplying the content type is optional, you should include type information whenever the content type is known, such as using CONTENT_TYPE_MOVIE for a movie streaming service or CONTENT_TYPE_MUSIC for a music playback application.

Supply one of the following content type values for any instance:

• CONTENT_TYPE_UNKNOWN (default)
• CONTENT_TYPE_MOVIE
• CONTENT_TYPE_MUSIC
• CONTENT_TYPE_SONIFICATION
• CONTENT_TYPE_SPEECH

Audio attribute content type values are mutually exclusive. For details on content types, refer to the audio attribute API.

Contexts

Each sound in Android is identified by the responsible application and reason for generating the sound; and Android device uses this information to determine how to present the sound. In Android 8.x and lower, applications can report the sound generation reason using legacy stream types (e.g. AudioSystem.STREAM_MUSIC) or AudioAttributes. In Android 9, AudioAttributes.usage values are abstracted at the HAL level as Contexts.

HAL audio contexts	AudioAttributes usage
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

You can supply one of the following CONTEXT_NUMBER values for any instance:

• MUSIC_CONTEXT // Music playback
• NAVIGATION_CONTEXT // Navigation directions
• VOICE_COMMAND_CONTEXT // Voice command session
• CALL_RING_CONTEXT // Voice call ringing
• CALL_CONTEXT // Voice call
• ALARM_CONTEXT // Alarm sound from Android
• NOTIFICATION_CONTEXT // Notifications
• SYSTEM_SOUND_CONTEXT // User interaction sounds (button clicks, etc)

Flags

Flags specify how the audio framework applies effects to the audio playback. Supply one or more of the following flags for an instance:

• FLAG_AUDIBILITY_ENFORCED. Requests the system to ensure the audibility of the sound. Use to address the needs of legacy STREAM_SYSTEM_ENFORCED (such as forcing camera shutter sounds).
• HW_AV_SYNC. Requests the system to select an output stream that supports hardware A/V synchronization.

Audio attribute flags are non-exclusive and can be combined. For details on these flags, refer to the audio attribute API.

Example

In this example, AudioAttributes.Builder defines the AudioAttributes to be used by a new AudioTrack instance:

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

Compatibility

Application developers should use audio attributes when creating or updating applications for Android 5.0 and higher. However, applications are not required to take advantage of attributes; they can handle legacy stream types only or remain unaware of attributes (i.e. a generic media player that doesn't know anything about the content it's playing).

In such cases, the framework maintains backwards compatibility with older devices and Android releases by automatically translating legacy audio stream types to audio attributes. However, the framework does not enforce or guarantee this mapping across devices, manufacturers, or Android releases.

Compatibility mappings:

Android 5.0 and higher	Android 4.4 and earlier
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

Note: @hide streams are used internally by the framework but are not part of the public API.

Deprecated stream types

Android 9 deprecates the following stream types for automotive use:

• 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

For more details, see Automotive Audio.