ExoPlayer 库的核心是 Player
接口。Player
提供了传统的高级媒体播放器功能,如缓冲媒体、播放、暂停和跳转的功能。默认实现 ExoPlayer
无需对播放的媒体类型、存储方式和位置以及呈现方式做出少量假设(因此对媒体的限制也很少)。ExoPlayer
实现会将此工作委托给在创建播放器或将新媒体来源传递给播放器时注入的组件,而不是直接实现媒体的加载和渲染。所有 ExoPlayer
实现共有以下组件:
MediaSource
实例,用于定义要播放的媒体、加载媒体以及从中读取加载的媒体。MediaSource
实例由播放器内的MediaSource.Factory
根据MediaItem
创建。您还可以使用基于媒体来源的播放列表 API 将它们直接传递到播放器。MediaSource.Factory
实例,可将MediaItem
转换为MediaSource
。MediaSource.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
参数包含有关失败加载的更多信息,可根据错误类型或失败请求自定义逻辑。
自定义提取器标志
提取器标志可用于自定义如何从渐进式媒体中提取各种格式。您可以在提供给 DefaultMediaSourceFactory
的 DefaultExtractorsFactory
上设置它们。以下示例传递了一个标志,用于为 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
传递给 MediaCodecVideoRenderer
和 MediaCodecAudioRenderer
构造函数。
使用 ForwardingPlayer
拦截方法调用
您可以自定义 Player
实例的某些行为,只需将该实例封装在 ForwardingPlayer
的子类中并替换相应方法即可:
- 先访问参数,然后再将其传递给委托
Player
。 - 在将其返回之前,先访问委托
Player
的返回值。 - 完全重新实现该方法。
替换 ForwardingPlayer
方法时,请务必确保实现保持自一致性且与 Player
接口兼容,尤其是在处理旨在具有相同或相关行为的方法时。例如:
- 如果要替换每个“播放”操作,则需要同时替换
ForwardingPlayer.play
和ForwardingPlayer.setPlayWhenReady
,因为调用方希望这些方法的行为在playWhenReady = true
时相同。 - 如果您想要更改快进增量,则需要替换
ForwardingPlayer.seekForward
以使用自定义增量执行跳转,并替换ForwardingPlayer.getSeekForwardIncrement
以便将正确的自定义增量报告给调用方。 - 如果您想控制播放器实例通告的
Player.Commands
,则必须同时替换Player.getAvailableCommands()
和Player.isCommandAvailable()
,并监听Player.Listener.onAvailableCommandsChanged()
回调,以便在底层播放器发生更改时收到通知。
MediaSource 自定义
上面的示例注入了自定义组件,以便在传递给播放器的所有 MediaItem
对象播放期间使用。需要进行精细自定义时,还可以将自定义组件注入到可直接传递给播放器的单个 MediaSource
实例中。以下示例展示了如何自定义 ProgressiveMediaSource
以使用自定义的 DataSource.Factory
、ExtractorsFactory
和 LoadErrorHandlingPolicy
:
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
将其发送到组件,以传递配置更改。发送要在播放线程上传送的消息可确保这些消息按照在播放器上执行的任何其他操作的顺序执行。