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

# Vue d'ensemble de XAPU

> API XBOX Audio Processing Unit (XAPU) pour le décodage Opus accéléré par le matériel et la conversion de fréquence d'échantillonnage de haute qualité sur XBOX Series X|S.

Cette rubrique fournit une vue d'ensemble des [API XAPU](/fr/reference/audio/xapu/xapu_members) pour le décodage de fichiers Opus accéléré par le matériel et la conversion de fréquence d'échantillonnage de haute qualité.

## Fonctionnalités de la version du décodage matériel Opus

Historiquement, XMA était la seule offre de la famille de consoles XBOX One à proposer un décodage déchargé sur le matériel. Désormais, sur la génération de consoles XBOX Series X|S, nous introduisons le décodage Opus déchargé sur le matériel via l'API XAPU (XBOX Audio Processing Unit).
Opus est un codec de compression audio libre de redevances, conçu pour coder efficacement la parole et l'audio général dans un format unique. Opus offre une faible latence. Lors d'évaluations internes, Opus a surpassé XMA en matière de qualité et de taux de compression de la taille des fichiers.

En outre, un convertisseur de fréquence d'échantillonnage de haute qualité (HSRC) a été ajouté pour fonctionner conjointement avec la fonctionnalité de décodage matériel (Opus). En combinant le décodage Opus déchargé sur le matériel avec la fonctionnalité HSRC pour modifier la hauteur tonale, les développeurs constateront une meilleure qualité de sortie par rapport à l'offre SHAPE de la génération précédente. (SHAPE reste pris en charge sur les consoles XBOX Series X|S à des fins de rétrocompatibilité.)

### Nouveautés de cette version

* Nouveauté de June FAL QFE3 : pour les scénarios Quick Resume, les titres ne sont plus tenus de rétablir leur connexion au matériel après une reprise.
* Nouveauté de June FAL QFE4 : les paquets Opus d'une durée de 2,5 et 5 ms sont désormais pris en charge pour CELT.
* Version August 2020 Preview Recovery 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 ultérieure : changement cassant dans l'implémentation de [XApuDecodeConvertCommand](/fr/reference/audio/xapu/structs/xapudecodeconvertcommand) : les données résiduelles ne sont désormais plus incluses lors de l'utilisation de firstFrameIndex, alors qu'elles l'étaient auparavant. Pour plus de détails, consultez la section Bonnes pratiques ou la page de référence de l'API [XApuDecodeConvertCommand](/fr/reference/audio/xapu/structs/xapudecodeconvertcommand).
* Si la mémoire tampon de traitement de sortie HSRC contenait des données et que la commande de vidage était utilisée, une perte de données se produisait auparavant (vous pouviez perdre une partie des données audio converties et la sortie n'était pas celle attendue)
* Si des paquets Opus non pris en charge sont envoyés pour traitement, une erreur est désormais levée au lieu d'un blocage. (Par ex. envoi d'un paquet Opus de 2,5 ms alors que seuls les paquets de 10 ms ou 20 ms sont pris en charge)
* FIFO est activé par défaut
* Améliorations globales des performances et correctifs de stabilisation

## Spécifications de la version du décodage matériel Opus

Le tableau suivant décrit les commandes et fonctionnalités disponibles :

| - | CELT | - | - | - | SILK | - | - | - | Hybride | - | - | - | PCM | - | - | - |
| - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - | - |
| Commandes | Mode pris en charge | Recherche et bouclage | Réinitialisation | HSRC | Mode pris en charge | Recherche et bouclage | Réinitialisation | HSRC | Mode pris en charge | Recherche et bouclage | Réinitialisation | HSRC | Mode pris en charge | Recherche et bouclage | Réinitialisation | HSRC |
| DECODE | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | | | | |
| DECODE et CONVERT | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | Oui | | | | |
| CONVERT ONLY | | | | | | | | | | | | | Oui | Oui | Oui | Oui |

### Remarque importante sur l'utilisation de HSRC

Le convertisseur de fréquence d'échantillonnage de haute qualité (HSRC) présente un temps de propagation de groupe dépendant de la fréquence, d'environ *5 trames* pour les fréquences inférieures à 10 kHz.

Le retard attendu en sortie est de *5 trames* lorsque le convertisseur de fréquence d'échantillonnage est actif, et l'appelant peut effectuer les ajustements nécessaires. Si vous utilisez une solution d'intergiciel pour l'audio, ce retard est peut-être déjà géré pour votre titre.

### Bonnes pratiques

* Concernant l'implémentation de [XApuDecodeConvertCommand](/fr/reference/audio/xapu/structs/xapudecodeconvertcommand) : le paramètre firstFrameIndex passé à [XApuDecodeConvertCommand](/fr/reference/audio/xapu/structs/xapudecodeconvertcommand) spécifie la première trame qui sera copiée dans la mémoire tampon de sortie PCM. firstFrameIndex, combiné à frameCount, spécifie ce qui est copié dans la mémoire tampon de sortie. Notre implémentation n'inclut pas les données résiduelles lors de l'utilisation de firstFrameIndex. S'il y a 100 trames résiduelles, que firstFrameIndex est défini sur 50 et frameCount sur 200, 200 trames seront ajoutées à la totalité des données résiduelles, à partir de la 50e trame des données décodées. Cela signifie que la mémoire tampon envoyée au HSRC contiendra les 100 trames résiduelles d'origine, suivies de 200 trames à partir de la 50e trame du paquet décodé actuel.
* Nous vous recommandons de créer les clients XAPU avec précaution.  Il est préférable de créer les clients XAPU dès le départ (lors de l'activation des ressources du moteur audio) et de continuer à les utiliser pendant toute la durée de vie du jeu.  Les appels à [XApuConnect](/fr/reference/audio/xapu/functions/xapuconnect) et [XAapuDisconnect](/fr/reference/audio/xapu/functions/xapudisconnect) sont coûteux en calcul.  Vous risquez de manquer de ressources si des clients ayant des besoins en mémoire variables sont fréquemment créés et supprimés.
* Pour le bouclage, il appartient à l'appelant d'utiliser ou non [XApuCommandType::Reset](/fr/reference/audio/xapu/enums/xapucommandtype), car cela peut provoquer un effet transitoire en sortie. Toutefois, lorsque [XApuCommandType::Reset](/fr/reference/audio/xapu/enums/xapucommandtype) est utilisé, des paquets de pré-roll doivent être soumis pour éviter cet effet transitoire.
* Pour obtenir les meilleures performances, utilisez des flux Opus encodés avec une taille de paquet de 20 ms
* En matière de performances, il peut être préférable d'utiliser moins de clients avec plus de flux plutôt que moins de flux avec plus de clients. Par exemple, 5 clients avec 20 flux par client, soit un total de 100 flux, offrent de meilleures performances que 50 clients avec 2 flux chacun. Les deux configurations permettent de décoder 100 flux, mais la première sera plus performante
* OPUS\_SET\_PREDICTION\_DISABLED désactive la prédiction inter-paquets et est pris en charge.  L'encodage avec cet indicateur réduit les performances de compression et dégrade ainsi la qualité de la sortie décodée.
* XAPU renvoie l'erreur [XAPU\_E\_DEVICE\_FATAL](/fr/reference/audio/xapu/enums/xapuerrors) lorsque le périphérique matériel est dans un état incorrect. Tous les clients XAPU doivent alors être déconnectés avant de créer de nouveaux clients pour récupérer de cette erreur.
* Le mécanisme de signalisation des achèvements de commandes fonctionne sur un minuteur de 3 ms et signale une seule fois l'ensemble des commandes achevées jusqu'à présent pour chaque client XAPU, quel que soit le nombre de commandes ayant utilisé l'indicateur [XApuCommandOptions::SignalOnCompletion](/fr/reference/audio/xapu/enums/xapucommandoptions).
* Si le titre ne peut pas tolérer le mécanisme de signalisation de 3 ms, il peut rechercher les réponses dans une boucle ou utiliser Sleep(0) et vérifier les réponses.
* Il est important d'attendre toutes les réponses avant de déconnecter le client. [XApuDisconnect](/fr/reference/audio/xapu/functions/xapudisconnect) renvoie désormais l'erreur [XAPU\_E\_PENDING\_RESULTS](/fr/reference/audio/xapu/enums/xapuerrors) s'il existe des requêtes en attente qui n'ont pas été récupérées. Cette erreur ne requiert aucune action et ne doit être utilisée que pendant le développement. XApuDisconnect libère toutes les ressources allouées au client et, s'il est appelé alors que le matériel traite encore des commandes pour ce client, une corruption de la mémoire peut se produire, car le matériel écrit dans une mémoire qui a été libérée.
* Tous les pointeurs de mémoire transmis au matériel (par ex. inputData, outPutData et processingBuffer) doivent être alignés sur 16 octets.
* Lors de l'utilisation des modes ConvertOnly ou DecodeConvert, des tailles de nombre de trames de sortie plus importantes offrent de meilleures performances. La taille de trame de sortie maximale prise en charge avec DecodeConvert et Convert est de 1024.
* Seul l'encodage à débit variable (VBR) est pris en charge. L'encodage à débit constant (CBR) n'est pas pris en charge, car il ajoute des paquets de transition, moins efficaces et de moins bonne qualité que les paquets de redondance utilisés dans l'encodage VBR. Par conséquent, ce type de paquet et, par extension, CBR ne sont pas pris en charge.
* Pour HYBRID et SILK : seuls les flux Opus mono et stéréo sont pris en charge, avec des paquets de 10 ou 20 ms et une fréquence d'échantillonnage de 48 000 Hz.
* Pour CELT : seuls les flux Opus mono et stéréo sont pris en charge, avec des paquets de 2,5, 5, 10 ou 20 ms et une fréquence d'échantillonnage de 48 000 Hz.

### Mise en pause et reprise d'un titre

Un titre doit pouvoir être mis en pause et repris, par exemple lorsque l'utilisateur le place en mode contraint. Lorsque le gestionnaire de suspension est appelé, cessez simplement de soumettre des commandes XAPU au matériel. Les commandes déjà soumises s'achèveront normalement et seront placées dans leurs files d'attente de réponses correspondantes.

### Exemples (code source disponible dans un fichier .zip externe, à demander par e-mail à [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com))

* Decode One Opus Stream. (Vue d'ensemble de cet exemple disponible [ici](/fr/build/console-features/audio/overviews/xapu-overview-single-stream-audio-decode).)
* Decode Multi-Opus Streams.
* Play One Opus Stream. (Le threading est différent de celui de "Decode One Opus Stream".)
* Play Multi-Opus Streams.
* Decode Convert One Opus Stream, avec une option de bouclage et de recherche précise à l'échantillon près.
* Decode Convert Multi-Opus Streams.
* Play Decode Convert One Opus Stream.
* SimpleXAPU (exemple de décodage d'un flux Opus dans un titre GDK doté d'une interface utilisateur.)

### Contact

Si vous avez des questions ou des préoccupations concernant cette fonctionnalité, envoyez un e-mail à [AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) ou utilisez les forums en ligne.

## Documentation de référence de l'API

* [Xapu (contenu de l'API)](/fr/reference/audio/xapu/xapu_members)
  * Fonctions
    * [XApuConnect](/fr/reference/audio/xapu/functions/xapuconnect)
    * [XAapuDisconnect](/fr/reference/audio/xapu/functions/xapudisconnect)
  * Structures
    * [XApuDecodeConvertCommand](/fr/reference/audio/xapu/structs/xapudecodeconvertcommand)


## Related topics

- [Vue d'ensemble d'Unity](/fr/paths/unity/overview.md)
- [Vue d'ensemble du portage](/fr/paths/porting/overview.md)
- [Vue d'ensemble de XBOX Series X|S](/fr/paths/series-xs/overview.md)
- [Vue d'ensemble d'Unreal Engine](/fr/paths/unreal/overview.md)
- [Vue d'ensemble de l'accessibilité GDK](/fr/build/game-principles/accessibility/accessibility-overview.md)