さまざまなフォーム ファクタに合わせてメディア コンテンツをスケーリングする

Android は、従来の縦向きのスマートフォンだけでなく、折りたたみ式デバイス、タブレット、デスクトップ ウィンドウ環境、外部ディスプレイなど、さまざまなフォーム ファクタに対応しています。画面の形状が静的であると想定すると、メディア コンテンツが引き伸ばされたり、切り抜かれたり、意図しないレターボックスが表示されたりする可能性があります。アプリは、進化するディスプレイ モード全体で、さまざまなソースメディアのアスペクト比(従来の 4:3 からウルトラワイドまで)に動的に適応する必要があります。

Jetpack Compose でのメディア レイアウトの失敗のほとんどは、次の 3 つの一般的なアーキテクチャ上の落とし穴に起因しています。

  • ウィンドウ インセットの処理とエッジ ツー エッジの競合が不整合。
  • ウィンドウ サイズの計算が正しくないため、レイアウトの更新に一貫性がない。
  • コンテンツ スケーリング オプションの構成ミス。

このガイドでは、Media3 と Jetpack Compose を使用して、これらの各領域に対処するための戦略とベスト プラクティスについて説明します。

ウィンドウ インセットとエッジ ツー エッジの競合を処理する

Android 15(API レベル 35)以降を搭載したデバイスでは、API レベル 35 以降を対象とするアプリはデフォルトでエッジ ツー エッジで表示されます。ステータスバー、ナビゲーション バー、デスクトップ キャプション バーなどのシステムバーは、アプリのコンテンツの上に描画されます。また、ディスプレイ カットアウトによってコンテンツの一部が隠れることがあります。

ウィンドウ インセットを適切に管理しないと、次の 2 つの大きなレイアウト競合が発生します。

  • システムバーの重なり: 動画フレーム、字幕、再生コントロールが、ステータスバー(時計、バッテリー アイコン)、ジェスチャー バー、ナビゲーション バー、ディスプレイ カットアウト(カメラノッチ)によって部分的に隠れています。一般的な設定手順については、エッジ ツー エッジを設定するをご覧ください。
  • デスクトップ モードのキャプション バーの干渉: デスクトップ ウィンドウ モードでは、ウィンドウ管理のために上部にキャプション バーが導入されます。このキャプションバーを考慮せずにカスタム ヘッダーやエッジツーエッジのメディア キャンバスをレンダリングする標準レイアウトでは、動画フレームと上部の再生コントロールが隠れてクリックできなくなります。ウィンドウの状態の詳細については、デスクトップ ウィンドウをサポートするをご覧ください。
エッジ ツー エッジのメディア キャンバスと再生コントロールに重なっているシステム ステータスバー。 ジェスチャー ナビゲーション バーがエッジ ツー エッジのメディア キャンバスと重なっている。 パソコンの字幕バーが上部の動画再生コントロールと重なっている。
図 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. 動画プレーヤーが没入モードになると、システムバーが非表示になります。

動的なウィンドウ サイズ設定とレイアウト更新を計算する

アプリの起動時に画面の幅または高さを 1 回だけ計算すると、デバイス構成が変更されたとき(折りたたみ式デバイスが展開されたとき、マルチウィンドウ セッションのサイズが変更されたとき、ディスプレイが回転されたときなど)に、レイアウトが古い値に依存することになります。

このような場合、子コンポーネントが Modifier.fillMaxWidth() を正しく使用していても、親コンテナが古いサイズで制約されていると、適応に失敗し、レイアウトの引き伸ばし、クリッピング、応答不能が発生します。

次の例では、左側のフレームは標準のビューポートでの正しいレンダリングを示しています。一方、右側のフレームは、デバイスが展開されたときに古いウィンドウ サイズが適応されず、コンテンツ レイアウトがレスポンシブにならないことを示しています。

動的なアスペクト比の調整により、標準のビューポートで正しくレンダリングされる。 デバイスを開いたときに、古いウィンドウのサイズが調整されない。
図 4. 動的なアスペクト比適応の比較。

古いレイアウト制約を回避するには、Jetpack Media Query API を使用します。この API は試験運用版であり、デフォルトで無効になっているため、まず ComposeUiFlags.isMediaQueryIntegrationEnabled = true を設定して mediaQuery 関数を有効にし(たとえば、setContent を呼び出す前に)、@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 構成が重要になります。不適切なコンテンツ スケールを選択すると、動画の歪み(引き伸ばし)や、ビューポートに空白スペースが残る意図しないレターボックスなど、レイアウトの問題が発生する可能性があります。これらのオプションを使用せずに動画サーフェスを手動で管理すると、画面の回転や折りたたみ式デバイスの状態変化時にレイアウトが崩れる可能性があります。

16:9 の動画を 4:3 の画面に表示する場合でも、4:3 の動画を 16:9 のディスプレイに表示する場合でも、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 を使用して、重要な視覚的コンテキストを保護します。