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

# XAPU の概要

> XBOX Series X|S 上でハードウェア アクセラレーションによる Opus デコードおよび高品質サンプル レート変換を行うための XBOX Audio Processing Unit (XAPU) API。

このトピックでは、ハードウェア アクセラレーションによる Opus ファイルのデコードおよび高品質サンプル レート変換用の [XAPU API](/reference/audio/xapu/xapu_members) の概要を提供します。

## Opus ハードウェア デコード リリース機能

これまで、XMA は、ハードウェア オフロード デコードを提供する XBOX One ファミリー コンソール上で唯一の選択肢でした。現在、XBOX Series X|S ファミリー コンソールでは、XAPU (XBOX Audio Processing Unit) API を通じて Opus ハードウェア オフロード デコードを導入しています。
Opus は、音声と一般的なオーディオを単一のフォーマットに効率的にコーディングするように設計された、ロイヤリティフリーのオーディオ圧縮コーデックです。Opus は低レイテンシーです。内部評価では、Opus は品質とファイル サイズ圧縮率で XMA を上回っています。

さらに、ハードウェア デコード機能 (Opus) と連携する High-quality Sample Rate Convertor (HSRC) が追加されています。ピッチを変更するために Opus ハードウェア オフロード デコードと HSRC 機能を組み合わせると、開発者は以前世代の SHAPE 提供と比較して出力品質の向上に気付くことでしょう (SHAPE は下位互換性のために XBOX Series X|S コンソールで引き続きサポートされています)。

### このリリースの新機能

* June FAL QFE3 での新機能: Quick Resume シナリオでは、タイトルが再開後にハードウェアとの接続を再確立する必要がなくなりました。
* June FAL QFE4 での新機能: CELT に対して 2.5 および 5 ms 長の Opus パケットがサポートされるようになりました。
* 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) 以降: [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand) 実装への破壊的変更: firstFrameIndex を使用する場合、以前は含まれていた残差データが含まれなくなりました。詳細については、Best Practice セクションまたは API リファレンス ページ [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand) を参照してください。
* HSRC 出力処理バッファーにデータがあり、flush コマンドが使用される場合、以前はデータの損失がありました (一部の変換されたオーディオ データが失われ、期待どおりの出力にならない可能性がありました)。
* サポートされていない Opus パケットが処理のために送信された場合、ハングではなくエラーがスローされるようになりました (例: 10 ms または 20 ms のみサポートされる 2.5 ms の Opus パケットを送信した場合)。
* FIFO は既定で有効になっています
* 全体的なパフォーマンスの改善と安定化の修正

## Opus ハードウェア デコード リリース仕様

以下の表は、利用可能なコマンドと機能の概要を示しています。

| -                  | CELT       | -       | -     | -    | SILK       | -       | -     | -    | Hybrid     | -       | -     | -    | PCM        | -       | -     | -    |
| ------------------ | ---------- | ------- | ----- | ---- | ---------- | ------- | ----- | ---- | ---------- | ------- | ----- | ---- | ---------- | ------- | ----- | ---- |
| コマンド               | サポートされるモード | シークとループ | Reset | HSRC | サポートされるモード | シークとループ | Reset | HSRC | サポートされるモード | シークとループ | Reset | HSRC | サポートされるモード | シークとループ | Reset | HSRC |
| DECODE             | あり         | あり      | あり    | あり   | あり         | あり      | あり    | あり   | あり         | あり      | あり    | あり   |            |         |       |      |
| DECODE and CONVERT | あり         | あり      | あり    | あり   | あり         | あり      | あり    | あり   | あり         | あり      | あり    | あり   |            |         |       |      |
| CONVERT ONLY       |            |         |       |      |            |         |       |      |            |         |       |      | あり         | あり      | あり    | あり   |

### HSRC の使用に関する重要な注意事項

High-quality Sample Rate Convertor (HSRC) には、10 kHz 未満の周波数に対して周波数に依存する群遅延があり、約 *5 フレーム*です。

サンプル レート コンバーターが有効になっている場合、出力の予想される遅延は *5 フレーム*であり、呼び出し元はそれに応じて調整できます。オーディオ用のミドルウェア ソリューションを使用している場合、この遅延はタイトル用に既に処理されている可能性があります。

### ベスト プラクティス

* [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand) の実装に関して: [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand) に渡される firstFrameIndex は、PCM 出力バッファーにコピーされる最初のフレームを指定します。firstFrameIndex を frameCount と組み合わせて、出力バッファーにコピーされるものを指定します。当社の実装では、firstFrameIndex を使用する場合、残差データは含まれません。100 個の残差フレームがあり、firstFrameIndex が 50 に設定され、frameCount が 200 に設定されている場合、200 フレームがデコード済みデータの 50 番目のフレームから始まる残差全体に追加されます。これは、HSRC へのバッファーに残差からの元の 100 フレームが含まれ、その後に現在のデコード済みパケットの 50 番目のフレームから始まる 200 フレームが続くことを意味します。
* XAPU クライアントの作成には注意することをお勧めします。事前に (オーディオ エンジン リソースのアクティブ化時に) XAPU クライアントを作成し、ゲームのライフタイム全体にわたって使用し続けるのが最善です。[XApuConnect](/reference/audio/xapu/functions/xapuconnect) および [XAapuDisconnect](/reference/audio/xapu/functions/xapudisconnect) の呼び出しは、計算コストが高いです。メモリ要件の異なるクライアントが頻繁に作成および削除されると、リソースが不足するリスクがあります。
* ループ目的では、[XApuCommandType::Reset](/reference/audio/xapu/enums/xapucommandtype) を使用するかどうかは呼び出し元次第です。使用すると出力に過渡的なエフェクトが生じる可能性があります。ただし、[XApuCommandType::Reset](/reference/audio/xapu/enums/xapucommandtype) を使用する場合は、過渡的エフェクトを回避するためにプリロール パケットを送信する必要があります。
* 最高のパフォーマンスを得るには、20 ms のパケット サイズでエンコードされた Opus ストリームを使用してください
* パフォーマンス的には、より多くのクライアントで少ないストリームよりも、少ないクライアントで多くのストリームを使用する方がよい場合があります。たとえば、クライアントあたり 20 ストリームで 5 つのクライアント (合計 100 ストリーム) の方が、クライアントあたり 2 ストリームで 50 のクライアントよりもパフォーマンスが良くなります。どちらも 100 ストリームをデコードするために使用できますが、最初の方がパフォーマンスが良くなります
* OPUS\_SET\_PREDICTION\_DISABLED はパケット間予測を無効にし、サポートされています。このフラグを付けてエンコードすると、圧縮パフォーマンスが低下し、それによってデコードされた出力の品質が低下します。
* XAPU は、ハードウェア デバイスが不良状態にあるときに [XAPU\_E\_DEVICE\_FATAL](/reference/audio/xapu/enums/xapuerrors) エラーを返します。このエラーから回復するには、新しいクライアントを作成する前に、この時点ですべての XAPU クライアントを切断する必要があります。
* コマンド完了のシグナリング メカニズムは 3 ms タイマーで動作し、いくつのコマンドが [XApuCommandOptions::SignalOnCompletion](/reference/audio/xapu/enums/xapucommandoptions) フラグを使用したかに関係なく、各 XAPU クライアントに対してこれまでに完了したすべてのコマンドに対して 1 回シグナリングします。
* タイトルが 3 ms シグナリング メカニズムを許容できない場合、ループで応答を探すか、Sleep(0) を使用して応答をチェックできます。
* クライアントを切断する前に、すべての応答を待つことが重要です。[XApuDisconnect](/reference/audio/xapu/functions/xapudisconnect) は、ピックアップされていない未処理の要求がある場合、[XAPU\_E\_PENDING\_RESULTS](/reference/audio/xapu/enums/xapuerrors) エラーを返すようになりました。このエラーは実行可能ではなく、開発時にのみ使用する必要があります。XApuDisconnect は、クライアント用に割り当てられたすべてのリソースを解放します。ハードウェアがこのクライアントのコマンドを処理中に呼び出されると、ハードウェアが解放されたメモリに書き込むため、メモリ破損が発生する可能性があります。
* ハードウェアに渡されるすべてのメモリ ポインター (例: inputData、outPutData、および processingBuffer) は 16 バイトにアラインされている必要があります。
* ConvertOnly または DecodeConvert モードを使用する場合、出力フレーム数のサイズが大きいほどパフォーマンスが向上します。decode convert および convert を使用する場合にサポートされる最大出力フレーム サイズは 1024 です。
* 可変ビット レート (VBR) エンコードのみがサポートされています。一定ビット レート (CBR) エンコードは、VBR エンコードで使用される冗長パケットよりも効率が低く品質も悪い遷移パケットを追加するため、サポートされていません。したがって、このパケット タイプ、およびその延長として CBR はサポートされていません。
* HYBRID および SILK の場合: 48000 Hz のサンプル レートでの 10 または 20 ms パケットのモノラルおよびステレオ Opus ストリームのみサポートされます。
* CELT の場合: 48000 Hz のサンプル レートでの 2.5、5、10、または 20 ms パケットのモノラルおよびステレオ Opus ストリームのみサポートされます。

### タイトルの一時停止と再開

タイトルは、たとえばユーザーが Constrained モードにしたときなど、一時停止と再開ができる必要があります。suspend ハンドラーが呼び出されたら、単純にハードウェアへの XAPU コマンドの送信を停止してください。既に送信されたコマンドは正常に完了し、対応する応答キューに配置されます。

### サンプル (ソース コードは外部の .zip ファイルで入手可能。[AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) にメールで要求してください)

* Decode One Opus Stream (このサンプルの概要は[こちら](/build/console-features/audio/overviews/xapu-overview-single-stream-audio-decode)で入手可能)。
* Decode Multi-Opus Streams。
* Play One Opus Stream (スレッドは「Decode One Opus Stream」とは異なります)。
* Play Multi-Opus Streams。
* ループおよびサンプル正確シークのオプション付き Decode Convert One Opus Stream。
* Decode Convert Multi-Opus Streams。
* Play Decode Convert One Opus Stream。
* SimpleXAPU (UI を備えた GDK タイトル内での Opus ストリーム デコードの例)。

### 連絡先

この機能についてご質問やご懸念がある場合は、[AnaAud@microsoft.com](mailto:AnaAud@microsoft.com) までメールでお問い合わせいただくか、オンライン フォーラムをご利用ください。

## リファレンス API ドキュメント

* [Xapu (API 内容)](/reference/audio/xapu/xapu_members)
  * 関数
    * [XApuConnect](/reference/audio/xapu/functions/xapuconnect)
    * [XAapuDisconnect](/reference/audio/xapu/functions/xapudisconnect)
  * 構造体
    * [XApuDecodeConvertCommand](/reference/audio/xapu/structs/xapudecodeconvertcommand)


## Related topics

- [XBOX Series X|S オーディオ ハードウェアの概要](/ja-jp/build/console-features/audio/overviews/scarlett-audio.md)
- [XApuConnect](/ja-jp/reference/audio/xapu/functions/xapuconnect.md)
- [XApuDisconnect](/ja-jp/reference/audio/xapu/functions/xapudisconnect.md)
- [XApuDecodeConvertCommand](/ja-jp/reference/audio/xapu/structs/xapudecodeconvertcommand.md)
- [ADPCM の概要](/ja-jp/build/console-features/audio/overviews/adpcm-overview.md)