自定义

ExoPlayer 库的核心是 Player 接口。Player 提供了传统的高级媒体播放器功能,如缓冲媒体、播放、暂停和跳转的功能。默认实现 ExoPlayer 无需对播放的媒体类型、存储方式和位置以及呈现方式做出少量假设(因此对媒体的限制也很少)。ExoPlayer 实现会将此工作委托给在创建播放器或将新媒体来源传递给播放器时注入的组件,而不是直接实现媒体的加载和渲染。所有 ExoPlayer 实现共有以下组件:

  • MediaSource 实例,用于定义要播放的媒体、加载媒体以及从中读取加载的媒体。MediaSource 实例由播放器内的 MediaSource.Factory 根据 MediaItem 创建。您还可以使用基于媒体来源的播放列表 API 将它们直接传递到播放器。
  • MediaSource.Factory 实例,可将 MediaItem 转换为 MediaSourceMediaSource.Factory 是在创建播放器时注入的。
  • Renderer 实例,用于渲染媒体的各个组件。这些是在创建播放器时注入的。
  • 一个 TrackSelector,用于选择由 MediaSource 提供的轨道供每个可用的 Renderer 使用。创建播放器时注入 TrackSelector
  • 一个 LoadControl,用于控制 MediaSource 何时缓冲更多媒体以及缓冲多少媒体。在创建播放器时注入了 LoadControl
  • 一个 LivePlaybackSpeedControl,用于控制实时播放期间的播放速度,使播放器能够靠近配置的实时偏移量。LivePlaybackSpeedControl 是在创建播放器时注入的。

整个库中都存在注入实现播放器功能的组件的概念。某些组件的默认实现会将工作委托给进一步注入的组件。这样,就可以将许多子组件单独替换为以自定义方式配置的实现。

播放器自定义

下面介绍了通过注入组件自定义播放器的一些常见示例。

配置网络堆栈

我们提供了一个关于如何自定义 ExoPlayer 使用的网络堆栈的页面。

缓存从网络加载的数据

请参阅有关临时缓存下载媒体的指南。

自定义服务器互动

某些应用可能想要拦截 HTTP 请求和响应。您可能想要注入自定义请求标头、读取服务器的响应标头、修改请求的 URI 等。例如,您的应用可能会在请求媒体段时注入令牌作为标头,以此进行自我身份验证。

以下示例演示了如何通过将自定义 DataSource.Factory 注入 DefaultMediaSourceFactory 来实现这些行为:

Kotlin

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

Java

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 在每个 HTTP 请求中包含标头 "Header: Value"。系统会针对与 HTTP 来源的每次互动固定此行为。

如需采用更精细的方法,您可以使用 ResolvingDataSource 注入即时行为。以下代码段展示了如何在与 HTTP 来源交互之前注入请求标头:

Kotlin

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

Java

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

您还可以使用 ResolvingDataSource 对 URI 进行即时修改,如以下代码段所示:

Kotlin

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

Java

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

自定义错误处理

通过实现自定义 LoadErrorHandlingPolicy,应用可以自定义 ExoPlayer 对加载错误的反应方式。例如,应用可能希望快速失败而不是重试多次,或者可能需要自定义退避逻辑,该逻辑用于控制玩家在每次重试之间的等待时间。以下代码段展示了如何实现自定义退避逻辑:

Kotlin

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

Java

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 参数包含有关失败加载的更多信息,可根据错误类型或失败请求自定义逻辑。

自定义提取器标志

提取器标志可用于自定义如何从渐进式媒体中提取各种格式。您可以在提供给 DefaultMediaSourceFactoryDefaultExtractorsFactory 上设置它们。以下示例传递了一个标志,用于为 MP3 流启用基于索引的跳转。

Kotlin

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

Java

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

Kotlin

val extractorsFactory = DefaultExtractorsFactory().setConstantBitrateSeekingEnabled(true)

Java

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

然后,可以根据上述自定义提取器标志的说明,通过 DefaultMediaSourceFactory 注入 ExtractorsFactory

启用异步缓冲区队列

异步缓冲区队列是 ExoPlayer 渲染流水线的一项增强功能,该流水线以异步模式运行 MediaCodec 实例,并使用额外的线程安排数据的解码和渲染。启用该模式可以减少丢帧和音频欠载。

异步缓冲区队列在搭载 Android 12(API 级别 31)及更高版本的设备上默认处于启用状态,并且从 Android 6.0(API 级别 23)开始可以手动启用。请考虑针对存在丢帧或音频欠载的特定设备启用此功能,尤其是在播放受 DRM 保护或高帧速率的内容时。

在最简单的情况下,您需要向播放器注入一个 DefaultRenderersFactory,如下所示:

Kotlin

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

Java

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

如果您要直接实例化渲染程序,请将 AsynchronousMediaCodecAdapter.Factory 传递给 MediaCodecVideoRendererMediaCodecAudioRenderer 构造函数。

使用 ForwardingPlayer 拦截方法调用

您可以自定义 Player 实例的某些行为,只需将该实例封装在 ForwardingPlayer 的子类中并替换相应方法即可:

  • 先访问参数,然后再将其传递给委托 Player
  • 在将其返回之前,先访问委托 Player 的返回值。
  • 完全重新实现该方法。

替换 ForwardingPlayer 方法时,请务必确保实现保持自一致性且与 Player 接口兼容,尤其是在处理旨在具有相同或相关行为的方法时。例如:

  • 如果要替换每个“播放”操作,则需要同时替换 ForwardingPlayer.playForwardingPlayer.setPlayWhenReady,因为调用方希望这些方法的行为在 playWhenReady = true 时相同。
  • 如果您想要更改快进增量,则需要替换 ForwardingPlayer.seekForward 以使用自定义增量执行跳转,并替换 ForwardingPlayer.getSeekForwardIncrement 以便将正确的自定义增量报告给调用方。
  • 如果您想控制播放器实例通告的 Player.Commands,则必须同时替换 Player.getAvailableCommands()Player.isCommandAvailable(),并监听 Player.Listener.onAvailableCommandsChanged() 回调,以便在底层播放器发生更改时收到通知。

MediaSource 自定义

上面的示例注入了自定义组件,以便在传递给播放器的所有 MediaItem 对象播放期间使用。需要进行精细自定义时,还可以将自定义组件注入到可直接传递给播放器的单个 MediaSource 实例中。以下示例展示了如何自定义 ProgressiveMediaSource 以使用自定义的 DataSource.FactoryExtractorsFactoryLoadErrorHandlingPolicy

Kotlin

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

Java

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 可让应用自定义根据 MediaItem 创建 MediaSource 的方式。
  • DataSource - ExoPlayer 的上游软件包已包含适用于不同用例的多个 DataSource 实现。您可能需要实现自己的 DataSource 类以以其他方式加载数据,例如通过自定义协议、自定义 HTTP 堆栈或从自定义永久性缓存加载数据。

构建自定义组件时,我们建议您执行以下操作:

  • 如果自定义组件需要将事件报告回应用,我们建议您使用与现有 ExoPlayer 组件相同的模型来执行此操作,例如使用 EventDispatcher 类,或将 Handler 与监听器一起传递给组件的构造函数。
  • 我们建议自定义组件使用与现有 ExoPlayer 组件相同的模型,以允许应用在播放期间重新配置。为此,自定义组件应实现 PlayerMessage.Target 并通过 handleMessage 方法接收配置更改。应用代码应通过调用 ExoPlayer 的 createMessage 方法、配置消息,然后使用 PlayerMessage.send 将其发送到组件,以传递配置更改。发送要在播放线程上传送的消息可确保这些消息按照在播放器上执行的任何其他操作的顺序执行。