1 page.title=Audio Attributes 2 @jd:body 3 4 <!-- 5 Copyright 2014 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <p>Audio players support attributes that define how the audio system handles routing, volume, and 28 focus decisions for the specified source. Applications can attach attributes to an audio playback 29 (such as music played by a streaming service or a notification for a new email) then pass the audio 30 source attributes to the framework, where the audio system uses the attributes to make mixing 31 decisions and to notify applications about the state of the system.</p> 32 33 <p class="note"><strong>Note:</strong> Applications can also attach attributes to an audio 34 recording (such as audio captured in a video recording), but this functionality is not exposed in 35 the public API.</p> 36 37 <p>In Android 4.4 and earlier, the framework made mixing decisions using only the audio stream type. 38 However, basing such decisions on stream type was too limiting to produce quality output across 39 multiple applications and devices. For example, on a mobile device, some applications (i.e. 40 Google Maps) played driving directions on the STREAM_MUSIC stream type; however, on mobile 41 devices in projection mode (i.e. Android Auto), applications cannot mix driving directions with 42 other media streams.</p> 43 44 <p>Using the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html"> 45 audio attribute API</a>, applications can now provide the audio system with detailed information 46 about a specific audio source:</p> 47 48 <ul> 49 <li><b>Usage</b>. Specifies why the source is playing and controls routing, focus, and volume 50 decisions.</li> 51 <li><b>Content type</b>. Specifies what the source is playing (music, movie, speech, 52 sonification, unknown).</li> 53 <li><b>Flags</b>. Specifies how the source should be played. Includes support for audibility 54 enforcement (camera shutter sounds required in some countries) and hardware audio/video 55 synchronization.</li> 56 </ul> 57 58 <p>For dynamics processing, applications must distinguish between movie, music, and speech content. 59 Information about the data itself may also matter, such as loudness and peak sample value.</p> 60 61 <h2 id="using">Using attributes</h2> 62 63 <p>Usage specifies the context in which the stream is used, providing information about why the 64 sound is playing and what the sound is used for. Usage information is more expressive than a stream 65 type and allows platforms or routing policies to refine volume or routing decisions.</p> 66 67 <p>Supply one of the following usage values for any instance:</p> 68 69 <ul> 70 <li><code>USAGE_UNKNOWN</code></li> 71 <li><code>USAGE_MEDIA</code></li> 72 <li><code>USAGE_VOICE_COMMUNICATION</code></li> 73 <li><code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code></li> 74 <li><code>USAGE_ALARM</code></li> 75 <li><code>USAGE_NOTIFICATION</code></li> 76 <li><code>USAGE_NOTIFICATION_RINGTONE</code></li> 77 <li><code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code></li> 78 <li><code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code></li> 79 <li><code>USAGE_NOTIFICATION_EVENT</code></li> 80 <li><code>USAGE_ASSISTANCE_ACCESSIBILITY</code></li> 81 <li><code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code></li> 82 <li><code>USAGE_ASSISTANCE_SONIFICATION</code></li> 83 <li><code>USAGE_GAME</code></li> 84 </ul> 85 86 <p>Audio attribute usage values are mutually exclusive. For examples, refer to <code> 87 <a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA"> 88 USAGE_MEDIA</a></code> and <code> 89 <a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM"> 90 USAGE_ALARM</a></code> definitions; for exceptions, refer to the <code> 91 <a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html"> 92 AudioAttributes.Builder</a></code> definition.</p> 93 94 <h2 id="content-type">Content type</h2> 95 96 <p>Content type defines what the sound is and expresses the general category of the content such as 97 movie, speech, or beep/ringtone. The audio framework uses content type information to selectively 98 configure audio post-processing blocks. While supplying the content type is optional, you should 99 include type information whenever the content type is known, such as using 100 <code>CONTENT_TYPE_MOVIE</code> for a movie streaming service or <code>CONTENT_TYPE_MUSIC</code> 101 for a music playback application.</p> 102 103 <p>Supply one of the following content type values for any instance:</p> 104 105 <ul> 106 <li><code>CONTENT_TYPE_UNKNOWN</code> (default)</li> 107 <li><code>CONTENT_TYPE_MOVIE</code></li> 108 <li><code>CONTENT_TYPE_MUSIC</code></li> 109 <li><code>CONTENT_TYPE_SONIFICATION</code></li> 110 <li><code>CONTENT_TYPE_SPEECH</code></li> 111 </ul> 112 113 <p>Audio attribute content type values are mutually exclusive. For details on content types, 114 refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html"> 115 audio attribute API</a>.</p> 116 117 <h2 id="flags">Flags</h2> 118 119 <p>Flags specify how the audio framework applies effects to the audio playback. Supply one or more 120 of the following flags for an instance:</p> 121 122 <ul> 123 <li><code>FLAG_AUDIBILITY_ENFORCED</code>. Requests the system ensure the audibility of the 124 sound. Use to address the needs of legacy <code>STREAM_SYSTEM_ENFORCED</code> (such as forcing 125 camera shutter sounds).</li> 126 <li><code>HW_AV_SYNC</code>. Requests the system select an output stream that supports hardware A/V 127 synchronization.</li> 128 </ul> 129 130 <p>Audio attribute flags are non-exclusive (can be combined). For details on these flags, 131 refer to the <a href="http://developer.android.com/reference/android/media/AudioAttributes.html"> 132 audio attribute API</a>.</p> 133 134 <h2 id="example">Example</h2> 135 136 <p>In this example, AudioAttributes.Builder defines the AudioAttributes to be used by a new 137 AudioTrack instance:</p> 138 139 <pre> 140 AudioTrack myTrack = new AudioTrack( 141 new AudioAttributes.Builder() 142 .setUsage(AudioAttributes.USAGE_MEDIA) 143 .setContentType(AudioAttributes.CONTENT_TYPE_MUSIC) 144 .build(), 145 myFormat, myBuffSize, AudioTrack.MODE_STREAM, mySession); 146 </pre> 147 148 <h2 id="compatibility">Compatibility</h2> 149 150 <p>Application developers should use audio attributes when creating or updating applications for 151 Android 5.0. However, applications are not required to take advantage of attributes; they can 152 handle legacy stream types only or remain unaware of attributes (i.e. a generic media player that 153 doesnt know anything about the content its playing).</p> 154 155 <p>In such cases, the framework maintains backwards compatibility with older devices and Android 156 releases by automatically translating legacy audio stream types to audio attributes. However, the 157 framework does not enforce or guarantee this mapping across devices, manufacturers, or Android 158 releases.</p> 159 160 <p>Compatibility mappings:</p> 161 162 <table> 163 <tr> 164 <th>Android 5.0</th> 165 <th>Android 4.4 and earlier</th> 166 </tr> 167 <tr> 168 <td> 169 <code>CONTENT_TYPE_SPEECH</code><br> 170 <code>USAGE_VOICE_COMMUNICATION</code> 171 </td> 172 <td> 173 <code>STREAM_VOICE_CALL</code> 174 </td> 175 </tr> 176 <tr> 177 <td> 178 <code>CONTENT_TYPE_SONIFICATION</code><br> 179 <code>USAGE_ASSISTANCE_SONIFICATION</code> 180 </td> 181 <td> 182 <code>STREAM_SYSTEM</code> 183 </td> 184 </tr> 185 <tr> 186 <td> 187 <code>CONTENT_TYPE_SONIFICATION</code><br> 188 <code>USAGE_NOTIFICATION_RINGTONE</code> 189 </td> 190 <td> 191 <code>STREAM_RING</code> 192 </td> 193 </tr> 194 <tr> 195 <td> 196 <code>CONTENT_TYPE_MUSIC</code><br> 197 <code>USAGE_UNKNOWN</code><br> 198 <code>USAGE_MEDIA</code><br> 199 <code>USAGE_GAME</code><br> 200 <code>USAGE_ASSISTANCE_ACCESSIBILITY</code><br> 201 <code>USAGE_ASSISTANCE_NAVIGATION_GUIDANCE</code><br> 202 </td> 203 <td> 204 <code>STREAM_MUSIC</code> 205 </td> 206 </tr> 207 <tr> 208 <td> 209 <code>CONTENT_TYPE_SONIFICATION</code><br> 210 <code>USAGE_ALARM</code> 211 </td> 212 <td> 213 <code>STREAM_ALARM</code> 214 </td> 215 </tr> 216 <tr> 217 <td> 218 <code>CONTENT_TYPE_SONIFICATION</code><br> 219 <code>USAGE_NOTIFICATION</code><br> 220 <code>USAGE_NOTIFICATION_COMMUNICATION_REQUEST</code><br> 221 <code>USAGE_NOTIFICATION_COMMUNICATION_INSTANT</code><br> 222 <code>USAGE_NOTIFICATION_COMMUNICATION_DELAYED</code><br> 223 <code>USAGE_NOTIFICATION_EVENT</code><br> 224 </td> 225 <td> 226 <code>STREAM_NOTIFICATION</code> 227 </td> 228 </tr> 229 <tr> 230 <td> 231 <code>CONTENT_TYPE_SPEECH</code> 232 </td> 233 <td> 234 (@hide)<code> STREAM_BLUETOOTH_SCO</code> 235 </td> 236 </tr> 237 <tr> 238 <td> 239 <code>FLAG_AUDIBILITY_ENFORCED</code> 240 </td> 241 <td> 242 (@hide)<code> STREAM_SYSTEM_ENFORCED</code> 243 </td> 244 </tr> 245 <tr> 246 <td> 247 <code>CONTENT_TYPE_SONIFICATION</code><br> 248 <code>USAGE_VOICE_COMMUNICATION_SIGNALLING</code> 249 </td> 250 <td> 251 (@hide)<code> STREAM_DTMF</code> 252 </td> 253 </tr> 254 </table> 255 256 <p class="note"><strong>Note:</strong> @hide streams are used internally by the framework but are 257 not part of the public API.</p>
