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

# XApuDecodeConvertCommand

> XApuDecodeConvertCommand

# XApuDecodeConvertCommand

Defines decode or decode-convert processing parameters

## Syntax

```cpp theme={null}
typedef struct XApuDecodeConvertCommand {  
    XApuCommandId id;  
    float pitchRampRate;  
    float targetPitch;  
    uint32_t firstFrameIndex;  
    uint32_t frameCount;  
    uint32_t inputDataLength;  
    void* inputData;  
    uint32_t maxOutputDataLength;  
    void* outputData;  
} XApuDecodeConvertCommand  
```

### Members

*id*\
Type: [XApuCommandId](/reference/audio/xapu/structs/xapucommandid)

Specifies the base command parameters to be sent to the hardware for processing. The same XApuCommandId will be set to [XApuResult::id](/reference/audio/xapu/structs/xapuresult)

*pitchRampRate*\
Type: float

This is a value that will be added to or subtracted from the current pitch for each output.
This value is unsigned and the Sample Rate Converter engine will automatically decide whether to add or subtract it from the current pitch depending on the target pitch value.
By default, this value should be set to *XAPU\_DEFAULT\_PITCH\_RAMP\_RATE*.

*targetPitch*\
Type: float

The target pitch for the current conversion operation. For [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype), this value is ignored.

*firstFrameIndex*\
Type: uint32\_t

Specifies the index of the first frame that will be copied to the output buffer. firstFrameIndex coupled with the frameCount specify what gets copied to the output buffer. Our implementation does not include the residual data when using the firstFrameIndex. If there are 100 residual frames and firstFrameIndex is set to 50 and the frameCount is set to 200, 200 frames will be added to the entire residual starting from the 50th frame in the decoded data. This means the buffer into the HSRC will have the original 100 frames from residual followed by 200 frames starting from the 50th frame in the current decoded packet.

An audio frame in a PCM stream is a set of samples (the set contains one sample for each channel in the stream) that will play or was captured at the same time (clock tick). Thus, the size of an audio frame is the sample size multiplied by the number of channels in the stream.

For example, the frame size for a stereo (2-channel) stream with 32-bit float samples is eight bytes. This value should be between 0 and 960 for Opus streams with 20 millisecond packet duration. It should be between 0 to 480 for or Opus streams with 10 millisecond packet duration. By default, this value is set to zero. For preroll inputs, this value should be larger than zero. Preroll inputs will be processed but will not produce output data.

*frameCount*\
Type: uint32\_t

This parameter is required when the input data is uncompressed in [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) processing with the following constraints:

* For mono and stereo input deinterleaved PCM data, the minimum value is 4, maximum value is 960, and the value must be multiple of 4.
* For stereo input interleaved PCM data, the minimum value is 8, maximum value is 960, and the value must be multiple of 8.
* For [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype), this value can be used to truncate the output frame count.
* For [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype), this value can used to truncate the number of decoded frames that will be passed to the converter.

If this parameter is used to truncate the last packet in a stream or a loop point, then any value between 0 and 960 can be used for Opus streams with a 20 millisecond packet duration, or any value between 0 and 480 for Opus streams with 10 millisecond packet duration.

If there is a case where this parameter is required to truncate the output of a packet in the middle of the stream then the value should be set according to the [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) constraints above.

If no truncation is required, this parameter should be set to 0xFFFFFFFF.

For [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype) and [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype) cases [XApuDecodeConvertCommand::frameCount](/reference/audio/xapu/structs/xapudecodeconvertcommand) and [XApuDecodeConvertCommand::firstFrameIndex](/reference/audio/xapu/structs/xapudecodeconvertcommand) parameters should be used for frame accurate seeking.

An audio frame in a PCM stream is a set of samples (the set contains one sample for each channel in the stream) that will play or was captured at the same time (clock tick). Thus, the size of an audio frame is the sample size multiplied by the number of channels in the stream. For example, the frame size for a stereo (2-channel) stream with 32-bit float samples is eight bytes.

*inputDataLength*\
Type: uint32\_t

Input data length in bytes. Must be a multiple of 16 in length. For [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) case, this value must equal to [XApuDecodeConvertCommand::frameCount](/reference/audio/xapu/structs/xapudecodeconvertcommand) x [XApuDecodeConvertActivateCommand::channelCount](/reference/audio/xapu/structs/xapudecodeconvertcommand) x sizeof(float)

*inputData*\
Type: void\*

Pointer to input data for processing. This value should be equal to or greater than [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) and less than [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) + [XApuConnectInputParameters::dataLength](/reference/audio/xapu/structs/xapuconnectinputparameters) that was returned by [XApuConnect](/reference/audio/xapu/functions/xapuconnect). *This buffer must be 16-byte aligned.*

For [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype) and [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype), the input data must be a single Opus packet (SILK, CELT or Hybrid)

For [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype), the input data must be PCM float (32 bit). If the [XApuConnectOptions::DeinterleavedInput](/reference/audio/xapu/enums/xapuconnectoptions) flag is set, the input PCM data must be deinterleaved.

For [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) deinterleaved input, the first channel data starts at [XApuDecodeConvertCommand::inputData](/reference/audio/xapu/structs/xapudecodeconvertcommand)
and the second channel data starts at [XApuDecodeConvertCommand::inputData](/reference/audio/xapu/structs/xapudecodeconvertcommand) + ([XApuDecodeConvertCommand::inputDataLength](/reference/audio/xapu/structs/xapudecodeconvertcommand) / 2)

*maxOutputDataLength*\
Type: uint32\_t

Length of the maximum output data in bytes. Must be a multiple of 16 in length. Should not exceed [XApuConnectInputParameters::baseDataLength](/reference/audio/xapu/structs/xapuconnectinputparameters).

*outputData*\
Type: void\*

Pointer to hold the output PCM float (32 bit) data. This value should be equal to or greater than [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) and less than [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) + [XApuConnectInputParameters::baseDataLength](/reference/audio/xapu/structs/xapuconnectinputparameters) that was returned by [XApuConnect](/reference/audio/xapu/functions/xapuconnect). This buffer must be 16-byte aligned.

When the [XapuConnectOptions::DeinterleavedOutput](/reference/audio/xapu/enums/xapuconnectoptions) flag is set, the data will be provided deinterleaved. In each packet, the deinterleave midpoint
will be specified as follows:

[XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype):

* Left channel frames will be placed from 0 to (XapuResult::outputFrameCount-1), Right channel frames will be placed from (XapuResult::outputFrameCount)
  to the end of the buffer

[XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype) and [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype):

* Left channel frames will be placed from 0 to ([XApuConnectInputParameters::maxFrameCountPerOutput](/reference/audio/xapu/structs/xapuconnectinputparameters) - 1)
* Right channel frames will be placed from [XApuConnectInputParameters::maxFrameCountPerOutput](/reference/audio/xapu/structs/xapuconnectinputparameters) to the end of the buffer
* This is true even if OutputFrameCount is less than maxFrameCountPerOutput. In this case, use the [XApuConnectInputParameters::maxFrameCountPerOutput](/reference/audio/xapu/structs/xapuconnectinputparameters) to determine the midpoint of the buffer, and [XapuResult::outputFrameCount](/reference/audio/xapu/structs/xapuresult) to calculate the number of frames per-channel to copy.

## Remarks

Used by `XApuDecodeConvertCommand` to decode and convert processing parameters. For information about the `XApuCommandId` members, see [XApuCommandId](/reference/audio/xapu/structs/xapucommandid). For more information about the `XApuPorcessType`, see [XApuProcessType](/reference/audio/xapu/enums/xapuprocesstype).

The range of the pitch ramp rate is from 2^-18 (0.000003814697265625) to 8.0.  Anything less than the minimum value will result in ramping not doing anything - the pitch will sit at the current value.  Any time the ramp rate is greater than the absolute value of the difference between current and target, the ramp happens within one sample period.

## Requirements

**Header:** xapu.h

**Supported platforms:** XBOX Series X|S

## Conceptual documentation

* [XAPU overview](/build/console-features/audio/overviews/xapu-overview)

## See also

[XApuEnqueueCommand](/reference/audio/xapu/functions/xapuenqueuecommand)\
[XApuResult](/reference/audio/xapu/structs/xapuresult)\
[XAPU](/reference/audio/xapu/xapu_members)


## Related topics

- [XApuCommandId](/reference/audio/xapu/structs/xapucommandid.md)
- [XApuConnect](/reference/audio/xapu/functions/xapuconnect.md)
- [XApuConnectInputParameters](/reference/audio/xapu/structs/xapuconnectinputparameters.md)
- [XApuProcessType](/reference/audio/xapu/enums/xapuprocesstype.md)
- [XAPU](/reference/audio/xapu/xapu_members.md)