このセクションでは、OpenSL ES API の使用を開始するために必要な基本情報を紹介します。
アプリに OpenSL ES を追加する
OpenSL ES は、C コードと C++ コードの両方から呼び出すことができます。OpenSL ES の主要な機能セットをアプリに追加するには、OpenSLES.h ヘッダー ファイルをインクルードします。
#include <SLES/OpenSLES.h>
OpenSL ES Android 拡張機能も追加する場合は、OpenSLES_Android.h ヘッダー ファイルをインクルードします。
#include <SLES/OpenSLES_Android.h>
OpenSLES_Android.h ヘッダー ファイルをインクルードすると、次のヘッダーが自動的にインクルードされます。
#include <SLES/OpenSLES_AndroidConfiguration.h> #include <SLES/OpenSLES_AndroidMetadata.h>
注: これらのヘッダーは必須ではなく、API を理解するための補助として紹介しています。
ビルドとデバッグ
OpenSL ES をビルドに組み込むには、NDK ビルドシステムの Makefile の 1 つとして機能する Android.mk ファイルで OpenSL ES を指定します。それには、次の行を Android.mk に追加します。
LOCAL_LDLIBS += -lOpenSLES
堅牢なデバッグを行うために、ほとんどの OpenSL ES API が返す SLresult 値を調べることをおすすめします。デバッグには、アサートや、さらに高度なエラー処理ロジックを使用できます。どちらか一方が特定のユースケースに適している場合もありますが、どちらも OpenSL ES の使用に関する固有のメリットはありません。
サンプルでアサートを使用しているのは、コーディング エラーとなる非現実的な条件の特定に役立つためです。本番環境で発生する可能性が高い他の条件には、明示的なエラー処理を使用しています。
API エラーの多くは、ゼロ以外の結果コードを生成するだけでなく、ログに記録されます。こうしたログエントリによって詳細情報がさらに提供され、Engine::CreateAudioPlayer などの比較的複雑な API では特に役立ちます。
ログはコマンドラインまたは Android Studio で確認できます。コマンドラインでログを確認するには、次のように入力します。
$ adb logcat
Android Studio でログを確認するには、[View] > [Tool Windows] > [Logcat] を選択します。 詳細については、logcat を使用したログの出力と確認をご覧ください。
サンプルコード
自分でコードを作成する場合、モデルとして使用可能な、サポート対象かつテスト済みのサンプルコードを使用することをおすすめします。このサンプルコードは、android-ndk GitHub リポジトリの audio-echo フォルダと native-audio フォルダにあります。
注意: OpenSL ES 1.0.1 仕様の付録にサンプルコードが含まれています（詳細については、Khronos OpenSL ES Registry をご覧ください）。ただし、「Appendix B: Sample Code」と「Appendix C: Use Case Sample Code」のサンプルでは、Android でサポートされていない機能が使用されています。また、誤植が含まれているサンプルや、変更される可能性がある API を使用しているサンプルもあります。これらのサンプルを参照するときには注意が必要です。コードは OpenSL ES 標準を理解するうえで役に立つこともありますが、Android で使用する場合は適宜変更してください。
オーディオ コンテンツ
アプリのオーディオ コンテンツはさまざまな方法でパッケージ化できます。以下にその一部を示します。
- リソース: オーディオ ファイルを
res/raw/フォルダに格納すると、Resourcesの関連 API で簡単にアクセスできるようになります。 ただし、リソースに直接ネイティブ アクセスすることはできないため、リソースを使用する前にコピーするコードを Java プログラミング言語で作成する必要があります。 - アセット: オーディオ ファイルを
assets/フォルダに格納することで、Android ネイティブ アセット マネージャー API から直接アクセスできるようになります。これらの API の詳細については、ヘッダー ファイルのandroid/asset_manager.hとandroid/asset_manager_jni.hをご覧ください。android-ndk GitHub リポジトリにあるサンプルコードでは、これらのネイティブ アセット マネージャー API を Android ファイル記述子データロケータと組み合わせて使用しています。 - ネットワーク: URI データロケータを使用して、ネットワークから直接オーディオ コンテンツを再生できます。ただし、セキュリティとパーミッションのセクションを必ずご確認ください。
- ローカル ファイル システム: URI データロケータでは、ローカル ファイルにアプリからアクセスできる場合に限って、ローカル ファイルで
file:スキームをサポートしています。Android セキュリティ フレームワークは Linux のユーザー ID とグループ ID のメカニズムを使用してファイル アクセスを制限することに注意してください。 - 録音: アプリはオーディオ データをマイク入力から録音し、そのコンテンツを保存して、後で再生することができます。サンプルコードでは、Playback クリップにこの方法を使用しています。
- インラインでのコンパイルとリンク: オーディオ コンテンツを共有ライブラリに直接リンクすると、オーディオ プレーヤーとバッファキュー データロケータを使用して再生することができます。この手法は、短い PCM 形式のクリップに最適です。サンプルコードでは、Hello クリップと Android クリップにこの手法を使用しています。PCM データは
bin2cツール（未提供）を使用して 16 進文字列に変換されています。 - リアルタイムの合成: アプリは、実行中に PCM データを合成し、オーディオ プレーヤーとバッファキュー データロケータを使用して再生することができます。これは比較的高度な手法であるため、オーディオ合成の詳細についてはこの記事では扱いません。
注: アプリに役立つオーディオ コンテンツの検索や作成については、この記事では説明しません。詳細については、「インタラクティブなオーディオ」、「ゲーム オーディオ」、「音声の設計」、「オーディオ プログラミング」などの検索キーワードでウェブ検索してください。
注意: コンテンツの再生と録音が法的に認められていることを確認する必要があります。コンテンツの録音について、プライバシーに関する考慮事項が存在する可能性があります。
コードサンプル
GitHub ページで次のサンプルアプリを入手できます。
- audio-echo: 入力と出力間のラウンドトリップ ループを作成します。
- native-audio: シンプルなオーディオ レコーダー / プレーヤーです。
OpenSL ES の Android NDK 実装は、いくつかの点で OpenSL ES 1.0.1 のリファレンス仕様と異なります。この違いが原因で、OpenSL ES リファレンス仕様から直接コピーしたサンプルコードが Android アプリで動作しない場合もあります。
リファレンス仕様と Android 実装の違いの詳細については、OpenSL ES for Android をご覧ください。