إضافات Android

يوسّع 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 نعم نعم لا لا
تأثير Android نعم لا لا نعم
إمكانات تأثيرات Android لا لا نعم لا
إرسال تأثير Android نعم لا لا لا
قائمة انتظار مخزن مؤقت بسيط لنظام Android نعم: المصدر (التشغيل) أو المصدر (فك الترميز) نعم لا لا
محدِّد مواقع بيانات قائمة الانتظار في المخزن المؤقت لنظام Android نعم: المصدر (فك الترميز) لا لا لا
محدِّد بيانات واصف ملفات Android نعم: المصدر لا لا لا
محدد مواقع بيانات قائمة انتظار المخزن المؤقت البسيط في Android نعم: المصدر (التشغيل) أو المصدر (فك الترميز) نعم: مصرف لا لا

واجهة إعداد 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 للتأثيرات الصوتية بدلاً من إضافات تأثيرات 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(). لذلك ننصحك بعدم إنشاء تبعية على أحدهما أو الآخر، بدلاً من ذلك، يجب أن يتمكن تطبيقك من التعامل مع كليهما.

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

على سبيل التيسير، يسمح تطبيق 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 بدون تشغيل فوري. يقدم الجدول أدناه اقتراحات لاستخدام هذه الإضافة والبدائل.

مستوى واجهة برمجة التطبيقات الخيارات البديلة
15 وأقل برنامج ترميز مفتوح المصدر حاصل على ترخيص مناسب
من 16 إلى 20 فئة MediaCodec أو برنامج ترميز مفتوح المصدر يحمل ترخيصًا مناسبًا
21 والأكبر NDK MediaCodec في ملفات العنوان <media/NdkMedia*.h> أو الفئة MediaCodec أو برنامج ترميز مفتوح المصدر يحمل ترخيصًا مناسبًا

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

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

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

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

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

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

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

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

ملاحظة: لفك ترميز بث مرمّز إلى PCM مع عدم تشغيلها على الفور، ننصحك باستخدام الفئة MediaCodec في التطبيقات التي تعمل بالإصدار 4.x من نظام التشغيل Android 4.x (مستويات واجهة برمجة التطبيقات 16–20). بالنسبة إلى التطبيقات الجديدة التي تعمل على نظام التشغيل 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;
يمكنك الاطّلاع على المزيد من المعلومات عن صوت النقطة العائمة في صفحة "عيّنات الصوت".