Redacción mágica

La biblioteca media3-ui-compose proporciona los componentes básicos para compilar una IU de contenido multimedia en Jetpack Compose. Está diseñada para desarrolladores que necesitan más personalización que la que ofrece la biblioteca de media3-ui-compose-material3. En esta página, se explica cómo usar los componentes principales y los contenedores de estado para crear una IU de reproductor multimedia personalizada.

Mezcla de componentes de Material 3 y Compose personalizados

La biblioteca media3-ui-compose-material3 está diseñada para ser flexible. Puedes usar los componentes compilados previamente para la mayor parte de tu IU, pero intercambiar un solo componente por una implementación personalizada cuando necesites más control. Aquí es cuando entra en juego la biblioteca de media3-ui-compose.

Por ejemplo, imagina que quieres usar los elementos estándar PreviousButton y NextButton de la biblioteca de Material 3, pero necesitas un PlayPauseButton completamente personalizado. Para ello, puedes usar PlayPauseButton de la biblioteca principal de media3-ui-compose y colocarlo junto con los componentes compilados previamente.

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)
}
ComposeCustomization.kt

Componentes disponibles

La biblioteca media3-ui-compose proporciona un conjunto de elementos componibles precompilados para los controles del reproductor comunes. Estos son algunos de los componentes que puedes usar directamente en tu app:

Personaliza el elemento Player componible

Cuando usas la biblioteca media3-ui-compose-material3, el elemento componible Player proporciona una experiencia de reproducción de contenido multimedia completa. Puedes personalizar su diseño proporcionando tus propios elementos que admiten composición a sus ranuras de contenido, o bien puedes aprovechar el objeto PlayerDefaults para personalizar partes específicas de la IU, como TopControls, CenterControls, BottomControls y ErrorOverlay.

En la Figura 1, se muestra dónde el elemento Player componible coloca sus ranuras. En la figura 2, se muestra el orden en el que se dibujan las capas.

Por ejemplo, puedes usar PlayerDefaults.CenterControls para anular solo el botón central de reproducción/pausa y dejar intacto el resto de los controles centrales. También puedes pasar un elemento componible completamente personalizado para un parámetro como topControls y omitir por completo otros, como bottomControls, para dejarlos en su valor predeterminado.

@Composable
fun CustomPlayerSlots(player: Player, showControls: Boolean, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier,
    showControls = showControls,
    topControls = {
      // Fully custom top controls
      Text("My custom title")
    },
    centerControls = {
      // Use default CenterControls but override the central button
      PlayerDefaults.CenterControls(
        player = player,
        central = {
          // A custom play/pause button
          Material3PlayPauseButton(player, modifier = Modifier.size(64.dp))
        },
      )
    },
    // bottomControls are left as default
  )
}
ComposeCustomization.kt

Contenedores de estado de la IU

Si ninguno de los componentes de scaffolding satisface tus necesidades, también puedes usar los objetos de estado directamente. Por lo general, se recomienda usar los métodos remember correspondientes para conservar el aspecto de la IU entre recomposiciones.

Para comprender mejor cómo puedes usar la flexibilidad de los contenedores de estado de la IU en comparación con los elementos componibles, lee sobre cómo Compose administra el estado.

Contenedores de estado de botones

Para algunos estados de la IU, la biblioteca supone que lo más probable es que los consuman elementos componibles similares a botones.

Ejemplo de uso de 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),
  )
}
ComposeCustomization.kt

Contenedores de estado de salida visual

CurrentMediaItemState proporciona información sobre el MediaItem que se está reproduciendo, mientras que PlaylistState expone información sobre el MediaItems establecido en el reproductor. Son útiles para mostrar información de metadatos en tu IU personalizada.

ErrorState proporciona información sobre el estado de error actual del reproductor, que se puede usar para mostrar una superposición de error.

PresentationState contiene información sobre cuándo se puede mostrar el resultado del video en un PlayerSurface o cuándo debe cubrirlo un elemento de la IU de marcador de posición. El elemento de componibilidad ContentFrame combina el control de la relación de aspecto con la visualización del obturador sobre una superficie que aún no está lista.

@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.videoAspectRatio)

  // Always leave PlayerSurface to be part of the Compose tree because it will be initialized 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()
  }
}
ComposeCustomization.kt

Aquí, podemos usar presentationState.videoAspectRatio para escalar la Surface a la relación de aspecto elegida (consulta Escala de contenido para conocer más tipos) y presentationState.coverSurface para saber cuándo no es el momento adecuado para mostrar la Surface. En este caso, puedes colocar un obturador opaco sobre la superficie, que desaparecerá cuando la superficie esté lista. ContentFrame te permite personalizar el obturador como una expresión lambda final, pero, de forma predeterminada, será un @Composable Box negro que llenará el tamaño del contenedor superior.

¿Dónde están los flujos?

Muchos desarrolladores de Android están familiarizados con el uso de objetos Flow de Kotlin para recopilar datos de la IU que cambian constantemente. Por ejemplo, es posible que estés buscando un flujo de Player.isPlaying que puedas collect de manera optimizada para ciclos de vida. O algo como Player.eventsFlow para proporcionarte un Flow<Player.Events> que puedes filter de la manera que quieras.

Sin embargo, usar flujos para el estado de la IU de Player tiene algunas desventajas. Una de las principales preocupaciones es la naturaleza asíncrona de la transferencia de datos. Queremos lograr la menor latencia posible entre un Player.Event y su consumo en el lado de la IU, evitando mostrar elementos de la IU que no estén sincronizados con el Player.

Otros puntos incluyen los siguientes:

• Un flujo con todos los Player.Events no se adheriría a un principio de responsabilidad única, y cada consumidor tendría que filtrar los eventos relevantes.
• Crear un flujo para cada Player.Event requerirá que los combines (con combine) para cada elemento de la IU. Existe una asignación de varios a varios entre un Player.Event y un cambio de elemento de la IU. Tener que usar combine podría llevar a la IU a estados potencialmente no permitidos.

Crea estados de IU personalizados

Puedes agregar estados de la IU personalizados si los existentes no satisfacen tus necesidades. Consulta el código fuente del estado existente para copiar el patrón. Una clase de contenedor de estado de la IU típica hace lo siguiente:

1. Recibe un objeto Player.
2. Se suscribe a Player con corrutinas. Consulta Player.listen para obtener más detalles.
3. Responde a un Player.Events en particular actualizando su estado interno.
4. Acepta comandos de lógica empresarial que se transformarán en una actualización de Player adecuada.
5. Se puede crear en varios lugares del árbol de la IU y siempre mantendrá una vista coherente del estado de Player.
6. Expone campos State de Compose que un elemento componible puede consumir para responder de forma dinámica a los cambios.
7. Incluye una función remember*State para recordar la instancia entre composiciones.

Qué sucede tras bambalinas:

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

  var someFieldValue by mutableStateOf(someFieldDefault)
    private set

  fun onClick() {
    player.actionA()
  }

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

Para reaccionar a tus propios Player.Events, puedes detectarlos con Player.listen, que es un suspend fun que te permite ingresar al mundo de las corrutinas y escuchar Player.Events de forma indefinida. La implementación de Media3 de varios estados de la IU ayuda al desarrollador final a no preocuparse por aprender sobre Player.Events.