Cómo definir una composición de elementos multimedia

La biblioteca Media3 Transformer proporciona un conjunto de herramientas para editar y manipular contenido multimedia. Un componente central para la edición de varios recursos es la Composition API. Esta API te permite organizar varios elementos de contenido multimedia de entrada, como clips de video, imágenes y pistas de audio, en una estructura única y coherente que se puede procesar, obtener una vista previa o exportar. Se puede considerar un Composition como una línea de tiempo que contiene una o más secuencias de contenido multimedia. Cada secuencia (definida por un EditedMediaItemSequence) contiene elementos multimedia individuales (definidos como instancias de EditedMediaItem). Las transformaciones y los efectos se pueden aplicar a un EditedMediaItem individual o a un Composition completo.

Estructura de un objeto Composition
La estructura de un objeto Composition

Un Composition es tu punto de entrada para una variedad de casos de uso con Media3 Transformer, como los siguientes:

  • Combinar secuencialmente recursos de audio, imagen y video
  • Superponer un video sobre otro (imagen en imagen)
  • Mezclar una pista de audio de fondo con una secuencia de video
  • Aplicar efectos visuales o de audio en toda una pieza editada
  • Manejar situaciones complejas, como el procesamiento de video HDR

En esta guía, se explica cómo definir y compilar objetos Composition, incluidas las clases clave involucradas, cómo crear composiciones básicas y más complejas con una o varias secuencias, y cómo aplicar efectos en diferentes niveles.

Conceptos y clases clave

Para usar la API de Composition de manera eficaz, es importante comprender las clases principales involucradas en la construcción de una composición de medios:

Effects:

  • Propósito: Un objeto Effects es una colección de procesadores de audio y efectos de video.
  • Cómo se usa: En el contexto de un Composition, se puede configurar un Effects en instancias individuales de EditedMediaItem para modificar clips específicos o en el Composition en su totalidad (por lo general, para efectos de Presentation que afectan el resultado final, como ajustar la resolución de pantalla o la velocidad de fotogramas).
  • Por qué es importante: Effects es el mecanismo para aplicar transformaciones, filtros y otros procesamientos a tu contenido multimedia a nivel de elemento individual y de composición general. Para obtener más información, consulta Transformations.

EditedMediaItem:

  • Propósito: Esta clase representa una sola pieza de contenido multimedia (como un video, una imagen o un archivo de audio) y las ediciones que se le aplicarán.
  • Cómo se usa: Un EditedMediaItem agrupa un MediaItem (que apunta al contenido multimedia real) con un objetoEffects.
  • Por qué es importante: Este es el componente básico fundamental de tu composición. Te permite definir con precisión qué contenido multimedia incluir y cómo debe verse y escucharse cada pieza individual antes de que se combine con otras en una secuencia.

EditedMediaItemSequence:

  • Propósito: Representa una secuencia lineal de objetos EditedMediaItem que se reproducirán uno después del otro.
  • Cómo se usa: Un EditedMediaItemSequence se construye con una lista de EditedMediaItem objetos. Cada secuencia dentro de un Composition es similar a una pista o capa en una línea de tiempo de edición de video de varias pistas. Por ejemplo, una secuencia puede contener tus clips de video principales, mientras que otra secuencia, que se superpone en el tiempo, puede contener clips de video que se superpondrán en la primera, y otra secuencia puede contener solo una pista de audio para la música de fondo.
  • Por qué es importante: Un EditedMediaItemSequence agrupa elementos multimedia relacionados que deben seguirse directamente. Si usas varias secuencias, puedes crear diseños más complejos, como superponer audio o crear superposiciones visuales.

Composition:

  • Propósito: Este es el objeto de nivel superior que representa toda la línea de tiempo del contenido multimedia que se procesará. Actúa como un contenedor para todas las secuencias de contenido multimedia y cualquier configuración o efecto global que se aplique a toda la salida.
  • Cómo se usa: Un Composition consta de uno o más EditedMediaItemSequence objetos. También puedes aplicar efectos en toda la composición y establecer configuraciones globales, como el modo HDR, directamente en el Composition. Si un Composition contiene varios objetos EditedMediaItemSequence, estas secuencias se pueden organizar para que se reproduzcan de forma secuencial o se superpongan en el tiempo, lo que permite diseños superpuestos, como imagen en imagen o transiciones de una secuencia a otra.
  • Por qué es importante: Un Composition define la estructura general del contenido multimedia de entrada que se procesará y es un objeto común que puedes usar para obtener una vista previa de las ediciones con un CompositionPlayer y exportar un video de salida con las ediciones aplicadas con Transformer.

Crea y exporta un Composition

Este es un ejemplo de cómo crear un recurso de video que consta de dos clips de video editados, superpuestos con una pista de audio, y exportarlo:

Kotlin

val video1 = EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build()

val video2 = EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build()

val videoSequence = EditedMediaItemSequence.withAudioAndVideoFrom(listOf(video1, video2))

val backgroundAudio = EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build()

val backgroundAudioSequence =
  EditedMediaItemSequence.withAudioFrom(listOf(backgroundAudio))
    .buildUpon()
    .setIsLooping(true) // Loop audio track through duration of videoSequence
    .build()

val composition = Composition.Builder(videoSequence, backgroundAudioSequence).build()

transformer.start(composition, filePath)

Java

EditedMediaItem video1 = new EditedMediaItem.Builder(MediaItem.fromUri(video1Uri)).build();

EditedMediaItem video2 = new EditedMediaItem.Builder(MediaItem.fromUri(video2Uri)).build();

EditedMediaItemSequence videoSequence =
    EditedMediaItemSequence.withAudioAndVideoFrom(ImmutableList.of(video1, video2));

EditedMediaItem backgroundAudio =
    new EditedMediaItem.Builder(MediaItem.fromUri(audioUri)).build();

EditedMediaItemSequence backgroundAudioSequence =
    EditedMediaItemSequence.withAudioFrom(ImmutableList.of(backgroundAudio))
        .buildUpon()
        .setIsLooping(true) // Loop audio track through duration of videoSequence
        .build();

Composition composition =
    new Composition.Builder(videoSequence, backgroundAudioSequence).build();

transformer.start(composition, filePath);

Ejemplos de casos de uso compatibles

Esta es una lista no exhaustiva de casos de uso que admite la API de Transformer con Composition:

  • Combinar secuencialmente recursos de audio, imagen y video
  • Agregar audio de fondo a un recurso de video
  • Agregar efectos a una composición
  • Asignar el tono de la entrada HDR a SDR para generar una salida SDR de mejor calidad visual

Limitaciones actuales

Las secuencias dentro de una composición deben cumplir con las condiciones que se describen en Transformer.start(). Además, aún no se admiten las siguientes operaciones cuando se trabaja con composiciones:

  • Fundido cruzado de pistas de audio o video

Solicitudes de funciones

Si tienes alguna solicitud de función para las APIs de Transformer, registra un problema en el repositorio de GitHub de Media3.