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