Redacción mágica

La biblioteca de media3-ui-compose proporciona los componentes básicos para compilar una IU de medios en Jetpack Compose. Está diseñada para los 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 personalizada del reproductor multimedia.

Combinación de componentes personalizados de Material 3 y Compose

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

Por ejemplo, imagina que quieres usar los elementos PreviousButton y NextButton estándar de la biblioteca de Material3, pero necesitas un PlayPauseButton completamente personalizado. Para ello, usa PlayPauseButton de la biblioteca principal media3-ui-compose y colócalo junto a los componentes previamente compilados.

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 de media3-ui-compose proporciona un conjunto de elementos componibles prediseñados para los controles comunes del reproductor. Estos son algunos de los componentes que puedes usar directamente en tu app:

Componente	Descripción
PlayPauseButton	Es un contenedor de estado para un botón que alterna entre reproducir y pausar.
SeekBackButton	Es un contenedor de estado para un botón que retrocede en un incremento definido.
SeekForwardButton	Es un contenedor de estado para un botón que avanza en un incremento definido.
NextButton	Es un contenedor de estado para un botón que busca el siguiente elemento multimedia.
PreviousButton	Es un contenedor de estado para un botón que busca el elemento multimedia anterior.
RepeatButton	Es un contenedor de estado para un botón que cambia entre los modos de repetición.
ShuffleButton	Es un contenedor de estado para un botón que activa o desactiva el modo aleatorio.
MuteButton	Es un contenedor de estado para un botón que silencia y activa el sonido del reproductor.
TimeText	Es un contenedor de estado para un elemento componible que muestra el progreso del jugador.
ContentFrame	Plataforma para mostrar contenido multimedia que controla la administración de la relación de aspecto, el cambio de tamaño y un obturador
PlayerSurface	Superficie sin procesar que une SurfaceView y TextureView en AndroidView.

Personaliza el elemento Player componible

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

Por ejemplo, puedes usar PlayerDefaults.CenterControls para anular solo el botón central de reproducir/pausar 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, modifier: Modifier = Modifier) {
  Player(
    player = player,
    modifier = modifier,
    topControls = { p, visible ->
      // Fully custom top controls
      AnimatedVisibility(visible) { Text("My custom title") }
    },
    centerControls = { p, visible ->
      // Use default CenterControls but override the central button
      PlayerDefaults.CenterControls(
        player = p,
        visible = visible,
        central = {
          // A custom play/pause button
          Material3PlayPauseButton(it, modifier = Modifier.size(64.dp))
        },
      )
    },
    // bottomControls are left as default
  )
}
ComposeCustomization.kt

Contenedores de estado de la IU

Si ninguno de los componentes de andamiaje satisface tus necesidades, también puedes usar los objetos de estado directamente. En general, es recomendable usar los métodos remember correspondientes para conservar el aspecto de la IU entre las 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 es más probable que los consuman elementos componibles similares a botones.

Estado	remember*State	Tipo
PlayPauseButtonState	rememberPlayPauseButtonState	2-Toggle
PreviousButtonState	rememberPreviousButtonState	Constante
NextButtonState	rememberNextButtonState	Constante
RepeatButtonState	rememberRepeatButtonState	3-Toggle
ShuffleButtonState	rememberShuffleButtonState	2-Toggle
PlaybackSpeedState	rememberPlaybackSpeedState	Menú o N-Toggle

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 conjunto de 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 pantalla superpuesta de error.

PresentationState contiene información sobre cuándo se puede mostrar el video de salida en un PlayerSurface o cuándo se debe cubrir con un elemento de IU de marcador de posición. El elemento ContentFrame componible combina el control de la relación de aspecto con el cuidado de mostrar el 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 ajustar la Surface a la relación de aspecto elegida (consulta Ajuste de contenido para ver 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 completará el tamaño del contenedor principal.

Nota: Estos elementos componibles forman una jerarquía de conveniencia: el elemento componible Player consta de un ContentFrame más ranuras de control de la IU, y ContentFrame consta de un PlayerSurface más lógica de cambio de tamaño y obturador. No es necesario que uses los elementos componibles de nivel inferior cuando uno de nivel superior se ajuste a tus necesidades.

¿Dónde se encuentran los Flows?

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 una manera que tenga en cuenta el ciclo de vida. O algo como Player.eventsFlow para proporcionarte un Player.eventsFlow que puedas filter como quieras.Flow<Player.Events>

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 cumpliría con un solo principio de responsabilidad, y cada consumidor tendría que filtrar los eventos pertinentes.
• 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 en un elemento de la IU. Tener que usar combine podría llevar a la IU a estados potencialmente ilegales.

Crea estados de IU personalizados

Puedes agregar estados de 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 IU típica hace lo siguiente:

1. Toma 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 del reproductor.
6. Expone los 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.

Nota: Player actúa como una única fuente de verdad. No debemos cambiar someField de forma externa, ya que esto generará una divergencia entre la vista de la IU del mundo y la de Player. Actuar sobre el botón (por ejemplo, con un clic) es un evento entrante. Reaccionamos a ella enviando la acción adecuada a Player sin actualizar ningún campo de forma local. Recibimos la actualización de Player en forma de un Player.Event, que actualiza el estado de la IU. El elemento de la IU, como un botón, que creó el estado de la IU de forma local puede extraer la información pertinente para mostrar el elemento de la IU correcto (ícono, forma, descripción del contenido, animación, etcétera). Obtén más información sobre el estado de Compose y el flujo de datos unidireccional.