Media Enhancement API 使用入门

媒体增强 API 是一款强大的工具，可利用设备端 GPU 加速功能执行高质量、低延迟的图片自动美化操作。这包括自动色调映射、去模糊、去噪和放大等功能。

在初始化 API 之前，您必须配置项目依赖项并在清单中声明硬件加速要求。跳过这些配置是导致 GLOBAL_INIT_FAILED 运行时错误的主要原因。

Gradle 依赖项

将以下依赖项添加到 app/build.gradle.kts 文件中。为了便于进行异步、非阻塞执行，请包含 Kotlin 协程和 Jetpack Media3 以进行硬件 Surface 处理。

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 的软件包详情，请参阅 Google 的 Maven 制品库。

我们还建议使用 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 清单要求

在 AndroidManifest.xml 文件的 <application> 标记内添加以下元素：

<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 及更高级别为目标平台的应用，此属性默认处于启用状态，但您仍需在 <activity> 代码中明确设置 android:hardwareAccelerated="true"。

设备兼容性和模块设置

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) }
}