شروع کار با Media Enhancement APIs

‫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 را برای تکالیف «بهبود رسانه» ارائه می‌دهد. اعلام این کتابخانه‌ها در مانیفست شما پیش‌نیازی برای API است تا از شتاب سخت‌افزاری استفاده کند، که برای انجام بهبودهای با کیفیت بالا و تأخیر کم ضروری است. برای اطلاعات بیشتر درباره OpenCL، به پیاده‌سازی‌های OpenCL مراجعه کنید.

‫OpenGL ES کتابخانه‌های گرافیکی بومی موردنیاز برای رندر کردن با عملکرد بالای خروجی‌های بهبود رسانه را ارائه می‌دهد. اعلام این کتابخانه‌ها در مانیفست شما ضروری است تا اطمینان حاصل شود که خط لوله پردازش می‌تواند به‌طور مؤثر رسانه‌های پردازش‌شده را روی سطوح با شتاب سخت‌افزاری نمایش دهد. برای کسب اطلاعات درباره OpenGL، به نمای کلی اسناد OpenGL API مراجعه کنید.

خط لوله پردازش Android باید شتاب سخت‌افزاری داشته باشد تا از گلوگاه‌ها جلوگیری شود. درحالی‌که به‌طور پیش‌فرض برای برنامه‌هایی که API 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) }
}