다양한 폼 팩터에 맞게 미디어 콘텐츠 확장

Android는 폴더블, 태블릿, 데스크톱 창 모드 환경, 외부 디스플레이를 비롯하여 기존의 세로 모드 스마트폰을 넘어 다양한 폼 팩터를 지원합니다. 화면 도형이 정적이라고 가정하면 미디어 콘텐츠가 늘어나거나 잘리거나 의도치 않게 레터박스 처리될 수 있습니다. 앱은 진화하는 디스플레이 모드 전반에서 다양한 소스 미디어 가로세로 비율(클래식 4:3부터 울트라 와이드까지)에 동적으로 적응해야 합니다.

Jetpack Compose의 대부분의 미디어 레이아웃 오류는 다음과 같은 세 가지 일반적인 아키텍처 문제에서 비롯됩니다.

  • 일관되지 않은 창 인셋 처리 및 더 넓은 화면 충돌
  • 잘못된 창 크기 계산으로 인해 레이아웃 업데이트가 일관되지 않습니다.
  • 콘텐츠 크기 조절 옵션의 잘못된 구성

이 가이드에서는 Media3 및 Jetpack Compose를 사용하여 이러한 각 영역을 해결하기 위한 전략과 권장사항을 설명합니다.

창 인셋 및 더 넓은 화면 충돌 처리

Android 15(API 수준 35) 이상을 실행하는 기기에서 API 수준 35 이상을 타겟팅하는 앱은 기본적으로 더 넓은 화면에 표시됩니다. 상태 표시줄, 탐색 메뉴, 데스크톱 자막 표시줄과 같은 시스템 표시줄은 앱 콘텐츠 위에 그려지며 디스플레이 컷아웃은 콘텐츠의 일부를 가릴 수 있습니다.

적절한 창 인셋 관리가 없으면 두 가지 주요 레이아웃 충돌이 발생합니다.

  • 시스템 표시줄 중복: 동영상 프레임, 자막, 재생 컨트롤이 상태 표시줄(시계, 배터리 아이콘), 동작 또는 탐색 메뉴, 디스플레이 컷아웃(카메라 노치)에 의해 부분적으로 가려집니다. 일반적인 설정 안내는 더 넓은 화면 설정을 참고하세요.
  • 데스크톱 모드 자막 표시줄 간섭: 데스크톱 창 모드에서 시스템은 창 관리를 위한 상단 자막 표시줄을 도입합니다. 이 자막 표시줄을 고려하지 않고 커스텀 헤더 또는 더 넓은 미디어 캔버스를 렌더링하는 표준 레이아웃은 동영상 프레임과 상단 재생 컨트롤이 가려져 클릭할 수 없게 됩니다. 창 상태에 관한 자세한 내용은 데스크톱 창 모드 지원을 참고하세요.
더 넓은 화면 미디어 캔버스와 재생 컨트롤과 겹치는 시스템 상태 표시줄 동작 탐색 메뉴가 더 넓은 화면 미디어 캔버스와 겹칩니다. 데스크톱 자막 표시줄이 상단 동영상 재생 컨트롤과 겹칩니다.
그림 1. 시스템 상태 표시줄, 동작 탐색 메뉴, 데스크톱 자막 표시줄이 더 넓은 화면 미디어 캔버스와 겹쳐 동영상 콘텐츠와 재생 컨트롤을 가립니다.

인셋 관리 전략

앱은 플레이어가 몰입형 모드인지 비몰입형 모드인지에 따라 시스템 인셋에 동적으로 적응해야 합니다.

비몰입형 구성

비몰입형 재생에서는 기기 컨텍스트를 유지하기 위해 시스템 표시줄이 계속 표시됩니다.

플레이어가 창 가장자리까지 확장되면 WindowInsets.safeDrawing 및 only와 함께 windowInsetsPadding를 시스템 표시줄 또는 디스플레이 컷아웃과 만나는 가장자리의 각 PlayerDefaults 컨트롤 막대에 적용합니다(예: TopControls의 Top + Horizontal 및 BottomControls의 Bottom + Horizontal). 이렇게 하면 동영상 표시 영역이 컨테이너 전체로 확장되는 동안 컨트롤이 시스템 표시줄에 가려지지 않습니다.

@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
              )
            ),
      )
    },
  )
}

비몰입형 모드에서 앱은 창 인셋 패딩을 통합하여 콘텐츠를 안쪽으로 동적으로 이동합니다.
그림 2. 비몰입형 모드에서는 앱이 창 인셋 패딩을 적용하여 컨트롤을 안쪽으로 이동합니다.

몰입형 구성(세로 및 가로 모드)

전체 화면 몰입형 모드의 목표는 재생 컨트롤에 액세스할 수 있도록 유지하면서 영화 같은 환경을 위해 캔버스를 최대화하는 것입니다.

  1. 미디어 컨트롤 오버레이(예: 상단 및 하단 컨트롤)에 windowInsetsPadding를 적용하여 디스플레이 컷아웃 또는 시스템 동작 영역과 겹치지 않도록 합니다(예: 하단 컨트롤에서 WindowInsets.displayCutout를 WindowInsets.systemGestures와 결합하여 탐색 메뉴가 가장자리 스와이프 동작과 충돌하지 않도록 함).
  2. DisposableEffect 내에서 WindowInsetsControllerCompat를 사용하여 시스템 표시줄을 숨겨 컴포저블을 나갈 때 시스템 UI 공개 상태가 복원되도록 합니다.

@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)
            ),
      )
    },
  )
}

동영상 플레이어가 몰입형 모드로 전환되면 시스템 표시줄이 자동으로 숨겨져 전체 화면 영화 감상 환경을 제공합니다.
그림 3. 동영상 플레이어가 몰입형 모드로 전환되면 시스템 표시줄이 숨겨집니다.

동적 창 크기 조절 및 레이아웃 업데이트 계산

앱 시작 시 화면 너비 또는 높이를 한 번만 계산하면 기기 설정이 변경될 때(예: 폴더블 기기가 펼쳐지거나 멀티 윈도우 세션의 크기가 조절되거나 디스플레이가 회전될 때) 레이아웃이 오래된 값에 의존하게 됩니다.

이러한 경우 하위 구성요소가 Modifier.fillMaxWidth()를 올바르게 사용하더라도 상위 컨테이너가 오래된 크기로 제한되면 적응하지 못하여 늘어남, 잘림 또는 반응하지 않는 레이아웃이 발생합니다.

다음 예에서 왼쪽 프레임은 표준 표시 영역에서 올바른 렌더링을 보여주고 오른쪽 프레임은 기기가 펼쳐질 때 오래된 창 크기가 조정되지 않아 콘텐츠 레이아웃이 반응하지 않는 것을 보여줍니다.

동적 가로세로 비율 조정으로 표준 표시 영역에서 올바르게 렌더링됩니다. 기기가 펼쳐질 때 오래된 창 크기가 조정되지 않습니다.
그림 4. 동적 가로세로 비율 조정 비교

오래된 레이아웃 제약 조건을 방지하려면 Jetpack 미디어 쿼리 API를 사용하세요. 이 API는 실험용이며 기본적으로 사용 중지되어 있으므로 먼저 ComposeUiFlags.isMediaQueryIntegrationEnabled = true를 설정하여(예: setContent를 호출하기 전) mediaQuery 함수를 사용 설정하고 @OptIn(ExperimentalMediaQueryApi::class)로 선택합니다.

derivedMediaQuery를 사용하여 현재 창 크기(예: windowWidth)의 조건을 평가하면 불필요한 재구성 없이 창이 변경될 때 레이아웃이 업데이트됩니다. derivedMediaQuery를 WindowSizeClass 중단점과 결합하여 창이 확장될 때 단일 창 플레이어 레이아웃과 멀티 창 플레이어 레이아웃 간에 전환할 수 있습니다.

@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() }
    }
  }
}

콘텐츠 확장 및 가로세로 비율 구성

사용 가능한 컨테이너 영역 관리와 미디어 콘텐츠 자체의 크기 조정을 구분합니다. 안전 영역 패딩과 같은 인셋 관리를 사용하여 시스템 표시줄 및 디스플레이 컷아웃을 기준으로 컨테이너 경계를 설정합니다. 그런 다음 해당 경계 내에서 확장 전략을 적용합니다. 컨테이너를 구조화하고 가로세로 비율에 따라 시각적 콘텐츠를 확장하는 방법에 관한 디자인 안내는 콘텐츠 구성 및 구조를 참고하세요.

다음 예에서 왼쪽 이미지는 전체 공개 상태가 필요할 때 자르기 전략이 콘텐츠를 잘라내는 방식을 보여주고, 오른쪽 이미지는 맞춤 전략이 전체 프레임 렌더링을 위해 기본 가로세로 비율을 유지하는 방식을 보여줍니다.

전체 가시성이 필요한 경우 콘텐츠가 크게 손실되는 자르기 전략 전체 프레임 렌더링을 위해 기본 가로세로 비율을 유지하는 맞춤 전략입니다.
그림 5. 확장 동작 비교

Media3 구성요소는 표준 동영상 가로세로 비율을 자동으로 처리하지만, 맞춤 Compose 레이아웃이나 제한된 컨테이너(예: 스크롤 가능한 소셜 피드)를 사용할 때는 명시적인 ContentScale 구성이 중요해집니다. 부적절한 콘텐츠 배율을 선택하면 동영상 왜곡(늘이기) 또는 표시 영역에 빈 공간을 남기는 의도하지 않은 레터박스와 같은 레이아웃 문제가 발생할 수 있습니다. 이러한 옵션 없이 동영상 표시 경로를 수동으로 관리하면 화면 회전 또는 폴더블 기기 상태 변경 중에 레이아웃이 손상될 수도 있습니다.

4:3 화면에 16:9 동영상을 표시하든 16:9 디스플레이에 4:3 동영상을 표시하든 Player 컴포저블은 기본적으로 ContentScale.Fit로 설정됩니다. 이렇게 하면 레터박스 또는 필러박스를 적용하여 클리핑 없이 전체 동영상을 표시할 수 있습니다.

이후의 표시 모드 변경(예: 확대/축소 또는 자르기)은 사용자가 주도해야 합니다. 예를 들어 ContentScale.Crop로 전환하여 컨테이너를 완전히 채웁니다. 대화형 크기 조절 전환은 레이아웃 요구사항과 사용자 선택의 균형을 맞춥니다.

샘플 구현

표준 Compose ContentScale 속성을 사용하여 전체 프레임 공개 상태를 적용하고 가로세로 비율을 처리할 수 있습니다.

Player 컴포저블 사용

가장 간단하고 직접적인 방법은 Player 컴포저블을 사용하는 것입니다. 크기 조절 경계를 자동으로 처리하는 상위 수준 래퍼 역할을 하며, 동영상 렌더링을 위한 ContentFrame를 맞춤설정 가능한 컨트롤 오버레이(topControls, centerControls, bottomControls) 및 셔터 레이어와 페어링합니다.

@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
  )
}

맞춤 동영상 플레이어 레이아웃을 빌드하거나 동영상 스트림 바로 위에 맞춤 UI 레이어를 배치할 때 ContentFrame를 직접 사용하여 정확한 하위 수준 레이아웃을 제어할 수 있습니다.

사용자가 제어하는 동적 확장 전환

앱의 시청 환경을 개선하기 위해 선택적 전환 버튼을 추가하여 다양한 콘텐츠 크기 조절 옵션 간에 전환할 수 있습니다. 두 번 탭 동작을 감지하여 플레이어 상태를 ContentScale.Fit와 ContentScale.Crop 간에 즉시 전환할 수 있습니다. 이 기능을 확장하여 최신 동영상 스트리밍 애플리케이션과 유사하게 손가락을 벌리거나 모아 확대/축소 또는 기타 멀티 터치 동작을 사용하여 동적 ContentScale 조정을 지원할 수도 있습니다.

그림 6. ContentScale.Fit과 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,
  )
}

여러 콘텐츠 크기 조정 옵션이 있지만 사용 사례에 따라 크기 조정 옵션을 선택하세요. 화면을 채우는 것이 주된 목표인 짧은 형식 동영상이나 스크롤 가능한 피드에는 ContentScale.Crop를 사용하고, 스포츠 점수나 자막과 같이 중요한 여백 정보가 있는 미디어에는 ContentScale.Fit를 기본값으로 사용하여 필수 시각적 컨텍스트를 보호하세요.