文章マジック

media3-ui-compose ライブラリは、Jetpack Compose でメディア UI を構築するための基盤となるコンポーネントを提供します。これは、media3-ui-compose-material3 ライブラリで提供されるものよりも詳細なカスタマイズが必要なデベロッパー向けに設計されています。このページでは、コア コンポーネントと状態ホルダーを使用してカスタム メディア プレーヤー UI を作成する方法について説明します。

Material3 とカスタムの Compose コンポーネントを組み合わせる

media3-ui-compose-material3 ライブラリは柔軟性を重視して設計されています。ほとんどの UI には事前構築済みのコンポーネントを使用できますが、より詳細な制御が必要な場合は、1 つのコンポーネントをカスタム実装に置き換えることができます。ここで media3-ui-compose ライブラリの出番となります。

たとえば、Material3 ライブラリの標準の PreviousButton と NextButton を使用したいが、完全にカスタムの PlayPauseButton が必要な場合を考えてみましょう。これを行うには、コア media3-ui-compose ライブラリの PlayPauseButton を使用して、構築済みのコンポーネントとともに配置します。

Row {
  // Use prebuilt component from the Media3 UI Compose Material3 library
  PreviousButton(player)
  // Use the scaffold component from Media3 UI Compose library
  PlayPauseButton(player) {
    // `this` is PlayPauseButtonState
    FilledTonalButton(
      onClick = {
        Log.d("PlayPauseButton", "Clicking on play-pause button")
        this.onClick()
      },
      enabled = this.isEnabled,
    ) {
      Icon(
        imageVector = if (showPlay) Icons.Default.PlayArrow else Icons.Default.Pause,
        contentDescription = if (showPlay) "Play" else "Pause",
      )
    }
  }
  // Use prebuilt component from the Media3 UI Compose Material3 library
  NextButton(player)
}
ComposeSnippets.kt

使用可能なコンポーネント

media3-ui-compose ライブラリは、一般的なプレーヤー コントロール用の事前構築済みコンポーザブルのセットを提供します。アプリで直接使用できるコンポーネントを以下に示します。

コンポーネント	説明
PlayPauseButton	再生と一時停止を切り替えるボタンの状態コンテナ。
SeekBackButton	定義された増分で巻き戻すボタンの状態コンテナ。
SeekForwardButton	定義された増分で早送りするボタンの状態コンテナ。
NextButton	次のメディア アイテムにシークするボタンの状態コンテナ。
PreviousButton	前のメディア アイテムにシークするボタンの状態コンテナ。
RepeatButton	リピート モードを切り替えるボタンの状態コンテナ。
ShuffleButton	シャッフル モードを切り替えるボタンの状態コンテナ。
MuteButton	プレーヤーをミュートおよびミュート解除するボタンの状態コンテナ。
TimeText	プレーヤーの進行状況を表示するコンポーザブルの状態コンテナ。
ContentFrame	アスペクト比の管理、サイズ変更、シャッターを処理するメディア コンテンツを表示するためのサーフェス
PlayerSurface	AndroidView で SurfaceView と TextureView をラップする未加工のサーフェス。

UI 状態ホルダー

スキャフォールディング コンポーネントのいずれもニーズを満たしていない場合は、状態オブジェクトを直接使用することもできます。一般的に、対応する remember メソッドを使用して、再コンポーズ間で UI の外観を保持することをおすすめします。

UI 状態ホルダーとコンポーザブルの柔軟性をどのように活用できるかをより深く理解するには、Compose が状態を管理する方法をご覧ください。

ボタンの状態ホルダー

一部の UI 状態では、ボタンのようなコンポーザブルで消費される可能性が高いと想定されます。

状態	remember*State	タイプ
PlayPauseButtonState	rememberPlayPauseButtonState	2-Toggle
PreviousButtonState	rememberPreviousButtonState	定数
NextButtonState	rememberNextButtonState	定数
RepeatButtonState	rememberRepeatButtonState	3-Toggle
ShuffleButtonState	rememberShuffleButtonState	2-Toggle
PlaybackSpeedState	rememberPlaybackSpeedState	メニューまたは N-Toggle

PlayPauseButtonState の使用例:

val state = rememberPlayPauseButtonState(player)

IconButton(onClick = state::onClick, modifier = modifier, enabled = state.isEnabled) {
  Icon(
    imageVector = if (state.showPlay) Icons.Default.PlayArrow else Icons.Default.Pause,
    contentDescription =
      if (state.showPlay) stringResource(R.string.playpause_button_play)
      else stringResource(R.string.playpause_button_pause),
  )
}
ComposeSnippets.kt

ビジュアル出力の状態ホルダー

PresentationState は、PlayerSurface の動画出力を表示できるタイミング、またはプレースホルダ UI 要素でカバーする必要があるタイミングに関する情報を保持します。ContentFrame コンポーザブルは、アスペクト比の処理と、まだ準備ができていないサーフェス上にシャッターを表示する処理を組み合わせます。

@Composable
fun ContentFrame(
  player: Player?,
  modifier: Modifier = Modifier,
  surfaceType: @SurfaceType Int = SURFACE_TYPE_SURFACE_VIEW,
  contentScale: ContentScale = ContentScale.Fit,
  keepContentOnReset: Boolean = false,
  shutter: @Composable () -> Unit = { Box(Modifier.fillMaxSize().background(Color.Black)) },
) {
  val presentationState = rememberPresentationState(player, keepContentOnReset)
  val scaledModifier =
    modifier.resizeWithContentScale(contentScale, presentationState.videoSizeDp)

  // Always leave PlayerSurface to be part of the Compose tree because it will be initialised in
  // the process. If this composable is guarded by some condition, it might never become visible
  // because the Player won't emit the relevant event, e.g. the first frame being ready.
  PlayerSurface(player, scaledModifier, surfaceType)

  if (presentationState.coverSurface) {
    // Cover the surface that is being prepared with a shutter
    shutter()
  }
}
ComposeSnippets.kt

ここでは、presentationState.videoSizeDp を使用して Surface を選択したアスペクト比にスケーリングし（他のタイプについては ContentScale のドキュメントを参照）、presentationState.coverSurface を使用して Surface を表示するタイミングが適切でない場合を把握します。この場合、サーフェスの最前面に不透明なシャッターを配置できます。このシャッターは、サーフェスの準備が整うと消えます。ContentFrame を使用すると、シャッターを後続のラムダとしてカスタマイズできますが、デフォルトでは、親コンテナのサイズを埋める黒い @Composable Box になります。

Flow はどこにありますか？

多くの Android デベロッパーは、Kotlin の Flow オブジェクトを使用して常に変化する UI データを収集することに慣れています。たとえば、ライフサイクル対応の方法で collect できる Player.isPlaying フローを探している場合などです。または、Player.eventsFlow のようなものを使用して、必要な方法で filter できる Flow<Player.Events> を提供します。

ただし、Player UI 状態にフローを使用することには、いくつかのデメリットがあります。主な懸念事項の 1 つは、データ転送の非同期性です。Player.Event と UI 側の消費との間のレイテンシをできるだけ小さくし、Player と同期していない UI 要素が表示されないようにします。

その他のポイント:

• すべての Player.Events を含むフローは単一責任原則に準拠せず、各コンシューマーは関連するイベントをフィルタリングする必要があります。
• 各 Player.Event のフローを作成するには、各 UI 要素に対してそれらを（combine を使用して）結合する必要があります。Player.Event と UI 要素の変更の間には多対多のマッピングがあります。combine を使用すると、UI が違法な状態になる可能性があります。

カスタム UI 状態を作成する

既存の UI 状態がニーズを満たしていない場合は、カスタム UI 状態を追加できます。既存の状態のソースコードをチェックアウトして、パターンをコピーします。一般的な UI 状態ホルダークラスは次の処理を行います。

1. Player を受け取ります。
2. コルーチンを使用して Player に登録します。詳しくは、Player.listen をご覧ください。
3. 特定の Player.Events に応答して、内部状態を更新します。
4. 適切な Player 更新に変換されるビジネス ロジック コマンドを受け入れます。
5. UI ツリーの複数の場所で作成でき、常にプレーヤーの状態の一貫したビューを維持します。
6. コンポーザブルで消費して変更に動的に対応できる Compose State フィールドを公開します。
7. コンポジション間でインスタンスを記憶するための remember*State 関数が付属しています。

具体的な仕組みを説明しましょう。

class SomeButtonState(private val player: Player) {
  var isEnabled by mutableStateOf(player.isCommandAvailable(Player.COMMAND_ACTION_A))
    private set

  var someField by mutableStateOf(someFieldDefault)
    private set

  fun onClick() {
    player.actionA()
  }

  suspend fun observe() =
    player.listen { events ->
      if (
        events.containsAny(
          Player.EVENT_B_CHANGED,
          Player.EVENT_C_CHANGED,
          Player.EVENT_AVAILABLE_COMMANDS_CHANGED,
        )
      ) {
        someField = this.someField
        isEnabled = this.isCommandAvailable(Player.COMMAND_ACTION_A)
      }
    }
}

独自の Player.Events に反応するには、Player.listen を使用してキャッチします。これは、コルーチンの世界に入り、Player.Events を無期限にリッスンできる suspend fun です。Media3 のさまざまな UI 状態の実装により、エンド デベロッパーは Player.Events について学習する必要がなくなります。

注: Player は信頼できる唯一の情報源として機能します。someField を外部から変更すると、UI のビューと Player のビューが異なるため、変更すべきではありません。ボタンに対する操作（クリックなど）は、受信イベントです。これに対し、ローカルでフィールドを更新することなく、適切なアクションを Player に送信します。Player から Player.Event の形式で更新を受け取り、UI 状態を更新します。UI 状態をローカルで作成したボタンなどの UI 要素は、関連情報を抽出して、正しい UI 要素（アイコン、形状、コンテンツの説明、アニメーションなど）を表示できます。Compose の状態と一方向のデータフローの詳細をご覧ください。