Настройка

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

• Экземпляры MediaSource определяют медиаданные для воспроизведения, загружают их и из которых можно считывать загруженные медиаданные. Экземпляр MediaSource создаётся из MediaItem с помощью MediaSource.Factory внутри проигрывателя. Их также можно передавать непосредственно в проигрыватель с помощью API плейлистов, основанных на медиаисточниках .
• Экземпляр MediaSource.Factory , который преобразует MediaItem в MediaSource . MediaSource.Factory внедряется при создании проигрывателя.
• Экземпляры Renderer , которые визуализируют отдельные компоненты медиаконтента. Они внедряются при создании проигрывателя.
• TrackSelector , который выбирает дорожки, предоставленные MediaSource , для использования каждым доступным Renderer . TrackSelector внедряется при создании проигрывателя.
• LoadControl , который управляет тем, когда MediaSource буферизует медиаданные и сколько их. LoadControl внедряется при создании проигрывателя.
• Элемент управления LivePlaybackSpeedControl , который управляет скоростью воспроизведения в режиме реального времени, позволяя проигрывателю придерживаться заданного смещения в режиме реального времени. Элемент LivePlaybackSpeedControl внедряется при создании проигрывателя.

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

Настройка игрока

Ниже описаны некоторые распространенные примеры настройки проигрывателя путем внедрения компонентов.

Настройка сетевого стека

У нас есть страница о настройке сетевого стека, используемого ExoPlayer .

Кэширование данных, загруженных из сети

Ознакомьтесь с руководствами по временному кэшированию «на лету» и загрузке медиафайлов .

Настройка взаимодействия с сервером

Некоторые приложения могут перехватывать HTTP-запросы и ответы. Вы можете внедрять пользовательские заголовки запросов, читать заголовки ответов сервера, изменять URI запросов и т. д. Например, ваше приложение может аутентифицировать себя, внедряя токен в качестве заголовка при запросе медиасегментов.

В следующем примере показано, как реализовать эти поведения путем внедрения пользовательского DataSource.Factory в DefaultMediaSourceFactory :

val dataSourceFactory =
  DataSource.Factory {
    val dataSource = httpDataSourceFactory.createDataSource()
    // Set a custom authentication request header.
    dataSource.setRequestProperty("Header", "Value")
    dataSource
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory)
    )
    .build()

DataSource.Factory dataSourceFactory =
    () -> {
      HttpDataSource dataSource = httpDataSourceFactory.createDataSource();
      // Set a custom authentication request header.
      dataSource.setRequestProperty("Header", "Value");
      return dataSource;
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context).setDataSourceFactory(dataSourceFactory))
        .build();

В приведённом выше фрагменте кода внедрённый HttpDataSource включает заголовок "Header: Value" в каждый HTTP-запрос. Это поведение фиксируется для каждого взаимодействия с HTTP-источником.

Для более детального подхода можно внедрить JIT-поведение с помощью ResolvingDataSource . Следующий фрагмент кода показывает, как внедрить заголовки запроса непосредственно перед взаимодействием с HTTP-источником:

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time request headers.
    dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri))
  }

    DataSource.Factory dataSourceFactory =
        new ResolvingDataSource.Factory(
            httpDataSourceFactory,
            // Provide just-in-time request headers.
            dataSpec -> dataSpec.withRequestHeaders(getCustomHeaders(dataSpec.uri)));

Вы также можете использовать ResolvingDataSource для выполнения своевременных изменений URI, как показано в следующем фрагменте:

val dataSourceFactory: DataSource.Factory =
  ResolvingDataSource.Factory(httpDataSourceFactory) { dataSpec: DataSpec ->
    // Provide just-in-time URI resolution logic.
    dataSpec.withUri(resolveUri(dataSpec.uri))
  }

DataSource.Factory dataSourceFactory =
    new ResolvingDataSource.Factory(
        httpDataSourceFactory,
        // Provide just-in-time URI resolution logic.
        dataSpec -> dataSpec.withUri(resolveUri(dataSpec.uri)));

Настройка обработки ошибок

Реализация пользовательской политики LoadErrorHandlingPolicy позволяет приложениям настраивать реакцию ExoPlayer на ошибки загрузки. Например, приложение может захотеть быстро завершить загрузку, вместо того чтобы повторять попытки много раз, или настроить логику задержки, которая управляет временем ожидания проигрывателя между повторными попытками. В следующем фрагменте кода показано, как реализовать пользовательскую логику задержки:

val loadErrorHandlingPolicy: LoadErrorHandlingPolicy =
  object : DefaultLoadErrorHandlingPolicy() {
    override fun getRetryDelayMsFor(loadErrorInfo: LoadErrorInfo): Long {
      // Implement custom back-off logic here.
      return 0
    }
  }
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(
      DefaultMediaSourceFactory(context).setLoadErrorHandlingPolicy(loadErrorHandlingPolicy)
    )
    .build()

LoadErrorHandlingPolicy loadErrorHandlingPolicy =
    new DefaultLoadErrorHandlingPolicy() {
      @Override
      public long getRetryDelayMsFor(LoadErrorInfo loadErrorInfo) {
        // Implement custom back-off logic here.
        return 0;
      }
    };

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(
            new DefaultMediaSourceFactory(context)
                .setLoadErrorHandlingPolicy(loadErrorHandlingPolicy))
        .build();

Аргумент LoadErrorInfo содержит дополнительную информацию о неудачной загрузке для настройки логики на основе типа ошибки или неудачного запроса.

Настройка флагов экстрактора

Флаги экстрактора можно использовать для настройки способа извлечения отдельных форматов из прогрессивных медиафайлов. Их можно задать в фабрике DefaultExtractorsFactory , которая предоставляется для DefaultMediaSourceFactory . В следующем примере передаётся флаг, который включает индексный поиск для потоков MP3.

val extractorsFactory =
  DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING)
val player =
  ExoPlayer.Builder(context)
    .setMediaSourceFactory(DefaultMediaSourceFactory(context, extractorsFactory))
    .build()

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setMp3ExtractorFlags(Mp3Extractor.FLAG_ENABLE_INDEX_SEEKING);

ExoPlayer player =
    new ExoPlayer.Builder(context)
        .setMediaSourceFactory(new DefaultMediaSourceFactory(context, extractorsFactory))
        .build();

Включение поиска постоянного битрейта

Для потоков MP3, ADTS и AMR можно включить приблизительный поиск с использованием предположения о постоянном битрейте с помощью флагов FLAG_ENABLE_CONSTANT_BITRATE_SEEKING . Эти флаги можно установить для отдельных экстракторов с помощью отдельных методов DefaultExtractorsFactory.setXyzExtractorFlags , как описано выше. Чтобы включить поиск с постоянным битрейте для всех экстракторов, которые его поддерживают, используйте DefaultExtractorsFactory.setConstantBitrateSeekingEnabled .

val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)

DefaultExtractorsFactory extractorsFactory =
    new DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true);

Затем ExtractorsFactory можно внедрить через DefaultMediaSourceFactory , как описано выше для настройки флагов экстрактора.

Включение асинхронной очереди буферов

Асинхронная организация очереди буферов — это усовершенствование конвейера рендеринга ExoPlayer, который управляет экземплярами MediaCodec в асинхронном режиме и использует дополнительные потоки для планирования декодирования и рендеринга данных. Включение этой функции может уменьшить количество пропущенных кадров и опустошение аудио.

Асинхронная очередь буферов включена по умолчанию на устройствах под управлением Android 12 (уровень API 31) и выше, и может быть включена вручную, начиная с Android 6.0 (уровень API 23). Рассмотрите возможность включения этой функции на устройствах, на которых наблюдаются пропуски кадров или задержка звука, особенно при воспроизведении контента с защитой DRM или высокой частотой кадров.

В простейшем случае вам нужно внедрить DefaultRenderersFactory в проигрыватель следующим образом:

val renderersFactory = 
  DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing()
val exoPlayer = ExoPlayer.Builder(context, renderersFactory).build()

DefaultRenderersFactory renderersFactory =
    new DefaultRenderersFactory(context).forceEnableMediaCodecAsynchronousQueueing();
ExoPlayer exoPlayer = new ExoPlayer.Builder(context, renderersFactory).build();

Если вы создаете экземпляры рендереров напрямую, передайте new DefaultMediaCodecAdapter.Factory(context).forceEnableAsynchronous() конструкторам MediaCodecVideoRenderer и MediaCodecAudioRenderer .

Настройка операций с помощью ForwardingSimpleBasePlayer

Вы можете настроить некоторые функции экземпляра Player , обернув его в подкласс ForwardingSimpleBasePlayer . Этот класс позволяет перехватывать определённые «операции», избавляя от необходимости напрямую реализовывать методы Player . Это обеспечивает согласованное поведение, например, play() , pause() и setPlayWhenReady(boolean) . Это также гарантирует корректную передачу всех изменений состояния зарегистрированным экземплярам Player.Listener . Для большинства случаев настройки ForwardingSimpleBasePlayer следует предпочесть более подверженному ошибкам ForwardingPlayer благодаря этим гарантиям согласованности.

Например, чтобы добавить пользовательскую логику при запуске или остановке воспроизведения:

class PlayerWithCustomPlay(player: Player) : ForwardingSimpleBasePlayer(player) {
  override fun handleSetPlayWhenReady(playWhenReady: Boolean): ListenableFuture<*> {
    // Add custom logic
    return super.handleSetPlayWhenReady(playWhenReady)
  }
}

class PlayerWithCustomPlay extends ForwardingSimpleBasePlayer {

  public PlayerWithCustomPlay(Player player) {
    super(player);
  }

  @Override
  protected ListenableFuture<?> handleSetPlayWhenReady(boolean playWhenReady) {
    // Add custom logic
    return super.handleSetPlayWhenReady(playWhenReady);
  }
}

Или запретить команду SEEK_TO_NEXT (и убедиться, что Player.seekToNext не является командой):

class PlayerWithoutSeekToNext(player: Player) : ForwardingSimpleBasePlayer(player) {
  override fun getState(): State {
    val state = super.getState()
    return state
      .buildUpon()
      .setAvailableCommands(
        state.availableCommands.buildUpon().remove(COMMAND_SEEK_TO_NEXT).build()
      )
      .build()
  }

  // We don't need to override handleSeek, because it is guaranteed not to be called for
  // COMMAND_SEEK_TO_NEXT since we've marked that command unavailable.
}

class PlayerWithoutSeekToNext extends ForwardingSimpleBasePlayer {

  public PlayerWithoutSeekToNext(Player player) {
    super(player);
  }

  @Override
  protected State getState() {
    State state = super.getState();
    return state
        .buildUpon()
        .setAvailableCommands(
            state.availableCommands.buildUpon().remove(COMMAND_SEEK_TO_NEXT).build())
        .build();
  }

  // We don't need to override handleSeek, because it is guaranteed not to be called for
  // COMMAND_SEEK_TO_NEXT since we've marked that command unavailable.
}

Настройка MediaSource

В приведённых выше примерах реализовано внедрение настраиваемых компонентов для использования во время воспроизведения всех объектов MediaItem , переданных проигрывателю. Если требуется детальная настройка, можно также внедрять настраиваемые компоненты в отдельные экземпляры MediaSource , которые затем передаются непосредственно проигрывателю. В примере ниже показано, как настроить ProgressiveMediaSource для использования настраиваемых DataSource.Factory , ExtractorsFactory и LoadErrorHandlingPolicy :

val mediaSource =
  ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
    .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
    .createMediaSource(MediaItem.fromUri(streamUri))

ProgressiveMediaSource mediaSource =
    new ProgressiveMediaSource.Factory(customDataSourceFactory, customExtractorsFactory)
        .setLoadErrorHandlingPolicy(customLoadErrorHandlingPolicy)
        .createMediaSource(MediaItem.fromUri(streamUri));

Создание пользовательских компонентов

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

• Renderer — возможно, вам захочется реализовать собственный Renderer для обработки типа мультимедиа, не поддерживаемого реализациями по умолчанию, предоставляемыми библиотекой.
• TrackSelector – реализация пользовательского TrackSelector позволяет разработчику приложения изменить способ, которым дорожки, отображаемые MediaSource , выбираются для использования каждым из доступных Renderer .
• LoadControl – реализация пользовательского LoadControl позволяет разработчику приложения изменять политику буферизации проигрывателя.
• Extractor — если вам нужна поддержка формата контейнера, который в настоящее время не поддерживается библиотекой, рассмотрите возможность реализации собственного класса Extractor .
• MediaSource – Реализация пользовательского класса MediaSource может быть целесообразна, если вы хотите получать образцы медиаданных для передачи их рендерерам особым образом или если вы хотите реализовать собственное поведение композиции MediaSource .
• MediaSource.Factory – реализация пользовательского MediaSource.Factory позволяет приложению настраивать способ создания MediaSource из MediaItem .
• DataSource – базовый пакет ExoPlayer уже содержит ряд реализаций DataSource для различных вариантов использования. Вы можете реализовать собственный класс DataSource для загрузки данных другим способом, например, по собственному протоколу, с использованием собственного HTTP-стека или из собственного постоянного кэша.

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

• Если пользовательскому компоненту необходимо сообщать о событиях обратно в приложение, мы рекомендуем делать это, используя ту же модель, что и существующие компоненты ExoPlayer, например, используя классы EventDispatcher или передавая Handler вместе со слушателем в конструктор компонента.
• Мы рекомендовали, чтобы пользовательские компоненты использовали ту же модель, что и существующие компоненты ExoPlayer, чтобы приложение могло перенастраивать их во время воспроизведения. Для этого пользовательские компоненты должны реализовывать PlayerMessage.Target и получать изменения конфигурации в методе handleMessage . Код приложения должен передавать изменения конфигурации, вызывая метод createMessage класса ExoPlayer, настраивая сообщение и отправляя его компоненту с помощью PlayerMessage.send . Отправка сообщений в поток воспроизведения гарантирует их выполнение в том же порядке, что и любые другие операции, выполняемые в проигрывателе.