Expo 视频（expo-video）
一个提供用于在应用中实现视频播放 API 的库。
For the complete documentation index, see llms.txt. Use this Use this file to discover all available pages.
expo-video 是一个适用于 React Native 和 Expo 的跨平台、高性能视频组件，并支持 Web。
已知问题 Android
当两个 VideoView 组件重叠，且它们的 contentFit 属性设置为 cover 时，其中一个视频可能会显示到边界之外。这是一个 已知的上游问题。要解决此问题，请使用 surfaceType 属性并将其设置为 textureView。
安装
- npx expo install expo-videoIf you are installing this in an existing React Native app, make sure to install expo in your project.
在应用配置中进行配置
如果你的项目使用配置插件（Continuous Native Generation (CNG)），你可以使用 expo-video 内置的 配置插件 来进行配置。该插件允许你配置一些无法在运行时设置、且需要构建新的应用二进制文件后才会生效的属性。如果你的应用不使用 CNG，那么你需要手动配置该库。
Example app.json with config plugin
{ "expo": { "plugins": [ [ "expo-video", { "supportsBackgroundPlayback": true, "supportsPictureInPicture": true } ] ], } }
Configurable properties
| Name | Default | Description |
|---|---|---|
supportsBackgroundPlayback | undefined | 一个布尔值，用于启用后台播放支持。如果为 |
supportsPictureInPicture | undefined | 一个布尔值，用于在 Android 和 iOS 上启用画中画。如果为 |
用法
下面是一个带有播放和暂停按钮的视频简单示例。
import { useEvent } from 'expo'; import { useVideoPlayer, VideoView } from 'expo-video'; import { StyleSheet, View, Button } from 'react-native'; const videoSource = 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4'; export default function VideoScreen() { const player = useVideoPlayer(videoSource, player => { player.loop = true; player.play(); }); const { isPlaying } = useEvent(player, 'playingChange', { isPlaying: player.playing }); return ( <View style={styles.contentContainer}> <VideoView style={styles.video} player={player} fullscreenOptions={{ enable: true }} allowsPictureInPicture /> <View style={styles.controlsContainer}> <Button title={isPlaying ? '暂停' : '播放'} onPress={() => { if (isPlaying) { player.pause(); } else { player.play(); } }} /> </View> </View> ); } const styles = StyleSheet.create({ contentContainer: { flex: 1, padding: 10, alignItems: 'center', justifyContent: 'center', paddingHorizontal: 50, }, video: { width: 350, height: 275, }, controlsContainer: { padding: 10, }, });
接收事件
VideoPlayer 属性的变化不会更新 React 状态。因此，要显示有关 VideoPlayer 当前状态的信息，有必要监听它发出的 事件。
该事件系统基于 expo 包中的 EventEmitter 类和 hooks。有几种方式可以监听事件：
useEvent hook
创建一个监听器，返回一个可在组件中使用的状态值。它还会在组件卸载时自动清理。
import { useEvent } from 'expo'; // ... 其他导入、组件定义、播放器创建等。 const { status, error } = useEvent(player, 'statusChange', { status: player.status }); // 组件其余部分...
useEventListener hook
基于 Player.addListener 和 Player.removeListener 方法构建，创建一个带自动清理的事件监听器。
import { useEventListener } from 'expo'; // ...其他导入、组件定义、播放器创建等。 useEventListener(player, 'statusChange', ({ status, error }) => { setPlayerStatus(status); setPlayerError(error); console.log('播放器状态已更改：', status); }); // 组件其余部分...
Player.addListener 方法
这是监听事件最灵活的方式，但需要手动清理，并且需要更多样板代码。
// ...导入、组件定义、播放器创建等。 useEffect(() => { const subscription = player.addListener('statusChange', ({ status, error }) => { setPlayerStatus(status); setPlayerError(error); console.log('播放器状态已更改：', status); }); return () => { subscription.remove(); }; }, []); // 组件其余部分...
播放 assets 目录中的本地媒体
expo-video 支持播放使用 require 函数加载的本地媒体。你可以直接将结果用作源，也可以将其赋值给 VideoSource 的 assetId 参数，如果你还想配置其他属性的话。
import { VideoSource } from 'expo-video'; const assetId = require('./assets/bigbuckbunny.mp4'); const videoSource: VideoSource = { assetId, metadata: { title: 'Big Buck Bunny', artist: 'The Open Movie Project', }, }; const player1 = useVideoPlayer(assetId); // 你可以直接使用 `asset` 作为视频源 const player2 = useVideoPlayer(videoSource);
播放媒体库中的媒体
expo-video 支持使用 expo-media-library 播放从用户媒体库中选取的视频，或任何具有相应权限的有效 PHAsset URI。
要播放媒体库中的视频，你应当使用 MediaLibrary.getAssetsAsync() 获取一个 Asset 对象，并使用其 uri 属性作为视频源的 uri。
在播放之前，务必使用 MediaLibrary.requestPermissionsAsync() 请求所需权限。
在 iOS 上，请务必不要使用资产信息中的 localUri 属性，因为它不包含读取该资产所需的权限。
import * as MediaLibrary from 'expo-media-library'; import { VideoSource, useVideoPlayer, VideoView } from 'expo-video'; // ...组件定义、播放器创建等。 const loadAssetAndReplace = async () => { const { granted } = await MediaLibrary.requestPermissionsAsync(false, ['video']); if (!granted) { return; } const pagedAssets = await MediaLibrary.getAssetsAsync({ mediaType: 'video', }); if (pagedAssets.assets.length > 0) { const [asset] = pagedAssets.assets; const videoSource: VideoSource = { uri: asset.uri, metadata: { title: asset.filename, }, }; await player.replaceAsync(videoSource); await player.replaceAsync(asset.uri); // 或者你也可以直接使用 asset uri player.play(); } }; // 你现在可以使用 loadAssetAndReplace 来加载并播放媒体库中的第一个视频
预加载视频
当另一个视频正在播放时，可以先加载某个视频，再将其显示到视图中。这样可以让后续视频之间的切换更快，并带来更好的用户体验。
要预加载视频，你需要使用视频源创建一个 VideoPlayer。即使播放器没有连接到 VideoView，它也会填充缓冲区。一旦它连接到 VideoView，就能够在不缓冲的情况下开始播放。
在某些情况下，在屏幕生命周期的稍后阶段预加载视频会更有利。在这种情况下，应创建一个源为 null 的 VideoPlayer。要开始预加载，可以使用 replace() 函数将播放器源替换为视频源。
下面是一个如何预加载视频的示例：
import { useVideoPlayer, VideoView, VideoSource } from 'expo-video'; import { useState, useCallback } from 'react'; import { StyleSheet, Text, TouchableOpacity, View } from 'react-native'; const bigBuckBunnySource: VideoSource = 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4'; const elephantsDreamSource: VideoSource = 'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4'; export default function PreloadingVideoPlayerScreen() { const player1 = useVideoPlayer(bigBuckBunnySource, player => { player.play(); }); const player2 = useVideoPlayer(elephantsDreamSource, player => { player.currentTime = 20; }); const [currentPlayer, setCurrentPlayer] = useState(player1); const replacePlayer = useCallback(async () => { currentPlayer.pause(); if (currentPlayer === player1) { setCurrentPlayer(player2); player1.pause(); player2.play(); } else { setCurrentPlayer(player1); player2.pause(); player1.play(); } }, [player1, currentPlayer]); return ( <View style={styles.contentContainer}> <VideoView player={currentPlayer} style={styles.video} nativeControls={false} /> <TouchableOpacity style={styles.button} onPress={replacePlayer}> <Text style={styles.buttonText}>替换播放器</Text> </TouchableOpacity> </View> ); } const styles = StyleSheet.create({ contentContainer: { flex: 1, padding: 10, alignItems: 'center', justifyContent: 'center', paddingHorizontal: 50, }, button: { alignItems: 'center', justifyContent: 'center', borderRadius: 3, paddingVertical: 8, paddingHorizontal: 12, backgroundColor: '#4630ec', }, buttonText: { fontSize: 12, fontWeight: 'bold', color: '#eeeeee', textAlign: 'center', }, video: { width: 300, height: 168.75, marginVertical: 20, }, });
直接使用 VideoPlayer
在大多数情况下，应使用 useVideoPlayer hook 来创建 VideoPlayer 实例。它会管理播放器的生命周期，并确保在组件卸载时正确释放。不过，在某些高级用例中，可能需要创建一个在组件卸载时不会自动销毁的 VideoPlayer。
在这些情况下，可以使用 createVideoPlayer 函数创建 VideoPlayer。你需要注意这种方式带来的风险，因为当播放器不再需要时，必须由你负责调用 release() 方法。如果处理不当，这种方式可能会导致内存泄漏。
import { createVideoPlayer } from 'expo-video'; const player = createVideoPlayer(videoSource);
警告 在 Android 上，使用同一个
VideoPlayer实例同时挂载多个VideoView组件将无法工作，这是由于 平台限制。
缓存视频
如果你的应用经常重复播放同一个视频，可以使用缓存来尽量减少网络流量并提升用户体验，代价是会增加设备存储占用。expo-video 支持在 Android 和 iOS 平台上进行视频缓存。通过将 VideoSource 对象的 useCaching 属性设置为 true 即可启用此功能。
缓存是持久化的，并且在超过首选大小后会按照最近最少使用原则进行清理。此外，由于存储空间不足，系统也可能清除缓存，因此不建议依赖缓存来存储关键数据。
缓存可离线工作。如果视频的部分或全部内容已被缓存，那么在设备离线时也可以从缓存中播放，直到缓存数据耗尽为止。
由于平台限制，iOS 上的 HLS 视频源不能使用缓存。Android 和 iOS 不支持缓存受 DRM 保护的视频。
管理缓存
- 可以使用
setVideoCacheSizeAsync函数定义首选缓存大小（单位：字节）。默认缓存大小为 1GB。 - 可使用
getCurrentVideoCacheSize获取当前缓存占用的存储空间（单位：字节）。 - 可使用
clearVideoCacheAsync清除所有已缓存的视频。
API
import { VideoView, useVideoPlayer } from 'expo-video';
Components
Type: React.PureComponent<VideoViewProps>
booleanDetermines whether the player allows Picture in Picture (PiP) mode.
Note: The
supportsPictureInPictureproperty of the config plugin has to be configured for the PiP to work.
boolean • Default: trueSpecifies whether to perform video frame analysis (Live Text in videos). Check official Apple documentation for more details.
ButtonOptionsConfiguration for controlling the visibility of player control buttons.
VideoContentFit • Default: 'contain'Describes how the video should be scaled to fit in the container.
Options are 'contain', 'cover', and 'fill'.
{
dx: number,
dy: number
}Determines the position offset of the video inside the container.
string • Default: undefinedDetermines the cross origin policy used by the underlying native view on web.
If undefined (default), does not use CORS at all. If set to 'anonymous', the video will be loaded with CORS enabled.
Note that some videos may not play if CORS is enabled, depending on the CDN settings.
If you encounter issues, consider adjusting the crossOrigin property.
Acceptable values are: 'anonymous' | 'use-credentials'
FullscreenOptionsDetermines the fullscreen mode options.
boolean • Default: trueDetermines whether native controls should be displayed or not.
Note: Due to platform limitations, the native controls are always enabled in fullscreen mode.
() => voidA callback to call after the mounted VideoPlayer has rendered the first frame into the VideoView.
This event can be used to hide any cover images that conceal the initial loading of the player.
Note: This event may also be called during playback when the current video track changes (for example when the player switches video quality).
() => voidA callback to call after the video player enters fullscreen mode.
() => voidA callback to call after the video player exits fullscreen mode.
() => voidA callback to call after the video player enters Picture in Picture (PiP) mode.
() => voidA callback to call after the video player exits Picture in Picture (PiP) mode.
unionA video player instance. Use useVideoPlayer() hook to create one.
Acceptable values are: VideoPlayer | null
booleanDetermines whether a video should be played "inline", that is, within the element's playback area.
boolean • Default: falseDetermines whether the player allows the user to skip media content.
boolean • Default: trueDetermines whether the timecodes should be displayed or not.
boolean • Default: falseDetermines whether the player should start Picture in Picture (PiP) automatically when the app is in the background.
Note: Only one player can be in Picture in Picture (PiP) mode at a time.
Note: The
supportsPictureInPictureproperty of the config plugin has to be configured for the PiP to work.
SurfaceType • Default: 'surfaceView'Determines the type of the surface used to render the video.
This prop should not be changed at runtime.
boolean • Default: falseUse Audio Nodes for sound playback. When the same player is playing in multiple video views the audio won't increase in volume as the number of players increases.
Note: This property is experimental, when enabled it is known to break audio for some sources. Do not change this property at runtime.
boolean • Default: falseDetermines whether the player should use the default ExoPlayer shutter that covers the VideoView before the first video frame is rendered.
Setting this property to false makes the Android behavior the same as iOS.
Type: React.Element<VideoAirPlayButtonProps>
A view displaying the AVRoutePickerView. Shows a button, when pressed, an AirPlay device picker shows up, allowing users to stream the currently playing video
to any available AirPlay sink.
When using this view, make sure that the
allowsExternalPlaybackplayer property is set totrue.
ColorValue • Default: undefinedThe color of the button icon while AirPlay sharing is active.
() => voidA callback called when the AirPlay route selection popup is about to show.
() => voidA callback called when the AirPlay route selection popup has disappeared.
boolean • Default: trueDetermines whether the AirPlay device selection popup should show video outputs first.
ColorValue • Default: undefinedThe color of the button icon while AirPlay sharing is not active.
Component Methods
Enters fullscreen mode.
Promise<void>Exits fullscreen mode.
Promise<void>Enters Picture in Picture (PiP) mode. Throws an exception if the device does not support PiP.
Note: Only one player can be in Picture in Picture (PiP) mode at a time.
Note: The
supportsPictureInPictureproperty of the config plugin has to be configured for the PiP to work.
Promise<void>Exits Picture in Picture (PiP) mode.
Promise<void>Hooks
| Parameter | Type | Description |
|---|---|---|
| source | VideoSource | A video source that is used to initialize the player. |
| setup(optional) | (player: VideoPlayer) => void | A function that allows setting up the player. It will run after the player is created. |
| playerBuilderOptions(optional) | PlayerBuilderOptions | Options to apply to the Android player builder before the native constructor is invoked. |
Creates a VideoPlayer, which will be automatically cleaned up when the component is unmounted.
VideoPlayerClasses
Type: Class extends SharedObject<VideoPlayerEvents>
A class that represents an instance of the video player.
VideoPlayer Properties
boolean • Default: trueDetermines whether the player should allow external playback.
AudioMixingMode • Default: 'auto'Determines how the player will interact with other audio playing in the system.
union • Default: nullSpecifies the audio track currently played by the player. null when no audio is played.
Acceptable values are: AudioTrack | null
AudioTrack[]An array of audio tracks available for the current video.
SubtitleTrack[]An array of subtitle tracks available for the current video.
VideoTrack[]An array of video tracks available for the current video.
On iOS, when using a HLS source, make sure that the uri contains
.m3u8extension or that thecontentTypeproperty of theVideoSourcehas been set to'hls'. Otherwise, the video tracks will not be available.
numberFloat value indicating how far the player has buffered the video in seconds.
This value is 0 when the player has not buffered up to the current playback time. When it's impossible to determine the buffer state (for example, when the player isn't playing any media), this value is -1.
BufferOptionsSpecifies buffer options which will be used by the player when buffering the video.
You should provide a
BufferOptionsobject when setting this property. Setting individual buffer properties is not supported.
unionThe exact timestamp when the currently displayed video frame was sent from the server,
based on the EXT-X-PROGRAM-DATE-TIME tag in the livestream metadata.
If this metadata is missing, this property will return null.
Acceptable values are: number | null
unionFloat value indicating the latency of the live stream in seconds.
If a livestream doesn't have the required metadata, this will return null.
Acceptable values are: number | null
numberFloat value indicating the current playback time in seconds.
If the player is not yet playing, this value indicates the time position
at which playback will begin once the play() method is called.
Setting currentTime to a new value seeks the player to the given time.
Check out the seekTolerance property to configure the seeking precision.
numberFloat value indicating the duration of the current video in seconds.
booleanIndicates whether the player is currently playing back the media to an external device via AirPlay.
booleanBoolean value indicating whether the player is currently playing a live stream.
boolean • Default: trueBoolean indicating if the player should keep the screen on while playing.
On Android, this property has an effect only when a
VideoViewis visible. If you want to keep the screen awake at all times useexpo-keep-awake.
boolean • Default: falseDetermines whether the player should automatically replay after reaching the end of the video.
boolean • Default: falseBoolean value whether the player is currently muted.
Setting this property to true/false will mute/unmute the player.
number • Default: 1.0Float value between 0 and 16.0 indicating the current playback speed of the player.
booleanBoolean value whether the player is currently playing.
Use
playandpausemethods to control the playback.
boolean • Default: trueBoolean value indicating if the player should correct audio pitch when the playback speed changes.
ScrubbingModeOptionsDetermines whether the scrubbing mode is enabled and what scrubbing optimizations should be enabled.
See
SeekToleranceto set the seeking tolerance, which can also affect the scrubbing performance.
SeekToleranceDetermines the time that the actual position seeked to may precede or exceed the requested seek position.
This property affects the precision of setting the currentTime property and the seekBy method, and on Android, it also affects the accuracy of the scrubber from the default native controls.
By default, the player seeks to the exact requested time.
If you are trying to optimize for scrubbing (many frequent seeks), also see
ScrubbingModeOptions.
boolean • Default: falseBoolean value determining whether the player should show the now playing notification.
Note: On Android,
supportsBackgroundPlaybackproperty of the config plugin has to betruefor the now playing notification to work.
VideoPlayerStatusIndicates the current status of the player.
boolean • Default: falseDetermines whether the player should continue playing after the app enters the background.
Note: The
supportsBackgroundPlaybackproperty of the config plugin has to betruefor the background playback to work.
union • Default: nullSpecifies the subtitle track which is currently displayed by the player. null when no subtitles are displayed.
To ensure a valid subtitle track, always assign one of the subtitle tracks from the
availableSubtitleTracksarray.
Acceptable values are: SubtitleTrack | null
number • Default: 0Float value indicating the interval in seconds at which the player will emit the timeUpdate event.
When the value is equal to 0, the event will not be emitted.
union • Default: nullSpecifies the video track currently played by the player. null when no video is displayed.
Acceptable values are: VideoTrack | null
VideoPlayer Methods
| Parameter | Type |
|---|---|
| times | number | number[] |
| options(optional) | VideoThumbnailOptions |
Generates thumbnails from the currently played asset. The thumbnails are references to native images,
thus they can be used as a source of the Image component from expo-image.
Promise<VideoThumbnail[]>| Parameter | Type |
|---|---|
| source | VideoSource |
| disableWarning(optional) | boolean |
Replaces the current source with a new one.
On iOS, this method loads the asset data synchronously on the UI thread and can block it for extended periods of time. Use
replaceAsyncto load the asset asynchronously and avoid UI lags.
This method will be deprecated in the future.
void| Parameter | Type |
|---|---|
| source | VideoSource |
Replaces the current source with a new one, while offloading loading of the asset to a different thread.
On Android and Web, this method is equivalent to
replace.
Promise<void>| Parameter | Type |
|---|---|
| seconds | number |
Seeks the playback by the given number of seconds. The time to which the player seeks may differ from the specified requested time for efficiency,
depending on the encoding and what is currently buffered by the player. Use this function to implement playback controls that seek by specific amount of time,
in which case, the actual time usually does not have to be precise. For frame accurate seeking, use the currentTime property.
voidType: Class extends SharedRef<'image'>
Represents a video thumbnail that references a native image.
Instances of this class can be passed as a source to the Image component from expo-image.
VideoThumbnail Properties
Methods
Clears all video cache.
This function can be called only if there are no existing
VideoPlayerinstances.
Promise<void>A promise that fulfills after the cache has been cleaned.
| Parameter | Type | Description |
|---|---|---|
| source | VideoSource | A video source that is used to initialize the player. |
| playerBuilderOptions(optional) | PlayerBuilderOptions | Options to apply to the Android player builder before the native constructor is invoked. |
Creates a direct instance of VideoPlayer that doesn't release automatically.
For most use cases you should use theuseVideoPlayerhook instead. See the Using the VideoPlayer Directly section for more details.
VideoPlayerReturns the space currently occupied by the video cache in bytes.
numberReturns whether the current device supports Picture in Picture (PiP) mode.
booleanA boolean which is true if the device supports PiP mode, and false otherwise.
| Parameter | Type |
|---|---|
| sizeBytes | number |
Sets desired video cache size in bytes. The default video cache size is 1GB. Value set by this function is persistent. The cache size is not guaranteed to be exact and the actual cache size may be slightly larger. The cache is evicted on a least-recently-used basis.
This function can be called only if there are no existing
VideoPlayerinstances.
Promise<void>A promise that fulfills after the cache size has been set.
Types
Literal Type: string
Specifies the audio mode that the player should use. Audio mode is set on per-app basis, if there are multiple players playing and
have different a AudioMode specified, the highest priority mode will be used. Priority order: 'doNotMix' > 'auto' > 'duckOthers' > 'mixWithOthers'.
mixWithOthers: The player will mix its audio output with other apps.duckOthers: The player will lower the volume of other apps if any of the active players is outputting audio.auto: The player will allow other apps to keep playing audio only when it is muted. On iOS it will always interrupt other apps whenshowNowPlayingNotificationistruedue to system requirements.doNotMix: The player will pause playback in other apps, even when it's muted.
On iOS, the Now Playing notification is dependent on the audio mode. If the audio mode is different from
doNotMixorautothis feature will not work.
Acceptable values are: 'mixWithOthers' | 'duckOthers' | 'auto' | 'doNotMix'
| Property | Type | Description |
|---|---|---|
| autoSelect(optional) | boolean | Only for: Android iOS Indicates whether this track should be auto-selected based on user preferences. |
| id(optional) | string | Only for: Android A string used by expo-video to identify the audio track. |
| isDefault(optional) | boolean | Only for: Android iOS Indicates whether this is the default audio track. |
| label | string | Label of the audio track in the language of the device. |
| language | string | Language of the audio track. For example, 'en', 'pl', 'de'. |
| name(optional) | string | Only for: Android iOS Name of the audio track as specified in the media source. |
Specifies buffer options which will be used by the player when buffering the video.
| Property | Type | Description |
|---|---|---|
| maxBufferBytes(optional) | number | null | Only for: Android The maximum number of bytes that the player can buffer from the network. When 0 the player will automatically decide appropriate buffer size. Default: 0 |
| minBufferForPlayback(optional) | number | Only for: Android Minimum duration of the buffer in seconds required to continue playing after the player has been paused or started buffering.
Default: 2 |
| preferredForwardBufferDuration(optional) | number | Only for: Android iOS The duration in seconds which determines how much media the player should buffer ahead of the current playback time. On iOS when set to Equivalent to Default: Android: 20, iOS: 0 |
| prioritizeTimeOverSizeThreshold(optional) | boolean | Only for: Android A Boolean value which determines whether the player should prioritize time over size when buffering media. Default: false |
| waitsToMinimizeStalling(optional) | boolean | Only for: iOS A Boolean value that indicates whether the player should automatically delay playback in order to minimize stalling. Equivalent to Default: true |
Configuration for controlling the visibility of player control buttons.
The fullscreen button should be controlled with
fullscreenOptions.enable.
| Property | Type | Description |
|---|---|---|
| showBottomBar(optional) | boolean | Whether to show the bottom control bar (containing time, progress bar, and buttons).
When set to
Default: true |
| showNext(optional) | boolean | Whether to show the next button. Default: false |
| showPlayPause(optional) | boolean | Whether to show the play/pause button. Default: true |
| showPrevious(optional) | boolean | Whether to show the previous button. Default: false |
| showSeekBackward(optional) | boolean | Whether to show the seek backward button. Default: true |
| showSeekForward(optional) | boolean | Whether to show the seek forward button. Default: true |
| showSettings(optional) | boolean | Whether to show the settings button. Default: true |
| showSubtitles(optional) | boolean | null | Whether to show the subtitles button.
Default: undefined |
Literal Type: string
Specifies the content type of the source.
auto: The player will automatically determine the content type of the video.progressive: The player will use progressive download content type. This is the defaultContentTypewhen the uri does not contain an extension.hls: The player will use HLS content type.dash: The player will use DASH content type (Android-only).smoothStreaming: The player will use SmoothStreaming content type (Android-only).
Default:`auto`
Acceptable values are: 'auto' | 'progressive' | 'hls' | 'dash' | 'smoothStreaming'
Specifies DRM options which will be used by the player while loading the video.
| Property | Type | Description |
|---|---|---|
| base64CertificateData(optional) | string | Only for: iOS Specifies the base64 encoded certificate data for the FairPlay DRM.
When this property is set, the |
| certificateUrl(optional) | string | Only for: iOS Specifies the certificate URL for the FairPlay DRM. |
| contentId(optional) | string | Only for: iOS Specifies the content ID of the stream. |
| headers(optional) | Record<string, string> | Determines headers sent to the license server on license requests. |
| licenseServer | string | Determines the license server URL. |
| multiKey(optional) | boolean | Only for: Android Specifies whether the DRM is a multi-key DRM. |
| type | DRMType | Determines which type of DRM to use. |
Literal Type: string
Specifies which type of DRM to use:
- Android supports ClearKey, PlayReady and Widevine.
- iOS supports FairPlay.
Acceptable values are: 'clearkey' | 'fairplay' | 'playready' | 'widevine'
| Property | Type | Description |
|---|---|---|
| isExternalPlaybackActive | boolean | The current external playback status. |
| oldIsExternalPlaybackActive(optional) | boolean | The previous external playback status. |
Data delivered with the mutedChange event.
| Property | Type | Description |
|---|---|---|
| muted | boolean | Boolean value whether the player is currently muted. |
| oldMuted(optional) | boolean | Previous value of the |
Data delivered with the playbackRateChange event.
| Property | Type | Description |
|---|---|---|
| oldPlaybackRate(optional) | number | Previous value of the |
| playbackRate | number | Float value indicating the current playback speed of the player. |
Options to apply to the player builder before the native constructor is invoked
| Property | Type | Description |
|---|---|---|
| seekBackwardIncrement(optional) | number | Only for: Android Seek backward increment in seconds. Values will be clamped between 0.001 and 999 seconds. |
| seekForwardIncrement(optional) | number | Only for: Android Seek forward increment in seconds. Values will be clamped between 0.001 and 999 seconds. |
Contains information about any errors that the player encountered during the playback
| Property | Type | Description |
|---|---|---|
| message | string | - |
Data delivered with the playingChange event.
| Property | Type | Description |
|---|---|---|
| isPlaying | boolean | Boolean value whether the player is currently playing. |
| oldIsPlaying(optional) | boolean | Previous value of the |
Defines scrubbing mode options used by a VideoPlayer.
| Property | Type | Description |
|---|---|---|
| allowSkippingMediaCodecFlush(optional) | boolean | Only for: Android Sets whether to avoid flushing the decoder (where possible) in scrubbing mode.
When Default: true |
| enableDynamicScheduling(optional) | boolean | Only for: Android Sets whether ExoPlayer's dynamic scheduling should be enabled in scrubbing mode. This can result in available output buffers being handled more quickly when seeking. Default: true |
| increaseCodecOperatingRate(optional) | boolean | Only for: Android Whether the codec operating rate should be increased in scrubbing mode. Default: true |
| scrubbingModeEnabled(optional) | boolean | Only for: Android iOS Whether the codec operating rate should be increased in scrubbing mode. You should only enable this when the player is receiving a large number of seeks in a short period of time. For less frequent seeks, fine-tuning the On Android, the player may consume more resources in this mode, so it should only be used for short periods of time in response to user interaction (for example, dragging on a progress bar UI element). On Android, when
Default: false |
| useDecodeOnlyFlag(optional) | boolean | Only for: Android Sets whether to use Default: true |
Determines the time that the actual position seeked to may precede or exceed the requested seek position.
Larger tolerance will usually result in faster seeking.
This property affects the precision of setting the currentTime property and the seekBy method, and on Android, it also affects the accuracy of the scrubber from the default native controls.
If you are trying to optimize for scrubbing (many frequent seeks), also see
ScrubbingModeOptions.
| Property | Type | Description |
|---|---|---|
| toleranceAfter(optional) | number | The maximum time that the actual position seeked to may exceed the requested seek position, in seconds. Must be non-negative. Default: 0 |
| toleranceBefore(optional) | number | The maximum time that the actual position seeked to may precede the requested seek position, in seconds. Must be non-negative. Default: 0 |
Data delivered with the sourceChange event.
| Property | Type | Description |
|---|---|---|
| oldSource(optional) | VideoSource | Previous source of the player. |
| source | VideoSource | New source of the player. |
Data delivered with the sourceLoad event, contains information about the video source that has finished loading.
| Property | Type | Description |
|---|---|---|
| availableAudioTracks | AudioTrack[] | Audio tracks available for the loaded video source. |
| availableSubtitleTracks | SubtitleTrack[] | Subtitle tracks available for the loaded video source. |
| availableVideoTracks | VideoTrack[] | Video tracks available for the loaded video source.
|
| duration | number | Duration of the video source in seconds. |
| videoSource | VideoSource | null | The video source that has been loaded. |
Data delivered with the statusChange event.
| Property | Type | Description |
|---|---|---|
| error(optional) | PlayerError | Error object containing information about the error that occurred. |
| oldStatus(optional) | VideoPlayerStatus | Previous status of the player. |
| status | VideoPlayerStatus | New status of the player. |
| Property | Type | Description |
|---|---|---|
| autoSelect(optional) | boolean | Only for: Android iOS Indicates whether this track should be auto-selected based on user preferences. |
| id(optional) | string | Only for: Android A string used by |
| isDefault(optional) | boolean | Only for: Android iOS Indicates whether this is the default subtitle track. |
| label | string | Label of the subtitle track in the language of the device. |
| language | string | Language of the subtitle track. For example, |
| name(optional) | string | Only for: Android iOS Name of the subtitle track as specified in the media source. |
| Property | Type | Description |
|---|---|---|
| oldSubtitleTrack(optional) | SubtitleTrack | null | Previous subtitle track of the player. |
| subtitleTrack | SubtitleTrack | null | New subtitle track of the player. |
Literal Type: string
Describes the type of the surface used to render the video.
surfaceView: Uses theSurfaceViewto render the video. This value should be used in the majority of cases. Provides significantly lower power consumption, better performance, and more features.textureView: Uses theTextureViewto render the video. Should be used in cases where the SurfaceView is not supported or causes issues (for example, overlapping video views).
You can learn more about surface types in the official ExoPlayer documentation.
Acceptable values are: 'textureView' | 'surfaceView'
Data delivered with the timeUpdate event, contains information about the current playback progress.
| Property | Type | Description |
|---|---|---|
| bufferedPosition | number | Only for: Android iOS Float value indicating how far the player has buffered the video in seconds.
Same as the |
| currentLiveTimestamp | number | null | Only for: Android iOS The exact timestamp when the currently displayed video frame was sent from the server,
based on the |
| currentOffsetFromLive | number | null | Only for: Android iOS Float value indicating the latency of the live stream in seconds.
Same as the |
| currentTime | number | Float value indicating the current playback time in seconds. Same as the |
Literal Type: string
Describes how a video should be scaled to fit in a container.
contain: The video maintains its aspect ratio and fits inside the container, with possible letterboxing/pillarboxing.cover: The video maintains its aspect ratio and covers the entire container, potentially cropping some portions.fill: The video stretches/squeezes to completely fill the container, potentially causing distortion.
Acceptable values are: 'contain' | 'cover' | 'fill'
Contains information that will be displayed in the now playing notification when the video is playing.
| Property | Type | Description |
|---|---|---|
| artist(optional) | string | Only for: Android iOS Secondary text that will be displayed under the title. |
| artwork(optional) | string | Only for: Android iOS The uri of the video artwork. |
| title(optional) | string | Only for: Android iOS The title of the video. |
Handlers for events which can be emitted by the player.
| Property | Type | Description |
|---|---|---|
| audioTrackChange | (payload: AudioTrackChangeEventPayload) => void | Handler for an event emitted when the current audio track changes. |
| availableAudioTracksChange | (payload: AvailableAudioTracksChangeEventPayload) => void | Handler for an event emitted when the available audio tracks change. |
| availableSubtitleTracksChange | (payload: AvailableSubtitleTracksChangeEventPayload) => void | Handler for an event emitted when the available subtitle tracks change. |
| isExternalPlaybackActiveChange | (payload: IsExternalPlaybackActiveChangeEventPayload) => void | Only for: iOS Handler for an event emitted when the video player starts or stops sharing the video via AirPlay. |
| mutedChange | (payload: MutedChangeEventPayload) => void | Handler for an event emitted when the |
| playbackRateChange | (payload: PlaybackRateChangeEventPayload) => void | Handler for an event emitted when the |
| playingChange | (payload: PlayingChangeEventPayload) => void | Handler for an event emitted when the player starts or stops playback. |
| playToEnd | () => void | Handler for an event emitted when the player plays to the end of the current source. |
| sourceChange | (payload: SourceChangeEventPayload) => void | Handler for an event emitted when the current media source of the player changes. |
| sourceLoad | (payload: SourceLoadEventPayload) => void | Handler for an event emitted when the player has finished loading metadata for the current video source.
This event is emitted when the player has finished metadata for a |
| statusChange | (payload: StatusChangeEventPayload) => void | Handler for an event emitted when the status of the player changes. |
| subtitleTrackChange | (payload: SubtitleTrackChangeEventPayload) => void | Handler for an event emitted when the current subtitle track changes. |
| timeUpdate | (payload: TimeUpdateEventPayload) => void | Handler for an event emitted in a given interval specified by the |
| videoTrackChange | (payload: VideoTrackChangeEventPayload) => void | Handler for an event emitted when the current video track changes. |
| volumeChange | (payload: VolumeChangeEventPayload) => void | Handler for an event emitted when the |
Literal Type: string
Describes the current status of the player.
idle: The player is not playing or loading any videos.loading: The player is loading video data from the provided sourcereadyToPlay: The player has loaded enough data to start playing or to continue playback.error: The player has encountered an error while loading or playing the video.
Acceptable values are: 'idle' | 'loading' | 'readyToPlay' | 'error'
Specifies the size of a video track.
| Property | Type | Description |
|---|---|---|
| height | number | Height of the video track in pixels. |
| width | number | Width of the video track in pixels. |
Literal Type: union
Acceptable values are: string | number | null | VideoSourceObject
| Property | Type | Description |
|---|---|---|
| assetId(optional) | number | The asset ID of a local video asset, acquired with the |
| contentType(optional) | ContentType | Only for: Android iOS Specifies the content type of the video source. When set to You should use this property when playing HLS, SmoothStreaming or DASH videos from an uri, which does not contain a standardized extension for the corresponding media type. Default: 'auto' |
| drm(optional) | DRMOptions | Specifies the DRM options which will be used by the player while loading the video. |
| headers(optional) | Record<string, string> | Only for: Android iOS Specifies headers sent with the video request.
|
| metadata(optional) | VideoMetadata | Only for: Android iOS Specifies information which will be displayed in the now playing notification. When undefined the player will display information contained in the video metadata. |
| uri(optional) | string | The URI of the video. On iOS, This property is exclusive with the |
| useCaching(optional) | boolean | Only for: Android iOS Specifies whether the player should use caching for the video.
Default: false |
Additional options for video thumbnails generation.
| Property | Type | Description |
|---|---|---|
| maxHeight(optional) | number | Only for: Android iOS If provided, the generated thumbnail will not exceed this height in pixels, preserving its aspect ratio. |
| maxWidth(optional) | number | Only for: Android iOS If provided, the generated thumbnail will not exceed this width in pixels, preserving its aspect ratio. |
Specifies a VideoTrack loaded from a VideoSource.
| Property | Type | Description |
|---|---|---|
| averageBitrate | number | null | Specifies the average bitrate in bits per second or null if the value is unknown. |
| bitrate | number | null |
Specifies the bitrate in bits per second. This is the peak bitrate if known, or else the average bitrate if known, or else null. |
| frameRate | number | null | Specifies the frame rate of the video track in frames per second. |
| id | string | The id of the video track.
|
| isSupported | boolean | Only for: Android Indicates whether the video track format is supported by the device. |
| mimeType | string | null | MimeType of the video track or null if unknown. |
| peakBitrate | number | null | Specifies the average bitrate in bits per second or null if the value is unknown. |
| size | VideoSize | Size of the video track. |
| url | string | null | The URL of the |
Data delivered with the videoTrackChange event, contains information about the video track which is currently being played.
| Property | Type | Description |
|---|---|---|
| oldVideoTrack(optional) | VideoTrack | null | Previous video track of the player. |
| videoTrack | VideoTrack | null | New video track of the player. |
Data delivered with the volumeChange event.
| Property | Type | Description |
|---|---|---|
| oldVolume(optional) | number | Previous value of the |
| volume | number | Float value indicating the current volume of the player. |