إضافات Android

تحذير: تم إيقاف OpenSL ES نهائيًا. على المطوّرين استخدام مكتبة Oboe المفتوحة المصدر المتوفّرة على GitHub. Oboe عبارة عن برنامج تضمين C++ يوفر واجهة برمجة تطبيقات تشبه إلى حد كبير AAudio: يتصل Oboe بواجهة AAudio عند توفّرها، ويستخدم OpenSL ES كحل احتياطي في حال عدم توفّر AAudio.

توسّع أداة OpenSL ES في Android مواصفات OpenSL ES المرجعية لجعلها متوافقة مع Android، والاستفادة من إمكانيات النظام الأساسي Android ومرونته.

يتوفّر تعريف واجهة برمجة التطبيقات لإضافات Android في OpenSLES_Android.h وملفات الرأس التي تتضمّنها. يمكنك الرجوع إلى OpenSLES_Android.h لمعرفة تفاصيل عن هذه الإضافات. يقع هذا الملف ضمن الدليل الجذر للتثبيت، في الدليل sysroot/usr/include/SLES. ما لم يُذكر خلاف ذلك، تكون جميع الواجهات صريحة.

تحدّ هذه الإضافات من إمكانية نقل تطبيقك إلى عمليات تنفيذ OpenSL ES الأخرى، لأنّها خاصة بنظام Android. يمكنك التخفيف من حدة هذه المشكلة عن طريق أيضًا، تجنُّب استخدام الإضافات أو استخدام #ifdef لاستبعادها أثناء التجميع.

يعرض الجدول التالي الواجهات الخاصة بنظام التشغيل Android وأدوات تحديد مواقع البيانات التي يوفّرها Android OpenSL ES. لكل نوع من أنواع الكائنات. تشير قيم Yes في الخلايا إلى الواجهات والبيانات محددات المواقع المتوفرة لكل نوع من أنواع الكائنات.

واجهة إعداد Android

توفر واجهة إعداد Android وسيلة لضبط والمعلمات الخاصة بالنظام الأساسي للكائنات. تختلف هذه الواجهة عن واجهات OpenSL ES 1.0.1 الأخرى في أنّ تطبيقك يمكنه استخدامها قبل إنشاء العنصر المقابل، وبالتالي، يمكنك ضبط العنصر قبل إنشائه. تشير رسالة الأشكال البيانية ملف العنوان OpenSLES_AndroidConfiguration.h، يوجد في /sysroot/usr/include/SLES، لتوثيق مفاتيح وقيم التهيئة المتاحة التالية:

• نوع البث لمشغّلات الصوت (القيمة التلقائية SL_ANDROID_STREAM_MEDIA).
• ملف الضبط لتسجيل الصوت في مسجّلات الصوت (الإعداد التلقائي SL_ANDROID_RECORDING_PRESET_GENERIC)

يعرض مقتطف الرمز التالي مثالاً على كيفية ضبط نوع البث الصوتي في Android على مقطع صوتي. اللاعب:

// CreateAudioPlayer and specify SL_IID_ANDROIDCONFIGURATION
// in the required interface ID array. Do not realize player yet.
// ...
SLAndroidConfigurationItf playerConfig;
result = (*playerObject)->GetInterface(playerObject,
    SL_IID_ANDROIDCONFIGURATION, &playerConfig);
assert(SL_RESULT_SUCCESS == result);
SLint32 streamType = SL_ANDROID_STREAM_ALARM;
result = (*playerConfig)->SetConfiguration(playerConfig,
    SL_ANDROID_KEY_STREAM_TYPE, &streamType, sizeof(SLint32));
assert(SL_RESULT_SUCCESS == result);
// ...
// Now realize the player here.

يمكنك استخدام رمز مشابه لضبط الإعداد المُسبَق لتطبيق تسجيل الصوت:

// ... obtain the configuration interface as the first four lines above, then:
SLuint32 presetValue = SL_ANDROID_RECORDING_PRESET_VOICE_RECOGNITION;
result = (*playerConfig)->SetConfiguration(playerConfig,
    RECORDING_PRESET, &presetValue, sizeof(SLuint32));

واجهات تأثيرات Android

توفر واجهات إمكانيات التأثير وإرسال التأثيرات والتأثيرات في Android آلية عامة لأحد التطبيقات للاستعلام عن الأجهزة الخاصة بالأجهزة واستخدامها والمؤثرات الصوتية. على الشركات المصنّعة للأجهزة توثيق أي تأثيرات صوتية متاحة متعلّقة بالجهاز وتقدّمها.

يجب أن تستخدم التطبيقات المحمولة واجهات برمجة التطبيقات OpenSL ES 1.0.1 API للحصول على التأثيرات الصوتية بدلاً من Android إضافات التأثيرات.

أداة البحث عن البيانات في أداة وصف ملفات Android

يسمح لك أداة تحديد بيانات ملف الوصف في Android بتحديد مصدر مشغّل الصوت كملف وصف مفتوح مع إذن بالقراءة. يجب أن يكون تنسيق البيانات MIME.

تكون هذه الإضافة مفيدة بشكل خاص مع "أداة إدارة مواد العرض" الأصلية، لأنّه يقرأ التطبيق مواد العرض من حزمة APK من خلال ملف وصفي.

أداة البحث عن بيانات قائمة انتظار المخزن المؤقت البسيطة في Android وواجهتها

في المواصفات المرجعية لـ OpenSL ES 1.0.1، يمكن استخدام قوائم انتظار المخزن المؤقت لمشغلات الصوت فقط، وهي متوافقة مع PCM وتنسيقات البيانات الأخرى. مواصفات واجهة ومحدد بيانات "قائمة انتظار التخزين المؤقت البسيط" في Android متطابقة مع المواصفات المرجعية، باستثناء أمرَين:

• يمكنك استخدام قوائم انتظار التخزين المؤقت البسيطة في Android مع مسجّلات الصوت ومشغّلات الصوت.
• لا يمكنك استخدام تنسيق بيانات PCM إلا مع هذه الطوابير.

للتسجيل، يجب أن يدرِج تطبيقك مخازن مؤقتة فارغة. عندما يُرسِل طلب إعادة الاتصال المسجَّل إشعارًا بأنّ النظام قد انتهى من كتابة البيانات في ذاكرة تخزين مؤقت، يمكن للتطبيق قراءة البيانات من ذاكرة التخزين المؤقت هذه.

ويعمل التشغيل بالطريقة نفسها. لرمز المصدر المستقبلي إلا أننا نقترح أن تستخدم التطبيقات نظام Android قوائم انتظار المخزن المؤقت بدلاً من قوائم انتظار المخزن المؤقت OpenSL ES 1.0.1.

سلوك قائمة انتظار المخزن المؤقت

لا تشمل آلية تنفيذ Android للمواصفات المرجعية الذي يقضي بعودة مؤشر التشغيل إلى البداية من المخزن المؤقت قيد التشغيل حاليًا عند دخول عملية التشغيل في SL_PLAYSTATE_STOPPED الولاية. وقد يتوافق هذا التنفيذ مع هذا السلوك، أو قد يخرج مكان التشغيل. بدون تغيير. نتيجةً لذلك، لا يمكن لتطبيقك افتراض حدوث أي من السلوكَين. لذلك، يجب استدعاء الطريقة BufferQueue::Clear() صراحةً بعد الانتقال إلى SL_PLAYSTATE_STOPPED. يؤدي ذلك إلى ضبط قائمة انتظار المخزن المؤقت على حالة معروفة.

وبالمثل، لا تتوفّر مواصفات تحكم في ما إذا كان يجب أن يكون عامل التفعيل لطلب إعادة الاتصال بقائمة الانتظار المؤقتة هو انتقال إلى SL_PLAYSTATE_STOPPED أو تنفيذ BufferQueue::Clear(). لذلك، ننصحك بعدم إنشاء تبعية على أحدهما أو الآخر وإنما يجب أن يتمكن التطبيق من التعامل مع الاثنين معًا.

الواجهات الديناميكية عند إنشاء العناصر

لتسهيل الاستخدام، يسمح لك تطبيق Android الذي يستخدم OpenSL ES 1.0.1 بتحديد الواجهات الديناميكية عند إنشاء عنصر. يمكنك بدلاً من ذلك استخدام DynamicInterfaceManagement::AddInterface(). لإضافة هذه الواجهات بعد إنشاء مثيلها.

إعداد تقارير عن الإضافات

هناك ثلاث طرق للاستعلام عن ما إذا كان النظام الأساسي متوافقًا مع إضافات Android. هذه الطرق هي:

• Engine::QueryNumSupportedExtensions()
• Engine::QuerySupportedExtension()
• Engine::IsExtensionSupported()

وتُرجع أي من هذه الطرق ANDROID_SDK_LEVEL_<API-level>، حيث API-level هو مستوى واجهة برمجة التطبيقات للنظام الأساسي على سبيل المثال، ANDROID_SDK_LEVEL_23. يعني المستوى 9 أو أعلى لواجهة برمجة التطبيقات الخاصة بالنظام الأساسي أنّ النظام الأساسي متوافق مع الإضافات.

فك ترميز الصوت إلى PCM

يصف هذا القسم إضافة تم إيقافها نهائيًا خاصة بنظام Android إلى الإصدار OpenSL ES 1.0.1. لفك ترميز بث مرمّز إلى PCM بدون تشغيل فوري. يقدِّم الجدول أدناه اقتراحات لاستخدام هذه الإضافة والبدائل.

ملاحظة: لا تتوفّر حاليًا أي مستندات لإصدار NDK من واجهة برمجة التطبيقات MediaCodec. ومع ذلك، يمكنك الرجوع إلى رمز native-codec النموذجي للحصول على مثال.

يشغِّل مشغّل الصوت العادي المحتوى على جهاز صوت، مع تحديد مزيج الإخراج كمصدر بيانات. تختلف إضافة Android عن إضافة iOS في أنّ مشغّل الصوت يؤدي بدلاً من ذلك دورًا في فك التشفير إذا حدّد التطبيق مصدر البيانات إما كمعرّف موارد منتظم أو كمعترِف بيانات وصف ملف Android описанًا باستخدام تنسيق بيانات MIME. في هذه الحالة، يكون مصدر البيانات هو أداة تحديد بيانات "قائمة الانتظار في المخزن المؤقت البسيط" في Android التي تستخدم تنسيق بيانات PCM.

هذه الميزة مخصّصة في المقام الأول للألعاب لتحميل مواد العرض الصوتية مسبقًا عند الانتقال إلى مستوى جديد في اللعبة، وهي مشابهة للوظيفة التي تقدّمها فئة SoundPool .

يجب أن يضيف التطبيق في البداية مجموعة من وحدات التخزين المؤقت الفارغة إلى قائمة انتظار وحدات التخزين المؤقت البسيطة في Android. بعد ذلك، يملؤ التطبيق وحدات التخزين المؤقت ببيانات PCM. يتم تشغيل دالة الاستدعاء لصف انتظار ملف التخزين المؤقت البسيط في Android بعد ملء كل ملف تخزين مؤقت. يعالج معالج معاودة الاتصال بيانات PCM، وتُعيد إدراج المخزن المؤقت الفارغ الآن في قائمة الانتظار، ثم تُرجع. يتحمّل التطبيق مسؤولية تتبُّع وحدات التخزين المؤقت التي تم ترميزها، ولا تتضمّن قائمة مَعلمات طلب الاستدعاء معلومات كافية للإشارة إلى وحدة التخزين المؤقت التي تحتوي على البيانات أو وحدة التخزين المؤقت التي يجب إضافتها إلى "قائمة الانتظار" بعد ذلك.

يُبلغ مصدر البيانات ضمنيًا عن نهاية البث (EOS) من خلال تقديم حدث SL_PLAYEVENT_HEADATEND في نهاية البث المباشر. بعد فك ترميز التطبيق جميع البيانات التي تلقاها، فإنها لا تجري أي اتصالات إضافية لمعاودة الاتصال بقائمة انتظار المخزن المؤقت البسيط في Android.

يتطابق تنسيق بيانات PCM الخاص بوحدة الاستقبال عادةً مع تنسيق مصدر البيانات المشفَّر باستثناء معدّل أخذ العينات وعدد القنوات وعمق البت. ومع ذلك، يمكنك فك الترميز إلى معدل العينة أو عدد القنوات أو عمق البت. للحصول على معلومات عن أحد المتطلبات لاكتشاف تنسيق PCM الفعلي، راجع حدِّد تنسيق بيانات PCM التي تم فك ترميزها من خلال البيانات الوصفية.

تتيح ميزة فك ترميز PCM في OpenSL ES لنظام التشغيل Android إمكانية الإيقاف المؤقت والتقديم/الترجيع الأوّلي، ولا تتيح إمكانية التحكّم في مستوى الصوت أو التأثيرات أو التشغيل المتكرّر أو معدّل التشغيل.

قد يتطلب فك التشفير موارد بناءً على منصة التنفيذ الأساسية لا يمكن تركها خاملة. لذلك، ننصحك بالتأكد من تقديم عدد كافٍ من المخازن المؤقتة بتنسيق PCM الفارغة وإلا، يتضور برنامج فك الترميز. وقد يحدث ذلك، على سبيل المثال، إذا عاد تطبيقك من طلب إعادة الاتصال بصفّ انتظار المخزن المؤقت البسيط في Android بدون إضافة مخزن مؤقت فارغ آخر إلى صفّ الانتظار. إن نتيجة تجويع برنامج فك الترميز هي غير محددة، ولكنها قد تتضمن ما يلي: حذف البيانات التي تم فك ترميزها بيانات PCM أو إيقاف عملية فك الترميز مؤقتًا أو إنهاء برنامج فك الترميز تمامًا

ملاحظة: لفك ترميز بث مُرمَّز إلى PCM مع عدم تشغيله فورًا للتطبيقات التي تعمل على في الإصدار 4.x من نظام التشغيل Android (مستويات واجهة برمجة التطبيقات من 16 إلى 20)، ننصح باستخدام الفئة MediaCodec. بالنسبة إلى التطبيقات الجديدة التي تعمل بنظام التشغيل Android 5.0 (المستوى 21 لواجهة برمجة التطبيقات) أو الإصدارات الأحدث، ننصح باستخدام NDK. ما يعادل <NdkMedia*.h>. تقع ملفات الرأس هذه في الدليل media/ ضمن دليل التثبيت.

فك ترميز البث من ADTS AAC إلى PCM

يعمل مشغّل الصوت كأداة فك ترميز للبث إذا كان مصدر البيانات هو أداة تحديد موقع بيانات قائمة الانتظار المؤقتة في Android التي تستخدم تنسيق بيانات MIME، وكانت أداة جمع البيانات هي أداة تحديد موقع بيانات قائمة الانتظار المؤقتة البسيطة في Android التي تستخدم تنسيق بيانات PCM. اضبط تنسيق بيانات MIME على النحو التالي:

• الحاوية: SL_CONTAINERTYPE_RAW
• سلسلة نوع MIME: SL_ANDROID_MIME_AACADTS

هذه الميزة مخصّصة في المقام الأول لتطبيقات بث الوسائط التي تتعلّق بصوت AAC ولكنها تحتاج إلى إجراء معالجة صوتية مخصّصة قبل التشغيل. إنّ معظم التطبيقات التي تحتاج إلى فك ترميز الصوت إلى PCM повинна تستخدم الطريقة الموضّحة في مقالة فك ترميز الصوت إلى PCM، لأنّ هذه الطريقة أبسط وتتعامل مع المزيد من تنسيقات الصوت. إنّ الأسلوب الموضّح هنا هو نهج أكثر تخصصًا، ولا يُستخدَم إلا في حال انطباق هذين الشرطَين:

• مصدر الصوت المضغوط هو مجموعة من إطارات AAC المضمّنة في عناوين ADTS.
• يدير التطبيق هذا البث. لا تقع البيانات داخل مورد شبكة يكون معرفه هو معرف موارد منتظم (URI) أو داخل ملف محلي يكون معرفه واصف ملف.

من المفترض أن يدرِج التطبيق مجموعة من المخازن المؤقتة التي تم ملؤها في قائمة انتظار المخزن المؤقت Android في البداية. يحتوي كل مخزن مؤقت على إطار ADTS AAC كامل أو أكثر. يتم تنشيط معاودة الاتصال لقائمة انتظار المخزن المؤقت لنظام التشغيل Android بعد إفراغ كل ذاكرة تخزين مؤقت. من المفترض أن يُعيد معالِج طلب الاستدعاء ملء المخزن المؤقت وإعادة إدراجه في قائمة الانتظار، ثم يعود. لا يحتاج التطبيق إلى تتبع الموارد الاحتياطية المشفرة؛ مَعلمة معاودة الاتصال معلومات كافية لتحديد المورد الاحتياطي الذي يجب وضعه في قائمة الانتظار بعد ذلك. يتم وضع علامة EOS على نهاية البث بشكل واضح من خلال إدراج عنصر EOS في قائمة الانتظار. بعد انتهاء فترة التوفّر، لن يُسمح بإضافة أي تطبيقات أخرى إلى قائمة الانتظار.

نوصيك بالتأكد من تقديم كامل يقوم ADTS AAC بتخزين مؤقت، لتجنب تجويع برنامج فك الترميز. قد يحدث ذلك، على سبيل المثال، إذا كان تطبيقك يعود من طلب إعادة الاتصال بقائمة انتظار وحدة التخزين المؤقت في Android بدون إضافة وحدة تخزين مؤقت أخرى كاملة إلى قائمة الانتظار. لم يتم تحديد نتيجة تجويع برنامج فك الترميز.

في جميع الجوانب باستثناء مصدر البيانات، تكون طريقة فك ترميز البث هي نفسها الذي يصفه فك ترميز الصوت إلى PCM.

على الرغم من تشابه الأسماء، فإنّ "قائمة انتظار وحدة التخزين المؤقت" في Android ليست مماثلة لقائمة انتظار وحدة التخزين المؤقت البسيطة في Android. يستخدم برنامج ترميز البث كلا النوعَين من قوائم الانتظار المؤقتة: قائمة انتظار مؤقتة في Android لمصدر بيانات ADTS AAC وقائمة انتظار مؤقتة بسيطة في Android لوجهة بيانات PCM . للحصول على مزيد من المعلومات حول واجهة برمجة تطبيقات قائمة انتظار المخزن المؤقت البسيط على Android، يمكنك الاطّلاع على نظام التشغيل Android. وواجهة ومحدِّد موقع بيانات قائمة انتظار المخزن المؤقت البسيط. لمزيد من المعلومات حول واجهة برمجة تطبيقات قائمة انتظار المخزن المؤقت على Android، يمكنك الاطّلاع على الملف index.html في الدليل docs/Additional_library_docs/openmaxal/ ضمن جذر التثبيت.

تحديد تنسيق بيانات PCM التي تم فك ترميزها من خلال البيانات الوصفية

واجهة SLMetadataExtractionItf هي جزء من مواصفات المرجع. ومع ذلك، فإن مفاتيح بيانات التعريف التي تشير إلى التنسيق الفعلي لبيانات PCM التي تم فك ترميزها مخصصة Android يحدِّد ملف العنوان OpenSLES_AndroidMetadata.h مفاتيح البيانات الوصفية هذه. يقع ملف العنوان هذا ضمن دليل التثبيت الجذري، في الدليل /sysroot/usr/include/SLES.

تتوفّر فهارس مفاتيح البيانات الوصفية مباشرةً بعد انتهاء تنفيذ الطريقة Object::Realize(). ومع ذلك، فإن القيم المرتبطة ليست متاح إلى أن يفكّ التطبيق ترميز أول بيانات مشفّرة. جيدة التدريب العملي على البحث عن الفهارس الرئيسية في سلسلة التعليمات الرئيسية بعد استدعاء طريقة Object::Realize، وقراءة قيم البيانات الوصفية لتنسيق PCM بطريقة بسيطة في Android معالِج معاودة الاتصال لقائمة انتظار المخزن المؤقت عند طلبه لأول مرة. يمكنك الرجوع إلى مثال الرمز البرمجي في حزمة ‎NDK للحصول على أمثلة على استخدام هذه الواجهة.

أسماء مفاتيح البيانات الوصفية ثابتة، ولكنّ فهارس المفاتيح غير موثَّقة، وقد تتغيّر. يجب ألا يفترض التطبيق أنّ الفهارس تظل موجودة في عمليات التنفيذ المختلفة، وألا يفترض أنّه تشترك عدّة نُسخ من العناصر في الفهارس ضمن عملية التنفيذ نفسها.

بيانات الأعداد العائمة

يمكن لأي تطبيق يعمل على نظام التشغيل Android 5.0 (المستوى 21 من واجهة برمجة التطبيقات) والإصدارات الأحدث تقديم بيانات إلى مشغِّل الصوت في تنسيق نقطة عائمة أحادي الدقة.

في نموذج الرمز التالي، تنشئ الطريقة Engine::CreateAudioPlayer() مشغّل صوت. التي تستخدم بيانات النقطة العائمة:

#include <SLES/OpenSLES_Android.h>
...
SLAndroidDataFormat_PCM_EX pcm;
pcm.formatType = SL_ANDROID_DATAFORMAT_PCM_EX;
pcm.numChannels = 2;
pcm.sampleRate = SL_SAMPLINGRATE_44_1;
pcm.bitsPerSample = 32;
pcm.containerSize = 32;
pcm.channelMask = SL_SPEAKER_FRONT_LEFT | SL_SPEAKER_FRONT_RIGHT;
pcm.endianness = SL_BYTEORDER_LITTLEENDIAN;
pcm.representation = SL_ANDROID_PCM_REPRESENTATION_FLOAT;
...
SLDataSource audiosrc;
audiosrc.pLocator = ...
audiosrc.pFormat = &pcm;