スタートガイド

このセクションでは、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.handroid/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 は、シンプルなオーディオ レコーダー / プレーヤーです。
  • SimpleSynth は、正弦波を出力します。最適なオーディオ レイテンシと安定した計算スループットの算出方法を示します。

OpenSL ES の Android NDK 実装は、多くの点で OpenSL ES 1.0.1 のリファレンス仕様とは異なります。OpenSL ES リファレンス仕様から直接コピーするサンプルコードが Android アプリで動作しない場合がありますが、その理由として重要なのがこの差異になります。

リファレンス仕様と Android 実装の違いの詳細については、OpenSL ES for Android をご覧ください。