Começar a usar as APIs Media Enhancement

A API Media Enhancement é uma ferramenta poderosa que usa a aceleração de GPU no dispositivo para fazer melhorias de imagem de alta qualidade e baixa latência. Isso inclui recursos como mapeamento automático de tons, remoção de desfoque e ruído e aumento da resolução.

Antes de inicializar a API, configure as dependências do projeto e declare os requisitos de aceleração de hardware no manifesto. Ignorar essas configurações é a principal causa de erros de tempo de execução do GLOBAL_INIT_FAILED.

Dependências do Gradle

Adicione as seguintes dependências ao arquivo app/build.gradle.kts. Para facilitar a execução assíncrona e sem bloqueio, inclua corrotinas do Kotlin e Jetpack Media3 para processamento de superfície de hardware.

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

Consulte os detalhes do pacote para play-services-media-effect-enhancement no repositório Maven do Google.

Também recomendamos o uso de corrotinas Kotlin para gerenciar as sessões de melhoria de forma assíncrona.

// 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")

Requisitos de manifesto do Android

Adicione os seguintes elementos à tag <application> do arquivo 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>

O OpenCL fornece as bibliotecas de computação nativas necessárias para ativar a aceleração neural de NPU e GPU para tarefas de melhoria de mídia. Declarar essas bibliotecas no manifesto é um pré-requisito para que a API aproveite a aceleração de hardware, essencial para fazer melhorias de alta qualidade e baixa latência. Para mais informações sobre o OpenCL, consulte Implementações do OpenCL.

O OpenGL ES fornece as bibliotecas de gráficos nativas necessárias para a renderização de alto desempenho de saídas de melhoria de mídia. Declarar essas bibliotecas no manifesto é essencial para garantir que o pipeline de renderização possa mostrar mídia processada de maneira eficaz em superfícies aceleradas por hardware. Para informações sobre OpenGL, consulte a visão geral da documentação da API OpenGL.

O pipeline de renderização do Android precisa ser acelerado por hardware para evitar gargalos. Embora esteja ativado por padrão para apps direcionados à API 14 ou mais recente, defina explicitamente android:hardwareAccelerated="true" nas tags <activity>.

Compatibilidade do dispositivo e configuração do módulo

O Google Play Services entrega modelos de machine learning de forma dinâmica para conservar o espaço de armazenamento inicial do APK. Antes de fazer melhorias, o aplicativo precisa usar o EnhancementClient para verificar o suporte de hardware e garantir que os pesos do modelo necessários sejam baixados e armazenados em cache localmente. Esse processo ocorre só uma vez por dispositivo.

Usando suspendCancellableCoroutine, você pode encapsular os callbacks do cliente baseados em tarefas em funções de suspensão padrão do Kotlin para uma execução mais limpa e sequencial:

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