Escalonar conteúdo de mídia em vários formatos

O Android oferece suporte a uma ampla variedade de formatos além dos smartphones convencionais em modo retrato, incluindo dobráveis, tablets, ambientes de modo janela para computador e telas externas. Se você presumir que a geometria da tela é estática, o conteúdo de mídia pode acabar esticado, cortado ou com letterbox não intencional. O app precisa se adaptar dinamicamente a várias proporções de mídia de origem (do clássico 4:3 ao ultra-wide) em diferentes modos de exibição.

A maioria das falhas de layout de mídia no Jetpack Compose se deve a três armadilhas arquitetônicas comuns:

  • Tratamento inconsistente de inserções de janela e colisões de ponta a ponta.
  • Atualizações de layout inconsistentes devido ao cálculo incorreto do tamanho da janela.
  • Configuração incorreta das opções de escalonamento de conteúdo.

Este guia aborda estratégias e práticas recomendadas para lidar com cada uma dessas áreas usando o Media3 e o Jetpack Compose.

Processar encartes de janela e colisões de ponta a ponta

Em dispositivos com o Android 15 (nível 35 da API) e versões mais recentes, os apps que segmentam o nível 35 da API ou versões mais recentes são mostrados de ponta a ponta por padrão. As barras de sistema, como a barra de status, a barra de navegação e a barra de legenda da área de trabalho, são renderizadas sobre o conteúdo do app, e os cortes da tela podem ocultar partes dele.

Sem o gerenciamento adequado de inserções de janela, ocorrem dois conflitos de layout principais:

  • Sobreposições da barra de sistema: frames de vídeo, legendas e controles de mídia são parcialmente ocultados pela barra de status (relógio, ícones de bateria), pela barra de gestos ou de navegação ou por cortes da tela (entalhes da câmera). Para orientações gerais de configuração, consulte Configurar de ponta a ponta.
  • Interferência da barra de legenda do modo área de trabalho: no modo janela para computador, o sistema introduz uma barra de legenda na parte de cima para o gerenciamento de janelas. Os layouts padrão que renderizam cabeçalhos personalizados ou telas de mídia de ponta a ponta sem considerar essa barra de legenda acabam com frames de vídeo e controles de mídia superiores ocultos e não clicáveis. Para mais detalhes sobre os estados de janela, consulte Suporte ao modo janela para computador.
Barra de status do sistema sobrepondo a tela de mídia de ponta a ponta e os controles de mídia. Barra de navegação por gestos sobrepondo a tela de mídia de ponta a ponta. Barra de legendas para computador sobrepondo os controles de mídia superiores do vídeo.
Figura 1. A barra de status do sistema, a barra de navegação por gestos e a barra de legenda do computador se sobrepõem à tela de mídia de ponta a ponta e ocultam o conteúdo do vídeo e os controles de mídia.

Estratégias de gerenciamento de encartes

O app precisa se adaptar dinamicamente às inserções do sistema com base no modo imersivo ou não imersivo do player.

Configurações não imersivas

Na reprodução não imersiva, as barras de sistema permanecem visíveis para preservar o contexto do dispositivo.

Quando o player se estender até as bordas da janela, aplique windowInsetsPadding com WindowInsets.safeDrawing e only a cada barra de controle PlayerDefaults nas bordas em que ela se encontra com as barras do sistema ou o corte da tela (por exemplo, Top + Horizontal em TopControls e Bottom + Horizontal em BottomControls). Isso mantém os controles livres de barras do sistema enquanto a superfície do vídeo se estende pelo contêiner.

@Composable
fun NonImmersiveVideoPlayer(
  player: Player,
  showControls: Boolean,
  modifier: Modifier = Modifier,
) {
  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the status bar, caption bar, and display cutout
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(WindowInsetsSides.Top + WindowInsetsSides.Horizontal)
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the navigation bar and display cutout
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.safeDrawing.only(
                WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal
              )
            ),
      )
    },
  )
}

No modo não imersivo, o app integra o padding de inserção de janela para deslocar o conteúdo dinamicamente para dentro.
Figura 2. No modo não imersivo, o app aplica padding de inserção de janela para deslocar os controles para dentro.

Configurações imersivas (retrato e paisagem)

No modo imersivo de tela cheia, o objetivo é maximizar a tela para uma experiência cinematográfica, mantendo os controles de mídia acessíveis:

  1. Aplique windowInsetsPadding a sobreposições de controle de mídia (como controles superiores e inferiores) para evitar que elas se sobreponham a cortes da tela ou áreas de gestos do sistema (por exemplo, combinando WindowInsets.displayCutout com WindowInsets.systemGestures nos controles inferiores para que a barra de busca não entre em conflito com gestos de deslizar na borda).
  2. Oculte as barras de sistema usando WindowInsetsControllerCompat dentro de um DisposableEffect, garantindo que a visibilidade da IU do sistema seja restaurada ao sair do elemento combinável.

@Composable
fun ImmersiveVideoPlayer(player: Player, showControls: Boolean, modifier: Modifier = Modifier) {
  val view = LocalView.current

  // Manages the system UI lifecycle to create an edge-to-edge cinematic experience
  DisposableEffect(view) {
    // Finds the hosting Activity, unwrapping any ContextWrapper around the view's context
    val activity =
      generateSequence(view.context) { (it as? ContextWrapper)?.baseContext }
        .filterIsInstance<Activity>()
        .firstOrNull()
    val window = activity?.window ?: return@DisposableEffect onDispose {}
    val controller = WindowCompat.getInsetsController(window, view)

    // Records the current system bar state so it can be restored on dispose
    val insets = ViewCompat.getRootWindowInsets(view)
    val wereSystemBarsVisible =
      insets == null ||
        insets.isVisible(WindowInsetsCompat.Type.statusBars()) ||
        insets.isVisible(WindowInsetsCompat.Type.navigationBars())
    val previousBehavior = controller.systemBarsBehavior

    // Hides status bars, navigation bars, and caption bars to maximize the video canvas
    controller.hide(WindowInsetsCompat.Type.systemBars())

    // Allows hidden system bars to temporarily reappear with a swipe gesture from the edge
    controller.systemBarsBehavior =
      WindowInsetsControllerCompat.BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE

    onDispose {
      // Restores the previous system bar state when leaving the composable
      controller.systemBarsBehavior = previousBehavior
      if (wereSystemBarsVisible) {
        controller.show(WindowInsetsCompat.Type.systemBars())
      }
    }
  }

  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    // Keep top controls clear of the display cutout while the system bars are hidden
    topControls = {
      PlayerDefaults.TopControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout.only(
                WindowInsetsSides.Top + WindowInsetsSides.Horizontal
              )
            ),
      ) {
        MuteButton(player = player, modifier = Modifier.align(Alignment.TopEnd).padding(16.dp))
      }
    },
    // Keep bottom controls clear of the display cutout and system gesture areas
    bottomControls = {
      PlayerDefaults.BottomControls(
        player = player,
        modifier =
          Modifier.fillMaxWidth()
            .windowInsetsPadding(
              WindowInsets.displayCutout
                .union(WindowInsets.systemGestures)
                .only(WindowInsetsSides.Bottom + WindowInsetsSides.Horizontal)
            ),
      )
    },
  )
}

A barra de sistema é ocultada automaticamente quando o player de vídeo entra no modo imersivo, proporcionando uma experiência cinematográfica em tela cheia.
Figura 3. As barras de sistema são ocultadas quando o player de vídeo entra no modo imersivo.

Calcular o dimensionamento dinâmico de janelas e as atualizações de layout

Calcular a largura ou a altura da tela apenas uma vez na inicialização do app faz com que os layouts dependam de valores desatualizados quando a configuração do dispositivo muda, como quando um dispositivo dobrável é desdobrado, uma sessão de várias janelas é redimensionada ou a tela é girada.

Nesses casos, mesmo que um componente filho use corretamente Modifier.fillMaxWidth(), ele não vai se adaptar se o contêiner pai for restrito por dimensões desatualizadas, causando alongamento, corte ou layouts que não respondem.

No exemplo a seguir, o frame à esquerda ilustra a renderização correta em uma janela de visualização padrão, enquanto o frame à direita demonstra a falha de adaptação das dimensões desatualizadas da janela quando um dispositivo é aberto, resultando em um layout de conteúdo não responsivo.

Renderização correta na janela de visualização padrão com adaptação dinâmica da proporção. Falha na adaptação das dimensões da janela desatualizada quando o dispositivo é aberto.
Figura 4. Comparação da adaptação dinâmica da proporção.

Para evitar restrições de layout desatualizadas, use a API Jetpack Media Query. Como essa API é experimental e está desativada por padrão, primeiro ative a função mediaQuery definindo ComposeUiFlags.isMediaQueryIntegrationEnabled = true (por exemplo, antes de chamar setContent) e ative-a com @OptIn(ExperimentalMediaQueryApi::class).

Use derivedMediaQuery para avaliar as condições no tamanho atual da janela, como windowWidth, para que o layout seja atualizado quando a janela mudar sem recomposições desnecessárias. É possível combinar derivedMediaQuery com pontos de interrupção WindowSizeClass para alternar entre layouts de player de painel único e de vários painéis conforme a janela se expande:

@OptIn(ExperimentalMediaQueryApi::class)
@Composable
fun AdaptiveVideoPlayerScreen(
  player: Player,
  modifier: Modifier = Modifier,
  relatedContent: @Composable () -> Unit,
) {
  val isWideWindow by derivedMediaQuery {
    windowWidth >= WindowSizeClass.WIDTH_DP_MEDIUM_LOWER_BOUND.dp
  }

  if (isWideWindow) {
    // Medium or expanded width: place the player alongside a details or playlist pane
    Row(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.weight(0.65f).fillMaxHeight())
      Box(modifier = Modifier.weight(0.35f).fillMaxHeight()) { relatedContent() }
    }
  } else {
    // Compact width: stack a 16:9 player above the details pane
    Column(modifier = modifier.fillMaxSize()) {
      Player(player = player, modifier = Modifier.fillMaxWidth().aspectRatio(16f / 9f))
      Box(modifier = Modifier.weight(1f).fillMaxWidth()) { relatedContent() }
    }
  }
}

Configurar o dimensionamento de conteúdo e as proporções

Diferenciar o gerenciamento da área de contêiner disponível do dimensionamento do conteúdo de mídia. Use o gerenciamento de margens, como o preenchimento de área segura, para definir os limites do contêiner em relação às barras de sistema e aos cortes da tela. Em seguida, aplique estratégias de escalonamento dentro desses limites. Para orientações de design sobre como estruturar contêineres e dimensionar conteúdo visual em proporções, consulte Composição e estrutura de conteúdo.

No exemplo a seguir, a imagem à esquerda mostra como uma estratégia de corte pode cortar o conteúdo quando a visibilidade total é necessária, enquanto a imagem à direita mostra como uma estratégia de ajuste preserva a proporção nativa para renderização em tela cheia.

Estratégia de corte que causa perda significativa de conteúdo quando a visibilidade total é necessária. Estratégia de ajuste que mantém a proporção nativa para renderização em tela cheia.
Figura 5. Comparação de comportamentos de escalonamento.

Os componentes do Media3 processam proporções de vídeo padrão automaticamente, mas as configurações explícitas de ContentScale se tornam essenciais ao trabalhar com layouts personalizados do Compose ou contêineres restritos (como feeds de redes sociais roláveis). Selecionar uma escala de conteúdo inadequada pode causar problemas de layout, como distorção de vídeo (alongamento) ou letterboxing não intencional que deixa espaço vazio na janela de visualização. Gerenciar superfícies de vídeo manualmente sem essas opções também pode resultar em layouts corrompidos durante rotações de tela ou mudanças de estado de dispositivos dobráveis.

Seja ao mostrar um vídeo de 16:9 em uma tela de 4:3 ou um vídeo de 4:3 em uma tela de 16:9, o elemento combinável Player usa como padrão ContentScale.Fit. Isso mantém o vídeo inteiro visível sem cortes, aplicando letterbox ou pillarbox.

As mudanças subsequentes no modo de exibição (como zoom ou corte) precisam ser orientadas pelo usuário. Por exemplo, mude para ContentScale.Crop para preencher o contêiner completamente. Um botão interativo de dimensionamento equilibra os requisitos de layout com a escolha do usuário.

Implementações de exemplo

É possível aplicar a visibilidade de frame completo e processar proporções usando as propriedades padrão ContentScale do Compose.

Usar o elemento combinável Player

A abordagem mais simples e direta é usar o elemento combinável Player. Ele funciona como um wrapper de alto nível que processa automaticamente os limites de escalonamento, combinando um ContentFrame para renderização de vídeo com sobreposições de controle personalizáveis (topControls, centerControls, bottomControls) e uma camada de obturador:

@Composable
fun FitVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier.fillMaxSize(), // Fill the available space
    contentScale = ContentScale.Fit, // Default; shown for clarity
  )
}

Ao criar um layout de player de vídeo personalizado ou colocar camadas de interface personalizadas diretamente sobre o stream de vídeo, use ContentFrame diretamente para um controle de layout preciso e de nível inferior.

Botão de escalonamento dinâmico controlado pelo usuário

Para melhorar a experiência de visualização do app, adicione um botão opcional para alternar entre diferentes opções de escala de conteúdo. Ao detectar um gesto de toque duplo, você pode alternar instantaneamente o estado do player entre ContentScale.Fit e ContentScale.Crop. Também é possível estender essa funcionalidade para oferecer suporte a ajustes dinâmicos de ContentScale usando o gesto de pinça para aplicar zoom ou outros gestos multitoque, semelhantes aos aplicativos modernos de streaming de vídeo.

Figura 6. Alternar entre ContentScale.Fit e ContentScale.Crop.

@Composable
fun ZoomableVideoPlayer(player: Player, modifier: Modifier = Modifier) {
  var isCropped by rememberSaveable { mutableStateOf(false) }

  Player(
    player = player,
    modifier =
      modifier
        .fillMaxSize()
        // Handle double-tap to toggle between Fit and Crop scaling
        .pointerInput(Unit) { detectTapGestures(onDoubleTap = { isCropped = !isCropped }) },
    contentScale = if (isCropped) ContentScale.Crop else ContentScale.Fit,
  )
}

Embora existam várias opções de dimensionamento de conteúdo, escolha a opção com base no seu caso de uso: use ContentScale.Crop para vídeos de curta duração ou feeds roláveis em que o objetivo principal é preencher a tela e use ContentScale.Fit como padrão para mídias com informações de margem importantes, como placares esportivos ou legendas, para proteger o contexto visual essencial.