This is documentation for the next SDK version. For up-to-date documentation, see the latest version (SDK 57).

Expo 视频（expo-video）

一个提供 API 用于在应用中实现视频播放的库。

Android

iOS

tvOS

Web

Included in Expo Go

GitHub

npm

更新日志

expo-video 是一个跨平台、高性能的视频组件，适用于 React Native 和 Expo，并支持 Web。

已知问题
Android

当两个 VideoView 组件相互重叠，并且它们的 contentFit 属性设置为 cover 时，其中一个视频可能会显示到边界之外。这是一个已知的上游问题。要解决此问题，请使用 surfaceType 属性，并将其设置为 textureView。

安装

Terminal

- npx expo install expo-video

- yarn expo install expo-video

- pnpm expo install expo-video

- bun expo install expo-video

If you are installing this in an existing React Native app, make sure to install expo in your project.

在 app 配置中进行配置

如果你的项目使用了配置插件（Continuous Native Generation (CNG)），你可以使用 expo-video 内置的配置插件进行配置。该插件允许你配置一些无法在运行时设置、且需要重新构建应用二进制文件才会生效的属性。如果你的应用不使用 CNG，则需要手动配置该库。

Example app.json with config plugin

app.json

{
  "expo": {
    "plugins": [
      [
        "expo-video",
        {
          "supportsBackgroundPlayback": true,
          "supportsPictureInPicture": true
        }
      ]
    ],
  }
}

Configurable properties

Name	Default	Description
`supportsBackgroundPlayback`	`undefined`	一个布尔值，用于启用后台播放支持。如果为 `true`，在 iOS 上，会将 `audio` 键添加到 Info.plist 文件中的 `UIBackgroundModes` 数组；如果为 `false`，则移除该键；如果为 `undefined`，则不会修改该键。在 Android 上，如果为 `true`，会添加前台服务权限，并在 AndroidManifest.xml 中创建一个 expo-video 前台服务。
`supportsPictureInPicture`	`undefined`	一个布尔值，用于在 Android 和 iOS 上启用画中画。如果为 `true`，会在 Android 上启用 `android:supportsPictureInPicture` 属性，并在 iOS 上将 `audio` 键添加到 Info.plist 文件中的 `UIBackgroundModes` 数组；如果为 `false`，则移除该键；如果为 `undefined`，则不会修改配置。

用法

下面是一个带有播放和暂停按钮的视频简单示例。

视频

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 当前状态的信息，必须监听它发出的事件。事件系统基于 EventEmitter 类以及来自 expo 包的钩子。监听事件有几种方式：

`useEvent` 钩子

创建一个监听器，返回一个可用于组件中的有状态值。组件卸载时也会自动清理。

useEvent

import { useEvent } from 'expo';
// ... 其他导入、组件定义、创建 player 等。

const { status, error } = useEvent(player, 'statusChange', { status: player.status });
// 组件其余部分...

`useEventListener` 钩子

基于 Player.addListener 和 Player.removeListener 方法，创建一个带自动清理的事件监听器。

useEventListener

import { useEventListener } from 'expo';
// ...其他导入、组件定义、创建 player 等。

useEventListener(player, 'statusChange', ({ status, error }) => {
  setPlayerStatus(status);
  setPlayerError(error);
  console.log('播放器状态已更改：', status);
});
// 组件其余部分...

`Player.addListener` 方法

监听事件最灵活的方式，但需要手动清理，并且需要更多样板代码。

Player.addListener

// ...导入、组件定义、创建 player 等。

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/legacy 从用户的媒体库中挑选的视频，或任何带有相应权限的有效 PHAsset URI。

要播放媒体库中的视频，你应当使用 MediaLibrary.getAssetsAsync() 获取一个 Asset 对象，并将其 uri 属性作为视频源的 uri。在播放之前，请务必使用 MediaLibrary.requestPermissionsAsync() 请求所需权限。

在 iOS 上，请务必不要使用资产信息中的 localUri 属性，因为它不包含读取该资产所需的权限。

播放媒体库中的媒体

import * as MediaLibrary from 'expo-media-library/legacy';
import { VideoSource, useVideoPlayer, VideoView } from 'expo-video';

// ...组件定义、创建 player 等。

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 函数清除所有已缓存视频。

拦截原生资源加载

这是 expo-video 的一个原生功能，面向高级用户。展开以了解更多。

简介

expo-video 在 iOS 上包含一个名为 VideoAssetTransportProvider 的原生扩展点。它允许你拦截特定视频源，自定义底层 AVURLAsset 的创建方式，并覆盖其加载数据的方式。

当某个源无法被 AVKit 直接处理、需要原生预处理时，这非常有用。例如，provider 可以重写 URL、附加自定义的 AVAssetResourceLoaderDelegate、启动本地代理服务器，或在播放开始前将一种流格式转换为另一种。

Providers 会在模块启动时注册到 VideoAssetTransportRegistry 中。当 expo-video 加载某个源时，它会创建一个 VideoAssetSourceDescriptor，并按优先级顺序询问已注册的 providers 是否愿意处理该源。第一个返回 VideoAssetLoadPlan 的 provider 会被使用。

此 API 面向高级原生集成。它需要自定义原生模块，因此在 Expo Go 中不可用。请改用开发构建。

可自定义属性

主要的自定义点是 VideoAssetTransportProvider 的字段以及它返回的 VideoAssetLoadPlan 的字段。

VideoAssetTransportProvider 允许你控制以下属性：

属性	描述
`identifier`	provider 的稳定名称。用于替换或注销 provider。
`priority`	当多个 provider 匹配同一源时，哪个 provider 获胜。数值越高优先级越高。
`makeLoadPlan(for:)`	匹配和配置的入口点。返回 `nil` 表示忽略某个源，或返回 `VideoAssetLoadPlan` 以处理它。

VideoAssetLoadPlan 允许你通过以下属性控制 expo-video 如何构建和管理资源：

属性	描述
`assetURL`	用于初始化底层 `AVURLAsset` 的 URL。可以是原始源 URL，也可以是传输相关的替代 URL，例如重写后的 scheme、本地代理 URL，或生成的播放列表 URL。
`assetOptions`	可选的 `AVURLAsset` 初始化选项。用于覆盖 `expo-video` 通常会根据源推导出的默认选项。
`reportedContentTypeHint`	一个可选的内容类型，用于描述 `assetURL` 的实际播放格式。当传输方式改变了源类型时使用，例如将 DASH 转换为 HLS。
`resourceLoaderDelegate`	可选的 `AVAssetResourceLoaderDelegate`，应附加到资源加载器上。
`resourceLoaderQueue`	可选的 dispatch 队列，`resourceLoaderDelegate` 会在其上接收回调。
`prepareAsset`	在 `expo-video` 主动加载资源属性之前执行的可选异步任务。用于传输引导，例如获取清单或启动本地服务器。
`retainedObjects`	可选的辅助对象数组，这些对象必须在资源生命周期内保持存活，例如本地 HTTP 服务器、解析器或传输状态持有者。
`attachErrorHandler`	一个可选 hook，允许传输在加载计划应用后将异步错误回传给 `expo-video`。
`onAssetDeinit`	在 `VideoAsset` 被释放时执行的可选清理操作。

实现与使用

典型设置如下：

使用 create-expo-module 创建一个 Expo 模块。
添加一个符合 VideoAssetTransportProvider 的类。
在模块的 OnCreate 块中注册该 provider。
构建应用，使原生模块被编译进你的项目。

如果你只需要在单个应用中使用该 provider，请使用本地 Expo 模块流程。

如果你想在多个应用之间复用该 provider，请改用独立 Expo 模块流程。

基础使用示例

定义 provider 和加载计划。创建模块后，添加一个符合 VideoAssetTransportProvider 的类。在 makeLoadPlan(for:) 中，检查 VideoAssetSourceDescriptor，并对你不想处理的源返回 nil。

import ExpoVideo

final class ExampleVideoTransportProvider: VideoAssetTransportProvider {
  static let providerIdentifier = "com.example.video-transport"

  let identifier = Self.providerIdentifier
  let priority = 500

  func makeLoadPlan(for source: VideoAssetSourceDescriptor) -> VideoAssetLoadPlan? {
    guard source.contentTypeHint == .dash, source.url.pathExtension == "mpd" else {
      return nil
    }

    let transformedURL = URL(string: "http://127.0.0.1:8080/master.m3u8")!

    return VideoAssetLoadPlan(
      assetURL: transformedURL,
      reportedContentTypeHint: .hls
    )
  }
}

要注册 provider，推荐在 Expo 模块的 OnCreate 块中注册。这样可以确保在视频开始加载之前 provider 已可用。

import ExpoModulesCore
import ExpoVideo

public final class CustomVideoTransportModule: Module {
  public func definition() -> ModuleDefinition {
    Name("CustomVideoTransport")

    OnCreate {
      VideoAssetTransportRegistry.registerProvider(ExampleVideoTransportProvider())
    }

    OnDestroy {
      VideoAssetTransportRegistry.unregisterProvider(
        withId: ExampleVideoTransportProvider.providerIdentifier
      )
    }
  }
}

完整示例

你可以使用以下完整示例，更好地理解如何使用此 API。

基础 DASH 支持 provider - Bare Expo 中的一个本地模块，为 iOS 上的 expo-video 提供有限的 DASH 支持。
expo-video iOS 缓存 - 内置缓存 provider 的实现。

API

import { VideoView, useVideoPlayer } from 'expo-video';

Components

`VideoView`

Android

iOS

tvOS

Web

Type: React.PureComponent<VideoViewProps>

VideoViewProps

`allowsPictureInPicture`

Android

iOS

Web

Optional • Type: boolean

Determines whether the player allows Picture in Picture (PiP) mode.

Note: The supportsPictureInPicture property of the config plugin has to be configured for the PiP to work.

`allowsVideoFrameAnalysis`

iOS 16.0+

Optional • Type: boolean • Default: true

Specifies whether to perform video frame analysis (Live Text in videos). Check official Apple documentation for more details.

`buttonOptions`

Android

Optional • Type: ButtonOptions

Configuration for controlling the visibility of player control buttons.

`contentFit`

Android

iOS

tvOS

Web

Optional • Type: VideoContentFit • Default: 'contain'

Describes how the video should be scaled to fit in the container. Options are 'contain', 'cover', and 'fill'.

`contentPosition`

iOS

Optional • Type:

{
  dx: number, 
  dy: number
}

Determines the position offset of the video inside the container.

`controllerAutoShow`

Android

Optional • Type: boolean • Default: true

Determines whether the native controls are shown automatically when playback starts, pauses, or ends. When false, the controls won't appear automatically, but can still be shown by tapping the view. This is useful when playback is driven programmatically (for example an auto-advancing playlist), where the controls appearing on every play reads as a flash.

`crossOrigin`

Web

Optional • Literal type: string • Default: undefined

Determines 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'

`fullscreenOptions`

Android

iOS

tvOS

Web

Optional • Type: FullscreenOptions

Determines the fullscreen mode options.

`nativeControls`

Android

iOS

tvOS

Web

Optional • Type: boolean • Default: true

Determines whether native controls should be displayed or not.

Note: Due to platform limitations, the native controls are always enabled in fullscreen mode.

`onFirstFrameRender`

Android

iOS

tvOS

Web

Optional • Type: () => void

A 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).

`onFullscreenEnter`

Android

iOS

tvOS

Web

Optional • Type: () => void

A callback to call after the video player enters fullscreen mode.

`onFullscreenExit`

Android

iOS

tvOS

Web

Optional • Type: () => void

A callback to call after the video player exits fullscreen mode.

`onPictureInPictureStart`

Android

iOS

Web

Optional • Type: () => void

A callback to call after the video player enters Picture in Picture (PiP) mode.

`onPictureInPictureStop`

Android

iOS

Web

Optional • Type: () => void

A callback to call after the video player exits Picture in Picture (PiP) mode.

`player`

Android

iOS

tvOS

Web

Optional • Literal type: union

A video player instance. Use useVideoPlayer() hook to create one.

Acceptable values are: VideoPlayer | null

`playsInline`

Web

Optional • Type: boolean

Determines whether a video should be played "inline", that is, within the element's playback area.

`requiresLinearPlayback`

Android

iOS

Optional • Type: boolean • Default: false

Determines whether the player allows the user to skip media content.

`showsTimecodes`

iOS

Optional • Type: boolean • Default: true

Determines whether the timecodes should be displayed or not.

`startsPictureInPictureAutomatically`

Android 12+

iOS

Optional • Type: boolean • Default: false

Determines 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 supportsPictureInPicture property of the config plugin has to be configured for the PiP to work.

`surfaceType`

Android

Optional • Type: SurfaceType • Default: 'surfaceView'

Determines the type of the surface used to render the video.

This prop should not be changed at runtime.

`useAudioNodePlayback`

Experimental

•

Web

Optional • Type: boolean • Default: false

Use 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.

`useExoShutter`

Android

Optional • Type: boolean • Default: false

Determines 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.

Inherited props

ViewProps

`VideoAirPlayButton`

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 allowsExternalPlayback player property is set to true.

VideoAirPlayButtonProps

`activeTint`

iOS

Optional • Type: ColorValue • Default: undefined

The color of the button icon while AirPlay sharing is active.

`onBeginPresentingRoutes`

iOS

Optional • Type: () => void

A callback called when the AirPlay route selection popup is about to show.

`onEndPresentingRoutes`

iOS

Optional • Type: () => void

A callback called when the AirPlay route selection popup has disappeared.

`prioritizeVideoDevices`

iOS

Optional • Type: boolean • Default: true

Determines whether the AirPlay device selection popup should show video outputs first.

`tint`

iOS

Optional • Type: ColorValue • Default: undefined

The color of the button icon while AirPlay sharing is not active.

Inherited props

Omit<ViewProps, 'children'>

Component methods

`enterFullscreen()`

Android

iOS

tvOS

Web

Enters fullscreen mode.

Returns:

Promise<void>

`exitFullscreen()`

Android

iOS

tvOS

Web

Exits fullscreen mode.

Note: On Android the JS runtime is paused when the VideoView is in fullscreen mode. Because of this exitFullscreen will only work when called from a native listener - see the example below.

Returns:

Promise<void>

Example

  const ref = useRef<VideoView>()
  const player = useVideoPlayer(source)

  // This will work on all platforms
  useEventListener(player, 'playToEnd', () => {
    ref.current?.exitFullscreen();
  });

  // This will not work on Android
  const enterAndExit = useCallback(() => {
    setTimeout(() => {
      ref.current?.exitFullscreen()
    }, 5000)
    ref.current?.enterFullscreen()
  },[])

`startPictureInPicture()`

Android

iOS

Web

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 supportsPictureInPicture property of the config plugin has to be configured for the PiP to work.

Returns:

Promise<void>

`stopPictureInPicture()`

Android

iOS

Web

Exits Picture in Picture (PiP) mode.

Returns:

Promise<void>

Hooks

`useVideoPlayer(source, setup, playerBuilderOptions)`

Android

iOS

tvOS

Web

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.

Returns:

VideoPlayer

Classes

`VideoPlayer`

Android

iOS

tvOS

Web

Type: Class extends SharedObject<VideoPlayerEvents>

A class that represents an instance of the video player.

VideoPlayer Properties

`allowsExternalPlayback`

iOS

Type: boolean • Default: true

Determines whether the player should allow external playback.

`audioMixingMode`

Android

iOS

Type: AudioMixingMode • Default: 'auto'

Determines how the player will interact with other audio playing in the system.

`audioTrack`

Android

iOS

Literal type: union • Default: null

Specifies the audio track currently played by the player. null when no audio is played.

Acceptable values are: AudioTrack | null

`availableAudioTracks`

Android

iOS

Read only • Type: AudioTrack[]

An array of audio tracks available for the current video.

`availableSubtitleTracks`

Android

iOS

Read only • Type: SubtitleTrack[]

An array of subtitle tracks available for the current video.

`availableVideoTracks`

Android

iOS

Read only • Type: VideoTrack[]

An array of video tracks available for the current video.

On iOS, when using a HLS source, make sure that the uri contains .m3u8 extension or that the contentType property of the VideoSource has been set to 'hls'. Otherwise, the video tracks will not be available.

`bufferedPosition`

Android

iOS

tvOS

Web

Read only • Type: number

Float 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.

`bufferOptions`

Android

iOS

Type: BufferOptions

Specifies buffer options which will be used by the player when buffering the video.

You should provide a BufferOptions object when setting this property. Setting individual buffer properties is not supported.

`currentLiveTimestamp`

Android

iOS

Read only • Literal type: union

The 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

`currentOffsetFromLive`

Android

iOS

Read only • Literal type: union

Float 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

`currentTime`

Android

iOS

tvOS

Web

Type: number

Float 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.

`duration`

Android

iOS

tvOS

Web

Read only • Type: number

Float value indicating the duration of the current video in seconds.

`isExternalPlaybackActive`

iOS

Read only • Type: boolean

Indicates whether the player is currently playing back the media to an external device via AirPlay.

`isLive`

Android

iOS

tvOS

Web

Read only • Type: boolean

Boolean value indicating whether the player is currently playing a live stream.

`keepScreenOnWhilePlaying`

Android

iOS

Type: boolean • Default: true

Boolean indicating if the player should keep the screen on while playing.

On Android, this property has an effect only when a VideoView is visible. If you want to keep the screen awake at all times use expo-keep-awake.

`loop`

Android

iOS

tvOS

Web

Type: boolean • Default: false

Determines whether the player should automatically replay after reaching the end of the video.

`maxResolution`

Android

iOS

Literal type: union • Default: null

Specifies the maximum resolution that the player will select when choosing between the video tracks of an adaptive stream. The player picks the highest-quality track that does not exceed this resolution.

Set this property to null to remove the limit and allow all available resolutions. Dimensions which are not greater than zero are treated the same as null.

The cap is enforced differently per platform:

On Android it is a hard constraint, unless no track satisfies it, in which case the lowest-resolution track is used.
On iOS it is a preferred maximum, which the player treats as a soft hint when selecting a track.

Note: On iOS this property only applies to HTTP Live Streaming (HLS) sources.

Acceptable values are: VideoSize | null

`muted`

Android

iOS

tvOS

Web

Type: boolean • Default: false

Boolean value whether the player is currently muted. Setting this property to true/false will mute/unmute the player.

`playbackRate`

Android

iOS

tvOS

Web

Type: number • Default: 1.0

Float value between 0 and 16.0 indicating the current playback speed of the player.

`playing`

Android

iOS

tvOS

Web

Read only • Type: boolean

Boolean value whether the player is currently playing.

Use play and pause methods to control the playback.

`preservesPitch`

Android

iOS

tvOS

Web

Type: boolean • Default: true

Boolean value indicating if the player should correct audio pitch when the playback speed changes.

`scrubbingModeOptions`

Android

iOS

tvOS

Web

Type: ScrubbingModeOptions

Determines whether the scrubbing mode is enabled and what scrubbing optimizations should be enabled.

See SeekTolerance to set the seeking tolerance, which can also affect the scrubbing performance.

`seekTolerance`

Android

iOS

tvOS

Web

Type: SeekTolerance

Determines 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.

`showNowPlayingNotification`

Android

iOS

Type: boolean • Default: false

Boolean value determining whether the player should show the now playing notification.

Note: On Android, supportsBackgroundPlayback property of the config plugin has to be true for the now playing notification to work.

`status`

Android

iOS

tvOS

Web

Read only • Type: VideoPlayerStatus

Indicates the current status of the player.

`staysActiveInBackground`

Android

iOS

Type: boolean • Default: false

Determines whether the player should continue playing after the app enters the background.

Note: The supportsBackgroundPlayback property of the config plugin has to be true for the background playback to work.

`subtitleTrack`

Android

iOS

Literal type: union • Default: null

Specifies 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 availableSubtitleTracks array.

Acceptable values are: SubtitleTrack | null

`targetOffsetFromLive`

iOS

Type: number

Float value indicating the time offset from the live in seconds.

`timeUpdateEventInterval`

Android

iOS

tvOS

Web

Type: number • Default: 0

Float 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.

`videoTrack`

Android

iOS

Read only • Literal type: union • Default: null

Specifies the video track currently played by the player. null when no video is displayed.

Acceptable values are: VideoTrack | null

`volume`

Android

iOS

tvOS

Web

Type: number • Default: 1.0

Float value between 0 and 1.0 representing the current volume. Muting the player doesn't affect the volume. In other words, when the player is muted, the volume is the same as when unmuted. Similarly, setting the volume doesn't unmute the player.

VideoPlayer Methods

`generateThumbnailsAsync(times, options)`

Android

iOS

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.

Returns:

Promise<VideoThumbnail[]>

`pause()`

Android

iOS

tvOS

Web

Pauses the player.

Returns:

void

`play()`

Android

iOS

tvOS

Web

Resumes the player.

Returns:

void

`replace(source, disableWarning)`

Android

iOS

tvOS

Web

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 replaceAsync to load the asset asynchronously and avoid UI lags.

This method will be deprecated in the future.

Returns:

void

`replaceAsync(source)`

Android

iOS

tvOS

Web

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.

Returns:

Promise<void>

`replay()`

Android

iOS

tvOS

Web

Seeks the playback to the beginning.

Returns:

void

`seekBy(seconds)`

Android

iOS

tvOS

Web

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.

Returns:

void

`VideoThumbnail`

Android

iOS

Type: 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

Returns:

Promise<void>

A promise that fulfills after the cache has been cleaned.

`视频.createVideoPlayer(source, playerBuilderOptions)`

Android

iOS

tvOS

Web

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 the useVideoPlayer hook instead. See the Using the VideoPlayer Directly section for more details.

Returns:

VideoPlayer

`视频.getCurrentVideoCacheSize()`

Android

iOS

Returns the space currently occupied by the video cache in bytes.

Returns:

number

`视频.isPictureInPictureSupported()`

Android

iOS

Returns whether the current device supports Picture in Picture (PiP) mode.

Returns:

boolean

A boolean which is true if the device supports PiP mode, and false otherwise.

`视频.setVideoCacheSizeAsync(sizeBytes)`

Android

iOS

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 VideoPlayer instances.

Returns:

Promise<void>

A promise that fulfills after the cache size has been set.

Types

`AudioMixingMode`

Android

iOS

tvOS

Web

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 when showNowPlayingNotification is true due 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 doNotMix or auto this feature will not work.

Acceptable values are: 'mixWithOthers' | 'duckOthers' | 'auto' | 'doNotMix'

`AudioTrack`

Android

iOS

tvOS

Web

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.

`BufferOptions`

Android

iOS

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. This property will be ignored if `preferredForwardBufferDuration` is lower. 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 `0` the player will automatically decide appropriate buffer duration. Equivalent to `AVPlayerItem.preferredForwardBufferDuration`. 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 `AVPlayer.automaticallyWaitsToMinimizeStalling`. Default:`true`

`ButtonOptions`

Android

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 `false`, the entire bottom bar including the progress bar will be hidden. Note: The bottom bar is always visible in fullscreen mode to allow users to exit fullscreen. 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. `true`: Button is always visible `false`: Button is never visible `undefined`: Button is visible only when subtitles are available (default behavior) Default:`undefined`

`ContentType`

Android

iOS

tvOS

Web

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 default ContentType when 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'

`DRMOptions`

Android

iOS

tvOS

Web

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` property is ignored.
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.

`DRMType`

Android

iOS

tvOS

Web

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'

`IsExternalPlaybackActiveChangeEventPayload`

Android

iOS

tvOS

Web

Property	Type	Description
isExternalPlaybackActive	`boolean`	The current external playback status.
oldIsExternalPlaybackActive(optional)	`boolean`	The previous external playback status.

`MutedChangeEventPayload`

Android

iOS

tvOS

Web

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 `isMuted` property.

`PlaybackRateChangeEventPayload`

Android

iOS

tvOS

Web

Data delivered with the playbackRateChange event.

Property	Type	Description
oldPlaybackRate(optional)	`number`	Previous value of the `playbackRate` property.
playbackRate	`number`	Float value indicating the current playback speed of the player.

`PlayerBuilderOptions`

Android

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.
videoChangeFrameRateStrategy(optional)	`VideoChangeFrameRateStrategy`	Only for: Android Determines whether the player is allowed to change the display refresh rate to match the frame rate of the video. Default:`'onlyIfSeamless'`

`PlayerError`

Android

iOS

tvOS

Web

Contains information about any errors that the player encountered during the playback

Property	Type	Description
message	`string`	-

`PlayingChangeEventPayload`

Android

iOS

tvOS

Web

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 `isPlaying` property.

`ScrubbingModeOptions`

Android

iOS

tvOS

Web

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 `true`, avoids flushing the decoder when a new seek starts decoding from a key-frame in compatible content. 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 `SeekTolerance` may be sufficient. 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 `scrubbingModeEnabled` is `true`, the playback is suppressed. You should set this property back to `false` when the user interaction ends to allow the playback to resume. For best results, on iOS you should pause the playback when scrubbing. For best scrubbing performance, consider also increasing the seeking tolerance using the `SeekTolerance` property. Other scrubbing mode options will have no effect when this is `false`. Default:`false`
useDecodeOnlyFlag(optional)	`boolean`	Only for: Android Sets whether to use `MediaCodec.BUFFER_FLAG_DECODE_ONLY` in scrubbing mode. When playback is using MediaCodec on API 34+, this flag can speed up seeking by signalling that the decoded output of buffers between the previous keyframe and the target frame is not needed by the player. Default:`true`

`SeekTolerance`

Android

iOS

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`

`SourceChangeEventPayload`

Android

iOS

tvOS

Web

Data delivered with the sourceChange event.

Property	Type	Description
oldSource(optional)	`VideoSource`	Previous source of the player.
source	`VideoSource`	New source of the player.

`SourceLoadEventPayload`

Android

iOS

tvOS

Web

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. On iOS, when using a HLS source, make sure that the uri contains `.m3u8` extension or that the `contentType` property of the `VideoSource` has been set to `'hls'`. Otherwise, the video tracks will not be available.
duration	`number`	Duration of the video source in seconds.
videoSource	`VideoSource \| null`	The video source that has been loaded.

`StatusChangeEventPayload`

Android

iOS

tvOS

Web

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.

`SubtitleTrack`

Android

iOS

tvOS

Web

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 subtitle track.
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, `en`, `pl`, `de`.
name(optional)	`string`	Only for: Android iOS Name of the subtitle track as specified in the media source.

`SubtitleTrackChangeEventPayload`

Android

iOS

tvOS

Web

Property	Type	Description
oldSubtitleTrack(optional)	`SubtitleTrack \| null`	Previous subtitle track of the player.
subtitleTrack	`SubtitleTrack \| null`	New subtitle track of the player.

`SurfaceType`

Android

Literal type: string

Describes the type of the surface used to render the video.

surfaceView: Uses the SurfaceView to 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 the TextureView to 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'

`TimeUpdateEventPayload`

Android

iOS

tvOS

Web

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 `bufferedPosition` property.
currentLiveTimestamp	`number \| null`	Only for: Android iOS The 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. Same as the `currentLiveTimestamp` property.
currentOffsetFromLive	`number \| null`	Only for: Android iOS Float value indicating the latency of the live stream in seconds. Same as the `currentOffsetFromLive` property.
currentTime	`number`	Float value indicating the current playback time in seconds. Same as the `currentTime` property.

`VideoChangeFrameRateStrategy`

Android

Literal type: string

Determines whether the player is allowed to call Surface.setFrameRate to match the display refresh rate to the frame rate of the video being played.

'onlyIfSeamless': the display refresh rate is changed only when the switch is seamless (no visual interruption). This is the ExoPlayer default.
'off': the player never calls Surface.setFrameRate.

On devices with adaptive refresh rate displays (for example, Pixel 9 and 10 series), the platform can respond to a 30 fps video by lowering the display render rate and capping the rendering of the entire app, including scrolling and animations, at 30 Hz for as long as the video is visible. Set this option to 'off' to keep the UI running at the full refresh rate, for example in a vertical video feed. Frame rate matching mainly benefits TV-class displays, where mismatched rates cause judder.

Acceptable values are: 'off' | 'onlyIfSeamless'

`VideoContentFit`

Android

iOS

tvOS

Web

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'

`VideoMetadata`

Android

iOS

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.

`VideoPlayerEvents`

Android

iOS

tvOS

Web

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 `muted` property of the player changes
playbackRateChange	`(payload: PlaybackRateChangeEventPayload) => void`	Handler for an event emitted when the `playbackRate` property of the player changes.
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 `VideoSource`, but it doesn't mean that there is enough data buffered to start the playback.
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 `timeUpdateEventInterval`.
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 `volume` of `muted` property of the player changes.

`VideoPlayerStatus`

Android

iOS

tvOS

Web

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 source
readyToPlay: 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'

`VideoRange`

Android

iOS

tvOS

Web

Literal type: string

Specifies the dynamic range of the video content.

sdr: Standard Dynamic Range video.
hlg: Hybrid Log-Gamma - HDR backward-compatible with SDR displays
pq: Perceptual Quantizer - Formats like HDR10 and Dolby Vision

Acceptable values are: 'sdr' | 'hlg' | 'pq'

`VideoSize`

Android

iOS

tvOS

Web

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.

`VideoSource`

Android

iOS

tvOS

Web

Literal type: union

Acceptable values are: string | number | null | VideoSourceObject

`VideoSourceObject`

Android

iOS

tvOS

Web

Property	Type	Description
assetId(optional)	`number`	The asset ID of a local video asset, acquired with the `require` function. This property is exclusive with the `uri` property. When both are present, the `assetId` will be ignored.
contentType(optional)	`ContentType`	Only for: Android iOS Specifies the content type of the video source. When set to `'auto'`, the player will try to automatically determine the content type. 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. For DRM license headers use the `headers` field of `DRMOptions`.
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, `PHAsset` URIs are supported, but can only be loaded using the `replaceAsync` method or the default `VideoPlayer` constructor. This property is exclusive with the `assetId` property. When both are present, the `assetId` will be ignored.
useCaching(optional)	`boolean`	Only for: Android iOS Specifies whether the player should use caching for the video. Due to platform limitations, the cache cannot be used with HLS video sources on iOS. Caching DRM-protected videos is not supported on Android and iOS. Default:`false`

`VideoThumbnailOptions`

Android

iOS

tvOS

Web

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.

`VideoTrack`

Android

iOS

tvOS

Web

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`	Deprecated: Use `peakBitrate` or `averageBitrate` instead. 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. This field is platform-specific and may return different depending on the operating system.
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 `VideoTrack` for HLS video sources. `null` for other source types.
videoRange	`VideoRange`	Specifies the video range of the video track.

`VideoTrackChangeEventPayload`

Android

iOS

tvOS

Web

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.

`VolumeChangeEventPayload`

Android

iOS

tvOS

Web

Data delivered with the volumeChange event.

Property	Type	Description
oldVolume(optional)	`number`	Previous value of the `volume` property.
volume	`number`	Float value indicating the current volume of the player.

Expo 视频（expo-video）

已知问题 Android

安装

在 app 配置中进行配置

Example app.json with config plugin

Configurable properties

用法

接收事件

useEvent 钩子

useEventListener 钩子

Player.addListener 方法

播放 assets 目录中的本地媒体

播放媒体库中的媒体

预加载视频

直接使用 VideoPlayer

视频缓存

缓存管理

拦截原生资源加载

简介

可自定义属性

实现与使用

基础使用示例

完整示例

API

Components

VideoView

allowsPictureInPicture

allowsVideoFrameAnalysis

buttonOptions

contentFit

contentPosition

controllerAutoShow

crossOrigin

fullscreenOptions

nativeControls

onFirstFrameRender

onFullscreenEnter

onFullscreenExit

onPictureInPictureStart

onPictureInPictureStop

player

playsInline

requiresLinearPlayback

showsTimecodes

startsPictureInPictureAutomatically

surfaceType

useAudioNodePlayback

useExoShutter

Inherited props

VideoAirPlayButton

activeTint

onBeginPresentingRoutes

onEndPresentingRoutes

prioritizeVideoDevices

tint

Inherited props

Component methods

enterFullscreen()

exitFullscreen()

startPictureInPicture()

stopPictureInPicture()

Hooks

useVideoPlayer(source, setup, playerBuilderOptions)

Classes

VideoPlayer

allowsExternalPlayback

audioMixingMode

audioTrack

availableAudioTracks

availableSubtitleTracks

availableVideoTracks

bufferedPosition

bufferOptions

currentLiveTimestamp

currentOffsetFromLive

currentTime

duration

isExternalPlaybackActive

isLive

keepScreenOnWhilePlaying

已知问题
Android

`useEvent` 钩子

`useEventListener` 钩子

`Player.addListener` 方法

`VideoView`

`allowsPictureInPicture`

`allowsVideoFrameAnalysis`

`buttonOptions`

`contentFit`

`contentPosition`

`controllerAutoShow`

`crossOrigin`

`fullscreenOptions`

`nativeControls`

`onFirstFrameRender`

`onFullscreenEnter`

`onFullscreenExit`

`onPictureInPictureStart`

`onPictureInPictureStop`

`player`

`playsInline`

`requiresLinearPlayback`

`showsTimecodes`

`startsPictureInPictureAutomatically`

`surfaceType`

`useAudioNodePlayback`

`useExoShutter`

`VideoAirPlayButton`

`activeTint`

`onBeginPresentingRoutes`

`onEndPresentingRoutes`

`prioritizeVideoDevices`

`tint`

`enterFullscreen()`

`exitFullscreen()`

`startPictureInPicture()`

`stopPictureInPicture()`

`useVideoPlayer(source, setup, playerBuilderOptions)`

`VideoPlayer`

`allowsExternalPlayback`

`audioMixingMode`

`audioTrack`

`availableAudioTracks`

`availableSubtitleTracks`

`availableVideoTracks`

`bufferedPosition`

`bufferOptions`

`currentLiveTimestamp`

`currentOffsetFromLive`

`currentTime`

`duration`

`isExternalPlaybackActive`

`isLive`

`keepScreenOnWhilePlaying`

`loop`

`maxResolution`

`muted`

`playbackRate`

`playing`

`preservesPitch`

`scrubbingModeOptions`

`seekTolerance`

`showNowPlayingNotification`

`status`

`staysActiveInBackground`

`subtitleTrack`

`targetOffsetFromLive`

`timeUpdateEventInterval`

`videoTrack`

`volume`

`generateThumbnailsAsync(times, options)`

`pause()`

`play()`

`replace(source, disableWarning)`

`replaceAsync(source)`

`replay()`

`seekBy(seconds)`

`VideoThumbnail`

`actualTime`

`height`