> ## Documentation Index
> Fetch the complete documentation index at: https://docs.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)

## 使用 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 要求所有输入文件要么全是单声道，要么全是立体声，其中最后一个流可以是单声道或立体声，具体取决于所编码的声道数。 **注意：** 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` = 右后。 **注意：** 如果输入文件没有声道掩码，或声道掩码中设置的位数与文件的声道数不匹配，且未通过 `Speaker` 选项指定任何扬声器分配，则生成的 XMA 文件的声道掩码为 0。 |
| `/MeasureTime` | 显示编码所用时间。 |
| `/Verbose` | 启用详细输出。 |
| `/Help` | 显示此用法信息。 |

### 备注

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

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

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

## 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]);
    }  
```

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

## 编写自己的 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](https://docs.xbox.com/zh-CN/build/console-features/audio/tools/xma2encoder/methods/xaudio2xmaencoder-xmaencoder-xbox-microsoft-m.md)。

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

## 本节内容

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

## 另请参阅

[XMA2 概述](https://docs.xbox.com/zh-CN/build/console-features/audio/overviews/xma2-overview.md)


## Related topics

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