OpenSL ES لأجهزة Android

توفر هذه الصفحة تفاصيل حول كيفية تنفيذ 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 الحالي كما هو (على الرغم من إيقافها نهائيًا)، يجب ألا تتطلب أي تغييرات فورية في الرمز البرمجي لموقعك الإلكتروني.