تحذير: تم إيقاف OpenSL ES نهائيًا. على المطوّرين استخدام مكتبة Oboe المفتوحة المصدر المتوفّرة على GitHub. Oboe هو برنامج تضمين لـ C++ يقدّم واجهة برمجة تطبيقات تشبه إلى حد كبير AAudio. يُطلِق Oboe مكتبة AAudio عندما تكون متاحة، ويستخدم OpenSL ES كحل احتياطي إذا لم تكن AAudio متاحة.
يوفّر هذا القسم المعلومات اللازمة لبدء استخدام واجهات برمجة التطبيقات OpenSL ES.
إضافة OpenSL ES إلى تطبيقك
يمكنك استدعاء OpenSL ES من الرمزين C وC++. لإضافة مجموعة ميزات OpenSL ES
الأساسية إلى تطبيقك، أدرِج ملف الرأس OpenSLES.h:
#include <SLES/OpenSLES.h>
لإضافة إضافات Android لـ OpenSL ES،
أدرِج أيضًا ملف الرأس OpenSLES_Android.h:
#include <SLES/OpenSLES_Android.h>
عند تضمين ملف العنوان OpenSLES_Android.h، يتم تضمين العناوين التالية
تلقائيًا:
#include <SLES/OpenSLES_AndroidConfiguration.h> #include <SLES/OpenSLES_AndroidMetadata.h>
ملاحظة: هذه العناوين غير مطلوبة، ولكن يتم عرضها كمساعدة في تعلُّم واجهة برمجة التطبيقات.
الإنشاء وتصحيح الأخطاء
يمكنك دمج OpenSL ES في عملية الإنشاء من خلال تحديده في ملف
Android.mk الذي يُعدّ أحد ملفات الإنشاء في
نظام إنشاء NDK. أضِف السطر التالي إلى
Android.mk:
LOCAL_LDLIBS += -lOpenSLES
لتصحيح الأخطاء بشكلٍ فعّال، ننصحك بفحص قيمة SLresult التي تعرضها معظم واجهتَي برمجة التطبيقات
OpenSL ES. يمكنك استخدام
عمليات التحقق
أو منطق أكثر تقدمًا لمعالجة الأخطاء من أجل تصحيح الأخطاء، ولا يقدّم أيّ منهما
ميزة أساسية للعمل مع OpenSL ES، على الرغم من أنّ أحدهما أو الآخر قد يكونان أكثر ملاءمةً
لحالة استخدام معيّنة.
نستخدم التأكيدات في أمثلة، لأنّها تساعد في رصد الشروط غير الواقعية التي قد تشير إلى خطأ في الترميز. لقد استخدمنا معالجة الأخطاء الصريحة للشروط الأخرى التي يُرجح حدوثها في مرحلة الإنتاج.
تؤدي العديد من أخطاء واجهة برمجة التطبيقات إلى إدخال في السجلّ، بالإضافة إلى رمز نتيجة غير صفري. يمكن أن تقدّم إدخالات السجلّ هذه
تفاصيل إضافية تُثبت أنّها مفيدة بشكل خاص لواجهات برمجة التطبيقات المعقدة نسبيًا، مثل
Engine::CreateAudioPlayer.
يمكنك الاطّلاع على السجلّ من سطر الأوامر أو من Android Studio. لفحص السجل من سطر الأوامر، اكتب ما يلي:
$ adb logcat
لفحص السجلّ من "استوديو Android"، اختَر عرض > نوافذ الأدوات > Logcat. لمزيد من المعلومات، يُرجى الاطّلاع على كتابة السجلّات وعرضها باستخدام Logcat.
مثال على الرمز البرمجي
ننصحك باستخدام نموذج رمز متوافق ومجرب يمكن استخدامه كنموذج لرمزك الخاص، والذي يمكن العثور عليه في مجلّدي audio-echo و native-audio في مستودع GitHub android-ndk.
تنبيه: تحتوي مواصفات OpenSL ES 1.0.1 على نموذج للرمز البرمجي في الملحقات (يمكنك الاطّلاع على Khronos OpenSL ES Registry لمزيد من التفاصيل). مع ذلك، فإنّ الأمثلة الواردة في الملحق ب: نموذج رمز والملحق ج: رمز نموذجي لحالة الاستخدام تستخدم ميزات لا يوفّرها Android. تحتوي بعض الأمثلة أيضًا على أخطاء مطبعية أو تستخدم واجهات برمجة تطبيقات من المحتمل أن تتغير. يُرجى توخي الحذر عند الرجوع إلى هذه الرموز البرمجية، لأنّه على الرغم من أنّها قد تكون مفيدة في فهم معيار OpenSL ES بالكامل، إلا أنّه لا يجب استخدامها كما هي مع Android.
محتوى صوتي
في ما يلي بعض الطرق العديدة لحزمة محتوى صوتي لتطبيقك:
- المَراجع: من خلال وضع ملفاتك الصوتية في مجلد
res/raw/، يمكن الوصول إليها بسهولة من خلال واجهات برمجة التطبيقات المرتبطةResources. ومع ذلك، لا تتوفّر إمكانية وصول مباشرة إلى الموارد، لذا عليك كتابة رمز لغة برمجة Java لنسخها قبل استخدامها. - مواد العرض: عند وضع ملفاتك الصوتية في مجلد
assets/، يمكن الوصول إليها مباشرةً من خلال واجهات برمجة التطبيقات لنظام إدارة مواد العرض الأصلية في Android. اطّلِع على الملفَّين headerandroid/asset_manager.hوandroid/asset_manager_jni.hللحصول على مزيد من المعلومات عن هذين وجهتَي برمجة التطبيقات. إنّ مثال الرمز البرمجي المتوفّر في مستودع GitHub android-ndk يستخدم واجهات برمجة التطبيقات هذه الخاصة بمدير مواد العرض الأصلية مع أداة تحديد مكان بيانات وصف ملف Android. - الشبكة: يمكنك استخدام أداة البحث عن بيانات معرّف الموارد المنتظم (URI) لتشغيل المحتوى الصوتي مباشرةً من الشبكة. ومع ذلك، احرص على قراءة الأمان والأذونات.
- نظام الملفات على الجهاز: يتيح أداة البحث عن البيانات باستخدام عنوان URL استخدام المخطط
file:للملفات على الجهاز، شرط أن يكون بإمكان التطبيق الوصول إلى الملفات. يُرجى العِلم أنّ إطار عمل أمان Android يفرض قيودًا على الوصول إلى الملفات من خلال آليات معرّف مستخدم Linux ومعرّف المجموعة. - المحتوى المسجَّل: يمكن لتطبيقك تسجيل بيانات صوتية من إدخال الميكروفون، وتخزين هذا المحتوى، ثم تشغيله لاحقًا. يستخدم مثال الرمز البرمجي هذه الطريقة لمقطع التشغيل.
- مُجمَّع ومرتبط بشكل مضمّن: يمكنك ربط المحتوى الصوتي مباشرةً بملف APK في
المكتبة المشتركة، ثم تشغيله باستخدام مشغّل صوت يتضمّن أداة لتحديد بيانات قائمة الانتظار في المخزن المؤقت. وهو
الأنسب للمقاطع القصيرة بتنسيق PCM. يستخدم الرمز النموذجي هذا الأسلوب لمقاطع
Hello وAndroid. تم تحويل بيانات PCM إلى سلاسل سداسية عشرية باستخدام أداة
bin2c(غير موفّرة). - التجميع في الوقت الفعلي: يمكن لتطبيقك تجميع بيانات PCM أثناء التشغيل، ثمّ تشغيلها باستخدام مشغّل صوت يتضمّن أداة لتحديد موقع بيانات قائمة الانتظار في المخزن المؤقت. هذه تقنية متقدمة نسبيًا، وتفاصيل تركيب الصوت خارج نطاق هذه المقالة.
ملاحظة: لا يتناول نطاق هذه المقالة كيفية العثور على محتوى صوتي مفيد لتطبيقك أو إنشاؤه. ويمكنك استخدام عبارات بحث على الويب، مثل محتوى صوتي تفاعلي والأصوات الصوتية في اللعبة وتصميم الصوت والبرمجة الصوتية للعثور على مزيد من المعلومات.
تحذير: تقع على عاتقك مسؤولية التأكّد من أنّه يُسمح لك قانونًا بتشغيل المحتوى أو تسجيله. قد تكون هناك اعتبارات خصوصية لتسجيل المحتوى.
عيّنات الرموز البرمجية
تتوفّر نماذج التطبيقات هذه على صفحتنا على GitHub:
- تُنشئ دالة audio-echo حلقة مسار ذهاب وإياب من الإدخال إلى الإخراج.
- Native-audio هو مشغّل/مسجّل صوت بسيط.
يختلف تنفيذ Android NDK لـ OpenSL ES عن المواصفات المرجعية للإصدار OpenSL ES 1.0.1 من حيث عدد الجوانب. هذه الاختلافات هي سبب مهم لعدم عمل نموذج الرمز الذي تنسخه مباشرةً من مواصفات OpenSL ES المرجعية في تطبيق Android.
لمزيد من المعلومات عن الاختلافات بين المواصفة المرجعية وطريقة تنفيذ برمجة تطبيقات Android، يُرجى الاطّلاع على OpenSL ES لنظام التشغيل Android.