> ## 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.

# XMA2 编码器工具

> XMA2 编码器工具

XMA2 命令行编码器工具 (XMA2Encode) 可将一组脉冲编码调制 (PCM) 文件转换为 XMA2 格式，也可将 XMA2 文件转换回 PCM 格式。

该工具可用于 XBOX 360 和 XBOX One。对于 XBOX 360，可直接使用该工具的输出；对于 XBOX One，`seek` 表可能需要进行字节交换。相关代码见本主题 [XBOX One 格式](#ID4E2DAC) 部分。

* [使用 XMA2Encode](#ID4E1)
* [XBOX One 格式](#ID4E2DAC)
* [编写自己的 XMA 编码器工具](#ID4EPEAC)

<a id="ID4E1" />

## 使用 XMA2Encode

下面的代码和表格说明了如何使用 XMA2Encode。

| 列 1                                                                                                                                                                                                                    |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `XMA2Encode file [/TargetFile xmafile][/PCMOutputFile pcmfile][/DecodeToPCM pcmfile][/BlockSize][/Quality value][/FilterHighFrequencies][/LoopWholeFile][/UseLoopPoints][/Speaker pos][/MeasureTime][/Verbose][/Help]` |

| 选项                       | 说明                                                                                                                                                                                                                                                                          |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`                   | 指定要转换的文件名。可以指定多组 file/speaker 位置对：`XMA2ENCODE pcmfile [/Speaker pos ...] [pcmfile [/Speaker pos ...] ...] [options]`。编码多个文件时，XMA2Encode 要求所有输入文件要么全是单声道，要么全是立体声，其中最后一个流可以是单声道或立体声，具体取决于所编码的声道数。<br /><br />**注意：** XMA2Encode 仅支持 PCM 格式的音频文件，或使用 `/DecodeToPCM` 的 XMA2 格式。 |
| `/TargetFile xmafile`    | 编码到 `xmafile`（仅允许一个目标文件）。                                                                                                                                                                                                                                                   |
| `/PCMOutputFile pcmfile` | 将生成的 XMA2 文件解码回 `pcmfile`。使用此选项时，工具会生成两份输出：一份 XMA2 编码的音频文件，以及一份 PCM 文件——后者是刚创建的 XMA2 文件解码后的结果。生成的 PCM 文件与新的 XMA2 文件音质一致，可用于在 Windows 上预览 XMA2 文件的质量。                                                                                                                        |
| `/DecodeToPCM pcmfile`   | 将已有的 XMA2 文件解码为 `pcmfile`。                                                                                                                                                                                                                                                  |
| `/BlockSize`             | 指定要使用的 XMA2 压缩块大小（2 KB 到 8,190 KB）。默认块大小为 64 KB。                                                                                                                                                                                                                            |
| `/Quality value`         | 指定要使用的 XMA2 压缩质量级别（1 到 100）。默认质量值为 60。                                                                                                                                                                                                                                      |
| `/FilterHighFrequencies` | 过滤掉源文件中的高频。                                                                                                                                                                                                                                                                 |
| `/LoopWholeFile`         | 循环整个文件，即使已有循环点也一样。`LoopWholeFile` 与 `UseLoopPoints` 互斥。如果两者都未指定，即使文件存在循环点也不会循环。                                                                                                                                                                                             |
| `/UseLoopPoints`         | 若存在循环点，则使用现有循环点；否则不进行循环。`LoopWholeFile` 与 `UseLoopPoints` 互斥。如果两者都未指定，即使文件存在循环点也不会循环。                                                                                                                                                                                       |
| `/Speaker pos`           | 为源文件的某个声道指定扬声器分配。该选项必须紧跟文件名。`pos` 可为 `L`、`R`、`C`、`LFE`、`LS`、`RS`、`LB` 或 `RB`，其中 `L` = 前左，`R` = 前右，`C` = 前中，`LFE` = 低频，`LS` = 左环绕，`RS` = 右环绕，`LB` = 左后，`RB` = 右后。<br /><br />**注意：** 如果输入文件没有声道掩码，或声道掩码中设置的位数与文件的声道数不匹配，且未通过 `Speaker` 选项指定任何扬声器分配，则生成的 XMA 文件的声道掩码为 0。      |
| `/MeasureTime`           | 显示编码所用时间。                                                                                                                                                                                                                                                                   |
| `/Verbose`               | 启用详细输出。                                                                                                                                                                                                                                                                     |
| `/Help`                  | 显示此用法信息。                                                                                                                                                                                                                                                                    |

<a id="remarks" />

### 备注

所有选项都可以缩写为首字母。

下表列出了 XMA2Encode 在遇到编码问题时可能输出的错误码。

| 错误码        | 说明            |
| ---------- | ------------- |
| 0x88890001 | 指定的循环点无效。     |
| 0x88890002 | 指定的格式无效。      |
| 0x88890003 | 参数超出范围。       |
| 0x88890004 | 读操作失败。        |
| 0x88890005 | 存在无效的 XMA 帧。  |
| 0x88890006 | 存在不完整的 XMA 帧。 |
| 0x88890007 | 填充位为零。        |
| 0x88890008 | 数据获取失败。       |

<a id="ID4E2DAC" />

## XBOX One 格式

XMA2Encode 的输出对于 XBOX One 必须按 `ULONG` 进行字节交换。如果输入是 .wav 文件，输出可以直接使用无需修改。

要对 `seek` 表进行字节交换，请使用以下代码。

```cpp theme={null}
for(UINT32 i = 0;(i < xmaformat->BlockCount);i++)
    {
       rgpXMASeekTable[i] = _byteswap_ulong(rgpXMASeekTable[i]);
    }  
```

可以先把这几行代码加到你的应用中以验证功能，然后再考虑写一个单独的工具来完成交换，让你的应用不必进行预处理。

<a id="ID4EPEAC" />

## 编写自己的 XMA 编码器工具

你可以使用 *xmaencoder.h* 中定义、由 *xmaencoder.lib* 实现的方法来编写自己的编码器工具。*xmaencoder.h* 默认位于 *C:\Program Files (x86)\Microsoft GDK\191100\GXDK\toolKit\include* 文件夹，*xmaencoder.lib* 默认位于 *C:\Program Files (x86)\Microsoft GDK\191100\GXDK\toolKit\lib\amd64* 文件夹。

头文件与库中提供的唯一方法是 [XAudio2XMAEncoder](/build/console-features/audio/tools/xma2encoder/methods/xaudio2xmaencoder-xmaencoder-xbox-microsoft-m)。

请勿使用头文件中定义的 `XMA2InMemoryEncoder` 和 `XMAInMemoryEncoder` 方法（属于遗留 API）。

<a id="ID4EDFAC" />

## 本节内容

[XMA2 编码器参考](/build/console-features/audio/tools/xma2encoder/atoc-xmaencoder)
介绍 *xmaencoder.lib* 中提供的函数。

<a id="ID4EJFAC" />

## 另请参阅

[XMA2 概述](/build/console-features/audio/overviews/xma2-overview)


## Related topics

- [工具](/zh-CN/build/console-features/audio/tools/index.md)
- [XMA2 概述](/zh-CN/build/console-features/audio/overviews/xma2-overview.md)
- [XAudio2XMAEncoder](/zh-CN/build/console-features/audio/tools/xma2encoder/methods/xaudio2xmaencoder-xmaencoder-xbox-microsoft-m.md)
- [XMA2 编码器库与命令行工具](/zh-CN/build/console-features/audio/tools/xma2encoder/index.md)
- [XMA2 编码器参考信息](/zh-CN/build/console-features/audio/tools/xma2encoder/atoc-xmaencoder.md)