zh-cn/devices/audio/attributes.html - platform/docs/source.android.com - Git at Google

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

 <p class="note"><strong>注意</strong>：应用还可以将属性附加到音频录制（例如在视频录制中截取的音频）上，但此功能不会在公共 API 中提供。</p>

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

 <p>现在，应用可以使用<a href="http://developer.android.com/reference/android/media/AudioAttributes.html">音频属性 API</a> 为音频系统提供有关特定音频源的详细信息：</p>

 <ul>
 <li><b>用法</b>。指定播放来源的原因，并控制导向、焦点和音量决策。</li>
 <li><b>内容类型</b>。指定播放来源的类型（音乐、电影、语音、发音、未知）。</li>
 <li><b>标记</b>。指定来源的播放方式。包括对可听性强制执行（一些国家/地区要求发出相机快门提示音）和硬件音频/视频同步的支持。</li>
 </ul>

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

 <h2 id="using">使用属性</h2>

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

 <p>为任何实例提供以下用法值之一：</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>音频属性用法值是互斥的。有关示例，请参阅 <code>
 <a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA">
 USAGE_MEDIA</a></code> 和 <code>
 <a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM">
 USAGE_ALARM</a></code> 定义；有关异常，请参阅 <code>
 <a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html">
 AudioAttributes.Builder</a></code> 定义。</p>

 <h2 id="content-type">内容类型</h2>

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

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

 <ul>
 <li><code>CONTENT_TYPE_UNKNOWN</code>（默认）</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>音频属性内容类型值是互斥的。有关内容类型的详细信息，请参阅<a href="http://developer.android.com/reference/android/media/AudioAttributes.html">音频属性 API</a>。</p>

 <h2 id="flags">标记</h2>

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

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

 <p>音频属性标记是非专有的（可以组合使用）。要详细了解这些标记，请参阅<a href="http://developer.android.com/reference/android/media/AudioAttributes.html">音频属性 API</a>。</p>

 <h2 id="example">示例</h2>

 <p>在此示例中，AudioAttributes.Builder 定义了一个新的 AudioTrack 实例将使用的音频属性：</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">兼容性</h2>

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

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

 <p>兼容性映射：</p>

 <table>
 <tbody><tr>
   <th>Android 5.0</th>
   <th>Android 4.4 及更早版本</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>
 </tbody></table>

 <p class="note"><strong>注意</strong>：@hide 流在框架内部使用，不是公共 API 的一部分。</p>

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

	<p class="note"><strong>注意</strong>：应用还可以将属性附加到音频录制（例如在视频录制中截取的音频）上，但此功能不会在公共 API 中提供。</p>

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

	<p>现在，应用可以使用<a href="http://developer.android.com/reference/android/media/AudioAttributes.html">音频属性 API</a> 为音频系统提供有关特定音频源的详细信息：</p>

	<ul>
	<li><b>用法</b>。指定播放来源的原因，并控制导向、焦点和音量决策。</li>
	<li><b>内容类型</b>。指定播放来源的类型（音乐、电影、语音、发音、未知）。</li>
	<li><b>标记</b>。指定来源的播放方式。包括对可听性强制执行（一些国家/地区要求发出相机快门提示音）和硬件音频/视频同步的支持。</li>
	</ul>

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

	<h2 id="using">使用属性</h2>

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

	<p>为任何实例提供以下用法值之一：</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>音频属性用法值是互斥的。有关示例，请参阅 <code>
	<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_MEDIA">
	USAGE_MEDIA</a></code> 和 <code>
	<a href="http://developer.android.com/reference/android/media/AudioAttributes.html#USAGE_ALARM">
	USAGE_ALARM</a></code> 定义；有关异常，请参阅 <code>
	<a href="http://developer.android.com/reference/android/media/AudioAttributes.Builder.html">
	AudioAttributes.Builder</a></code> 定义。</p>

	<h2 id="content-type">内容类型</h2>

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

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

	<ul>
	<li><code>CONTENT_TYPE_UNKNOWN</code>（默认）</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>音频属性内容类型值是互斥的。有关内容类型的详细信息，请参阅<a href="http://developer.android.com/reference/android/media/AudioAttributes.html">音频属性 API</a>。</p>

	<h2 id="flags">标记</h2>

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

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

	<p>音频属性标记是非专有的（可以组合使用）。要详细了解这些标记，请参阅<a href="http://developer.android.com/reference/android/media/AudioAttributes.html">音频属性 API</a>。</p>

	<h2 id="example">示例</h2>

	<p>在此示例中，AudioAttributes.Builder 定义了一个新的 AudioTrack 实例将使用的音频属性：</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">兼容性</h2>

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

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

	<p>兼容性映射：</p>

	<table>
	<tbody><tr>
	<th>Android 5.0</th>
	<th>Android 4.4 及更早版本</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>
	</tbody></table>

	<p class="note"><strong>注意</strong>：@hide 流在框架内部使用，不是公共 API 的一部分。</p>

	</body></html>