> ## 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 定义解码或解码转换处理参数。 ## 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) 指定要发送到硬件进行处理的基本命令参数。相同的 XApuCommandId 将被设置到 [XApuResult::id](/reference/audio/xapu/structs/xapuresult) 中。 *pitchRampRate*\ Type: float 此值将在每次输出时相对于当前音高进行加或减。 该值为无符号,采样率转换器引擎将根据目标音高值自动决定是从当前音高加上还是减去它。 默认情况下,此值应设置为 *XAPU\_DEFAULT\_PITCH\_RAMP\_RATE*。 *targetPitch*\ Type: float 当前转换操作的目标音高。对于 [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype),此值将被忽略。 *firstFrameIndex*\ Type: uint32\_t 指定将复制到输出缓冲区的第一帧的索引。firstFrameIndex 与 frameCount 配合使用,指定复制到输出缓冲区的内容。我们的实现在使用 firstFrameIndex 时不包括残余数据。如果有 100 个残余帧,firstFrameIndex 设置为 50,frameCount 设置为 200,则会将 200 帧添加到整个残余中,从解码数据的第 50 帧开始。这意味着进入 HSRC 的缓冲区将包含来自残余的原始 100 帧,后跟从当前解码数据包的第 50 帧开始的 200 帧。 PCM 流中的音频帧是一组样本(该组每个通道包含一个样本),这些样本将在同一时刻(时钟节拍)播放或已被采集。因此,一个音频帧的大小为样本大小乘以流中的通道数。 例如,具有 32 位浮点样本的立体声(2 通道)流的帧大小为 8 字节。对于包时长为 20 毫秒的 Opus 流,该值应介于 0 到 960 之间。对于包时长为 10 毫秒的 Opus 流,该值应介于 0 到 480 之间。默认情况下,此值设置为零。对于预滚输入,此值应大于零。预滚输入将被处理,但不会产生输出数据。 *frameCount*\ Type: uint32\_t 当在 [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) 处理中输入数据为未压缩时,此参数是必需的,其约束如下: * 对于单声道和立体声输入的非交错 PCM 数据,最小值为 4,最大值为 960,并且该值必须是 4 的倍数。 * 对于立体声输入的交错 PCM 数据,最小值为 8,最大值为 960,并且该值必须是 8 的倍数。 * 对于 [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype),此值可用于截断输出帧数。 * 对于 [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype),此值可用于截断将传递到转换器的解码帧数。 如果使用此参数截断流的最后一个数据包或循环点,则对于包时长为 20 毫秒的 Opus 流可以使用 0 到 960 之间的任何值,或者对于包时长为 10 毫秒的 Opus 流可以使用 0 到 480 之间的任何值。 如果需要使用此参数在流中间截断数据包的输出,则应根据上述 [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) 约束设置该值。 如果不需要截断,则应将此参数设置为 0xFFFFFFFF。 对于 [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype) 和 [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype) 场景,应使用 [XApuDecodeConvertCommand::frameCount](/reference/audio/xapu/structs/xapudecodeconvertcommand) 和 [XApuDecodeConvertCommand::firstFrameIndex](/reference/audio/xapu/structs/xapudecodeconvertcommand) 参数进行帧精确的查找。 PCM 流中的音频帧是一组样本(该组每个通道包含一个样本),这些样本将在同一时刻(时钟节拍)播放或已被采集。因此,一个音频帧的大小为样本大小乘以流中的通道数。例如,具有 32 位浮点样本的立体声(2 通道)流的帧大小为 8 字节。 *inputDataLength*\ Type: uint32\_t 输入数据长度(以字节为单位)。长度必须是 16 的倍数。对于 [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) 场景,此值必须等于 [XApuDecodeConvertCommand::frameCount](/reference/audio/xapu/structs/xapudecodeconvertcommand) x [XApuDecodeConvertActivateCommand::channelCount](/reference/audio/xapu/structs/xapudecodeconvertcommand) x sizeof(float)。 *inputData*\ Type: void\* 指向要处理的输入数据的指针。此值应大于或等于 [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) 并且小于 [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) + [XApuConnectInputParameters::dataLength](/reference/audio/xapu/structs/xapuconnectinputparameters)(由 [XApuConnect](/reference/audio/xapu/functions/xapuconnect) 返回)。*此缓冲区必须按 16 字节对齐。* 对于 [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype) 和 [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype),输入数据必须是单个 Opus 数据包(SILK、CELT 或 Hybrid)。 对于 [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype),输入数据必须是 PCM 浮点(32 位)。如果设置了 [XApuConnectOptions::DeinterleavedInput](/reference/audio/xapu/enums/xapuconnectoptions) 标志,则输入的 PCM 数据必须为非交错。 对于 [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype) 的非交错输入,第一个通道的数据从 [XApuDecodeConvertCommand::inputData](/reference/audio/xapu/structs/xapudecodeconvertcommand) 开始, 第二个通道的数据从 [XApuDecodeConvertCommand::inputData](/reference/audio/xapu/structs/xapudecodeconvertcommand) + ([XApuDecodeConvertCommand::inputDataLength](/reference/audio/xapu/structs/xapudecodeconvertcommand) / 2) 开始。 *maxOutputDataLength*\ Type: uint32\_t 最大输出数据的长度(以字节为单位)。长度必须是 16 的倍数。不应超过 [XApuConnectInputParameters::baseDataLength](/reference/audio/xapu/structs/xapuconnectinputparameters)。 *outputData*\ Type: void\* 用于存放输出 PCM 浮点(32 位)数据的指针。此值应大于或等于 [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) 并且小于 [XApuConnectOutputParameters::data](/reference/audio/xapu/structs/xapuconnectoutputparameters) + [XApuConnectInputParameters::baseDataLength](/reference/audio/xapu/structs/xapuconnectinputparameters)(由 [XApuConnect](/reference/audio/xapu/functions/xapuconnect) 返回)。此缓冲区必须按 16 字节对齐。 当设置了 [XapuConnectOptions::DeinterleavedOutput](/reference/audio/xapu/enums/xapuconnectoptions) 标志时,提供的数据将是非交错的。在每个数据包中,非交错的中点指定如下: [XApuProcessType::DecodeOpus](/reference/audio/xapu/enums/xapuprocesstype): * 左声道帧将放置在 0 到 (XapuResult::outputFrameCount-1) 处,右声道帧将放置在 (XapuResult::outputFrameCount) 到缓冲区末尾之间。 [XApuProcessType::DecodeConvertOpus](/reference/audio/xapu/enums/xapuprocesstype) 和 [XApuProcessType::ConvertPCM](/reference/audio/xapu/enums/xapuprocesstype): * 左声道帧将放置在 0 到 ([XApuConnectInputParameters::maxFrameCountPerOutput](/reference/audio/xapu/structs/xapuconnectinputparameters) - 1) 之间。 * 右声道帧将放置在 [XApuConnectInputParameters::maxFrameCountPerOutput](/reference/audio/xapu/structs/xapuconnectinputparameters) 到缓冲区末尾之间。 * 即使 OutputFrameCount 小于 maxFrameCountPerOutput,这也同样适用。在这种情况下,使用 [XApuConnectInputParameters::maxFrameCountPerOutput](/reference/audio/xapu/structs/xapuconnectinputparameters) 来确定缓冲区的中点,并使用 [XapuResult::outputFrameCount](/reference/audio/xapu/structs/xapuresult) 来计算要复制的每个通道的帧数。 ## Remarks `XApuDecodeConvertCommand` 使用它来解码和转换处理参数。有关 `XApuCommandId` 成员的信息,请参阅 [XApuCommandId](/reference/audio/xapu/structs/xapucommandid)。有关 `XApuPorcessType` 的详细信息,请参阅 [XApuProcessType](/reference/audio/xapu/enums/xapuprocesstype)。 音高斜率的范围为 2^-18 (0.000003814697265625) 到 8.0。任何小于最小值的值都会导致斜率不产生任何作用——音高将保持在当前值。当斜率大于当前值与目标值之差的绝对值时,斜率过程会在一个样本周期内完成。 ## Requirements **头文件:** xapu.h **支持的平台:** XBOX Series X|S ## Conceptual documentation * [XAPU 概述](/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 - [XApuConnect](/zh-CN/reference/audio/xapu/functions/xapuconnect.md) - [XApuCommandId](/zh-CN/reference/audio/xapu/structs/xapucommandid.md) - [XApuConnectInputParameters](/zh-CN/reference/audio/xapu/structs/xapuconnectinputparameters.md) - [XApuConnectOutputParameters](/zh-CN/reference/audio/xapu/structs/xapuconnectoutputparameters.md) - [XAPU 概述](/zh-CN/build/console-features/audio/overviews/xapu-overview.md)