開始使用

本節提供開始使用 OpenSL ES API 所需的資訊。

將 OpenSL ES 新增至應用程式

您可以透過 C 和 C++ 程式碼呼叫 OpenSL ES。如要為應用程式新增核心 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。

建構及偵錯

您可以在 Android.mk 檔案 (NDK 建構系統的 makefile 之一) 中指定 OpenSL ES,就能將 OpenSL ES 整合到建構項目中。在 Android.mk 中新增這一行:

LOCAL_LDLIBS += -lOpenSLES

為獲得理想的偵錯效果,建議您檢查大部分 OpenSL ES API 傳回的 SLresult 值。您可以使用 assert 或更進階的錯誤處理邏輯來進行偵錯,雖然在用於特定用途時,其中一種方式可能會更加適合,但是無論是 assert 還是錯誤處理邏輯,都無法在搭配 OpenSL ES 使用時發揮固有優勢。

我們在範例中使用 assert,因為 assert 能協助找到可指出程式設計錯誤的不切實際的情況。針對在實際環境中更有可能發生的其他狀況,我們採用了明確的錯誤處理機制。

許多 API 錯誤在出現時,除了會讓系統傳回非零結果代碼外,也會產生記錄項目。這些記錄項目可提供額外的詳細資訊,並且經證明對相對複雜的 API (例如 Engine::CreateAudioPlayer) 尤其實用。

您可以從指令列或 Android Studio 查看記錄。如要從指令列查看記錄,請輸入以下內容:

$ adb logcat

如要從 Android Studio 查看記錄,請依序選取「檢視」>「工具視窗」>「Logcat」。 詳情請參閱使用 Logcat 寫入及查看記錄

範例程式碼

建議使用支援且經測試的範例程式碼,這些程式碼位於 android-ndk GitHub 存放區的 audio-echonative-audio 資料夾中,可做為您的程式碼範本使用。

注意:OpenSL ES 1.0.1 規範的附錄有列出範例程式碼 (詳情請參閱 Khronos OpenSL ES Registry)。不過,「附錄 B:程式碼範例」和「附錄 C:程式碼範例使用情境」中的範例使用了 Android 不支援的功能。部分範例也含有打字錯誤,或是使用可能會變更的 API。參閱這些範例時,請務必謹慎小心;雖然這些程式碼對於瞭解完整的 OpenSL ES 標準相當有用,但建議不要完全不修改就直接將其用於 Android。

音訊內容

為應用程式封裝音訊內容的方法有很多,以下列舉幾種:

  • 資源:將音訊檔案放入 res/raw/ 資料夾,即可透過 Resources 的相關 API 輕鬆存取這些檔案。 不過,由於無法直接原生存取這些資源,因此您必須編寫 Java 程式設計語言程式碼,才能複製資源來使用。
  • 資產:將音訊檔案放入 assets/ 資料夾,即可透過 Android 原生資產管理器 API 直接存取這些檔案。如需進一步瞭解這些 API,請參閱標頭檔案 android/asset_manager.handroid/asset_manager_jni.handroid-ndk GitHub 存放區中的範例程式碼會將這些原生資產管理器 API 和 Android 檔案描述元資料定位器搭配使用。
  • 網路:您可以使用 URI 資料定位器直接從網路播放音訊內容。不過,請務必詳閱安全性和權限
  • 本機檔案系統:URI 資料定位器支援本機檔案的 file: 架構 (前提是應用程式可存取本機檔案)。請注意,Android 安全性架構透過 Linux 使用者 ID 和群組 ID 機制限制檔案存取權。
  • 已錄製的內容:應用程式可錄製麥克風輸入的音訊資料並儲存錄音內容,然後於之後播放。範例程式碼會將這種方法用於「播放」短片。
  • 編譯和連結的內嵌內容:您可以直接將音訊內容連結至共享程式庫,然後透過具有緩衝區佇列資料定位器的音訊播放器播放,這種方法最適合用於 PCM 格式短片。範例程式碼將這種方法用於「Hello」和「Android」短片。PCM 資料已透過 bin2c 工具 (並未提供) 轉換為十六進位字串。
  • 即時合成:您的應用程式可以即時合成 PCM 資料,然後透過具有緩衝區佇列資料定位器的音訊播放器播放。這是一種比較進階的技巧,而且詳細的音訊合成介紹不在本文的討論範圍內。

注意:為應用程式搜尋或建立有用的音訊內容不在本文討論範圍內。 您可以在網路上搜尋「互動式音訊」、「遊戲音訊」、「音效設計」和「音訊程式設計」等字詞,就能找出更多資訊。

注意:您有責任確保自己依法可播放或錄製內容。錄製內容時,可能需要考量隱私權問題。

程式碼範例

您可以在 GitHub 頁面中找到這些範例應用程式:

OpenSL ES 的 Android NDK 實作與 OpenSL ES 1.0.1 的參考規範在多個方面都有不同之處。 這些差異是導致您直接從 OpenSL ES 參考規範複製的程式碼範例可能無法用於 Android 應用程式的一大原因。

如要進一步瞭解參考規範和 Android 實作之間的差異,請參閱適用於 Android 的 OpenSL ES