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

‫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 مكتبات الحوسبة المجمّعة من رموز برمجية أصلية اللازمة لتفعيل التسريع العصبي لوحدة المعالجة العصبية ووحدة معالجة الرسومات لمهام "تحسين الوسائط". ويُعدّ الإفصاح عن هذه المكتبات في ملف البيان شرطًا أساسيًا لتستفيد واجهة برمجة التطبيقات من ميزة تسريع الأجهزة، وهي ضرورية لإجراء تحسينات عالية الجودة وبوقت استجابة منخفض. لمزيد من المعلومات حول OpenCL، يمكنك الاطّلاع على عمليات تنفيذ OpenCL.

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

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

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

توفّر "خدمات 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) }
}