توفر هذه الصفحة تفاصيل حول كيفية تنفيذ NDK لـ OpenSL تختلف ESTM عن المواصفات المرجعية لـ OpenSL ES 1.0.1. عند استخدام نموذج التعليمات البرمجية من قد تحتاج إلى تعديلها لتعمل على نظام Android.
تتوفّر جميع الميزات في الإصدار 2.3 (المستوى 9 من واجهة برمجة التطبيقات) والإصدارات الأحدث من نظام التشغيل Android، ما لم يُذكر خلاف ذلك. بعض الميزات متوفّرة فقط لنظام التشغيل Android 4.0 (المستوى 14 لواجهة برمجة التطبيقات). ملاحظة هذه الأمور.
ملاحظة: يذكر مستند تعريف التوافق مع Android (CDD) الأجهزة والبرامج. متطلبات جهاز Android متوافق. عرض التوافق مع Android للحصول على مزيد من المعلومات حول برنامج التوافق بشكل عام، CDD لمستند CDD الفعلي.
يوفّر OpenSL ES شهادة C لغوية يمكن الوصول إليها أيضًا باستخدام C++. يعرض ميزات مشابهة للصوت من واجهات برمجة تطبيقات Android Java التالية:
وكما هو الحال مع كل مجموعة أدوات تطوير البرامج (NDK) الأصلية لنظام التشغيل Android، فإن الغرض الأساسي من OpenSL ES يسهّل Android تنفيذ المكتبات المشتركة ليتم استدعاؤها باستخدام Java Native الواجهة (JNI) ). لم يتم تصميم NDK لكتابة تطبيقات C/C++ البحتة. ومع ذلك، تعد OpenSL ES من واجهة برمجة التطبيقات كاملة الميزات، ونتوقع أن تكون قادرًا على تلبية معظم احتياجاتك الصوتية باستخدام واجهة برمجة التطبيقات هذه فقط، بدون طلبات إضافية للترميز الذي يتم تشغيله في وقت تشغيل Android.
ملاحظة: وبناءً على OpenSL ES، لا تُعتبر واجهة برمجة تطبيقات الصوت الأصلي (الصوت العالي الأداء) من Android أي ملف شخصي للإصدار 1.0.1 من OpenSL ES (لعبة أو موسيقى أو هاتف) هذا بسبب لا ينفِّذ Android جميع الميزات التي يتطلبها أي ملف شخصي. أي حالات معروفة يختلف سلوك Android عن المواصفات الموضحة في إضافات Android.
الميزات المكتسبة من مواصفات المرجع
ويكتسب تطبيق Android NDK لـ OpenSL ES الكثير من مجموعة الميزات من مواصفات المراجع، مع بعض القيود.
نقاط الدخول العالمية
يدعم OpenSL ES لنظام التشغيل Android جميع نقاط الإدخال العامة في مواصفات Android. تشمل نقاط الدخول هذه ما يلي:
slCreateEngine
slQueryNumSupportedEngineInterfaces
slQuerySupportedEngineInterfaces
الكائنات والواجهات
يوضح الجدول التالي الكائنات والواجهات التي يتم تنفيذ Android NDK عليها يدعم OpenSL ES. إذا ظهرت القيمة Yes في الخلية، يعني ذلك أنّ الميزة متاحة في هذه الخلية. التنفيذ.
إتاحة Android NDK للكائنات والواجهات.
الميزة | مشغِّل الصوت | مسجِّل الصوت | محرّك | تشكيلة الإخراج |
---|---|---|---|---|
تحسين الصوت العميق الخفيض | نعم | لا | لا | نعم |
قائمة انتظار المخزن المؤقت | نعم | لا | لا | لا |
محدِّد موقع بيانات قائمة انتظار المخزن المؤقت | نعم: المصدر | لا | لا | لا |
إدارة الواجهة الديناميكية | نعم | نعم | نعم | نعم |
إرسال التأثير | نعم | لا | لا | لا |
محرّك | لا | لا | نعم | لا |
الصدى البيئي | لا | لا | لا | نعم |
معادِل الصوت | نعم | لا | لا | نعم |
محدِّد مواقع بيانات جهاز الإدخال والإخراج | لا | نعم: المصدر | لا | لا |
استخراج البيانات الوصفية | نعم: فك الترميز إلى PCM | لا | لا | لا |
كتم الصوت منفردًا | نعم | لا | لا | لا |
كائن | نعم | نعم | نعم | نعم |
أداة البحث عن أماكن مجموعة الإخراج | نعم: مغاسل | لا | لا | لا |
تشغيل | نعم | لا | لا | لا |
معدّل التشغيل | نعم | لا | لا | لا |
حالة الجلب المُسبَق | نعم | لا | لا | لا |
تردّد معدّ مسبقًا | لا | لا | لا | نعم |
تسجيل | لا | نعم | لا | لا |
استدعاء | نعم | لا | لا | لا |
محدِّد موقع بيانات معرّف الموارد المنتظم (URI) | نعم: المصدر | لا | لا | لا |
أداة المحاكاة الظاهرية | نعم | لا | لا | نعم |
مستوى الصوت | نعم | لا | لا | لا |
يوضّح القسم التالي القيود المفروضة على بعض هذه الميزات.
القيود
تنطبق بعض القيود على الميزات الموجودة في الجدول 1. هذه القيود تختلف عن مواصفات المراجع. يوفر باقي هذا القسم المعلومات حول هذه الاختلافات.
إدارة الواجهة الديناميكية
لا يتيح OpenSL ES لجهاز Android استخدام RemoveInterface
أو
ResumeInterface
مجموعات التأثير: صدى البيئة المحيطة والصدى المُعد مسبقًا
لا يمكن أن يكون لديك صدى بيئي وصدى صوت مُعدّ مسبقًا على مزيج الإخراج نفسه.
قد تتجاهل المنصة طلبات التأثير إذا قدرت أن سيكون حِمل وحدة المعالجة المركزية (CPU) مرتفعًا جدًا.
إرسال التأثير
تتيح SetSendLevel()
مستوى إرسال واحد لكل مشغّل صوت.
الصدى البيئي
لا يتوافق الصدى البيئي مع reflectionsDelay
،
reflectionsLevel
، أو reverbDelay
حقلاً من
هيكل SLEnvironmentalReverbSettings
.
تنسيق بيانات MIME
لا يمكنك استخدام تنسيق بيانات MIME إلا مع محدد موقع بيانات معرّف الموارد المنتظم (URI) ومع مقطع صوتي فقط لاعب. لا يمكنك استخدام تنسيق البيانات هذا لمسجّل صوت.
يتطلّب تطبيق OpenSL ES على Android إعداد mimeType
.
إلى NULL
أو سلسلة UTF-8 صالحة يجب عليك أيضًا تهيئة
containerType
إلى قيمة صالحة.
في غياب اعتبارات أخرى، مثل إمكانية النقل إلى منصات أخرى
عمليات التنفيذ أو تنسيقات المحتوى التي لا يستطيع التطبيق التعرُّف عليها من خلال العنوان
ننصحك
ضبط mimeType
على NULL
وcontainerType
إلى SL_CONTAINERTYPE_UNSPECIFIED
.
يتوافق OpenSL ES لنظام التشغيل Android مع تنسيقات الصوت التالية، طالما أن نظام Android الأساسي يتوافق معها أيضًا:
- WAV PCM.
- قانون WAV.
- WAV ulaw.
- MP3 Ogg Vorbis.
- AAC LC
- HE-AACv1 (AAC+ )
- HE-AACv2 (محسّن AAC+ )
- AMR.
- تنسيق FLAC
ملاحظة: للحصول على قائمة بتنسيقات الصوت المتوافقة مع Android، يُرجى الانتقال إلى تنسيقات الوسائط المسموح بها:
تنطبق القيود التالية على التعامل مع هذه التنسيقات وغيرها من التنسيقات في هذه تنفيذ OpenSL ES:
- الترميز المتقدّم للصوت يجب وضع التنسيقات ضمن حاوية MP4 أو ADTS.
- لا يتوافق OpenSL ES لجهاز Android. MIDI:
- تطبيق WMA ليس جزءًا من AOSP، ونحن لم يتم التحقق من توافقه مع OpenSL ES لنظام Android.
- لا يتوافق تنفيذ Android NDK من OpenSL ES مع الزيارات المباشرة. تشغيل محتوى DRM أو المحتوى المشفّر. لتشغيل محتوى صوتي محمي، يجب: فك تشفيره في التطبيق قبل تشغيله، مع فرض التطبيق أي سياسة لإدارة الحقوق الرقمية القيود.
الطرق المتعلقة بالأشياء
لا يتيح OpenSL ES لنظام Android استخدام الطرق التالية لمعالجة العناصر:
Resume()
RegisterCallback()
AbortAsyncOperation()
SetPriority()
GetPriority()
SetLossOfControlInterfaces()
تنسيق بيانات PCM
PCM هو تنسيق البيانات الوحيد الذي يمكنك استخدامه مع قوائم انتظار المخزن المؤقت. تضمين نبضي مشفر (PCM) متوافق إعدادات التشغيل في ما يلي الخصائص التالية:
- 8 بت غير موقَّعة أو موقّعة 16 بت
- صوت أحادي أو استيريو.
- ترتيب وحدات البايت الصغيرة.
- نماذج لمعدلات:
- 8000 هرتز
- 11,025 هرتز
- 12000 هرتز.
- 16000 هرتز
- 22050 هرتز
- 24000 هرتز
- 32000 هرتز.
- 44.100 هرتز
- 48000 هرتز
تتوفر التهيئات التي يدعمها OpenSL ES في Android للتسجيل: تعتمد على الجهاز تتوفّر عادةً حزمة 16000 هرتز أحادية/16 بت بغض النظر عن الجهاز.
تكون قيمة الحقل samplesPerSec
بوحدات المللي هرتز، على الرغم من القيمة المضللة
الاسم. لتجنب استخدام قيمة خاطئة بدون قصد، ننصحك بإعداد هذا الحقل باستخدام
وهو أحد الثوابت الرمزية المحددة لهذا الغرض، مثل SL_SAMPLINGRATE_44_1
.
Android 5.0 (مستوى واجهة برمجة التطبيقات 21) والإصدارات الأحدث بيانات النقطة العائمة.
معدّل التشغيل
يشير معدل التشغيل في OpenSL ES إلى السرعة التي يعرض أي كائن بيانات، معبرًا عنها بأجزاء من السرعة العادية أو لكل ميل. على سبيل المثال: فإن معدل التشغيل من 1000 لكل ميل يساوي 1000/1000، أو السرعة العادية. نطاق السعر هو فاصل زمني مغلق يعبّر عن نطاق من معدلات التشغيل المحتملة.
قد يختلف التوافق مع نطاقات معدلات التشغيل والإمكانات الأخرى حسب الفئة العمرية.
حول إصدار النظام الأساسي وتنفيذه. يمكن لتطبيقك تحديد هذه الإمكانات في وقت التشغيل من خلال
باستخدام PlaybackRate::GetRateRange()
أو
PlaybackRate::GetCapabilitiesOfRate()
لطلب البحث عن الجهاز.
يتوافق الجهاز عادةً مع نطاق المعدّل نفسه لمصدر بيانات بتنسيق PCM، مع معدّل اتحاد. ويتراوح من 1000 لكل ميل إلى 1000 لكل ميل للأشكال الأخرى؛ أي أن نطاق معدل الانسجام هو فعالية قيمة واحدة.
تسجيل
لا يتيح OpenSL ES لجهاز Android استخدام SL_RECORDEVENT_HEADATLIMIT
أو حدثَين (SL_RECORDEVENT_HEADMOVING
).
استدعاء
تتيح الطريقة SetLoop()
إمكانية تكرار الملف بالكامل. لتمكين التكرار الحلقي،
اضبط المعلمة startPos
على 0، والمعلمة endPos
إلى SL_TIME_UNKNOWN
.
محدِّد موقع بيانات قائمة انتظار المخزن المؤقت
يتوافق مشغِّل الصوت أو المسجّلة الذكية مع محدِّد مواقع البيانات لقائمة انتظار المخزن المؤقت مع تنسيق بيانات PCM فقط.
محدِّد مواقع بيانات جهاز الإدخال والإخراج
لا يدعم OpenSL ES لنظام Android استخدام محدِّد موقع بيانات جهاز الإدخال والإخراج إلا إذا كان لديك
حدّد محدِّد المواقع كمصدر البيانات لـ Engine::CreateAudioRecorder()
.
عليك إعداد محدِّد مواقع بيانات الجهاز باستخدام القيم المضمَّنة في مقتطف الرمز التالي:
SLDataLocator_IODevice loc_dev = {SL_DATALOCATOR_IODEVICE, SL_IODEVICE_AUDIOINPUT, SL_DEFAULTDEVICEID_AUDIOINPUT, NULL};
محدِّد موقع بيانات معرّف الموارد المنتظم (URI)
لا يمكن لـ OpenSL ES لنظام Android استخدام محدد موقع بيانات معرف الموارد المنتظم (URI) إلا مع تنسيق بيانات MIME،
لمشغّلات الصوت فقط لا يمكنك استخدام محدِّد موقع بيانات URI لمسجّل صوت. يمكن لعنوان URL فقط
استخدام المخططَين http:
وfile:
المخطّطات الأخرى، مثل https:
ftp:
، أو
لا يُسمح باستخدام content:
.
لم نتأكد من توافق rtsp:
مع الصوت على نظام Android الأساسي.
هياكل البيانات
يتوافق Android مع هياكل بيانات OpenSL ES 1.0.1 التالية:
SLDataFormat_MIME
SLDataFormat_PCM
SLDataLocator_BufferQueue
SLDataLocator_IODevice
SLDataLocator_OutputMix
SLDataLocator_URI
SLDataSink
SLDataSource
SLEngineOption
SLEnvironmentalReverbSettings
SLInterfaceID
إعدادات النظام الأساسي
تم تصميم OpenSL ES لنظام التشغيل Android ليناسب التطبيقات ذات سلاسل المحادثات المتعددة، كما أنه آمن مع سلاسل المحادثات. وهو يدعم محرك واحد لكل تطبيق وما يصل إلى 32 عنصرًا لكل محرك. قد تتضمن ذاكرة الجهاز ووحدة المعالجة المركزية (CPU) المتاحة تقييد عدد الكائنات القابل للاستخدام بشكل أكبر.
يتم التعرّف على خيارات المحرّكات هذه، ولكن يتم تجاهلها من قِبل slCreateEngine
:
SL_ENGINEOPTION_THREADSAFE
SL_ENGINEOPTION_LOSSOFCONTROL
يمكن استخدام OpenMAX AL وOpenSL ES معًا في التطبيق نفسه. في هذه الحالة، هناك عنصر محرّك مشترَك واحد داخليًا، والحدّ الأقصى البالغ 32 عنصرًا مشتركًا بين OpenMAX AL وOpenSL ES. وفي هذه الحالة، يجب على التطبيق إنشاء محرِّك البحث واستخدام كلا المحرّكَين، وفي النهاية وتدمير كلا المحركين. تحافظ عملية التنفيذ على عدد المراجع في المحرّك المشترَك لكي أنه تم إتلافه بشكل صحيح خلال عملية التدمير الثانية.
ملاحظات البرمجة
ملاحظات برمجة OpenSL ES توفير معلومات تكميلية لضمان التنفيذ الصحيح لـ OpenSL ES.
ملاحظة:
للتيسير عليك، أدرجنا نسخة من مواصفات OpenSL ES 1.0.1 مع NDK في
docs/opensles/OpenSL_ES_Specification_1.0.1.pdf
مشاكل النظام الأساسي
يصف هذا القسم المشاكل المعروفة في الإصدار الأولي من النظام الأساسي الذي يتوافق مع واجهات برمجة التطبيقات هذه.
إدارة الواجهة الديناميكية
ميزة "DynamicInterfaceManagement::AddInterface
" لا تعمل. بدلاً من ذلك، حدد الواجهة في
المصفوفة التي يتم تمريرها إلى Create()
، كما هو موضح في مثال الرمز الخاص بالصدى البيئي.
التخطيط للإصدارات المستقبلية من OpenSL ES
تستند واجهات برمجة التطبيقات الصوتية العالية الأداء في Android إلى Khronos Group OpenSL ES 1.0.1. أصدرت شركة Khronos نسخة منقحة 1.1 من المعيار. تشير رسالة الأشكال البيانية تتضمن النسخة المنقحة ميزات جديدة وتوضيحات وتصحيحات للأخطاء المطبعية بعض حالات عدم التوافق. معظم حالات عدم التوافق المتوقعة تكون طفيفة نسبيًا أو مناطق OpenSL ES غير المتوافقة مع Android.
تطبيق التي تم تطويرها بهذا الإصدار على الإصدارات المستقبلية من نظام Android الأساسي، بشرط اتباع الإرشادات الموضحة في خطة النظام الثنائي التوافق أدناه.
ملاحظة: لا يُعد التوافق مع المصادر المستقبلية هدفًا. أي إذا تمت الترقية إلى إصدار أحدث من NDK، قد تحتاج إلى تعديل رمز مصدر التطبيق ليتوافق مع واجهة برمجة التطبيقات الجديدة نتوقع أن يكون معظم ستكون هذه التغييرات طفيفة؛ يمكنك الاطّلاع على التفاصيل أدناه.
التخطيط للتوافق الثنائي
نقترح أن يتّبع تطبيقك هذه الإرشادات لتحسين التوافق الثنائي في المستقبل:
- لا تستخدِم سوى المجموعة الفرعية الموثَّقة من الميزات المتوافقة مع Android من الإصدار OpenSL ES 1.0.1.
- لا تعتمد على رمز نتيجة معين لإجراء عملية غير ناجحة؛ كن مستعدًا للتعامل باستخدام رمز نتيجة مختلف.
- تعمل معالِجات معاودة الاتصال بالتطبيق بشكل عام في سياق مقيَّد. يجب كتابتها أداء عملهم بسرعة، ثم العودة في أقرب وقت ممكن. عدم تنفيذ عمليات معقدة داخل معالج معاودة الاتصال. على سبيل المثال، ضمن معاودة الاتصال لإكمال قائمة انتظار المخزن المؤقت، يمكنك إدراج مخزن مؤقت آخر في قائمة انتظار ولكن لا تنشئ مشغل صوت.
- يجب أن تكون معالِجات معاودة الاتصال جاهزة ليتم طلبها بشكل متكرر أكثر أو أقل، وأنواع الأحداث الإضافية، كما يجب أن تتجاهل أنواع الأحداث التي لا يتم التعرف عليها. عمليات معاودة الاتصال التي مع قناع حدث مكون من أنواع أحداث مُفعَّلة، ينبغي تحضيره ليتم استدعاؤه مع مجموعة بتات متعددة لنوع الحدث في وقت واحد. استخدام "&" لاختبار كل وحدة بت الخاصة بالحدث بدلاً من حافظة تبديل.
- استخدِم حالة الجلب المُسبَق وعمليات معاودة الاتصال كمؤشرات عامة للتقدم، ولكن لا تعتمد على مستويات تعبئة محددة غير قابلة للتغيير في البرنامج أو تسلسلات معاودة الاتصال. معنى تعبئة حالة الجلب المسبق وقد يتغير سلوك المستخدم في ما يتعلق بالأخطاء التي يتم اكتشافها أثناء الجلب المسبق.
ملاحظة: راجع سلوك قائمة انتظار المخزن المؤقت لمزيد من التفاصيل.
التخطيط للتوافق مع المصادر
كما ذكرنا، يُتوقع عدم توافق رمز المصدر في الإصدار التالي من OpenSL ES من مجموعةKronos Group. تشمل مجالات التغيير المحتملة ما يلي:
- من المتوقع أن تحدث تغييرات مهمة في واجهة قائمة انتظار المخزن المؤقت، وخاصةً في المناطق
BufferQueue::Enqueue
وقائمة المعلَمات لـslBufferQueueCallback
اسم الحقلSLBufferQueueState.playIndex
. نوصي بأن يستخدم رمز التطبيق بدلاً من ذلك، يتم استخدام قوائم انتظار المخزن المؤقت البسيط في Android. في المثال الكود المقدم مع NDK، فقد استخدمنا قوائم انتظار المخزن المؤقت البسيط في Android لتشغيل لهذا السبب. (كما نستخدم أيضًا قائمة انتظار المخزن المؤقت البسيط في Android للتسجيل وفك ترميز PCM، ولكن لأن الإصدار العادي من OpenSL ES 1.0.1 لا يتيح التسجيل أو فك الترميز إلى بيانات قائمة انتظار المخزن المؤقت. بالوعاء). - ستكون هناك إضافة
const
إلى معلَمات الإدخال التي تم تمريرها كمرجع. إلىSLchar *
حقول الترتيب المستخدمة كقيم إدخال. ينبغي ألا يتطلب ذلك أي تغييرات على التعليمة البرمجية. - سيتم استبدال الأنواع غير الموقَّعة لبعض المَعلمات الموقَّعة حاليًا.
قد تحتاج إلى تغيير نوع المَعلمة من
SLint32
إلىSLuint32
أو ما شابه ذلك، أو لإضافة ممثل. - ينسخ
Equalizer::GetPresetName
السلسلة إلى ذاكرة التطبيق بدلاً من إرجاعه مؤشر لذاكرة التنفيذ. سيكون هذا تغييرًا كبيرًا، لذا ننصحك فإما أن تتجنب استدعاء هذه الطريقة، أو تعزل استخدامك لها. - ستكون هناك حقول إضافية في أنواع البنية. بالنسبة لمعلمات الإخراج، ستكون هذه الحقول الجديدة ولكن بالنسبة إلى معلمات الإدخال، يجب تهيئة الحقول الجديدة. لحسن الحظ، من المتوقع أن تكون جميع هذه الحقول في مناطق غير متاحة في نظام التشغيل Android.
- الواجهة ستتغير المعرفات الفريدة العامة (GUID). ارجع إلى الواجهات حسب الاسم الرمزي بدلاً من المعرّف الفريد العالمي لتجنُّب والتبعية.
- سيتم تغيير قيمة "
SLchar
" منunsigned char
إلىchar
. يؤثر هذا بشكل أساسي محدد موقع بيانات معرف الموارد المنتظم (URI) وتنسيق بيانات MIME. - ستتم إعادة تسمية "
SLDataFormat_MIME.mimeType
" إلى "pMimeType
" سيتم تغيير اسمSLDataLocator_URI.URI
إلىpURI
. ننصحك بتهيئة بنيتَي البياناتSLDataFormat_MIME
وSLDataLocator_URI
باستخدام قائمة قيم مضمّنة بين قوسين ومفصولة بفواصل، بدلاً من اسم الحقل، لعزل التعليمة البرمجية من هذا التغيير. يتم استخدام هذا الأسلوب في مثال التعليمة البرمجية. - لا يسمح الحقل
SL_DATAFORMAT_PCM
للتطبيق بتحديد تمثيل البيانات كعدد صحيح بعلامة أو عدد صحيح غير موقَّع أو نقطة عائمة التنفيذ في Android أن بيانات 8 بت عبارة عن عدد صحيح غير موقَّع، وأن 16 بت هي عدد صحيح بعلامة. بالإضافة إلى ذلك،samplesPerSec
هي دالة خاطئة، لأنّ الوحدات الفعلية هي ملي هرتز. هذه المشاكل متوقّعة. سيتم تناولها في إصدار OpenSL ES القادم، والذي سيقدم بيانات PCM جديدة موسّعة يسمح للتطبيق بتحديد التمثيل بشكل صريح ويصحح اسم الحقل. بما أنّ هذا سيكون تنسيق بيانات جديدًا، وسيظل تنسيق بيانات PCM الحالي كما هو (على الرغم من إيقافها نهائيًا)، يجب ألا تتطلب أي تغييرات فورية في الرمز البرمجي لموقعك الإلكتروني.