Media Enhancement API یک راهکار هوش مصنوعی دروندستگاهی با تأخیر کم و حافظ حریم خصوصی ارائه میدهد که از شتاب سختافزاری برای ارائه بهبودهای رسانهای با کیفیت بالا بدون افزایش حجم APK استفاده میکند. برای اطلاعات بیشتر، آشنایی با قابلیتهای بهبود رسانه را ببینید.
حالت Bitmap ایستا (EnhancementMode.BITMAP) برای پردازش تصویر ایستا و رمزگشاییشده طراحی شده است.
عملکرد در حالت «بیتمپ» مستلزم آن است که سیستمعامل دادههای پیکسل فشردهنشده را سریالسازی کند و آن را از حافظه واحد پردازش مرکزی ازطریق گذرگاه سیستم به حافظه واحد پردازش گرافیکی کپی کند و قاب پردازششده را ازطریق کپی معکوس برگرداند. این مدل برای اجرای تکفریم بهینهسازی شده است و با جاریسازی همزمان ویدیو سازگار نیست.
این گردش کار شامل ایجاد یک جلسه، پردازش یک نقشه بیتی با آن، و سپس مدیریت نتیجه است. نمونههای کد از بخشهای قبلی این مورد استفاده را بهطور دقیق پوشش میدهند.
- پیکربندی گزینهها: یک شیء
EnhancementOptionsایجاد کنید و مطمئن شوید کهenhancementModeرویEnhancementMode.BITMAPتنظیم شده باشد. - ایجاد جلسه: از پوشاننده
createSessionAsyncکه قبلاً تعریف کردیم برای ایجادEnhancementSessionاستفاده کنید. این شیء سنگین است، بنابراین آن را فقط درصورت نیاز ایجاد کنید. - پردازش تصویر: جلسه، بیتمپ ورودی، و گزینههای مدنظرتان را فراخوانی کنید.
- مدیریت نتیجه: تابع تعلیق درصورت موفقیت، Bitmap جدید و بهبودیافتهای را برمیگرداند یا درصورت شکست، استثنایی را ایجاد میکند.
- آزاد کردن جلسه: نکته مهم این است که وقتی کارتان تمام شد،
session.release()را فراخوانی کنید تا منابع GPU آزاد شود.
EnhancementSession یک شیء بافت سنگین است که خط لوله حافظه GPU یا NPU پایداری را حفظ میکند. این API حافظه دسترسی تصادفی ویدیویی (VRAM) اختصاصی
و دستگیرههای سیستم بومی را اختصاص میدهد. برای جلوگیری از نشت شدید حافظه و خرابیهای احتمالی
OutOfMemoryError، اصول چرخه حیات زیر را رعایت کنید:
- نمونهسازی تنبل: تا زمانی که کاربر کنش بهبود را شروع نکرده است، جلسه ایجاد نکنید.
- استفاده مجدد استراتژیک: هنگام پردازش چندین تصویر با پیکربندیهای یکسان (ابعاد و گزینههای روشن/خاموش)، یک نمونه جلسه واحد را حفظ کنید و دوباره از آن استفاده کنید.
- Prompt teardown: Invoke
session.release()immediately when visual tasks terminate to free shared hardware resources.
راهاندازی موتور بهبود
این روش یک بررسی دومرحلهای را سازماندهی میکند. این ابزار بررسی میکند که آیا سختافزار دستگاه از شتاب پشتیبانی میکند یا نه، و سپس مطمئن میشود که ماژولهای یادگیری ماشین موردنیاز وجود داشته باشند.
اجرای این مرحله بهعنوان پیشنیاز، با اعتبارسنجی قابلیتها قبلاز اینکه برنامهتان برای پردازش رسانه تلاش کند، از شکست مقداردهی اولیه زمان اجرا جلوگیری میکند.
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) } } } }
ایجاد کردن پوشانندههای پردازش بیتمپ و جلسه
از این پوشانندههای همروال 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@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() } }
بار کردن تدریجی تصاویر در شبکههای کُند
در شبکههای کند، برنامهتان میتواند بهجای فایل با وضوح کامل، نسخه کوچکتر و فشردهتر تصویر را بارگیری کند. سپس برنامهتان میتواند از حالت «بیتمپ» برای وضوحافزایی و رفع تاری تصویر در دستگاه استفاده کند. تصویر بهبودیافته جایگزین بارگیری با وضوح کامل میشود، بنابراین کاربران تصویر واضحتری را بدون انتقال فایل بزرگ میبینند.
زمان استفاده از این الگو
این الگو زمانی مناسب است که همه موارد زیر درست باشد:
- دستگاه پشتیبانی میشود:
isDeviceSupportedAsync()مقدارtrueرا برمیگرداند. این میانای برنامهسازی کاربردی به Android نسخه ۱۱ (سطح میانای برنامهسازی کاربردی ۳۰) یا بالاتر نیاز دارد و برای دستگاههای رده ممتاز بهینهسازی شده است. - تصویر بزرگتر از اندازه بارگیریشدهاش نمایش داده میشود: برای مثال، تصویر کوچکی که بهصورت تمامصفحه نشان داده میشود. اگر تصویر در اندازه ریزعکس باقی بماند، مقیاسافزایی مزیت قابلمشاهده کمی اضافه میکند.
- واحد بهبود قبلاً نصب شده است:
isModuleInstalledAsync()trueرا برمیگرداند. نصب واحد، فایلهای مدل را ازطریق شبکه بارگیری میکند. اگر اتصال کاربر ازقبل کند است، نصب را شروع نکنید.
اگر هرکدام از این شرایط برآورده نشد، تصویر بارگیریشده را بدون بهبود نمایش دهید.
الگو را پیادهسازی کنید
الگو بهصورت زیر عمل میکند:
- نمایش تصویر با وضوح پایین: تصویر کوچک را بهمحض بارگیری شدن رندر کنید.
- بهبود در پسزمینه: اگر موتور بهبود آماده است، تصویر را در حالت «بیتمپ» با فعال کردن مقیاسافزایی و رفع تاری پردازش کنید.
- جابهجایی در نتیجه: تصویر نمایشدادهشده را با نقشه بیتی بهبودیافته جایگزین کنید. یک محو تدریجی کوتاه باعث میشود که تعویض کمتر قابلتوجه باشد.
کلاس ProgressiveImageEnhancer زیر تصاویر را یکییکی پردازش میکند و
از یک جلسه برای تصاویر هماندازه مجدداً استفاده میکند. اگر بهبود ناموفق باشد،
enhance() null را برمیگرداند تا برنامهتان همچنان تصویر با وضوح پایین را نمایش دهد. این کلاس از پوشانندههای createSessionAsync و
processBitmapAsync تعریفشده در ایجاد جلسه و پوشانندههای پردازش
بیتمپ استفاده میکند.
واحد را ازقبل نصب کنید، همانطور که در راهاندازی موتور بهبود نشان داده شده است. اگر 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از ابعاد ورودی ثابت استفاده میکند. تصاویر با وضوح پایین را در یک اندازه ثابت درخواست کنید تا برنامهتان بتواند از یک جلسه واحد در تصاویر استفاده مجدد کند. - ذخیره کردن نتیجه بهبودیافته در حافظه نهان: بیتمپ بهبودیافته را در حافظه نهان تصویر ذخیره کنید تا برنامهتان دوباره همان تصویر را پردازش نکند. اگر فراپیمایی را فعال کنید، بیتمپ بهبودیافته بزرگتر از بیتمپ ورودی است. اندازه حافظه نهان را برای نگاشتهای بیتی بزرگتر تنظیم کنید.