Além de recursos únicos: como garantir combinações de recursos com o CameraX 1.5
Leitura de 6 min
Os apps de câmera modernos são definidos por recursos avançados e sobrepostos. Os usuários esperam gravar vídeos com HDR impressionante, capturar movimentos fluidos a 60 QPS e conseguir imagens suaves com a estabilização de prévia, muitas vezes tudo ao mesmo tempo.
Como desenvolvedores, sabemos que a realidade é mais complicada. Como garantir que um dispositivo específico seja compatível com uma determinada combinação? Até agora, ativar vários recursos costumava ser uma aposta. Você pode verificar se há suporte para recursos individuais, mas combiná-los pode levar a um comportamento indefinido ou, pior, a uma falha na sessão da câmera. Essa incerteza força os desenvolvedores a serem conservadores, o que impede que os usuários de dispositivos compatíveis tenham a melhor experiência possível.
Por exemplo, poucos dispositivos premium são compatíveis com HDR e vídeo de 60 QPS simultaneamente. Consequentemente, a maioria dos apps evita ativar os dois ao mesmo tempo para evitar uma experiência ruim do usuário na maioria dos smartphones.
Para resolver isso, estamos lançando o Feature Group no CameraX, uma nova API criada para eliminar essa incerteza. Agora é possível consultar se uma combinação específica de recursos é compatível antes de configurar a câmera ou simplesmente informar suas prioridades ao CameraX e deixar que ele ative a melhor combinação para você.
Para quem está começando a usar a CameraX
Antes de falarmos sobre a nova API Feature Group, vamos recapitular o que é o CameraX. Ele é uma biblioteca de suporte do Jetpack criada para facilitar o desenvolvimento de apps de câmera. Ela fornece uma superfície de API consistente e fácil de usar que funciona na maioria dos dispositivos Android, com compatibilidade com versões anteriores até o Android 6.0 (nível 23 da API). Se você não conhece o CameraX, recomendamos que consulte a documentação oficial e teste o codelab para começar.
O que você pode criar com a API Feature Group
Você não precisa mais adivinhar as combinações de recursos e pode oferecer as melhores experiências de câmera possíveis, como HDR simultâneo e vídeo de 60 QPS em hardware compatível (por exemplo, um Pixel 10 Pro), evitando erros em dispositivos que não oferecem suporte à combinação.
Com a API Feature Group, é possível:
- Crie interfaces mais inteligentes e dinâmicas: ative ou desative configurações de forma inteligente na interface com base na compatibilidade de hardware em tempo real. Por exemplo, se um usuário ativar o HDR, você poderá desativar instantaneamente a opção de 60 QPS se a combinação não for compatível com o dispositivo.
- Oferecer um modo de alta qualidade confiável: configure a câmera com uma lista de prioridades dos recursos desejados. O CameraX encontra e ativa automaticamente a melhor combinação para qualquer dispositivo, garantindo um ótimo resultado sem uma lógica complexa e específica do dispositivo.
- Evitar falhas na sessão da câmera: ao verificar a compatibilidade com antecedência, você evita que a câmera tente configurar uma combinação incompatível, eliminando uma fonte comum de falhas e oferecendo uma experiência do usuário tranquila.
Como funciona: os principais componentes
A nova API se concentra em adições importantes a SessionConfig e CameraInfo.
- GroupableFeature: essa API apresenta um conjunto de recursos agrupáveis predefinidos, como HDR_HLG10, FPS_60, PREVIEW_STABILIZATION e IMAGE_ULTRA_HDR. Devido a limitações computacionais, apenas um conjunto específico de recursos pode ser agrupado com o alto grau de confiabilidade que essa API oferece. Estamos trabalhando para expandir essa lista e vamos oferecer suporte a mais recursos em versões futuras.
- Novos parâmetros SessionConfig: essa classe, usada para iniciar uma sessão de câmera, agora aceita dois novos parâmetros:
requiredFeatureGroup: use para recursos que precisam ser compatíveis para que a configuração seja bem-sucedida. É ideal para recursos que um usuário ativa explicitamente, como um botão de HDR. Para garantir uma experiência determinística e consistente, a chamadabindToLifecyclevai gerar umIllegalArgumentExceptionse a combinação solicitada não for compatível, em vez de ignorar silenciosamente uma solicitação de recurso. A APICameraInfo#isFeatureGroupSupported(detalhes abaixo) precisa ser usada para consultar esse resultado com antecedência.preferredFeatureGroup: use para recursos que são desejáveis, mas opcionais, por exemplo, quando você quer implementar um modo padrão de "alta qualidade". Você fornece uma lista dos recursos desejados ordenados de acordo com suas prioridades, e a CameraX ativa automaticamente a combinação de maior prioridade que o dispositivo aceita.
- CameraInfo#isFeatureGroupSupported(): é o método de consulta principal para verificar explicitamente se um grupo de recursos é compatível, adequado para fornecer apenas opções de recursos compatíveis aos usuários na interface do app. Você transmite um
SessionConfig, e ele retorna um booleano indicando se a combinação é compatível. Se você pretende vincular umSessionConfigcom recursos obrigatórios, use essa API primeiro para garantir que ele seja compatível.
Implementação na prática
Vamos ver como usar esses componentes para criar uma experiência de câmera melhor.
Cenário 1: modo de alta qualidade "Best Effort"
Se você quiser ativar os melhores recursos possíveis por padrão, forneça uma lista priorizada para preferredFeatureGroup. Neste exemplo, instruímos o CameraX a priorizar o HDR, depois 60 QPS e, por fim, a estabilização de pré-visualização. A CameraX lida com a complexidade de verificar todas as combinações possíveis e escolher a melhor que o dispositivo aceita.
Por exemplo, se um dispositivo puder processar HDR e 60 QPS juntos, mas não com a estabilização de prévia, a CameraX vai ativar os dois primeiros e descartar o terceiro. Dessa forma, você tem a melhor experiência possível sem precisar escrever verificações complexas e específicas para cada dispositivo.
cameraProvider.bindToLifecycle(
lifecycleOwner,
cameraSelector,
SessionConfig(
useCases = listOf(preview, videoCapture),
// The order of features in this list determines their priority.
// CameraX will enable the best-supported combination based on these
// priorities: HDR_HLG10 > FPS_60 > Preview Stabilization.
preferredFeatureGroup =
listOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION),
).apply {
// (Optional) Get a callback with the enabled features
// to update your UI.
setFeatureSelectionListener { selectedFeatures ->
updateUiIndicators(selectedFeatures)
}
}
)Para esse snippet de código, a CameraX vai tentar ativar as combinações de recursos na seguinte ordem de prioridade, selecionando a primeira que o dispositivo aceita totalmente:
- HDR + 60 QPS + Estabilização da Visualização
- HDR + 60 QPS
- HDR + Estabilização da Visualização
- HDR
- 60 QPS + Estabilização da Visualização
- 60 QPS
- Estabilização da visualização
- Nenhum dos recursos acima
Cenário 2: criar uma interface reativa
Para criar uma interface que responda às seleções do usuário e impeça que ele selecione uma combinação de recursos incompatível, consulte diretamente o suporte. A função abaixo verifica quais recursos são incompatíveis com as seleções atuais do usuário, permitindo que você desative os elementos de interface correspondentes.
/**
* Returns a list of features that are NOT supported in combination
* with the currently selected features.
*/
fun getUnsupportedFeatures(
currentFeatures: Set<GroupableFeature>
): Set<GroupableFeature> {
val unsupportedFeatures = mutableSetOf<GroupableFeature>()
val appFeatureOptions = setOf(HDR_HLG10, FPS_60, PREVIEW_STABILIZATION)
// Iterate over every available feature option in your app.
appFeatureOptions.forEach { featureOption ->
// Skip features the user has already selected.
if (currentFeatures.contains(featureOption)) return@forEach
// Check if adding this new feature is supported.
val isSupported = cameraInfo.isFeatureGroupSupported(
SessionConfig(
useCases = useCases,
// Check the new feature on top of existing ones.
requiredFeatureGroup = currentFeatures + featureOption
)
)
if (!isSupported) {
unsupportedFeatures.add(featureOption)
}
}
return unsupportedFeatures
}Em seguida, você pode conectar essa lógica ao ViewModel ou ao controlador de IU para reagir à entrada do usuário e vincular novamente a câmera com uma configuração que funcione.
// Invoked when user turns some feature on/off.
fun onFeatureChange(currentFeatures: Set<GroupableFeature>) {
// Identify features that are unsupported with the current selection.
val unsupportedFeatures = getUnsupportedFeatures(currentFeatures)
// Update app UI so that users can't enable them.
updateDisabledFeatures(unsupportedFeatures)
// Since the UI now only allows selecting supported feature combinations,
// `currentFeatures` is always valid. This allows setting
// `requiredFeatureGroup` directly, without needing to re-check for
// support or set a feature selection listener.
cameraProvider.bindToLifecycle(
lifecycleOwner,
cameraSelector,
SessionConfig(
useCases = listOf(preview, videoCapture),
requiredFeatureGroup = currentFeatures,
)
)
}Para ver esses conceitos em um aplicativo em funcionamento, confira nosso app de teste interno. Ele oferece uma implementação completa dos cenários de "melhor esforço" e "IU reativa" discutidos acima.
Observação: este é um aplicativo de teste, não um exemplo oficialmente compatível. Embora seja uma ótima referência para a API Groups, ele não foi polido para uso em produção.
Comece a usar hoje mesmo
A API Feature Group remove a ambiguidade de trabalhar com recursos avançados de câmera. Ao fornecer uma maneira determinística de consultar o suporte a recursos, você pode criar apps de câmera mais eficientes e confiáveis com confiança.
A API está disponível como experimental no CameraX 1.5 e está programada para se tornar totalmente estável na versão 1.6, com mais suporte e melhorias a caminho.
Para saber mais, confira a documentação oficial. Mal podemos esperar para ver o que você vai criar e receber seu feedback. Para compartilhar comentários e reportar problemas, use os seguintes canais:
-
Notícias sobre produtosApós mais de um ano de preparação conjunta com líderes do setor, parceiros regionais, App Distribution e comunidades do Android, nossas proteções ao usuário entraram em vigor em 30 de setembro para as lojas participantes no Brasil, na Indonésia, em Singapura e na Tailândia.
Matthew Forsythe • Leitura de 2 min -
Notícias sobre produtosPara oferecer essas experiências aos jogadores e garantir que seus jogos se destaquem em todos os tamanhos de tela, o Google Play está lançando novos requisitos de qualidade para telas grandes em jogos.
Aurash Mahbod • Leitura de 4 min -
Notícias sobre produtosA versão de novembro de 2026 do Jetpack Compose está estável. Esta versão traz a versão 1.13 para os principais módulos do Compose (confira o mapeamento completo da BOM), introduzindo atualizações em texto, gráficos, layouts, desempenho e muito mais, além de algumas descontinuações e mudanças de comportamento importantes que você precisa conhecer.
Meghan Mehta • Leitura de 10 min
Receba os insights mais recentes sobre o desenvolvimento para Android na sua caixa de entrada toda semana.