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

# Visão geral da XAPU

> API XBOX Audio Processing Unit (XAPU) para decodificação Opus acelerada por hardware e conversão de taxa de amostragem de alta qualidade no XBOX Series X|S.

Este tópico fornece uma visão geral das [APIs XAPU](/pt-BR/reference/audio/xapu/xapu_members) para decodificação de arquivos Opus acelerada por hardware e conversão de taxa de amostragem de alta qualidade.

## Recursos da versão de decodificação de hardware Opus

Historicamente, o XMA era a única opção na família de consoles XBOX One que oferecia decodificação descarregada para o hardware. Agora, na geração de consoles XBOX Series X|S, estamos introduzindo a decodificação Opus descarregada para o hardware por meio da API XAPU (XBOX Audio Processing Unit).
O Opus é um codec de compressão de áudio livre de royalties, projetado para codificar com eficiência fala e áudio em geral em um único formato. O Opus tem baixa latência. Em avaliações internas, o Opus supera o XMA em qualidade e na taxa de compressão do tamanho do arquivo.

Além disso, foi adicionado um conversor de taxa de amostragem de alta qualidade (HSRC) para funcionar em conjunto com a funcionalidade de decodificação de hardware (Opus). Ao combinar a decodificação Opus descarregada para o hardware com o recurso HSRC para alterar o pitch, os desenvolvedores notarão uma qualidade de saída melhor em comparação com a oferta SHAPE da geração anterior. (Ela ainda tem suporte nos consoles XBOX Series X|S para compatibilidade com versões anteriores.)

### Novidades desta versão

* Novo no June FAL QFE3: para cenários de Quick Resume, não é mais necessário que os títulos restabeleçam a conexão com o hardware após uma retomada.
* Novo no June FAL QFE4: pacotes Opus com duração de 2,5 e 5 ms agora têm suporte para CELT.
* Versão de recuperação de prévia de agosto de 2020 10.0.19041.4124 (rs\_xbox\_release\_2008- 19041.4124.200814-0000) / 10.0.19041.3562 (rs\_xbox\_release\_sirius- 19041.3562.200814-2300) ou superior: alteração significativa na implementação de [XApuDecodeConvertCommand](/pt-BR/reference/audio/xapu/structs/xapudecodeconvertcommand): agora os dados residuais ao usar firstFrameIndex não são incluídos, ao contrário de antes. Confira a seção Práticas recomendadas ou a página de referência da API [XApuDecodeConvertCommand](/pt-BR/reference/audio/xapu/structs/xapudecodeconvertcommand) para obter detalhes adicionais.
* Se o buffer de processamento de saída do HSRC tivesse dados e o comando flush fosse usado, anteriormente havia perda de dados (era possível perder alguns dados de áudio convertidos e a saída não era a esperada)
* Se pacotes Opus sem suporte forem enviados para processamento, agora um erro é gerado em vez de um travamento. (ex.: enviar um pacote Opus de 2,5 ms quando apenas 10 ms ou 20 ms têm suporte)
* FIFO está ativado por padrão
* Melhorias gerais de desempenho e correções de estabilização

## Especificações da versão de decodificação de hardware Opus

A tabela a seguir descreve quais comandos e recursos estão disponíveis:

| - | CELT | - | - | - | SILK | - | - | - | Híbrido | - | - | - | PCM | - | - | - |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| Comandos | Modo com suporte | Busca e loop | Redefinição | HSRC | Modo com suporte | Busca e loop | Redefinição | HSRC | Modo com suporte | Busca e loop | Redefinição | HSRC | Modo com suporte | Busca e loop | Redefinição | HSRC |
| DECODE | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | | | | |
| DECODE e CONVERT | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | Sim | | | | |
| SOMENTE CONVERT | | | | | | | | | | | | | Sim | Sim | Sim | Sim |

### Observação importante sobre o uso do HSRC

O conversor de taxa de amostragem de alta qualidade (HSRC) tem um atraso de grupo dependente da frequência de aproximadamente *5 quadros* para frequências abaixo de 10 kHz.

O atraso esperado na saída é de *5 quadros* quando o conversor de taxa de amostragem está ativado, e o chamador pode fazer os ajustes necessários. Se você usar uma solução de middleware para áudio, esse atraso já pode estar sendo tratado para o seu título.

### Práticas recomendadas

* Em relação à implementação de [XApuDecodeConvertCommand](/pt-BR/reference/audio/xapu/structs/xapudecodeconvertcommand): o firstFrameIndex passado para [XApuDecodeConvertCommand](/pt-BR/reference/audio/xapu/structs/xapudecodeconvertcommand) especifica o primeiro quadro que será copiado para o buffer de saída PCM. O firstFrameIndex, combinado com o frameCount, especifica o que é copiado para o buffer de saída. Nossa implementação não inclui os dados residuais ao usar o firstFrameIndex. Se houver 100 quadros residuais, o firstFrameIndex estiver definido como 50 e o frameCount estiver definido como 200, 200 quadros serão adicionados a todo o residual a partir do 50º quadro nos dados decodificados. Isso significa que o buffer de entrada do HSRC terá os 100 quadros originais do residual seguidos por 200 quadros a partir do 50º quadro no pacote decodificado atual.
* Recomendamos que você crie clientes XAPU com cuidado.  É melhor criar os clientes XAPU antecipadamente (durante a ativação dos recursos do mecanismo de áudio) e continuar usando-os durante todo o tempo de vida do jogo.  As chamadas para [XApuConnect](/pt-BR/reference/audio/xapu/functions/xapuconnect) e [XAapuDisconnect](/pt-BR/reference/audio/xapu/functions/xapudisconnect) são computacionalmente caras.  Você corre o risco de ficar sem recursos se clientes com requisitos de memória variados forem criados e excluídos com frequência.
* Para fins de loop, cabe ao chamador usar ou não [XApuCommandType::Reset](/pt-BR/reference/audio/xapu/enums/xapucommandtype), pois isso pode causar um efeito transitório na saída. No entanto, quando [XApuCommandType::Reset](/pt-BR/reference/audio/xapu/enums/xapucommandtype) é usado, pacotes de pré-rolagem devem ser enviados para evitar o efeito transitório.
* Para obter o melhor desempenho, use fluxos Opus codificados com tamanho de pacote de 20 ms
* Em termos de desempenho, pode ser melhor usar menos clientes com mais fluxos do que menos fluxos com mais clientes. Por exemplo, ter 5 clientes com 20 fluxos por cliente, totalizando 100 fluxos, oferece melhor desempenho em comparação com 50 clientes com 2 fluxos cada. Ambos podem ser usados para decodificar 100 fluxos, mas o primeiro terá melhor desempenho
* OPUS\_SET\_PREDICTION\_DISABLED desabilita a previsão entre pacotes e tem suporte.  A codificação com esse sinalizador reduz o desempenho da compressão e, consequentemente, degrada a qualidade da saída decodificada.
* A XAPU retorna o erro [XAPU\_E\_DEVICE\_FATAL](/pt-BR/reference/audio/xapu/enums/xapuerrors) quando o dispositivo de hardware está em um estado inválido. Todos os clientes XAPU devem ser desconectados nesse ponto, antes de criar novos clientes, para se recuperar desse erro.
* O mecanismo de sinalização para conclusões de comandos funciona em um temporizador de 3 ms e sinaliza uma vez para todos os comandos concluídos até o momento para cada cliente XAPU, independentemente de quantos comandos usaram o sinalizador [XApuCommandOptions::SignalOnCompletion](/pt-BR/reference/audio/xapu/enums/xapucommandoptions).
* Se o título não puder tolerar o mecanismo de sinalização de 3 ms, ele poderá procurar respostas em um loop ou usar Sleep(0) e verificar as respostas.
* É importante aguardar todas as respostas antes de desconectar o cliente. [XApuDisconnect](/pt-BR/reference/audio/xapu/functions/xapudisconnect) agora retorna o erro [XAPU\_E\_PENDING\_RESULTS](/pt-BR/reference/audio/xapu/enums/xapuerrors) se houver solicitações pendentes que não foram coletadas. Esse erro não exige ação e deve ser usado apenas durante o desenvolvimento. XApuDisconnect libera todos os recursos alocados para o cliente e, se for chamado enquanto o hardware ainda estiver processando comandos desse cliente, poderá ocorrer corrupção de memória, pois o hardware grava em memória que já foi liberada.
* Todos os ponteiros de memória passados para o hardware (ex.: inputData, outPutData e o processingBuffer) devem estar alinhados em 16 bytes.
* Ao usar os modos ConvertOnly ou DecodeConvert, tamanhos maiores de contagem de quadros de saída resultarão em melhor desempenho. O maior tamanho de quadro de saída com suporte ao usar decode convert e convert é 1024.
* Somente a codificação de taxa de bits variável (VBR) tem suporte. A codificação de taxa de bits constante (CBR) não tem suporte porque adiciona pacotes de transição, que são menos eficientes e de pior qualidade do que os pacotes de redundância usados na codificação VBR. Portanto, esse tipo de pacote e, por extensão, a CBR, não têm suporte.
* Para HYBRID e SILK: somente fluxos Opus mono e estéreo têm suporte, com pacotes de 10 ou 20 ms e taxa de amostragem de 48000 Hz.
* Para CELT: somente fluxos Opus mono e estéreo têm suporte, com pacotes de 2,5, 5, 10 ou 20 ms e taxa de amostragem de 48000 Hz.

### Pausar e retomar um título

Um título deve ser capaz de pausar e retomar, por exemplo, quando o usuário o coloca no modo restrito. Quando o manipulador de suspensão for chamado, basta parar de enviar comandos XAPU para o hardware. Os comandos que já foram enviados serão concluídos normalmente e colocados em suas filas de resposta correspondentes.

### Exemplos (código-fonte disponível em um arquivo .zip externo; solicite enviando um email para [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com))

* Decode One Opus Stream. (Uma visão geral deste exemplo está disponível [aqui](/pt-BR/build/console-features/audio/overviews/xapu-overview-single-stream-audio-decode).)
* Decode Multi-Opus Streams.
* Play One Opus Stream. (O threading é diferente do "Decode One Opus Stream".)
* Play Multi-Opus Streams.
* Decode Convert One Opus Stream, com opção de loop e busca com precisão de amostra.
* Decode Convert Multi-Opus Streams.
* Play Decode Convert One Opus Stream.
* SimpleXAPU (exemplo de decodificação de um fluxo Opus em um título do GDK com uma interface do usuário).

### Contato

Se você tiver dúvidas ou preocupações sobre este recurso, envie um email para [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) ou use os fóruns online.

## Documentação de referência da API

* [Xapu (conteúdo da API)](/pt-BR/reference/audio/xapu/xapu_members)
  * Funções
    * [XApuConnect](/pt-BR/reference/audio/xapu/functions/xapuconnect)
    * [XAapuDisconnect](/pt-BR/reference/audio/xapu/functions/xapudisconnect)
  * Estruturas
    * [XApuDecodeConvertCommand](/pt-BR/reference/audio/xapu/structs/xapudecodeconvertcommand)


## Related topics

- [XApuDecodeConvertCommand](/pt-BR/reference/audio/xapu/structs/xapudecodeconvertcommand.md)
- [Visão geral da publicação](/pt-BR/publishing/game-publishing/overview.md)
- [Visão geral da XSAPI C](/pt-BR/services/xbox-services/fundamentals/xbox-services-api/live-xsapi-flat-c.md)
- [Visão geral da reputação](/pt-BR/services/xbox-services/community/reputation/live-reputation-overview.md)
- [Visão geral da programação assíncrona](/pt-BR/build/core-features/common/async/async-toc.md)