Overview of XMA2

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.

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.

This topic covers the following:

XMA2 encoding
XMA2 AXI bus error

XMA2 encoding

Encode audio data to XMA2 by using the XMA2 encoder tool, supplied as part of the Microsoft Game Development Kit (GDK). XMA2 files are .wav files that have the 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.

      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 method and freed by using the 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.

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

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.

      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.

Reference API documentation

APU (API contents)
- Functions
  - ApuAlloc
  - ApuFree
XMA2Defs (API contents)
- Structures
  - XMA2WAVEFORMATEX

GDK and Game Engines Integration

Steam porting guide

Game Principles

Core Features

Console Features

XMA2 encoding

XMA2 AXI bus error

Reference API documentation

See also

​XMA2 encoding

​XMA2 AXI bus error

​Reference API documentation

​See also

XMA2 encoding

XMA2 AXI bus error

Reference API documentation

See also