Media Enhancement API は、ハードウェア アクセラレーションを活用して高品質のメディア改善を実現する、低レイテンシでプライバシーの保護に優れたオンデバイス AI ソリューションを提供します。APK の肥大化はゼロです。詳しくは、メディア拡張機能 についてをご覧ください。
静的ビットマップ モード（EnhancementMode.BITMAP）は、静的なデコード済み画像処理用に設計されています。
ビットマップ モードで動作するには、OS が圧縮されていないピクセルデータをシリアル化し、システムバスを介して CPU メモリから GPU メモリにコピーする必要があります。処理されたフレームは、逆コピーによって返されます。シングルフレームの実行に最適化されており、リアルタイムの動画ストリーミングには対応していません。
このワークフローでは、セッションを作成し、そのセッションで単一のビットマップを処理してから、結果を処理します。前のセクションのコード例で、このユースケースについて詳しく説明しています。
- オプションを構成する:
EnhancementOptionsオブジェクトを作成し、enhancementModeがEnhancementMode.BITMAPに設定されていることを確認します。 - セッションを作成する: 先ほど定義した
createSessionAsyncラッパーを使用して、EnhancementSessionを作成します。これはヘビーウェイト オブジェクトなので、必要な場合にのみ作成してください。 - 画像を処理する: セッション、入力ビットマップ、必要なオプション を呼び出します。
- 結果を処理する: サスペンド関数は、 成功した場合は新しい拡張ビットマップを返し、失敗した場合は例外をスローします。
- セッションを解放する: 重要なこととして、完了したら
session.release()を呼び出して GPU リソースを解放します。
EnhancementSession は、永続的な GPU または NPU メモリ パイプラインを維持するヘビーウェイト コンテキスト
オブジェクトです。専用のビデオ RAM（VRAM）とネイティブ システム ハンドルを割り当てます。深刻なメモリリークや
OutOfMemoryError クラッシュを防ぐため、次のライフサイクル原則に従ってください。
- 遅延インスタンス化: ユーザーが 拡張アクションを開始するまでセッションを作成しないでください。
- 戦略的な再利用: 同じ構成（サイズと切り替えオプション）で複数の画像を処理する場合は、単一のセッション インスタンスを維持して再利用します。
- 迅速な破棄: 視覚的なタスクが終了したらすぐに
session.release()を呼び出して、共有ハードウェア リソースを解放します。
拡張エンジンを初期化する
このメソッドは、2 段階のチェックを調整します。デバイスのハードウェアがアクセラレーションをサポートしているかどうかを確認し、必要な機械学習モジュールが存在することを確認します。
これを前提条件として実行すると、アプリがメディアを処理しようとする前に機能を検証することで、ランタイムの初期化の失敗を防ぐことができます。
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)
}
}
}
}
セッションとビットマップ処理のラッパーを作成する
これらの Kotlin コルーチン ラッパーを使用して、タスクベースのクライアント コールバックを標準のサスペンド関数に変換し、よりクリーンで順次実行できるようにします。
// 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.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)
}
ViewModel でビットマップ パイプラインを実行する
拡張パイプラインをアプリケーション アーキテクチャに統合するには、ViewModel を使用してセッションのライフサイクルを管理します。この方法では、ViewModel がクリアされるときに、大量の GPU リソースが解放されます。
// 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
// 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 {
// 1. Establish the session lazily on demand
// Define enhancement options (for example, enable upscale, tonemapping) based
// on bitmap dimensions.
if (enhancementSession == null) {
val options = EnhancementOptions(
bitmap.width,
bitmap.height,
EnhancementMode.BITMAP,
enableTonemap = true,
enableDeblurDenoise = true,
enableDenoiseOnly = false,
enableUpscale = false,
)
enhancementSession = enhancementClient.createSessionAsync(options, enhancementExecutor)
}
val session = enhancementSession ?: throw IllegalStateException("Session unavailable.")
// 2. Dispatch image through the neural pipeline
val enhancedBitmap = session.processBitmapAsync(bitmap, session.defaultOptions)
// 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()
}
}