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

# Overview of XMA2

> How XMA2 hardware audio decompression works on XBOX One, and how it compares to xWMA software decoding for XAudio2 game audio content.

On XBOX One, XMA2 audio decompression is implemented in hardware. However, xWMA isn't, and it requires software decoding. XMA2 and xWMA both use the same compression algorithms, but xWMA provides a broader range of encoding formats. Encode for XMA2, for performance and compression benefits, but note that some high-fidelity music might sound better if rendered through xWMA - this would require listening tests. Coding XMA2 through `XAudio2` should be the simplest approach, but XMA2 can be coded directly to the hardware by using the Audio Control Processor (ACP) commands.

<Note>Both xWMA and XMA2 have their origins in the codecs developed for Windows Media Audio (WMA) and both have been developed specifically for XBOX games. The subset of the available codecs and parameters used by XMA2 is smaller than the subset used by xWMA. While both xWMA and XMA2 were developed for XBOX, they're not interchangeable: the headers for each file format differ, and the formats are incompatible with PC versions of Windows. The codecs used for XMA2 and xWMA are slightly different, too, so each will have its own artifacts from the compression system that's used.</Note>

This topic covers the following:

* [XMA2 encoding](#ID4E3)
* [XMA2 AXI bus error](#ID4ENC)

<a id="ID4E3" />

## XMA2 encoding

Encode audio data to XMA2 by using the [XMA2 encoder tool](/build/console-features/audio/tools/xma2encodertool), supplied as part of the Microsoft Game Development Kit (GDK). XMA2 files are .wav files that have the [XMA2WAVEFORMATEX](/reference/audio/xma2defs/structs/xma2waveformatex) format header and an additional `seek` chunk within the `Seek` location table.

The XMA2 format is compatible with XBOX 360, and the `Seek` table is to be `ULONG` byte-swapped for XBOX One. If the input is a .wav file, the output can be used without alteration.

To byte-swap the `Seek` table, use the following lines of code.

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

Consider adding this code to your app first to test the functionality, and then perhaps write a separate tool to perform the swap so that no pre-processing is required of your app.

For XBOX One, all Direct Memory Access (DMA) input and output buffers that are used with flowgraphs, and all XMA content submitted to a source buffer, must be allocated by using the [ApuAlloc](/reference/audio/apu/functions/apualloc) method and freed by using the [ApuFree](/reference/audio/apu/functions/apufree) method. This is shown in the following code. Note the use of the `SHAPE_XMA_INPUT_BUFFER_ALIGNMENT` flag to help ensure that the blocks are aligned correctly.

```cpp theme={null}
      HRESULT ApuVirtualAllocate(void** virtualAddress,UINT32 sizeInBytes)
      {
        DWORD dwsize = sizeInBytes;
        DWORD change = 0;
        if(FixBlockAlign((DWORD*)&sizeInBytes,SHAPE_XMA_INPUT_BUFFER_SIZE_ALIGNMENT,&change)) // Returns TRUE if an alignment was needed; else, returns FALSE.
        {
          return E_INVALIDARG;
        }
        return ApuAlloc(virtualAddress,NULL,sizeInBytes,SHAPE_XMA_INPUT_BUFFER_ALIGNMENT);
      }

      void ApuVirtualFree(void* virtualAddress)
      {
        if(virtualAddress)
        {
          ApuFree(virtualAddress);
        }
      }

      BOOL FixBlockAlign(DWORD* pBYTES,DWORD BLOCKALIGN,DWORD* pChange)
      {
        if(pBYTES && (BLOCKALIGN > 1))
        {
          DWORD bytes = (*pBYTES);
          (*pBYTES) /=  BLOCKALIGN;
          (*pBYTES) *=  BLOCKALIGN;
          if(pChange)
          {
            (*pChange) = bytes&mdash;(*pBYTES);
            if((*pChange) > 0)
            {
              return TRUE;
            }
          }
        }
        return FALSE;
      }  
```

For details about using the structure's fields with an XMA2-encoded file, see the [XMA2WAVEFORMATEX](/reference/audio/xma2defs/structs/xma2waveformatex) structure.

<a id="ID4ENC" />

## XMA2 AXI bus error

A long-standing bug in the XMA hardware decoder (and in XBOX 360) requires that titles provide a workaround if they use `AcpHal` directly. `XAudio2` already provides the workaround. However, until the XMA2 encoder tool is updated, make note of the following information.

When decoding XMA bit streams and using only a single XMA input buffer, you can trigger an AXI bus error if the last 64 bytes of the XMA buffer contain encoded data. An XMA bit stream rarely contains encoded data within the last 64 bytes. Nevertheless, this must be handled to prevent the AXI bus error. Until the XMA2 encoder tool is updated to ensure that no encoded files contain encoded data in the last 64 bytes of the bit stream, you can avoid this issue by using one of the following methods.

* Always use both XMA input buffers, and never set the pointer of either input buffer to an invalid value.

* Set the pointer of the unused input buffer to equal the pointer of the other input buffer, even though you won't enable the other buffer. An example is as follows.

```cpp theme={null}
      context->ptrRead1 = context->ptrRead0  
```

* While generating content, use an offline tool to scan your XMA files. If any one of the last 64 bytes of the encoded XMA bit stream is a value other than 0xFF, re-encode the file.

Any of these methods prevent the XMA prefetcher from reading an invalid address.

<a id="ID4EFD" />

## Reference API documentation

* [APU (API contents)](/reference/audio/apu/apu_members)
  * Functions
    * [ApuAlloc](/reference/audio/apu/functions/apualloc)
    * [ApuFree](/reference/audio/apu/functions/apufree)
* [XMA2Defs (API contents)](/reference/audio/xma2defs/xma2defs_members)
  * Structures
    * [XMA2WAVEFORMATEX](/reference/audio/xma2defs/structs/xma2waveformatex)

## See also

[XMA2 encoder tool](/build/console-features/audio/tools/xma2encodertool)


## Related topics

- [XMA2WAVEFORMAT](/reference/audio/xma2defs/structs/xma2waveformat.md)
- [XMA2STREAMFORMAT](/reference/audio/xma2defs/structs/xma2streamformat.md)
- [XMA2WAVEFORMATEX](/reference/audio/xma2defs/structs/xma2waveformatex.md)
- [XMA2PACKET](/reference/audio/xma2defs/structs/xma2packet.md)
- [LocalizeXma2Format](/reference/audio/xma2defs/functions/localizexma2format.md)