L'API Media Enhancement fornisce una soluzione di AI on-device a bassa latenza che tutela la privacy e sfrutta l'accelerazione hardware per offrire miglioramenti multimediali di alta qualità senza aumentare le dimensioni dell'APK. Per saperne di più, consulta Informazioni sulle funzionalità di miglioramento dei contenuti multimediali.
La modalità Bitmap statica (EnhancementMode.BITMAP) è progettata per l'elaborazione di immagini statiche decodificate.
Il funzionamento in modalità Bitmap richiede che il sistema operativo serializzi i dati dei pixel non compressi e li copi dalla memoria della CPU alla memoria della GPU tramite il bus di sistema, restituendo il frame elaborato tramite una copia inversa. È ottimizzato per l'esecuzione di singoli frame e non è compatibile con lo streaming video in tempo reale.
Questo flusso di lavoro prevede la creazione di una sessione, l'elaborazione di una singola bitmap con la sessione e la gestione del risultato. Gli esempi di codice delle sezioni precedenti illustrano questo caso d'uso in dettaglio.
- Configura le opzioni: crea un oggetto
EnhancementOptions, assicurandoti cheenhancementModesia impostato suEnhancementMode.BITMAP. - Crea sessione: utilizza il wrapper
createSessionAsyncdefinito in precedenza per creare unEnhancementSession. Si tratta di un oggetto pesante, quindi crealo solo quando necessario. - Elabora l'immagine: chiama la sessione, la bitmap di input e le opzioni che preferisci.
- Gestisci il risultato: la funzione di sospensione restituisce una nuova bitmap migliorata in caso di esito positivo o genera un'eccezione in caso di errore.
- Rilascia la sessione: è fondamentale chiamare
session.release()quando hai finito per liberare le risorse della GPU.
EnhancementSession è un oggetto di contesto pesante che mantiene una pipeline di memoria GPU o NPU persistente. Alloca RAM video (VRAM) dedicata e handle di sistema nativi. Per evitare gravi perdite di memoria e potenziali arresti anomali di OutOfMemoryError, rispetta i seguenti principi del ciclo di vita:
- Creazione di istanze lazy: non creare una sessione finché l'utente non avvia un'azione di miglioramento.
- Riutilizzo strategico: mantieni e riutilizza una singola istanza di sessione durante l'elaborazione di più immagini con configurazioni identiche (dimensioni e pulsanti on/off).
- Chiusura del prompt: richiama immediatamente
session.release()al termine delle attività visive per liberare le risorse hardware condivise.
Inizializza il motore di miglioramento
Questo metodo orchestra un controllo in due passaggi. Verifica se l'hardware del dispositivo supporta l'accelerazione e poi si assicura che siano presenti i moduli di machine learning richiesti.
L'esecuzione di questo passaggio come prerequisito evita errori di inizializzazione in fase di runtime convalidando le funzionalità prima che l'app tenti di elaborare i contenuti multimediali.
class MediaSetupViewModel(application: Application) : AndroidViewModel(application) {
private val enhancementClient = Enhancement.getClient(application)
fun initializeEnhancementEngine() {
viewModelScope.launch {
try {
// 1. Verify hardware capability
val isSupported = enhancementClient.isDeviceSupportedAsync()
if (!isSupported) {
notifyUiDeviceIncompatible()
return@launch
}
// 2. Verify and download the Google Play services ML modules
val isInstalled = enhancementClient.isModuleInstalledAsync()
if (!isInstalled) {
notifyUiDownloadingModels()
enhancementClient.installModule().await()
}
notifyUiEngineReady()
} catch (e: Exception) {
// Handle potential errors during session creation or image processing.
handleInitializationError(e)
}
}
}
}
Crea wrapper di processo per sessioni e bitmap
Utilizza questi wrapper di coroutine Kotlin per convertire i callback client basati su attività in funzioni di sospensione standard, consentendo un'esecuzione più pulita e sequenziale.
// Wraps the task-based createSession callback into a suspending function.
suspend fun EnhancementClient.createSessionAsync(
options: EnhancementOptions,
executor: Executor
): EnhancementSession = withContext(Dispatchers.Main) {
suspendCancellableCoroutine { continuation ->
// EnhancementSessionCallback handles session success or failure.
val callback = object : EnhancementSessionCallback {
override fun onSessionCreated(session: EnhancementSession) {
continuation.resume(session)
}
override fun onSessionCreationFailed(status: Status) {
continuation.resumeWithException(
Exception("Session creation failed: ${status.statusMessage} (${status.statusCode})")
)
}
override fun onSessionDestroyed() {}
override fun onSessionDisconnected(status: Status) {}
}
// Handles errors during the initial request trigger.
this@createSessionAsync.createSession(options, callback).addOnFailureListener(executor) { e ->
if (continuation.isActive) {
continuation.resumeWithException(e)
}
}
}
}
// Wraps this process in a suspending function for cleaner execution.
suspend fun EnhancementSession.processBitmapAsync(
bitmap: Bitmap,
options: EnhancementOptions
): Bitmap = suspendCancellableCoroutine { continuation ->
// EnhancementCallback returns the processed bitmap or an error code.
val callback = object : EnhancementCallback {
override fun onBitmapProcessed(enhancedBitmap: Bitmap) {
continuation.resume(enhancedBitmap)
}
override fun onError(statusCode: Int) {
continuation.resumeWithException(
Exception("Bitmap processing failed with status code: $statusCode")
)
}
override fun onSurfaceProcessed(timestamp: Long) {}
}
this.process(bitmap, options, callback)
}
Esegui la pipeline bitmap in un ViewModel
Per integrare la pipeline di miglioramento nell'architettura della tua applicazione, utilizza un
ViewModel per gestire il ciclo di vita della sessione. Questo approccio garantisce che le risorse GPU pesanti vengano rilasciate quando ViewModel viene cancellato.
// Define a data class to hold image information.
data class ImageInfo(val bitmap: Bitmap)
// Define a UI state class to hold loading status, errors, and enhanced image.
data class EnhancementUiState(
val isLoading: Boolean = false,
val enhancementError: String? = null,
val enhancedImage: ImageInfo? = null
)
class EnhancementViewModel(application: Application) : AndroidViewModel(application) {
// Backing field for UI state, initialized with default values.
private val _uiState = MutableStateFlow(EnhancementUiState())
// Publicly exposed UI state flow for observation.
val uiState: StateFlow<EnhancementUiState> = _uiState.asStateFlow()
// Initialize client to interact with the Media Enhancement service.
private val enhancementClient: EnhancementClient = Enhancement.getClient(application)
// Single-thread executor for processing background enhancement tasks.
private val enhancementExecutor = Executors.newSingleThreadExecutor()
// Track session state to enable reuse across multiple processing calls.
private var enhancementSession: EnhancementSession? = null
private var sessionOptions: EnhancementOptions? = null
// Primary function to trigger the enhancement workflow for a provided bitmap.
fun enhanceImage(bitmap: Bitmap) {
viewModelScope.launch(Dispatchers.IO) {
_uiState.update { it.copy(isLoading = true, enhancementError = null) }
try {
// Define enhancement options (for example, enable upscale, tonemapping) based
// on bitmap dimensions.
val options = EnhancementOptions(
bitmap.width,
bitmap.height,
EnhancementMode.BITMAP,
isTonemappingEnabled = true,
isDeblurAndDenoisePhotoEnabled = true,
isUpscalePhotoEnabled = false,
)
// 1. Establish the session lazily on demand. A session is configured for
// specific input dimensions, so replace it when the bitmap size changes.
if (enhancementSession == null ||
sessionOptions?.width != options.width ||
sessionOptions?.height != options.height
) {
enhancementSession?.release()
enhancementSession = null
enhancementSession = enhancementClient.createSessionAsync(options, enhancementExecutor)
sessionOptions = options
}
val session = enhancementSession ?: throw IllegalStateException("Session unavailable.")
// 2. Dispatch image through the neural pipeline
val enhancedBitmap = session.processBitmapAsync(bitmap, options)
// 3. Render output to UI
_uiState.update {
it.copy(enhancedImage = ImageInfo(bitmap = enhancedBitmap))
}
} catch (e: Exception) {
_uiState.update { it.copy(enhancementError = e.message) }
} finally {
// Ensure loading state is reset regardless of the outcome.
_uiState.update { it.copy(isLoading = false) }
}
}
}
override fun onCleared() {
// 4. Critical: Release native GPU hardware resources
enhancementSession?.release()
enhancementSession = null
enhancementExecutor.shutdown()
super.onCleared()
}
}
Carica le immagini in modo progressivo su reti lente
Su reti lente, l'app può scaricare una versione più piccola e compressa di un'immagine anziché il file a risoluzione massima. La tua app può quindi utilizzare la modalità Bitmap per eseguire l'upscaling e la rimozione della sfocatura dell'immagine sul dispositivo. L'immagine migliorata sostituisce il download a risoluzione massima, in modo che gli utenti vedano un'immagine più nitida senza un trasferimento di file di grandi dimensioni.
Quando utilizzare questo pattern
Questo pattern è adatto quando sono soddisfatte tutte le seguenti condizioni:
- Il dispositivo è supportato:
isDeviceSupportedAsync()restituiscetrue. L'API richiede Android 11 (livello API 30) o versioni successive ed è ottimizzata per i dispositivi di livello premium. - L'immagine viene visualizzata con dimensioni maggiori rispetto a quelle del download: ad esempio, un'immagine di piccole dimensioni mostrata a schermo intero. Se l'immagine rimane alle dimensioni della miniatura, l'upscaling aggiunge un vantaggio visibile minimo.
- Il modulo di miglioramento è già installato:
isModuleInstalledAsync()restituiscetrue. L'installazione del modulo scarica i file del modello tramite la rete. Se l'utente ha già una connessione lenta, non avviare l'installazione.
Se una di queste condizioni non viene soddisfatta, mostra l'immagine scaricata senza miglioramenti.
Implementa il pattern
Il pattern funziona nel seguente modo:
- Visualizza l'immagine a bassa risoluzione: esegui il rendering dell'immagine di piccole dimensioni non appena viene scaricata.
- Migliora in background: se il motore di miglioramento è pronto, elabora l'immagine in modalità Bitmap con l'upscaling e la rimozione della sfocatura attivati.
- Scambia nel risultato: sostituisci l'immagine visualizzata con la bitmap migliorata. Una breve dissolvenza incrociata rende lo scambio meno evidente.
La seguente classe ProgressiveImageEnhancer elabora un'immagine alla volta e riutilizza una singola sessione per immagini della stessa dimensione. Se il miglioramento non va a buon fine, enhance() restituisce null in modo che l'app continui a visualizzare l'immagine a bassa risoluzione. La classe utilizza i wrapper createSessionAsync e processBitmapAsync definiti in Crea wrapper di processo per sessione e bitmap.
Installa il modulo in anticipo, come mostrato in Inizializza il motore di ottimizzazione. Se isDeviceSupportedAsync() e isModuleInstalledAsync() restituiscono
true, chiama enhance().
class ProgressiveImageEnhancer(
private val enhancementClient: EnhancementClient,
private val executor: Executor,
) {
// Callers can request enhancements concurrently, but they all share one
// session, so process one image at a time.
private val mutex = Mutex()
private var session: EnhancementSession? = null
private var sessionOptions: EnhancementOptions? = null
// Enhancement is optional for this pattern, so return null instead of
// throwing. The caller can keep the low-resolution image without extra
// error handling.
suspend fun enhance(lowResBitmap: Bitmap): Bitmap? = mutex.withLock {
val options = EnhancementOptions(
width = lowResBitmap.width,
height = lowResBitmap.height,
enhancementMode = EnhancementMode.BITMAP,
isDeblurAndDenoisePhotoEnabled = true,
isUpscalePhotoEnabled = true,
)
try {
getOrCreateSession(options).processBitmapAsync(lowResBitmap, options)
} catch (e: CancellationException) {
// A cancelled request (for example, the user scrolled away) isn't
// an enhancement failure, so let the caller's scope handle it.
throw e
} catch (e: Exception) {
null
}
}
// Sessions are expensive to create and are configured for specific input
// dimensions, so reuse the current one until the image size changes.
private suspend fun getOrCreateSession(options: EnhancementOptions): EnhancementSession {
val currentSession = session
val currentOptions = sessionOptions
if (currentSession != null &&
currentOptions != null &&
currentOptions.width == options.width &&
currentOptions.height == options.height
) {
return currentSession
}
releaseSession()
return enhancementClient.createSessionAsync(options, executor).also {
session = it
sessionOptions = options
}
}
// A session holds GPU memory until it's released, so free it as soon as
// the images it enhances are no longer on screen. Taking the lock first
// waits for any in-progress enhancement, so a session that's still being
// created isn't leaked.
suspend fun release() = mutex.withLock { releaseSession() }
private fun releaseSession() {
session?.release()
session = null
sessionOptions = null
}
}
Quando utilizzi questo pattern, segui queste linee guida:
- Richiedi una dimensione coerente: un
EnhancementSessionutilizza dimensioni di input fisse. Richiedi immagini a bassa risoluzione di dimensioni coerenti in modo che la tua app possa riutilizzare una singola sessione per tutte le immagini. - Memorizza nella cache il risultato migliorato: memorizza la bitmap migliorata nella cache delle immagini in modo che l'app non elabori nuovamente la stessa immagine. Se attivi l'upscaling, la bitmap migliorata è più grande della bitmap di input. Dimensiona la cache per le bitmap più grandi.