Как определить композицию медиаобъектов

Библиотека Transformer из Media3 предоставляет набор инструментов для редактирования и обработки медиаконтента. Основной компонент для редактирования нескольких объектов – это API Composition. Этот API позволяет объединять несколько входных медиаобъектов, таких как видеоклипы, изображения и аудиодорожки, в единую структуру, которую можно обрабатывать, просматривать и экспортировать. Composition можно представить как временную шкалу, на которой размещены одна или несколько последовательностей медиаконтента. Каждая последовательность (определяемая элементом EditedMediaItemSequence) содержит отдельные медиаобъекты (определяемые как экземпляры EditedMediaItem). Преобразования и эффекты можно применять к отдельному EditedMediaItem или ко всему Composition.

Структура объекта Composition
Структура объекта Composition

Composition – это точка входа для различных вариантов использования Media3 Transformer, например:

  • Последовательное сочетание аудио-, видео- и графических объектов.
  • накладывать одно видео на другое (режим "картинка в картинке");
  • Смешивание фоновой звуковой дорожки с видеорядом.
  • Применение визуальных или аудиоэффектов ко всему отредактированному фрагменту.
  • Обработка сложных сценариев, например видео в формате HDR.

В этом руководстве рассказывается, как определять и создавать объекты Composition, в том числе о ключевых классах, создании простых и сложных композиций с одной или несколькими последовательностями и применении эффектов на разных уровнях.

Основные понятия и классы

Чтобы эффективно использовать API Composition, важно понимать основные классы, участвующие в создании медиакомпозиции:

Effects:

  • Назначение. Объект Effects представляет собой набор аудиопроцессоров и видеоэффектов.
  • Как используется. В контексте Composition Effects можно задать для отдельных экземпляров EditedMediaItem, чтобы изменить определенные клипы, или для Composition в целом (обычно для Presentation-эффектов, влияющих на конечный результат, например для изменения разрешения экрана или частоты кадров).
  • Почему это важно. Effects – это механизм, позволяющий применять преобразования, фильтры и другие виды обработки к медиаконтенту как на уровне отдельных объектов, так и на уровне композиции в целом. Дополнительную информацию вы найдете здесь: Transformations.

EditedMediaItem:

  • Назначение. Этот класс представляет собой отдельный медиафайл (например, видео, изображение или аудиофайл) и изменения, которые необходимо к нему применить.
  • Как используется. Тег EditedMediaItem группирует MediaItem (который указывает на фактический медиаконтент) с объектом Effects.
  • Почему это важно. Это основной элемент композиции. Она позволяет точно определить, какие медиафайлы нужно включить и как каждый из них должен выглядеть и звучать, прежде чем они будут объединены в последовательность.

EditedMediaItemSequence:

  • Цель. Представляет собой линейную последовательность объектов EditedMediaItem, которые должны воспроизводиться один за другим.
  • Как используется. Объект EditedMediaItemSequence создается на основе списка объектов EditedMediaItem. Каждая последовательность в Composition похожа на дорожку или слой на временной шкале многодорожечного видеоредактора. Например, одна последовательность может содержать основные видеоклипы, другая, перекрывающая первую по времени, – видеоклипы, которые будут наложены на первую, а третья – только звуковую дорожку с фоновой музыкой.
  • Важность. Тег EditedMediaItemSequence группирует связанные медиаобъекты, которые должны воспроизводиться друг за другом. Используя несколько последовательностей, вы можете создавать более сложные композиции, например накладывать аудио или визуальные эффекты.

Composition:

  • Назначение. Это объект верхнего уровня, представляющий всю временную шкалу медиаконтента, который нужно обработать. Он служит контейнером для всех медиапоследовательностей и любых глобальных настроек или эффектов, применяемых ко всему выходному сигналу.
  • Как используется. Объект Composition состоит из одного или нескольких объектов EditedMediaItemSequence. Кроме того, на Composition можно применять эффекты ко всей композиции и задавать глобальные настройки, например режим HDR. Если Composition содержит несколько объектов EditedMediaItemSequence, эти последовательности можно расположить так, чтобы они воспроизводились одна за другой или перекрывались по времени, что позволяет создавать наложенные макеты, например "картинка в картинке", или переходы от одной последовательности к другой.
  • Важность. Объект Composition определяет общую структуру входного медиаконтента, который нужно обработать. Это распространенный объект, который можно использовать как для предварительного просмотра изменений с помощью объекта CompositionPlayer, так и для экспорта выходного видео с изменениями, примененными с помощью объекта Transformer.

Как создать и экспортировать Composition

Ниже приведен пример создания видеообъекта, состоящего из двух отредактированных видеоклипов, на которые наложена звуковая дорожка, и его экспорта.

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);

Примеры поддерживаемых вариантов использования

Ниже приведен неполный список случаев, в которых Transformer API поддерживает Composition:

  • Последовательное сочетание аудио-, видео- и графических объектов.
  • Добавление фоновой аудиодорожки в видеообъект.
  • Добавление эффектов в композицию.
  • Сопоставление тонов HDR-входа с SDR для получения более качественного изображения SDR.

Текущие ограничения

Последовательности в композиции должны соответствовать условиям, описанным в разделе Transformer.start(). Кроме того, при работе с композициями пока не поддерживаются следующие операции:

  • Кроссфейдинг видео- или звуковых дорожек

Запросы на добавление функций

Если у вас есть предложения по улучшению API Transformer, создайте запрос на добавление функции в репозитории Media3 на GitHub.