1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
<html devsite>
<head>
<title>Audio Attributes</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>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.</p>
<p class="note"><strong>Note:</strong> 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.</p>
<p>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.</p>
<p>Using the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
audio attribute API</a>, applications can now provide the audio system with detailed information
about a specific audio source:</p>
<ul>
<li><b>Usage</b>. Specifies why the source is playing and controls routing, focus, and volume
decisions.</li>
<li><b>Content type</b>. Specifies what the source is playing (music, movie, speech,
sonification, unknown).</li>
<li><b>Flags</b>. Specifies how the source should be played. Includes support for audibility
enforcement (camera shutter sounds required in some countries) and hardware audio/video
synchronization.</li>
</ul>
<p>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.</p>
<h2 id="using">Using attributes</h2>
<p>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.</p>
<p>Supply one of the following usage values for any instance:</p>
<ul>
<li><code>USAGE_UNKNOWN</code></li>
<li><code>USAGE_MEDIA</code></li>
<li><code>USAGE_VOICE_COMMUNICATION</code></li>
<li><code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code></li>
<li><code>USAGE_ALARM</code></li>
<li><code>USAGE_NOTIFICATION</code></li>
<li><code>USAGE_NOTIFICATION_RINGTONE</code></li>
<li><code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code></li>
<li><code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code></li>
<li><code>USAGE_NOTIFICATION_EVENT</code></li>
<li><code>USAGE_ASSISTANCE_ACCESSIBILITY</code></li>
<li><code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code></li>
<li><code>USAGE_ASSISTANCE_SONIFICATION</code></li>
<li><code>USAGE_GAME</code></li>
</ul>
<p>Audio attribute usage values are mutually exclusive. For examples, refer to <code>
<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA">
USAGE_MEDIA</a></code> and <code>
<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM">
USAGE_ALARM</a></code> definitions; for exceptions, refer to the <code>
<a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html">
AudioAttributes.Builder</a></code> definition.</p>
<h2 id="content-type">Content type</h2>
<p>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
<code>CONTENT_TYPE_MOVIE</code> for a movie streaming service or <code>CONTENT_TYPE_MUSIC</code>
for a music playback application.</p>
<p>Supply one of the following content type values for any instance:</p>
<ul>
<li><code>CONTENT_TYPE_UNKNOWN</code> (default)</li>
<li><code>CONTENT_TYPE_MOVIE</code></li>
<li><code>CONTENT_TYPE_MUSIC</code></li>
<li><code>CONTENT_TYPE_SONIFICATION</code></li>
<li><code>CONTENT_TYPE_SPEECH</code></li>
</ul>
<p>Audio attribute content type values are mutually exclusive. For details on content types,
refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
audio attribute API</a>.</p>
<h2 id="flags">Flags</h2>
<p>Flags specify how the audio framework applies effects to the audio playback. Supply one or more
of the following flags for an instance:</p>
<ul>
<li><code>FLAG_AUDIBILITY_ENFORCED</code>. Requests the system ensure the audibility of the
sound. Use to address the needs of legacy <code>STREAM_SYSTEM_ENFORCED</code> (such as forcing
camera shutter sounds).</li>
<li><code>HW_AV_SYNC</code>. Requests the system select an output stream that supports hardware A/V
synchronization.</li>
</ul>
<p>Audio attribute flags are non-exclusive (can be combined). For details on these flags,
refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html">
audio attribute API</a>.</p>
<h2 id="example">Example</h2>
<p>In this example, AudioAttributes.Builder defines the AudioAttributes to be used by a new
AudioTrack instance:</p>
<pre class="devsite-click-to-copy">
AudioTrack myTrack = new AudioTrack(
new AudioAttributes.Builder()
.setUsage(AudioAttributes.USAGE_MEDIA)
.setContentType(AudioAttributes.CONTENT_TYPE_MUSIC)
.build(),
myFormat, myBuffSize, AudioTrack.MODE_STREAM, mySession);
</pre>
<h2 id="compatibility">Compatibility</h2>
<p>Application developers should use audio attributes when creating or updating applications for
Android 5.0. 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).</p>
<p>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.</p>
<p>Compatibility mappings:</p>
<table>
<tr>
<th>Android 5.0</th>
<th>Android 4.4 and earlier</th>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SPEECH</code><br />
<code>USAGE_VOICE_COMMUNICATION</code>
</td>
<td>
<code>STREAM_VOICE_CALL</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SONIFICATION</code><br />
<code>USAGE_ASSISTANCE_SONIFICATION</code>
</td>
<td>
<code>STREAM_SYSTEM</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SONIFICATION</code><br />
<code>USAGE_NOTIFICATION_RINGTONE</code>
</td>
<td>
<code>STREAM_RING</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_MUSIC</code><br />
<code>USAGE_UNKNOWN</code><br />
<code>USAGE_MEDIA</code><br />
<code>USAGE_GAME</code><br />
<code>USAGE_ASSISTANCE_ACCESSIBILITY</code><br />
<code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code>
</td>
<td>
<code>STREAM_MUSIC</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SONIFICATION</code><br />
<code>USAGE_ALARM</code>
</td>
<td>
<code>STREAM_ALARM</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SONIFICATION</code><br />
<code>USAGE_NOTIFICATION</code><br />
<code>USAGE_NOTIFICATION_COMMUNICATION_REQUEST</code><br />
<code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code><br />
<code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code><br />
<code>USAGE_NOTIFICATION_EVENT</code>
</td>
<td>
<code>STREAM_NOTIFICATION</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SPEECH</code>
</td>
<td>
(@hide)<code> STREAM_BLUETOOTH_SCO</code>
</td>
</tr>
<tr>
<td>
<code>FLAG_AUDIBILITY_ENFORCED</code>
</td>
<td>
(@hide)<code> STREAM_SYSTEM_ENFORCED</code>
</td>
</tr>
<tr>
<td>
<code>CONTENT_TYPE_SONIFICATION</code><br />
<code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code>
</td>
<td>
(@hide)<code> STREAM_DTMF</code>
</td>
</tr>
</table>
<p class="note"><strong>Note:</strong> @hide streams are used internally by the framework but are
not part of the public API.</p>
</body>
</html>
|
