Media Enhancement API – это решение на основе ИИ, которое работает на устройстве, обеспечивает низкую задержку и конфиденциальность, а также использует аппаратное ускорение, чтобы улучшать качество медиаконтента, не увеличивая размер APK-файла. Подробнее о возможностях улучшения медиаконтента…
Статический режим Bitmap (EnhancementMode.BITMAP) предназначен для обработки статических декодированных изображений.
При работе в режиме Bitmap операционная система должна сериализовать несжатые данные пикселей и скопировать их из памяти ЦП по системной шине в память графического процессора, возвращая обработанный кадр через обратную копию. Он оптимизирован для обработки отдельных кадров и несовместим с потоковой передачей видео в реальном времени.
Этот рабочий процесс включает создание сеанса, обработку одного растрового изображения с его помощью, а затем обработку результата. Примеры кода из предыдущих разделов подробно описывают этот вариант использования.
- Настройте параметры. Создайте объект
EnhancementOptions, убедившись, что дляenhancementModeзадано значениеEnhancementMode.BITMAP. - Создание сеанса. Используйте созданную ранее оболочку
createSessionAsync, чтобы создатьEnhancementSession. Это тяжелый объект, поэтому создавайте его только при необходимости. - Обработка изображения. Вызовите сеанс, входное растровое изображение и нужные параметры.
- Обработка результата. Функция приостановки возвращает новый улучшенный объект Bitmap в случае успеха или выдает исключение в случае неудачи.
- Завершение сеанса. По окончании работы вызовите
session.release(), чтобы освободить ресурсы графического процессора.
EnhancementSession – это тяжеловесный объект контекста, который поддерживает постоянный конвейер памяти графического или нейронного процессора. Он выделяет выделенную видеопамять (VRAM) и собственные системные дескрипторы. Чтобы избежать утечек памяти и сбоев в работе OutOfMemoryError, придерживайтесь следующих принципов:
- Отложенное создание экземпляра. Не создавайте сеанс, пока пользователь не инициирует действие по улучшению.
- Повторное использование. При обработке нескольких изображений с одинаковыми конфигурациями (размерами и параметрами с переключателями) используйте один и тот же экземпляр сеанса.
- Быстрое завершение. Вызывайте
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) } } } }
Создание оболочек для сеанса и обработки битовой карты
Используйте эти обертки сопрограмм 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 для управления жизненным циклом сеанса. Это позволяет освободить ресурсы графического процессора, когда 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) или более поздней версии. API оптимизирован для устройств премиум-уровня. - Изображение показывается в большем размере, чем оно было скачано. Например, маленькое изображение показывается в полноэкранном режиме. Если изображение остается в размере значка, масштабирование не дает видимых преимуществ.
- Модуль улучшения уже установлен.
isModuleInstalledAsync()возвращаетtrue. При установке модуля файлы модели скачиваются по сети. Если у пользователя медленное подключение, не начинайте установку.
Если хотя бы одно из этих условий не выполняется, покажите скачанное изображение без улучшений.
Реализация шаблона
Шаблон работает следующим образом:
- Показывать изображение с низким разрешением. Изображение небольшого размера показывается сразу после скачивания.
- Улучшение в фоновом режиме. Если движок улучшения готов, обработайте изображение в режиме Bitmap с включенным повышением разрешения и восстановлением резкости.
- Заменить результат. Замените отображаемое изображение улучшенным растровым. Короткое перекрестное затухание делает замену менее заметной.
Приведенный ниже класс 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используются фиксированные размеры входных данных. Запрашивайте изображения с низким разрешением одного размера, чтобы приложение могло повторно использовать один сеанс для разных изображений. - Кешируйте улучшенные результаты. Сохраняйте улучшенные битовые карты в кеше изображений, чтобы приложению не приходилось обрабатывать их повторно. Если включить масштабирование, улучшенная битовая карта будет больше исходной. Размер вашего кэша для больших растровых изображений.