> ## 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` | 指定要轉換之檔案的檔案名稱。您可以指定多個檔案/喇叭位置配對:`XMA2ENCODE pcmfile [/Speaker pos ...] [pcmfile [/Speaker pos ...] ...] [options]`。編碼多個檔案時,XMA2Encode 要求輸入檔案全部為單聲道,或全部為立體聲且最後一個串流為單聲道或立體聲,視要編碼的聲道數而定。<br /><br />**注意:** XMA2Encode 只支援 PCM 格式或 XMA2 格式 (搭配 `/DecodeToPCM`) 的音訊檔案。 |
| `/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` 互斥。如果 `LoopWholeFile` 和 `UseLoopPoints` 引數都未指定,檔案就不會迴圈播放,即使有迴圈點也一樣。 |
| `/UseLoopPoints` | 如果有現有的迴圈點則使用;否則不會迴圈播放。`LoopWholeFile` 和 `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](/zh-TW/build/console-features/audio/tools/xma2encoder/methods/xaudio2xmaencoder-xmaencoder-xbox-microsoft-m)。

請勿使用標頭中定義的 `XMA2InMemoryEncoder` 和 `XMAInMemoryEncoder` 方法 (舊版)。

<a id="ID4EDFAC" />

## 本節內容

[XMA2 編碼器參考](/zh-TW/build/console-features/audio/tools/xma2encoder/atoc-xmaencoder)
描述 *xmaencoder.lib* 中可用的函式。

<a id="ID4EJFAC" />

## 另請參閱

[XMA2 概觀](/zh-TW/build/console-features/audio/overviews/xma2-overview)


## Related topics

- [XMA2 编码器工具](/zh-CN/build/console-features/audio/tools/xma2encodertool.md)
- [工具](/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)