بدء استخدام واجهات برمجة تطبيقات تحسين الوسائط

‫Media Enhancement API هي أداة فعّالة تستخدم تسريع وحدة معالجة الرسومات (GPU) على الجهاز فقط لتنفيذ تحسينات عالية الجودة على الصور مع تقليل وقت الاستجابة. ويشمل ذلك ميزات مثل ربط درجات الألوان تلقائيًا وإزالة التشويش وإزالة الضوضاء وتحسين الدقة.

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

المهام التابعة في Gradle

أضِف التبعيات التالية إلى ملف app/build.gradle.kts. لتسهيل التنفيذ غير المتزامن وغير الحظر، عليك تضمين إجراءات Kotlin الفرعية وJetpack Media3 للتعامل مع مساحة العرض على الأجهزة.

dependencies {
    // Google Play services Media Enhancement Library (Beta)
    implementation("com.google.android.gms:play-services-media-effect-enhancement:16.0.0-beta04")
}

اطّلِع على تفاصيل الحزمة play-services-media-effect-enhancement في مستودع Maven من Google.

ننصحك أيضًا باستخدام إجراءات Kotlin الروتينية لإدارة جلسات التحسين بشكل غير متزامن.

// Kotlin coroutines for asynchronous API handling
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3")
  implementation("org.jetbrains.kotlinx:kotlinx-coroutines-play-services:1.7.3")

متطلبات ملف البيان في Android

أضِف العناصر التالية داخل علامة <application> في ملف AndroidManifest.xml:

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <application>
        <!-- 1. Google Play services version for runtime compatibility checks -->
        <meta-data
            android:name="com.google.android.gms.version"
            android:value="@integer/google_play_services_version" />
        <!-- 2. Declare OpenCL compute libraries for NPU/GPU neural acceleration -->
        <uses-native-library android:name="libOpenCL.so" android:required="false" />
        <uses-native-library android:name="libOpenCL-car.so" android:required="false" />
        <uses-native-library android:name="libOpenCL-pixel.so" android:required="false" />
        <!-- 3. Declare OpenGL ES for high-performance graphics rendering -->
        <uses-native-library android:name="libGLESv2.so" android:required="false" />
        <uses-native-library android:name="libGLESv3.so" android:required="false" />
    </application>
</manifest>

توفّر OpenCL مكتبات الحوسبة المجمّعة من رموز برمجية أصلية اللازمة لتفعيل التسريع العصبي لوحدة المعالجة العصبية (NPU) ووحدة معالجة الرسومات (GPU) لمهام "تحسين الوسائط". ويُعدّ الإفصاح عن هذه المكتبات في ملف البيان شرطًا أساسيًا كي تستفيد واجهة برمجة التطبيقات من ميزة تسريع الأجهزة، وهي ضرورية لإجراء تحسينات عالية الجودة وبزمن استجابة منخفض. لمزيد من المعلومات حول OpenCL، يمكنك الاطّلاع على عمليات تنفيذ OpenCL.

توفّر OpenGL ES مكتبات الرسومات الأصلية المطلوبة لعرض مخرجات تحسين الوسائط بأداء عالٍ. يُعدّ تعريف هذه المكتبات في ملف البيان أمرًا ضروريًا لضمان قدرة مسار العرض على عرض الوسائط المعالَجة بشكل فعّال على المساحات التي يتم تسريعها باستخدام الأجهزة. للحصول على معلومات حول OpenGL، يُرجى الاطّلاع على نظرة عامة على مستندات OpenGL API.

يجب أن يتم تسريع مسار العرض في Android باستخدام الأجهزة لتجنُّب حدوث أي مؤثِّرات سلبية. يجب ضبط android:hardwareAccelerated="true" بشكلٍ صريح ضمن علامات <activity>، علمًا بأنّ هذه الميزة تكون مفعّلة تلقائيًا للتطبيقات التي تستهدف المستوى 14 من واجهة برمجة التطبيقات أو أعلى.

توافق الجهاز وإعداد الوحدة

توفّر "خدمات Google Play" نماذج تعلُّم الآلة بشكل ديناميكي للحفاظ على مساحة التخزين الأولية لحزمة APK. قبل إجراء التحسينات، يجب أن يستخدم التطبيق EnhancementClient للتحقّق من توفّر الأجهزة المطلوبة، والتأكّد من تنزيل أوزان النماذج اللازمة وتخزينها مؤقتًا على الجهاز. هذه العملية تُجرى لمرة واحدة لكل جهاز.

باستخدام suspendCancellableCoroutine، يمكنك تضمين عمليات معاودة الاتصال المستندة إلى المهام في دوال تعليق Kotlin العادية لتنفيذها بشكل أكثر سلاسة وتسلسلاً:

// Verifies if host hardware supports NPU/GPU acceleration
suspend fun EnhancementClient.isDeviceSupportedAsync(): Boolean = suspendCancellableCoroutine { continuation ->
    this.isDeviceSupported()
        .addOnSuccessListener { result -> continuation.resume(result) }
        .addOnFailureListener { exception -> continuation.resumeWithException(exception) }
}
// Verifies the presence of required neural network models
suspend fun EnhancementClient.isModuleInstalledAsync(): Boolean = suspendCancellableCoroutine { continuation ->
    this.isModuleInstalled()
        .addOnSuccessListener { result -> continuation.resume(result) }
        .addOnFailureListener { exception -> continuation.resumeWithException(exception) }
}