> ## 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 定義解碼或解碼轉換的處理參數 ## 語法 ```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 ``` ### 成員 *id*\ 類型：[XApuCommandId](/zh-TW/reference/audio/xapu/structs/xapucommandid) 指定要傳送至硬體進行處理的基本命令參數。相同的 XApuCommandId 會設定至 [XApuResult::id](/zh-TW/reference/audio/xapu/structs/xapuresult) *pitchRampRate*\ 類型：float 此值會在每次輸出時加到目前音高或從目前音高中減去。 此值不帶正負號，取樣率轉換器引擎會根據目標音高值，自動決定要將其加到目前音高或從目前音高中減去。 根據預設，此值應設定為 *XAPU\_DEFAULT\_PITCH\_RAMP\_RATE*。 *targetPitch*\ 類型：float 目前轉換作業的目標音高。對於 [XApuProcessType::DecodeOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)，會忽略此值。 *firstFrameIndex*\ 類型：uint32\_t 指定將複製到輸出緩衝區的第一個框架索引。firstFrameIndex 搭配 frameCount 指定要複製到輸出緩衝區的內容。我們的實作在使用 firstFrameIndex 時不包含殘留資料。如果有 100 個殘留框架，且 firstFrameIndex 設定為 50、frameCount 設定為 200，則會從解碼資料的第 50 個框架開始，將 200 個框架加到整個殘留資料中。這表示進入 HSRC 的緩衝區會先有殘留資料中原本的 100 個框架，接著是從目前已解碼封包第 50 個框架開始的 200 個框架。 PCM 串流中的音訊框架是一組樣本 (該組針對串流中的每個通道各包含一個樣本)，這些樣本會在同一時間 (時脈刻度) 播放或擷取。因此，音訊框架的大小等於樣本大小乘以串流中的通道數目。 例如，具有 32 位元 float 樣本的立體聲 (2 通道) 串流，其框架大小為八個位元組。對於封包持續時間為 20 毫秒的 Opus 串流，此值應介於 0 到 960 之間。對於封包持續時間為 10 毫秒的 Opus 串流，此值應介於 0 到 480 之間。根據預設，此值設定為零。對於預捲輸入，此值應大於零。預捲輸入會經過處理，但不會產生輸出資料。 *frameCount*\ 類型：uint32\_t 在 [XApuProcessType::ConvertPCM](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 處理中輸入資料為未壓縮時，此參數為必要項目，並具有下列限制： * 對於單聲道和立體聲輸入的非交錯 PCM 資料，最小值為 4，最大值為 960，且值必須是 4 的倍數。 * 對於立體聲輸入的交錯 PCM 資料，最小值為 8，最大值為 960，且值必須是 8 的倍數。 * 對於 [XApuProcessType::DecodeOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)，此值可用來截斷輸出框架數目。 * 對於 [XApuProcessType::DecodeConvertOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)，此值可用來截斷將傳遞給轉換器的已解碼框架數目。 如果此參數用來截斷串流中的最後一個封包或迴圈點，則對於封包持續時間為 20 毫秒的 Opus 串流，可以使用 0 到 960 之間的任何值；對於封包持續時間為 10 毫秒的 Opus 串流，可以使用 0 到 480 之間的任何值。 如果需要使用此參數截斷串流中間某個封包的輸出，則應依照上述 [XApuProcessType::ConvertPCM](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 的限制來設定此值。 如果不需要截斷，此參數應設定為 0xFFFFFFFF。 在 [XApuProcessType::DecodeOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 和 [XApuProcessType::DecodeConvertOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 的情況下，應使用 [XApuDecodeConvertCommand::frameCount](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) 和 [XApuDecodeConvertCommand::firstFrameIndex](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) 參數進行框架精確的搜尋。 PCM 串流中的音訊框架是一組樣本 (該組針對串流中的每個通道各包含一個樣本)，這些樣本會在同一時間 (時脈刻度) 播放或擷取。因此，音訊框架的大小等於樣本大小乘以串流中的通道數目。例如，具有 32 位元 float 樣本的立體聲 (2 通道) 串流，其框架大小為八個位元組。 *inputDataLength*\ 類型：uint32\_t 輸入資料長度 (以位元組為單位)。長度必須是 16 的倍數。在 [XApuProcessType::ConvertPCM](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 的情況下，此值必須等於 [XApuDecodeConvertCommand::frameCount](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) x [XApuDecodeConvertActivateCommand::channelCount](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) x sizeof(float) *inputData*\ 類型：void\* 指向要處理之輸入資料的指標。此值應大於或等於 [XApuConnectOutputParameters::data](/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters)，且小於 [XApuConnect](/zh-TW/reference/audio/xapu/functions/xapuconnect) 所傳回的 [XApuConnectOutputParameters::data](/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters) + [XApuConnectInputParameters::dataLength](/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters)。*此緩衝區必須為 16 位元組對齊。* 對於 [XApuProcessType::DecodeOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 和 [XApuProcessType::DecodeConvertOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)，輸入資料必須是單一 Opus 封包 (SILK、CELT 或 Hybrid) 對於 [XApuProcessType::ConvertPCM](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)，輸入資料必須是 PCM float (32 位元)。如果已設定 [XApuConnectOptions::DeinterleavedInput](/zh-TW/reference/audio/xapu/enums/xapuconnectoptions) 旗標，輸入 PCM 資料必須為非交錯格式。 對於 [XApuProcessType::ConvertPCM](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 非交錯輸入，第一個通道的資料從 [XApuDecodeConvertCommand::inputData](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) 開始， 第二個通道的資料從 [XApuDecodeConvertCommand::inputData](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) + ([XApuDecodeConvertCommand::inputDataLength](/zh-TW/reference/audio/xapu/structs/xapudecodeconvertcommand) / 2) 開始 *maxOutputDataLength*\ 類型：uint32\_t 輸出資料的長度上限 (以位元組為單位)。長度必須是 16 的倍數。不應超過 [XApuConnectInputParameters::baseDataLength](/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters)。 *outputData*\ 類型：void\* 用來保存輸出 PCM float (32 位元) 資料的指標。此值應大於或等於 [XApuConnectOutputParameters::data](/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters)，且小於 [XApuConnect](/zh-TW/reference/audio/xapu/functions/xapuconnect) 所傳回的 [XApuConnectOutputParameters::data](/zh-TW/reference/audio/xapu/structs/xapuconnectoutputparameters) + [XApuConnectInputParameters::baseDataLength](/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters)。此緩衝區必須為 16 位元組對齊。 設定 [XapuConnectOptions::DeinterleavedOutput](/zh-TW/reference/audio/xapu/enums/xapuconnectoptions) 旗標時，資料會以非交錯格式提供。在每個封包中，非交錯的中點 會依下列方式指定： [XApuProcessType::DecodeOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)： * 左聲道框架會放在 0 到 (XapuResult::outputFrameCount-1)，右聲道框架會放在 (XapuResult::outputFrameCount) 到緩衝區結尾 [XApuProcessType::DecodeConvertOpus](/zh-TW/reference/audio/xapu/enums/xapuprocesstype) 和 [XApuProcessType::ConvertPCM](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)： * 左聲道框架會放在 0 到 ([XApuConnectInputParameters::maxFrameCountPerOutput](/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters) - 1) * 右聲道框架會放在 [XApuConnectInputParameters::maxFrameCountPerOutput](/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters) 到緩衝區結尾 * 即使 OutputFrameCount 小於 maxFrameCountPerOutput 也是如此。在此情況下，請使用 [XApuConnectInputParameters::maxFrameCountPerOutput](/zh-TW/reference/audio/xapu/structs/xapuconnectinputparameters) 來判斷緩衝區的中點，並使用 [XapuResult::outputFrameCount](/zh-TW/reference/audio/xapu/structs/xapuresult) 來計算每個通道要複製的框架數目。 ## 備註 由 `XApuDecodeConvertCommand` 用來解碼及轉換處理參數。如需 `XApuCommandId` 成員的資訊，請參閱 [XApuCommandId](/zh-TW/reference/audio/xapu/structs/xapucommandid)。如需 `XApuPorcessType` 的詳細資訊，請參閱 [XApuProcessType](/zh-TW/reference/audio/xapu/enums/xapuprocesstype)。 音高斜坡速率的範圍是從 2^-18 (0.000003814697265625) 到 8.0。任何小於最小值的值都會使斜坡沒有任何作用，音高會停留在目前的值。每當斜坡速率大於目前值與目標值之差的絕對值時，斜坡會在一個取樣週期內完成。 ## 需求 **標頭：** xapu.h **支援的平台：** XBOX Series X|S ## 概念文件 * [XAPU 概觀](/zh-TW/build/console-features/audio/overviews/xapu-overview) ## 另請參閱 [XApuEnqueueCommand](/zh-TW/reference/audio/xapu/functions/xapuenqueuecommand)\ [XApuResult](/zh-TW/reference/audio/xapu/structs/xapuresult)\ [XAPU](/zh-TW/reference/audio/xapu/xapu_members) ## Related topics - [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand.md) - [XApuCommandId](/reference/audio/xapu/structs/xapucommandid.md) - [XApuConnect](/ko/reference/audio/xapu/functions/xapuconnect.md)