Media Enhancement API cung cấp một giải pháp AI trên thiết bị, có độ trễ thấp, đảm bảo quyền riêng tư, tận dụng khả năng tăng tốc phần cứng để cải thiện chất lượng nội dung nghe nhìn mà không làm tăng kích thước tệp APK. Để biết thêm thông tin, hãy xem phần Tìm hiểu về các tính năng nâng cao nội dung nghe nhìn.
Chế độ Bitmap tĩnh (EnhancementMode.BITMAP) được thiết kế để xử lý hình ảnh tĩnh, đã giải mã.
Khi hoạt động ở chế độ Bitmap, hệ điều hành phải chuyển đổi tuần tự dữ liệu pixel chưa nén và sao chép dữ liệu đó từ bộ nhớ CPU qua bus hệ thống sang bộ nhớ GPU, trả về khung đã xử lý thông qua một bản sao đảo ngược. Mô hình này được tối ưu hoá để thực thi một khung hình và không tương thích với tính năng truyền trực tuyến video theo thời gian thực.
Quy trình này bao gồm việc tạo một phiên, xử lý một bitmap bằng phiên đó, rồi xử lý kết quả. Các ví dụ về mã trong các phần trước đề cập chi tiết đến trường hợp sử dụng này.
- Định cấu hình các tuỳ chọn: Tạo đối tượng
EnhancementOptions, đảm bảoenhancementModeđược đặt thànhEnhancementMode.BITMAP. - Tạo phiên: Sử dụng trình bao bọc
createSessionAsyncmà chúng ta đã xác định trước đó để tạoEnhancementSession. Đây là một đối tượng nặng, vì vậy chỉ tạo đối tượng này khi cần. - Xử lý hình ảnh: Gọi phiên, bitmap đầu vào và các tuỳ chọn bạn muốn.
- Xử lý kết quả: Hàm tạm ngưng trả về một Bitmap mới, được cải thiện khi thành công hoặc gửi một ngoại lệ khi không thành công.
- Giải phóng phiên: Quan trọng nhất là hãy gọi
session.release()khi bạn hoàn tất để giải phóng tài nguyên GPU.
EnhancementSession là một đối tượng ngữ cảnh nặng, duy trì một quy trình bộ nhớ GPU hoặc NPU ổn định. Nó phân bổ RAM video chuyên dụng (VRAM) và các trình xử lý hệ thống gốc. Để ngăn chặn tình trạng rò rỉ bộ nhớ nghiêm trọng và có thể xảy ra
OutOfMemoryError sự cố, hãy tuân thủ các nguyên tắc sau về vòng đời:
- Tạo thực thể từng phần: Đừng tạo phiên cho đến khi người dùng bắt đầu một hành động nâng cao.
- Sử dụng lại một cách chiến lược: Duy trì và sử dụng lại một phiên bản duy nhất khi xử lý nhiều hình ảnh có cấu hình giống hệt nhau (kích thước và các tuỳ chọn bật/tắt).
- Huỷ bỏ nhanh: Gọi
session.release()ngay lập tức khi các tác vụ hình ảnh kết thúc để giải phóng tài nguyên phần cứng dùng chung.
Khởi chạy công cụ nâng cao
Phương thức này điều phối quy trình kiểm tra gồm hai bước. Thư viện này xác minh xem phần cứng của thiết bị có hỗ trợ tính năng tăng tốc hay không, sau đó đảm bảo có các mô-đun học máy cần thiết.
Việc chạy bước này dưới dạng điều kiện tiên quyết sẽ giúp ngăn chặn lỗi khởi chạy trong thời gian chạy bằng cách xác thực các chức năng trước khi ứng dụng của bạn cố gắng xử lý nội dung nghe nhìn.
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) } } } }
Tạo trình bao bọc quy trình bitmap và phiên
Sử dụng các trình bao bọc coroutine Kotlin này để chuyển đổi lệnh gọi lại ứng dụng dựa trên tác vụ thành các hàm tạm ngưng tiêu chuẩn, cho phép thực thi tuần tự và rõ ràng hơn.
// 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) }
Thực thi quy trình bitmap trong ViewModel
Để tích hợp quy trình nâng cao vào cấu trúc ứng dụng, hãy sử dụng ViewModel để quản lý vòng đời của phiên. Phương pháp này đảm bảo rằng các tài nguyên GPU nặng sẽ được giải phóng khi ViewModel bị xoá.
// 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() } }
Tải hình ảnh dần dần trên mạng chậm
Trên các mạng chậm, ứng dụng của bạn có thể tải phiên bản hình ảnh nhỏ hơn, nén hơn xuống thay vì tệp có độ phân giải đầy đủ. Sau đó, ứng dụng của bạn có thể dùng chế độ Bitmap để nâng cấp và làm rõ hình ảnh trên thiết bị. Hình ảnh nâng cao sẽ thay thế hình ảnh tải xuống có độ phân giải đầy đủ, nhờ đó người dùng sẽ thấy hình ảnh sắc nét hơn mà không cần chuyển tệp lớn.
Trường hợp sử dụng mẫu này
Mẫu này phù hợp khi tất cả những điều sau đây đều đúng:
- Thiết bị được hỗ trợ:
isDeviceSupportedAsync()trả vềtrue. API này yêu cầu Android 11 (cấp độ API 30) trở lên và được tối ưu hoá cho các thiết bị Lớp cao cấp. - Hình ảnh hiển thị lớn hơn kích thước tải xuống: Ví dụ: hình ảnh nhỏ hiển thị toàn màn hình. Nếu hình ảnh vẫn ở kích thước hình thu nhỏ, thì việc nâng cấp sẽ không mang lại nhiều lợi ích rõ rệt.
- Mô-đun cải tiến đã được cài đặt:
isModuleInstalledAsync()trả vềtrue. Quá trình cài đặt mô-đun sẽ tải các tệp mô hình xuống qua mạng. Nếu người dùng đang sử dụng kết nối chậm, đừng bắt đầu cài đặt.
Nếu không đáp ứng được bất kỳ điều kiện nào trong số này, hãy hiển thị hình ảnh đã tải xuống mà không cần cải thiện.
Triển khai mẫu
Mẫu này hoạt động như sau:
- Hiển thị hình ảnh có độ phân giải thấp: Hiển thị hình ảnh nhỏ ngay khi tải xuống.
- Nâng cao trong nền: Nếu công cụ nâng cao đã sẵn sàng, hãy xử lý hình ảnh ở chế độ Bitmap khi bật tính năng nâng cấp và làm mờ.
- Hoán đổi trong kết quả: Thay thế hình ảnh hiển thị bằng bitmap nâng cao. Hiệu ứng chuyển cảnh mờ chồng ngắn giúp quá trình hoán đổi ít gây chú ý hơn.
Lớp ProgressiveImageEnhancer sau đây xử lý từng hình ảnh một và sử dụng lại một phiên cho các hình ảnh có cùng kích thước. Nếu không nâng cao được, enhance() sẽ trả về null để ứng dụng của bạn tiếp tục hiển thị hình ảnh có độ phân giải thấp. Lớp này sử dụng các trình bao bọc createSessionAsync và processBitmapAsync được xác định trong phần Tạo trình bao bọc quy trình bitmap và phiên.
Cài đặt trước mô-đun, như trong phần Khởi chạy công cụ nâng cao. Nếu isDeviceSupportedAsync() và isModuleInstalledAsync() trả về true, hãy gọi 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 } }
Khi bạn sử dụng mẫu này, hãy làm theo các nguyên tắc sau:
- Yêu cầu kích thước nhất quán:
EnhancementSessionsử dụng kích thước đầu vào cố định. Yêu cầu hình ảnh có độ phân giải thấp ở một kích thước nhất quán để ứng dụng của bạn có thể sử dụng lại một phiên duy nhất trên các hình ảnh. - Lưu kết quả nâng cao vào bộ nhớ đệm: Lưu trữ bitmap nâng cao trong bộ nhớ đệm hình ảnh để ứng dụng không xử lý lại cùng một hình ảnh. Nếu bạn bật tính năng nâng cấp, bitmap được nâng cao sẽ lớn hơn bitmap đầu vào. Định cỡ bộ nhớ đệm cho các bitmap lớn hơn.