Media Enhancement API הוא פתרון AI במכשיר ששומר על הפרטיות, פועל בזמן אחזור קצר ומשתמש בשיפור מהירות באמצעות חומרה כדי לספק שיפורי מדיה באיכות גבוהה בלי להגדיל את קובץ ה-APK. מידע נוסף זמין במאמר הסבר על היכולות של שיפורי המדיה.
מצב Bitmap הסטטי (EnhancementMode.BITMAP) מיועד לעיבוד תמונות סטטיות ומפוענחות.
כדי לפעול במצב Bitmap, מערכת ההפעלה צריכה להעביר נתוני פיקסלים לא דחוסים ב-serialization, להעתיק אותם מזיכרון המעבד (CPU) דרך אפיק המערכת לזיכרון ה-GPU, ולהחזיר את הפריים המעובד באמצעות העתקה הפוכה. הוא מותאם להפעלה של פריים בודד ולא תואם לסטרימינג של וידאו בזמן אמת.
תהליך העבודה הזה כולל יצירת סשן, עיבוד של מפת סיביות (bitmap) אחת וטיפול בתוצאה. הדוגמאות של הקוד מהקטעים הקודמים עוסקות בתרחיש לדוגמה הזה בפירוט.
- הגדרת אפשרויות: יוצרים אובייקט
EnhancementOptionsומוודאים שהערך שלenhancementModeמוגדר כ-EnhancementMode.BITMAP. - יצירת סשן: משתמשים ב-wrapper של
createSessionAsyncשהגדרנו קודם כדי ליצורEnhancementSession. זהו אובייקט כבד, לכן צריך ליצור אותו רק כשצריך. - עיבוד התמונה: קוראים לסשן, למפת הסיביות של הקלט ולאפשרויות הרצויות.
- טיפול בתוצאה: הפונקציה suspend מחזירה מפת סיביות חדשה ומשופרת אם הפעולה מצליחה, או מחזירה חריגה אם הפעולה נכשלת.
- שחרור הסשן: חשוב מאוד להפעיל את
session.release()בסיום כדי לפנות משאבי GPU.
EnhancementSession הוא אובייקט הקשר כבד ששומר על צינור עיבוד נתונים קבוע בזיכרון של ה-GPU או ה-NPU. הוא מקצה זיכרון RAM ייעודי לווידאו (VRAM) ומזהי מערכת מקוריים. כדי למנוע דליפות זיכרון חמורות וקריסות פוטנציאליות של OutOfMemoryError, חשוב לפעול לפי העקרונות הבאים של מחזור החיים:
- יצירת מופע עצל (lazy instantiation): אל תיצרו סשן עד שהמשתמש יתחיל פעולת שיפור.
- שימוש חוזר אסטרטגי: כדאי לשמור על מופע סשן יחיד ולהשתמש בו שוב כשמעבדים כמה תמונות עם הגדרות זהות (מידות ואפשרויות שהופעלו).
- פירוק מיידי של ההנחיה: מפעילים את
session.release()מיד כשמשימות חזותיות מסתיימות כדי לפנות משאבי חומרה משותפים.
הפעלת מנוע השיפור
השיטה הזו מפעילה בדיקה דו-שלבית. הוא בודק אם החומרה של המכשיר תומכת בהאצה, ואז מוודא שהמודולים הנדרשים של למידת המכונה קיימים.
הפעלת השלב הזה כתנאי מוקדם מונעת כשלים באתחול בזמן הריצה, על ידי אימות היכולות לפני שהאפליקציה מנסה לעבד מדיה.
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(installStatusCallback).await() } notifyUiEngineReady() } catch (e: Exception) { // Handle potential errors during session creation or image processing. handleInitializationError(e) } } } }
יצירת סשן ומעטפות לתהליכי מפת סיביות (bitmap)
אפשר להשתמש ב-wrapper האלה של פונקציות ה-coroutine של Kotlin כדי להמיר קריאות חוזרות (callbacks) של לקוחות שמבוססות על משימות לפונקציות השעיה רגילות, וכך לאפשר ביצוע נקי ורציף.
// 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) {} override fun onCancelled(statusCode: Int) {} } this.process(bitmap, options, callback) }
הפעלת צינור עיבוד הנתונים של מפת הסיביות ב-ViewModel
כדי לשלב את צינור עיבוד הנתונים לשיפור בארכיטקטורת האפליקציה, משתמשים ב-ViewModel לניהול מחזור החיים של הסשן. כך אפשר לוודא שמשאבי ה-GPU הכבדים משתחררים כשמנקים את ה-ViewModel.
// 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() } }
טעינת תמונות באופן הדרגתי ברשתות איטיות
ברשתות איטיות, האפליקציה יכולה להוריד גרסה קטנה ודחוסה יותר של תמונה במקום הקובץ ברזולוציה מלאה. לאחר מכן, האפליקציה יכולה להשתמש במצב Bitmap כדי לשפר את הרזולוציה של התמונה ולהסיר ממנה את הטשטוש במכשיר. התמונה המשופרת מחליפה את ההורדה ברזולוציה מלאה, כך שהמשתמשים רואים תמונה חדה יותר בלי העברת קובץ גדול.
מתי כדאי להשתמש בתבנית הזו
התבנית הזו מתאימה כשכל התנאים הבאים מתקיימים:
- המכשיר נתמך: הפונקציה
isDeviceSupportedAsync()מחזירה את הערךtrue. ה-API דורש Android מגרסה 11 (רמת API 30) ומעלה, והוא מותאם למכשירים ברמת פרימיום. - התמונה מוצגת בגודל גדול יותר מהגודל שבו היא הורדה: לדוגמה, תמונה קטנה שמוצגת במסך מלא. אם התמונה נשארת בגודל של תמונה ממוזערת, הגדלת קנה המידה לא מוסיפה הרבה יתרונות שאפשר לראות.
- מודול השיפור כבר מותקן:
isModuleInstalledAsync()מחזיר את הערךtrue. התקנת המודול מורידה קובצי מודלים דרך הרשת. אם המשתמש כבר מחובר בחיבור איטי, אל תתחילו את ההתקנה.
אם אחד מהתנאים האלה לא מתקיים, התמונה שהורדה תוצג בלי שיפור.
הטמעת התבנית
התבנית פועלת באופן הבא:
- הצגת התמונה ברזולוציה נמוכה: עיבוד התמונה הקטנה ברגע שהיא יורדת.
- שיפור ברקע: אם מנוע השיפור מוכן, מעבדים את התמונה במצב מפת סיביות (bitmap) כשהאפשרויות "הגדלת קנה מידה" ו"הסרת טשטוש" מופעלות.
- החלפה בתוצאה: החלפת התמונה המוצגת במפת הסיביות המשופרת. מעבר הדרגתי קצר הופך את ההחלפה לפחות מורגשת.
הקלאס ProgressiveImageEnhancer הבא מעבד תמונה אחת בכל פעם ומשתמש מחדש בסשן אחד לתמונות באותו גודל. אם השיפור נכשל, הפונקציה enhance() מחזירה את הערך null כדי שהאפליקציה תמשיך להציג את התמונה ברזולוציה הנמוכה. הכיתה משתמשת ב-wrappers של createSessionAsync ו-processBitmapAsync שמוגדרים בקטע יצירת wrappers של תהליכי סשן ומפת סיביות (bitmap).
מתקינים את המודול מראש, כמו שמוסבר בקטע הפעלת מנוע השיפור. אם isDeviceSupportedAsync() ו-isModuleInstalledAsync() מחזירים את הערך true, צריך להפעיל את 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 } }
כשמשתמשים בתבנית הזו, חשוב לפעול לפי ההנחיות הבאות:
- בקשת גודל עקבי:
EnhancementSessionמשתמש במאפייני קלט קבועים. בקשו תמונות ברזולוציה נמוכה בגודל עקבי אחד כדי שהאפליקציה תוכל להשתמש שוב בסשן אחד בתמונות שונות. - שמירת התוצאה המשופרת במטמון: שומרים את מפת הסיביות המשופרת במטמון התמונות כדי שהאפליקציה לא תעבד את אותה תמונה שוב. אם מפעילים את האפשרות הזו, מפת הסיביות המשופרת גדולה יותר ממפת הסיביות של הקלט. הגדירו את המטמון בהתאם למפות הסיביות הגדולות יותר.