> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XAPU 概述

> XBOX 音频处理单元 (XAPU) API，用于在 XBOX Series X|S 上实现硬件加速的 Opus 解码和高质量采样率转换。

本主题概述了用于硬件加速 Opus 文件解码和高质量采样率转换的 [XAPU API](/reference/audio/xapu/xapu_members)。

## Opus 硬件解码版本特性

以往在 XBOX One 家族主机上，XMA 是唯一提供硬件卸载解码的方案。现在，在 XBOX Series X|S 世代主机上，我们通过 XAPU (XBOX Audio Processing Unit) API 引入了 Opus 硬件卸载解码。
Opus 是一种免版权的音频压缩编解码器，旨在将语音和通用音频高效地编码到单一格式。Opus 具有低延迟。内部评测显示，Opus 在音质和文件大小压缩比方面均超越 XMA。

此外，还新增了高质量采样率转换器 (HSRC)，可配合硬件解码功能 (Opus) 工作。当将 Opus 硬件卸载解码与 HSRC 功能结合以进行音高变换时，开发者会发现输出质量优于上一代的 SHAPE 方案（在 XBOX Series X|S 主机上仍为向后兼容而保留）。

### 本版本新增

* June FAL QFE3 新增：在 Quick Resume 场景下，恢复后不再要求游戏重新建立与硬件的连接。
* June FAL QFE4 新增：CELT 现在支持 2.5 ms 和 5 ms 长度的 Opus 数据包。
* August 2020 Preview Recovery 版本 10.0.19041.4124 (rs\_xbox\_release\_2008-19041.4124.200814-0000) / 10.0.19041.3562 (rs\_xbox\_release\_sirius-19041.3562.200814-2300) 或更高版本：[XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand) 实现的破坏性变更：使用 firstFrameIndex 时，残余数据 (residual data) 现在不再被包含（此前是包含的）。更多细节请参见"最佳实践"一节或 API 参考页 [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand)。
* 如果 HSRC 输出处理缓冲区中还有数据，此前一旦使用 flush 命令就会造成数据丢失（可能丢失部分已转换的音频数据，输出也不符合预期）。
* 如果提交了不受支持的 Opus 数据包，现在会抛出错误，而不是导致挂起（例如仅支持 10 ms 或 20 ms 时提交了 2.5 ms 的 Opus 数据包）。
* FIFO 默认开启。
* 整体性能改进和稳定性修复。

## Opus 硬件解码版本规格

下表列出了可用的命令和特性：

| -                  | CELT    | -     | -  | -    | SILK    | -     | -  | -    | Hybrid  | -     | -  | -    | PCM     | -     | -  | -    |
| ------------------ | ------- | ----- | -- | ---- | ------- | ----- | -- | ---- | ------- | ----- | -- | ---- | ------- | ----- | -- | ---- |
| 命令                 | 是否支持该模式 | 定位与循环 | 重置 | HSRC | 是否支持该模式 | 定位与循环 | 重置 | HSRC | 是否支持该模式 | 定位与循环 | 重置 | HSRC | 是否支持该模式 | 定位与循环 | 重置 | HSRC |
| DECODE             | 是       | 是     | 是  | 是    | 是       | 是     | 是  | 是    | 是       | 是     | 是  | 是    |         |       |    |      |
| DECODE and CONVERT | 是       | 是     | 是  | 是    | 是       | 是     | 是  | 是    | 是       | 是     | 是  | 是    |         |       |    |      |
| CONVERT ONLY       |         |       |    |      |         |       |    |      |         |       |    |      | 是       | 是     | 是  | 是    |

### 关于 HSRC 使用的重要说明

高质量采样率转换器 (HSRC) 具有依赖于频率的群延迟，对于低于 10 kHz 的频率大约为 *5 帧*。

启用采样率转换器时，预期输出延迟为 *5 帧*，调用方可以相应调整。如果你使用的是音频中间件方案，这一延迟对你的游戏来说可能已经被处理。

### 最佳实践

* 关于 [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand) 的实现：传入的 firstFrameIndex 指定将被复制到 PCM 输出缓冲区的第一个帧。firstFrameIndex 与 frameCount 一起决定被复制到输出缓冲区的内容。我们的实现在使用 firstFrameIndex 时不包含残余数据。如果残余数据有 100 帧，firstFrameIndex 设置为 50，frameCount 设置为 200，则会在完整的残余数据之后再从解码数据的第 50 帧开始添加 200 帧。这意味着进入 HSRC 的缓冲区将由原始的 100 帧残余数据加上当前解码数据包中从第 50 帧开始的 200 帧组成。
* 建议谨慎创建 XAPU 客户端。最好在前期（音频引擎资源激活时）就创建好 XAPU 客户端，并在整个游戏生命周期内持续使用。[XApuConnect](/reference/audio/xapu/functions/xapuconnect) 和 [XAapuDisconnect](/reference/audio/xapu/functions/xapudisconnect) 调用计算开销较大。如果频繁创建和销毁具有不同内存需求的客户端，你可能会面临资源耗尽的风险。
* 对于循环场景，是否使用 [XApuCommandType::Reset](/reference/audio/xapu/enums/xapucommandtype) 由调用方自行决定，因为它可能在输出中造成瞬态效应。但一旦使用了 [XApuCommandType::Reset](/reference/audio/xapu/enums/xapucommandtype)，必须提交预滚 (pre-roll) 数据包以避免瞬态效应。
* 为获得最佳性能，请使用以 20 ms 数据包大小编码的 Opus 流。
* 从性能角度看，使用较少的客户端和较多的流可能优于较多的客户端和较少的流。例如，5 个客户端每个 20 条流，总计 100 条流，比 50 个客户端每个 2 条流性能更好。两者都能解码 100 条流，但前者性能更佳。
* 支持 OPUS\_SET\_PREDICTION\_DISABLED，可禁用数据包间预测。使用该标志编码会降低压缩性能，从而降低解码输出的质量。
* 当硬件设备处于异常状态时，XAPU 会返回 [XAPU\_E\_DEVICE\_FATAL](/reference/audio/xapu/enums/xapuerrors) 错误。此时应先断开所有 XAPU 客户端，再创建任何新客户端以从该错误中恢复。
* 命令完成的信号机制基于 3 ms 的定时器，且对每个 XAPU 客户端只发出一次信号，涵盖迄今为止已完成的所有命令，无论有多少命令使用了 [XApuCommandOptions::SignalOnCompletion](/reference/audio/xapu/enums/xapucommandoptions) 标志。
* 如果游戏无法容忍 3 ms 的信号机制，可以在循环中查找响应，或使用 Sleep(0) 并检查响应。
* 在断开客户端之前等待所有响应非常重要。如果仍有未领取的请求，[XApuDisconnect](/reference/audio/xapu/functions/xapudisconnect) 现在会返回 [XAPU\_E\_PENDING\_RESULTS](/reference/audio/xapu/enums/xapuerrors) 错误。该错误无法直接处理，仅供开发期使用。XApuDisconnect 会释放为该客户端分配的所有资源，如果在硬件仍在为该客户端处理命令时调用它，硬件可能向已被释放的内存写入，从而导致内存损坏。
* 传给硬件的所有内存指针（例如 inputData、outputData 和 processingBuffer）都应按 16 字节对齐。
* 使用 ConvertOnly 或 DecodeConvert 模式时，更大的输出帧数会带来更好的性能。decode convert 与 convert 支持的最大输出帧数为 1024。
* 仅支持可变比特率 (VBR) 编码。不支持恒定比特率 (CBR) 编码，因为 CBR 会加入过渡包 (transition packets)，其效率和质量都不如 VBR 编码中的冗余包 (redundancy packets)。因此，这种数据包类型（也就是 CBR）不受支持。
* 对于 HYBRID 和 SILK：仅支持单声道或立体声 Opus 流，数据包为 10 或 20 ms，采样率为 48000 Hz。
* 对于 CELT：仅支持单声道或立体声 Opus 流，数据包为 2.5、5、10 或 20 ms，采样率为 48000 Hz。

### 游戏的暂停与恢复

游戏必须能够暂停和恢复，例如当用户将其切换到 Constrained 模式时。挂起处理器被调用时，只需停止向硬件提交 XAPU 命令即可。已经提交的命令会正常完成，并放入其对应的响应队列中。

### 示例（源代码位于外部 .zip 文件中，可发送邮件至 [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) 索取）

* Decode One Opus Stream。（本示例概述见 [此处](/build/console-features/audio/overviews/xapu-overview-single-stream-audio-decode)。）
* Decode Multi-Opus Streams。
* Play One Opus Stream。（线程模型与 "Decode One Opus Stream" 不同。）
* Play Multi-Opus Streams。
* Decode Convert One Opus Stream，附带循环和采样级精确定位选项。
* Decode Convert Multi-Opus Streams。
* Play Decode Convert One Opus Stream。
* SimpleXAPU（在带 UI 的 GDK 游戏中进行 Opus 流解码的示例。）

### 联系

如果你对该功能有任何问题或疑问，请发送邮件至 [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) 或使用在线论坛。

## 参考 API 文档

* [Xapu (API 内容)](/reference/audio/xapu/xapu_members)
  * Functions
    * [XApuConnect](/reference/audio/xapu/functions/xapuconnect)
    * [XAapuDisconnect](/reference/audio/xapu/functions/xapudisconnect)
  * Structures
    * [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand)


## Related topics

- [XBOX Series X|S 音频硬件概述](/zh-CN/build/console-features/audio/overviews/scarlett-audio.md)
- [XApuConnect](/zh-CN/reference/audio/xapu/functions/xapuconnect.md)
- [XApuDisconnect](/zh-CN/reference/audio/xapu/functions/xapudisconnect.md)
- [XApuDecodeConvertCommand](/zh-CN/reference/audio/xapu/structs/xapudecodeconvertcommand.md)
- [概述](/zh-CN/build/console-features/audio/overviews/index.md)