Audio

删除与 StreamBuilder 关联的资源。

从 API 级别 26 开始可用。

根据 StreamBuilder 中的选项打开一个流。

AAudioStream_close() 必须在流使用完毕后调用，以回收内存并释放相关资源。

从 API 级别 26 开始可用。

指定此流音频是否可由其他应用或系统捕获。

默认值为 AAUDIO_ALLOW_CAPTURE_BY_ALL。

请注意，应用也可以设置其全局策略，在这种情况下，始终应用限制性最强的策略。请参阅 setAllowedCapturePolicy(int)

自 API 级别 29 开始可用。

声明创建流的上下文的归因标签。

这通常是

Context#getAttributionTag() 

如果您不调用此函数，默认值为 null。

从 API 级别 31 开始可用。

设置请求的缓冲区容量（以帧为单位）。

最终的 AAudioStream 容量可能不同，但可能至少有这么大。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED。

从 API 级别 26 开始可用。

请求流的通道数。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED。然后在流打开时选择最佳值。打开具有未指定值的流后，应用必须查询实际值，该值可能因设备而异。

如果指定了确切值，则打开的流将使用该值。如果无法使用指定值打开流，则打开将失败。

由于此处提供的通道数可能与 AAudioStreamBuilder_setChannelMask 中使用的通道掩码的相应通道数不同，因此如果同时调用此函数和 AAudioStreamBuilder_setChannelMask，将以最后调用的函数为准。

请注意，如果通道数为两个，当设备仅支持一个通道时，可能会混音为单声道。如果通道数大于两个但设备支持的通道数小于请求的值，则高于设备通道的通道将被丢弃。如果应混合或空间化较高通道，请改用 AAudioStreamBuilder_setChannelMask。

从 API 级别 26 开始可用。

设置流的音频通道掩码。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED。如果通道掩码和通道数均未设置，则在流打开时将选择立体声。打开具有未指定值的流后，应用必须查询实际值，该值可能因设备而异。

如果指定了确切值，则打开的流将使用该值。如果无法使用指定值打开流，则打开将失败。

由于此处提供的通道掩码的相应通道数可能与 AAudioStreamBuilder_setChannelCount 或 AAudioStreamBuilder_setSamplesPerFrame 中使用的通道数不同，因此如果同时调用此函数和 AAudioStreamBuilder_setChannelCount 或 AAudioStreamBuilder_setSamplesPerFrame，将以最后调用的函数为准。

自 API 级别 32 开始可用。

设置输出流将承载的音频数据类型。

AAudio 系统将使用此信息优化流的行为。例如，这可能会影响通知发生时流是否暂停。

如果您不调用此函数，默认值为 AAUDIO_CONTENT_TYPE_MUSIC。

如果您设置了 ContentType，则需要将音量键与结果流关联起来。否则音量键可能无法正常工作。这在 Java 中通过以下代码块完成。

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    AudioAttributes attributes = new AudioAttributes.Builder().setUsage(usage)
            .setContentType(contentType).build();
    setVolumeControlStream(attributes.getVolumeControlStream());
}

自 API 级别 28 开始可用。

请求 AAudio 在流运行时调用此函数。

请注意，使用此回调时，音频数据将作为参数传入或传出函数。因此，您不能在具有活动数据回调的同一流上调用 AAudioStream_write() 或 AAudioStream_read()。

在调用 AAudioStream_requestStart() 后，回调函数将开始被调用。在调用 AAudioStream_requestPause() 或 AAudioStream_requestStop() 后，它将停止被调用。

此回调函数将在 AAudio 拥有的实时线程上被调用。低延迟流的回调线程可能比普通流具有更高的优先级。有关更多信息，请参阅 AAudioStream_dataCallback。

请注意，AAudio 回调绝不会从多个线程同时调用。

从 API 级别 26 开始可用。

请求由 ID 标识的音频设备。

可以从 Java AudioManager 获取 ID。 AudioManager.getDevices() 返回 AudioDeviceInfo 数组，其中包含 getId() 方法。该 ID 可以传递给此函数。

您可能无法获得请求的设备。因此，如果这对您很重要，您应该在流打开后调用 AAudioStream_getDeviceId() 来验证实际 ID。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED，在这种情况下将使用主设备。

从 API 级别 26 开始可用。

请求流的方向。

如果您不调用此函数，默认值为 AAUDIO_DIRECTION_OUTPUT。

从 API 级别 26 开始可用。

请求 AAudio 在发生任何错误或流断开连接时调用此函数。

例如，如果耳机或 USB 设备拔出导致流设备不可用或“已断开连接”，则会调用此回调。其他可能的错误原因包括超时或意外的内部错误。

作为响应，此函数应发出信号或创建另一个线程来停止和关闭此流。然后，其他线程可以在其他设备上重新打开流。不要直接从此回调中停止或关闭流，或重新打开新流。

此回调不会因应用的操作而调用，例如停止或关闭流。

请注意，AAudio 回调绝不会从多个线程同时调用。

从 API 级别 26 开始可用。

请求采样数据格式，例如 AAUDIO_FORMAT_PCM_I16。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED。然后在流打开时选择最佳值。打开具有未指定值的流后，应用必须查询实际值，该值可能因设备而异。

如果指定了确切值，则打开的流将使用该值。如果无法使用指定值打开流，则打开将失败。

从 API 级别 26 开始可用。

设置请求的数据回调缓冲区大小（以帧为单位）。

请参阅 AAudioStream_dataCallback。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED。

为了获得可能的最低延迟，请勿调用此函数。然后 AAudio 将以最佳大小调用 dataProc 回调函数。该大小可能因回调而异。

仅当应用需要特定帧数进行处理时才使用此函数。例如，应用可能正在使用需要特定二的幂大小缓冲区的 FFT。

AAudio 可能需要添加额外的缓冲区，以便在内部缓冲区大小和请求的缓冲区大小之间进行调整。

如果您确实调用此函数，则请求的大小应小于缓冲区容量的一半，以允许双重缓冲。

从 API 级别 26 开始可用。

设置流的输入（捕获）预设。

AAudio 系统将使用此信息优化流的行为。例如，这可能会影响使用哪些麦克风以及如何处理录制的数据。

如果您不调用此函数，默认值为 AAUDIO_INPUT_PRESET_VOICE_RECOGNITION。这是因为在许多平台上，VOICE_RECOGNITION 是延迟最低的预设。

自 API 级别 28 开始可用。

指定此输出流的音频数据是否已为空间化进行处理。

如果流已进行空间化处理，将其设置为 true 将防止在会空间化音频数据的平台上出现双重处理等问题。

自 API 级别 32 开始可用。

声明创建流的包名。

这通常是

Context#getPackageName() 

如果您不调用此函数，默认值为调用 UID 中的随机包。绝大多数应用每个调用 UID 只有一个包。如果设置了无效的包名，输入流可能在启动时无法获得录音权限。

包名通常是您应用 build.gradle 文件中的 applicationId。

从 API 级别 31 开始可用。

设置请求的性能模式。

支持的模式有 AAUDIO_PERFORMANCE_MODE_NONE、AAUDIO_PERFORMANCE_MODE_POWER_SAVING * 和 AAUDIO_PERFORMANCE_MODE_LOW_LATENCY。

如果您不调用此函数，默认值为 AAUDIO_PERFORMANCE_MODE_NONE。

您可能无法获得请求的模式。您可以调用 AAudioStream_getPerformanceMode() 来查明流的最终模式。

从 API 级别 26 开始可用。

指示此输入流是否必须标记为隐私敏感。

当为 true 时，此输入流是隐私敏感的，不允许任何并发捕获。

默认情况下此选项关闭（false），除非输入预设为 AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION 或 AAUDIO_INPUT_PRESET_CAMCORDER。

明确设置时，始终优先于输入预设的默认值。

仅当流方向为 AAUDIO_DIRECTION_INPUT 时相关。

在 API 级别 30 中添加。

请求采样率（赫兹）。

如果您不调用此函数，默认值为 AAUDIO_UNSPECIFIED。然后在流打开时选择最佳值。打开具有未指定值的流后，应用必须查询实际值，该值可能因设备而异。

如果指定了确切值，则打开的流将使用该值。如果无法使用指定值打开流，则打开将失败。

从 API 级别 26 开始可用。

与 AAudioStreamBuilder_setChannelCount() 相同。

从 API 级别 26 开始可用。

已弃用。 使用 AAudioStreamBuilder_setChannelCount

设置请求的会话 ID。

会话 ID 可用于将流与效果处理器关联。效果使用 Android AudioEffect Java API 控制。

如果您不调用此函数，默认值为 AAUDIO_SESSION_ID_NONE。

如果设置为 AAUDIO_SESSION_ID_ALLOCATE，则在流打开时将分配会话 ID。

分配的会话 ID 可以通过调用 AAudioStream_getSessionId() 获得，然后在打开另一个流时与此函数一起使用。这允许在流之间共享效果。

来自 AAudio 的会话 ID 可以与 Android Java API 互通使用。因此，AAudio 流的会话 ID 可以传递给 Java，并使用 Java AudioEffect API 应用效果。

请注意，分配或设置会话 ID 可能导致流具有更高的延迟。

分配的会话 ID 始终为正值且非零。

自 API 级别 28 开始可用。

请求设备共享模式。

如果您不调用此函数，默认值为 AAUDIO_SHARING_MODE_SHARED。

请求的共享模式可能不可用。应用可以在流打开后查询实际模式。

从 API 级别 26 开始可用。

设置影响是否使用空间化的行为。

当支持并启用空间化效果时，AAudio 系统将使用此信息来选择流是否经过空间化效果处理。

自 API 级别 32 开始可用。

设置输出流的预期用例。

AAudio 系统将使用此信息优化流的行为。例如，这可能会影响流的音量和焦点处理方式。

如果您不调用此函数，默认值为 AAUDIO_USAGE_MEDIA。

如果您设置了 Usage，则需要将音量键与结果流关联起来。否则音量键可能无法正常工作。这在 Java 中通过以下代码块完成。

if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
    AudioAttributes attributes = new AudioAttributes.Builder().setUsage(usage)
            .setContentType(contentType).build();
    setVolumeControlStream(attributes.getVolumeControlStream());
}

自 API 级别 28 开始可用。

删除与 AAudioStreamBuilder_openStream() 创建的流相关的内部数据结构。

如果尚未调用 AAudioStream_release()，则将自动调用它。

从 API 级别 26 开始可用。

返回确定音频是否可由其他应用或系统捕获的策略。

自 API 级别 29 开始可用。

查询最大缓冲区容量（以帧为单位）。

从 API 级别 26 开始可用。

查询可以在不阻塞的情况下填充的最大帧数。

从 API 级别 26 开始可用。

一个流包含一个或多个数据通道。

一帧将包含每个通道的一个样本。

从 API 级别 26 开始可用。

返回流的通道掩码。

这将是使用 AAudioStreamBuilder_setChannelMask 设置的掩码，否则为 AAUDIO_UNSPECIFIED。

自 API 级别 32 开始可用。

返回流的内容类型。

自 API 级别 28 开始可用。

从 API 级别 26 开始可用。

从 API 级别 26 开始可用。

从 API 级别 26 开始可用。

查询应用为获得最佳性能应一次读取或写入的帧数。

如果应用写入不同数量的帧，这是可以接受的。但缓冲区大小可能需要更大，以避免下溢或溢出。

请注意，这可能与实际设备突发大小匹配或不匹配。对于某些端点，突发大小可以动态变化。但这往往是延迟较高的设备。

从 API 级别 26 开始可用。

查询将在 numFrames 参数中传递给 dataProc 回调的缓冲区大小。

如果应用需要在流启动之前知道 numFrames 的值，可以使用此调用。这通常不是必需的。

如果通过调用 AAudioStreamBuilder_setFramesPerDataCallback() 请求了特定大小，则此值将与该大小相同。

如果未调用 AAudioStreamBuilder_setFramesPerDataCallback()，则此函数将返回 AAudio 选择的大小，或 AAUDIO_UNSPECIFIED。

AAUDIO_UNSPECIFIED 表示此流的回调缓冲区大小可能因不同的 dataProc 回调而异。

从 API 级别 26 开始可用。

返回自流创建以来已读取的帧数。

对于输出流，此值由端点推进。对于输入流，此值由调用 read() 的应用或数据回调推进。

帧位置单调递增。

从 API 级别 26 开始可用。

返回自流创建以来已写入的帧数。

对于输出流，此值由调用 write() 的应用或数据回调推进。对于输入流，此值由端点推进。

帧位置单调递增。

从 API 级别 26 开始可用。

音频框架中可能存在通道转换。

流构建器中设置的通道数或通道掩码可能不是硬件中使用的实际通道数。

此函数返回硬件使用的通道数。

如果 AAudioStreamBuilder_openStream() 返回 AAUDIO_OK，结果应始终有效。

从 API 级别 34 开始可用。

音频框架中可能存在数据格式转换。

流构建器中设置的数据格式可能不是硬件中使用的实际格式。

此函数返回硬件使用的音频格式。

如果 AAudioStreamBuilder_openStream() 返回 AAUDIO_OK，此函数应始终返回 an aaudio_format_t。

AAudio 目前不支持 AUDIO_FORMAT_PCM_8_24_BIT，但硬件可能使用它。如果硬件使用 AUDIO_FORMAT_PCM_8_24_BIT，则返回 AAUDIO_FORMAT_PCM_I24_PACKED。

如果硬件使用的任何其他格式不受 AAudio 支持，则此函数将返回 AAUDIO_FORMAT_INVALID。

从 API 级别 34 开始可用。

音频框架中可能存在采样率转换。

流构建器中设置的采样率可能不是硬件中使用的实际采样率。

此函数以赫兹为单位返回硬件使用的采样率。

如果 AAudioStreamBuilder_openStream() 返回 AAUDIO_OK，结果应始终有效。

从 API 级别 34 开始可用。

返回流的输入预设。

自 API 级别 28 开始可用。

获取流使用的性能模式。

从 API 级别 26 开始可用。

从 API 级别 26 开始可用。

与 AAudioStream_getChannelCount() 相同。

从 API 级别 26 开始可用。

返回与此流关联的会话 ID。

会话 ID 可用于将流与效果处理器关联。效果使用 Android AudioEffect Java API 控制。

如果使用 AAudioStreamBuilder_setSessionId() 调用了 AAUDIO_SESSION_ID_ALLOCATE，则在流打开时应分配一个新的会话 ID。

如果使用先前分配的会话 ID 调用了 AAudioStreamBuilder_setSessionId()，则应返回该值。

如果未调用 AAudioStreamBuilder_setSessionId()，则此函数应返回 AAUDIO_SESSION_ID_NONE。

流的会话 ID 在流打开后不应更改。

自 API 级别 28 开始可用。

提供实际共享模式。

从 API 级别 26 开始可用。

返回流的空间化行为。

如果未明确设置，将返回默认的 AAUDIO_SPATIALIZATION_BEHAVIOR_AUTO 行为。

自 API 级别 32 开始可用。

查询客户端的当前状态，例如。

AAUDIO_STREAM_STATE_PAUSING

此函数将立即返回状态而不更新状态。如果您想根据服务器状态更新客户端状态，请调用 AAudioStream_waitForStateChange()，并将 currentState 设置为 AAUDIO_STREAM_STATE_UNKNOWN，超时时间为零。

从 API 级别 26 开始可用。

返回特定帧在扬声器或头戴式设备上播放或在麦克风上录制的时间。

这可用于将音频与视频或 MIDI 同步。也可用于将录制的流与播放流对齐。

framePosition 是音频数据流中的索引。播放或录制的第一帧位于 framePosition 0。

这些 framePosition 与您从 AAudioStream_getFramesRead() 或 AAudioStream_getFramesWritten() 获得的单位相同。“帧”是一组同时播放的音频样本值。例如，立体声流一帧中有两个样本，左声道和右声道。

仅当流处于 AAUDIO_STREAM_STATE_STARTED 状态时，时间戳才有效。如果流未启动，将返回 AAUDIO_ERROR_INVALID_STATE。请注意，由于 requestStart() 是异步的，时间戳直到调用 requestStart() 后短时间内才有效。因此，AAUDIO_ERROR_INVALID_STATE 不应被视为致命错误。稍后重试即可。

如果发生错误，则位置和时间将不会修改。

返回的位置和时间单调递增。

从 API 级别 26 开始可用。

返回流的用例。

自 API 级别 28 开始可用。

XRun 是 Underrun 或 Overrun。

播放期间，如果未及时写入流且系统缺少有效数据，将发生下溢。录音期间，如果未及时读取流且没有地方放置传入数据，将发生溢出，因此数据会被丢弃。

下溢或溢出可能导致可听见的“爆音”或“毛刺”。

请注意，某些输入设备可能不支持此函数。在这种情况下，始终返回 0。

从 API 级别 26 开始可用。

返回流的内容是否已空间化。

自 API 级别 32 开始可用。

返回此输入流是否标记为隐私敏感。

请参阅 AAudioStreamBuilder_setPrivacySensitive()。

在 API 级别 30 中添加。

从流中读取数据。

此调用将等待直到读取完成或超时。如果 timeoutNanos 为零，则此调用不会等待。

请注意，timeoutNanoseconds 是墙钟时间中的相对持续时间。如果线程处于睡眠状态，时间不会停止。因此它将使用 CLOCK_BOOTTIME 实现。

除非需要等待数据，否则此调用是“强非阻塞”的。

如果调用超时，则返回零或部分帧计数。

从 API 级别 26 开始可用。

释放与 AAudioStreamBuilder_openStream() 创建的流关联的音频资源。

在此函数调用后的某个时刻应调用 AAudioStream_close()。

调用此函数后，流将处于 AAUDIO_STREAM_STATE_CLOSING 状态

如果您想立即释放音频资源，但仍允许其他线程查询流，此函数很有用。如果您从 UI 线程监控流进度，通常会发生这种情况。

注意：此函数仅在 MMAP 流中完全实现，MMAP 流是一些设备支持的低延迟流。在其他“传统”流上，某些音频资源仍在使用，并且在此调用后某些回调可能仍在处理中。

自 API 级别 30 开始可用。

异步请求流刷新。

刷新将丢弃任何待处理的数据。此调用仅在流处于 OPEN、PAUSED、STOPPED 或 FLUSHED 状态时有效。在其他状态下调用此函数，或从 AAudio 回调函数中调用，将无效并返回错误。帧计数器不会因刷新而重置。它们可能会前进。调用此函数后，状态将处于 AAUDIO_STREAM_STATE_FLUSHING 或 AAUDIO_STREAM_STATE_FLUSHED 状态。

对于输入流，此函数将返回 AAUDIO_ERROR_UNIMPLEMENTED。

从 API 级别 26 开始可用。

异步请求流暂停。

暂停流将冻结数据流但不会清空任何缓冲区。使用 AAudioStream_requestStart() 在暂停后恢复播放。调用此函数后，状态将处于 AAUDIO_STREAM_STATE_PAUSING 或 AAUDIO_STREAM_STATE_PAUSED 状态。

对于输入流，此函数将返回 AAUDIO_ERROR_UNIMPLEMENTED。对于输入流，请使用 AAudioStream_requestStop()。

从 API 级别 26 开始可用。

异步请求开始播放流。

对于输出流，在开始前应向流写入数据以填充缓冲区。否则将发生下溢。调用此函数后，状态将处于 AAUDIO_STREAM_STATE_STARTING 或 AAUDIO_STREAM_STATE_STARTED 状态。

从 API 级别 26 开始可用。

异步请求流停止。

流将在当前所有缓冲数据播放完毕后停止。调用此函数后，状态将处于 AAUDIO_STREAM_STATE_STOPPING 或 AAUDIO_STREAM_STATE_STOPPED 状态。

从 API 级别 26 开始可用。

这可用于通过更改发生阻塞的阈值来调整缓冲区的延迟。

通过将其与 AAudioStream_getXRunCount() 结合使用，可以在运行时针对每个设备调整延迟。

此值不能高于 AAudioStream_getBufferCapacityInFrames()。

请注意，您可能无法获得请求的确切大小。您可以检查返回值或调用 AAudioStream_getBufferSizeInFrames() 来查看实际最终大小。

从 API 级别 26 开始可用。

等待直到当前状态不再与输入状态匹配。

这将更新当前客户端状态。

aaudio_result_t result = AAUDIO_OK;
aaudio_stream_state_t currentState = AAudioStream_getState(stream);
aaudio_stream_state_t inputState = currentState;
while (result == AAUDIO_OK && currentState != AAUDIO_STREAM_STATE_PAUSED) {
    result = AAudioStream_waitForStateChange(
                                  stream, inputState, ¤tState, MY_TIMEOUT_NANOS);
    inputState = currentState;
}

从 API 级别 26 开始可用。

将数据写入流。

此调用将等待直到写入完成或超时。如果 timeoutNanos 为零，则此调用不会等待。

请注意，timeoutNanoseconds 是墙钟时间中的相对持续时间。如果线程处于睡眠状态，时间不会停止。因此它将使用 CLOCK_BOOTTIME 实现。

除非需要等待缓冲区中的空间，否则此调用是“强非阻塞”的。

如果调用超时，则返回零或部分帧计数。

从 API 级别 26 开始可用。

文本是与 returnCode 对应的 ASCII 符号，或者是一条表示 returnCode 未识别的英文消息。

这旨在供开发者调试时使用。不用于向用户显示。

从 API 级别 26 开始可用。

文本是与流状态对应的 ASCII 符号，或者是一条表示该状态未识别的英文消息。

这旨在供开发者调试时使用。不用于向用户显示。

从 API 级别 26 开始可用。

创建一个可用于打开 Stream 的 StreamBuilder。

deviceId 最初未指定，表示将使用当前默认设备。

默认方向为 AAUDIO_DIRECTION_OUTPUT。默认共享模式为 AAUDIO_SHARING_MODE_SHARED。数据格式、samplesPerFrames 和 sampleRate 未指定，将在设备打开时由设备选择。

使用完构建器后，必须调用 AAudioStreamBuilder_delete()。

从 API 级别 26 开始可用。