Предварительный просмотр изменений с помощью CompositionPlayer

Библиотека Jetpack Media3 предоставляет API CompositionPlayer — мощную реализацию Player для предварительного просмотра отредактированного видео в реальном времени. Если ваше приложение позволяет пользователям редактировать видео, например, применять эффекты, обрезать или комбинировать несколько входных медиафайлов, CompositionPlayer поможет вам показать точный предварительный просмотр результата. Это может быть полезно в случаях, когда вам не нужно сохранять примененные изменения или проверять правильность настроек перед их фиксацией в окончательном видео для экспорта.

Что такое CompositionPlayer ?

CompositionPlayer — это специализированная реализация интерфейса Player , разработанная специально для воспроизведения объектов Composition . Composition определяет, как располагаются входные медиафайлы, такие как видеоклипы и аудиодорожки, и какие аудио- и видеоэффекты должны к ним применяться. Чтобы узнать больше об API Composition , см. раздел «Определение Composition медиаэлементов» .

Основная цель CompositionPlayer — отображение данной Composition со всеми указанными изменениями в режиме реального времени, позволяя пользователям видеть, как именно будут выглядеть их изменения, прежде чем приступать к потенциально трудоемкому и ресурсозатратному процессу экспорта. Тот же объект Composition затем можно использовать с экземпляром Transformer для экспорта, о чем вы можете узнать больше в разделе «Экспорт Composition .

CompositionPlayer против ExoPlayer

Хотя CompositionPlayer и ExoPlayer являются реализациями Player в Media3, они оптимизированы для разных сценариев использования:

Особенность

CompositionPlayer

ExoPlayer

Входной медиафайл

Принимает один объект Composition, который может состоять из нескольких экземпляров EditedMediaItem с эффектами для каждого элемента.

Принимает один объект MediaItem или плейлист из экземпляров MediaItem.

Хронология

Хронология и продолжительность основаны на всей композиции.

Временная шкала и продолжительность соответствуют активно воспроизводимому медиафайлу.

Эффекты

Эффекты определяются внутри композиции и могут применяться как к отдельному элементу EditedMediaItem, так и ко всей композиции.

Эффекты задаются непосредственно в экземпляре ExoPlayer с помощью метода setVideoEffects() , и каждый эффект применяется индивидуально к каждому элементу в плейлисте.

По сути, CompositionPlayer наиболее полезен, когда вам нужно отобразить сложную Composition из медиафайлов и эффектов, как правило, в контексте редактирования. Используйте ExoPlayer для воспроизведения аудио- или видеоконтента общего назначения или для предварительного просмотра редактирования отдельных элементов с помощью setVideoEffects() .

CompositionPlayer для предварительного просмотра

Интеграция CompositionPlayer в ваше приложение включает в себя несколько ключевых шагов. Во-первых, используйте шаблон проектирования Builder для создания экземпляра CompositionPlayer , а затем задайте Composition для воспроизведения: 

val compositionPlayer = CompositionPlayer.Builder(context).build()
compositionPlayer.setComposition(composition)
compositionPlayer.prepare()
compositionPlayer.play()

Инструкции по созданию Composition см. в разделе «Создание Composition .

Обратите внимание, что поскольку CompositionPlayer реализует интерфейс Player , вы можете установить целевой выходной сигнал и управлять проигрывателем с помощью стандартных методов Player .

Обработка ошибок

Прикрепите экземпляр Player.Listener к вашему CompositionPlayer , чтобы реагировать на события воспроизведения и ошибки. Колбэк onPlayerError() также будет выявлять любые проблемы, возникающие в компонентах, специфичных для редактирования, таких как Composition или VideoGraph.Factory . Подробнее см. в документации по событиям Player .

Важные соображения

При использовании CompositionPlayer следует учитывать некоторые особенности и ограничения:

  • Хотя CompositionPlayer основан на интерфейсе Player , некоторые его функции отличаются от ExoPlayer , поскольку для воспроизведения он зависит от Composition . Например, CompositionPlayer поддерживает установку режима повтора только в значения REPEAT_MODE_OFF или REPEAT_MODE_ALL .
  • По умолчанию CompositionPlayer использует SingleInputVideoGraph.Factory , но если ваша композиция содержит более одной последовательности с изображениями или видеоэлементами, вам следует использовать setVideoGraphFactory() при создании экземпляра CompositionPlayer , чтобы вместо этого использовать MultipleInputVideoGraph.Factory . SingleInputVideoGraph.Factory достаточно, если только одна последовательность содержит изображения или видеоэлементы, а остальные содержат только аудио.
  • Для всех медиаэлементов в вашей композиции необходимо явно задать длительность, либо с помощью MediaItem.Builder.setImageDurationMs() для изображений, либо с помощью EditedMediaItem.Builder.setDurationUs() для аудио или видео.

Поддерживаются следующие сценарии использования:

  • Предварительный просмотр отдельного актива.
  • Предварительный просмотр отдельных последовательностей (то есть, последовательных медиафайлов).
  • Предварительный просмотр одной видеопоследовательности + одной аудиопоследовательности (например, фонового звука).

В настоящее время активно разрабатываются следующие варианты использования:

  • Предварительный просмотр нескольких элементов, включая такие варианты отображения, как «картинка в картинке», «рядом» и «сетка», при работе с несколькими видеопоследовательностями.
  • Настройка процесса редактирования с использованием другого графического движка.

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

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