Expo 视频 (expo-video)

提供 API 以实现应用中的视频播放的库。

Android

iOS

tvOS

Web

Included in Expo Go

Recommended version:

~57.0.5

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

已知问题
Android

🌐 Known issues

Android

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

🌐 When two VideoView components are overlapping and have the contentFit prop set to cover, one of the videos may be displayed out of bounds. This is a known upstream issue. To work around this issue, use the surfaceType prop and set it to textureView.

安装

🌐 Installation

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.

应用配置中的配置

🌐 Configuration in app config

如果你在项目中使用配置插件（连续原生生成 (CNG)），可以使用其内置的配置插件来配置 expo-video。该插件允许你配置无法在运行时设置并且需要构建新的应用二进制文件才能生效的各种属性。如果你的应用不使用 CNG，那么你需要手动配置该库。

🌐 You can configure expo-video using its built-in config plugin if you use config plugins in your project (Continuous Native Generation (CNG)). The plugin allows you to configure various properties that cannot be set at runtime and require building a new app binary to take effect. If your app does not use CNG, then you'll need to manually configure the library.

Example app.json with config plugin

app.json

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

Configurable properties

Name	Default	Description
`supportsBackgroundPlayback`	`undefined`	A boolean value to enable background playback support. If `true`, on iOS, the `audio` key is added to the `UIBackgroundModes` array in the Info.plist file. If `false`, the key is removed. When `undefined`, the key is not modified. On Android, when `true` adds foreground service permissions and creates a expo-video foreground service in AndroidManifest.xml.
`supportsPictureInPicture`	`undefined`	A boolean value to enable Picture-in-Picture on Android and iOS. If `true`, enables the `android:supportsPictureInPicture` property on Android and adds the `audio` key to the `UIBackgroundModes` array in the Info.plist file on iOS. If `false`, the key is removed. When `undefined`, the configuration is not modified.

用法

🌐 Usage

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

🌐 Here's a simple example of a video with a play and pause button.

Video

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 ? 'Pause' : 'Play'}
          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,
  },
});

从资源目录播放本地媒体

🌐 Playing local media from the assets directory

expo-video 支持播放使用 require 函数加载的本地媒体。你可以直接将结果用作来源，或者如果你还想配置其他属性，可以将其分配给 VideoSource 的 assetId 参数。

Playing local media

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); // You can use the `asset` directly as a video source
const player2 = useVideoPlayer(videoSource);

从媒体库播放媒体

🌐 Playing media from the media library

expo-video 支持使用 expo-media-library/legacy 或任何具有适当权限的有效 PHAsset URI 播放从用户媒体库中选取的视频。

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

🌐 To play a video from the media library, you should obtain an Asset object with MediaLibrary.getAssetsAsync() and use its uri property as the uri of the video source. Before playing, make sure to request the necessary permissions using MediaLibrary.requestPermissionsAsync().

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

🌐 On iOS make sure not to use the localUri property of the asset info, as it does not contain the necessary permissions to read the asset.

Playing media from media library

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

// ...Definition of the component, creating the player etc.

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); // Alternatively you can use the asset uri directly
    player.play();
  }
};

// You can now use loadAssetAndReplace to load and play the first video from the media library

预加载视频

🌐 Preloading videos

在播放另一个视频的同时，可以在显示视频之前先加载它。这可以实现后续视频之间更快的切换，并提供更好的用户体验。

🌐 While another video is playing, a video can be loaded before showing it in the view. This allows for quicker transitions between subsequent videos and a better user experience.

要预加载视频，你必须创建一个带有视频源的 VideoPlayer。即使播放器未连接到 VideoView，它也会填充缓冲区。一旦连接到 VideoView，它就可以无缓冲地开始播放。

🌐 To preload a video, you have to create a VideoPlayer with a video source. Even when the player is not connected to a VideoView, it will fill the buffers. Once it is connected to the VideoView, it will be able to start playing without buffering.

在某些情况下，在屏幕生命周期的后期预加载视频是有益的。在这种情况下，应创建一个带有 null 源的 VideoPlayer。要开始预加载，请使用 replace() 函数将播放器源替换为视频源。

🌐 In some cases, it is beneficial to preload a video later in the screen lifecycle. In that case, a VideoPlayer with a null source should be created. To start preloading, replace the player source with a video source using the replace() function.

以下是如何预加载视频的示例：

🌐 Here is an example of how to preload a video:

Preloading videos

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}>Replace player</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,
  },
});

不使用其他 EAS 服务

🌐 Using the VideoPlayer directly

在大多数情况下，应该使用 useVideoPlayer 钩子来创建 VideoPlayer 实例。它会管理播放器的生命周期，并确保在组件卸载时正确释放。不过，在一些高级用例中，可能需要创建一个 VideoPlayer，它在组件卸载时不会自动销毁。在这种情况下，可以使用 createVideoPlayer 函数来创建 VideoPlayer。你需要注意这种做法带来的风险，因为当播放器不再需要时，你有责任调用 release() 方法。如果处理不当，这种做法可能会导致内存泄漏。

🌐 In most cases, the useVideoPlayer hook should be used to create a VideoPlayer instance. It manages the player's lifecycle and ensures that it is properly disposed of when the component is unmounted. However, in some advanced use cases, it might be necessary to create a VideoPlayer that does not get automatically destroyed when the component is unmounted. In those cases, the VideoPlayer can be created using the createVideoPlayer function. You need be aware of the risks that come with this approach, as it is your responsibility to call the release() method when the player is no longer needed. If not handled properly, this approach may lead to memory leaks.

Creating player instance

import { createVideoPlayer } from 'expo-video';
const player = createVideoPlayer(videoSource);

警告在 Android 上，由于平台限制，同时使用相同的 VideoPlayer 实例挂载多个 VideoView 组件将无法工作。

缓存视频

🌐 Caching videos

如果你的应用经常重复播放同一视频，可以利用缓存来减少网络使用并提升用户体验，尽管这会增加设备存储的使用。expo-video 支持在 Android 和 iOS 平台上进行视频缓存。可以通过将 VideoSource 对象的 useCaching 属性设置为 true 来启用此功能。

🌐 If your app frequently replays the same video, caching can be utilized to minimize network usage and enhance user experience, albeit at the cost of increased device storage usage. expo-video supports video caching on Android and iOS platforms. This feature can be activated by setting the useCaching property of a VideoSource object to true.

缓存是持久性的，一旦超过首选大小，将按最少使用原则进行清除。此外，由于存储空间不足，系统可能会清除缓存，因此不建议依赖缓存来存储关键数据。

🌐 The cache is persistent and will be cleared on a least-recently-used basis once the preferred size is exceeded. Furthermore, the system can clear the cache due to low storage availability, so it's not advisable to depend on the cache to store critical data.

缓存功能可以在离线状态下使用。如果视频的部分或全部已被缓存，即使设备处于离线状态，也可以从缓存中播放，直到缓存数据耗尽。

🌐 The cache functions offline. If a portion or the entirety of a video is cached, it can be played from the cache even when the device is offline until the cached data is exhausted.

由于平台限制，在 iOS 上无法将缓存用于 HLS 视频源。在 Android 和 iOS 上不支持缓存 DRM 保护的视频。

管理缓存

🌐 Managing the cache

首选的缓存大小（以字节为单位）可以使用 setVideoCacheSizeAsync 函数定义。默认的缓存大小为 1GB。
[getCurrentVideoCacheSize](#videogetcurrentvideocachesize) 可用于获取缓存当前占用的存储字节数。
所有缓存的视频都可以使用 clearVideoCacheAsync 功能清除。

拦截原生资源加载

🌐 Intercepting native asset loading

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

介绍

🌐 Introduction

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

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

🌐 This is useful when a source cannot be handled by AVKit directly and needs native preprocessing. For example, a provider can rewrite a URL, attach a custom AVAssetResourceLoaderDelegate, start a local proxy server, or transform one streaming format into another before playback begins.

提供者在模块启动时注册到 VideoAssetTransportRegistry。当 expo-video 加载一个源时，它会创建一个 VideoAssetSourceDescriptor 并按优先顺序询问注册的提供者他们是否想处理它。第一个返回 VideoAssetLoadPlan 的提供者将被使用。

🌐 Providers are registered in the VideoAssetTransportRegistry at module startup. When expo-video loads a source, it creates a VideoAssetSourceDescriptor and asks registered providers, in priority order, whether they want to handle it. The first provider that returns a VideoAssetLoadPlan is used.

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

🌐 This API is intended for advanced native integrations. It requires a custom native module, so it is not available in Expo Go. Use a development build instead.

可自定义属性

🌐 Customizable properties

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

🌐 The main customization points are the fields on VideoAssetTransportProvider and the fields on the VideoAssetLoadPlan it returns.

VideoAssetTransportProvider 让你可以控制以下属性：

属性	描述
`identifier`	提供程序的稳定名称。在替换或注销提供程序时使用。
`priority`	如果多个提供程序匹配相同的源，哪个提供程序胜出。值越高优先级越高。
`makeLoadPlan(for:)`	匹配和配置的入口点。返回 `nil` 以忽略某个源，或返回 `VideoAssetLoadPlan` 来处理它。

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

属性	描述
`assetURL`	用于初始化底层 `AVURLAsset` 的 URL。它可以是原始源 URL，也可以是特定传输的替代 URL，例如重写的方案、本地代理 URL 或生成的播放列表 URL。
`assetOptions`	可选的 `AVURLAsset` 初始化选项。使用此选项可以覆盖 `expo-video` 通常从源获取的默认选项。
`reportedContentTypeHint`	一个可选的内容类型，用于描述 `assetURL` 的有效播放格式。当传输改变源类型时设置，例如将 DASH 转换为 HLS。
`resourceLoaderDelegate`	可选的 `AVAssetResourceLoaderDelegate`，应附加到资源的资源加载器上。
`resourceLoaderQueue`	`resourceLoaderDelegate` 接收回调的可选调度队列。
`prepareAsset`	在 `expo-video` 急切加载资源属性之前可选的异步工作。用于传输引导，例如获取清单或启动本地服务器。
`retainedObjects`	可选的辅助对象数组，这些对象必须在资源的整个生命周期内保持活跃，例如本地 HTTP 服务器、解析器或传输状态的所有者。
`attachErrorHandler`	一个可选的钩子，它允许在加载计划应用后，将传输的异步错误转发回 `expo-video`。
`onAssetDeinit`	当 `VideoAsset` 被释放时可选择运行的清理操作。

实现与使用

🌐 Implementation and usage

一个典型的设置如下：

🌐 A typical setup looks as follows:

使用 create-expo-module 创建一个 Expo 模块。
添加一个符合 VideoAssetTransportProvider 的类。
在模块的 OnCreate 块中注册提供程序。
构建应用，以便将本地模块编译到你的项目中。

如果你只在一个应用中需要提供者，请使用本地 Expo 模块流程。

🌐 If you only need the provider in a single app, use the local Expo module flow.

如果你想在多个应用中重复使用该提供者，请改用独立 Expo 模块流程。

🌐 If you want to reuse the provider across multiple apps, use the standalone Expo module flow instead.

基本用法示例

🌐 Basic usage example

定义提供者和加载计划。创建模块后，添加一个符合 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
    )
  }
}

要注册提供者，推荐注册提供者的位置是 Expo 模块的 OnCreate 块。这确保在视频开始加载之前提供者可用。

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

完整示例

🌐 Complete examples

你可以使用以下完整示例来更好地掌握如何使用此 API。

🌐 You can use the following complete examples for a better grasp of how to use this API.

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

应用接口

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

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

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

`Video.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

`Video.getCurrentVideoCacheSize()`

Android

iOS

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

Returns:

number

`Video.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.

`Video.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.

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

`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

安装

应用配置中的配置

Example app.json with config plugin

Configurable properties

用法

推荐资源

useEvent 钩

useEventListener 钩

Player.addListener 方法

从资源目录播放本地媒体

从媒体库播放媒体

预加载视频

不使用其他 EAS 服务

缓存视频

管理缓存

拦截原生资源加载

介绍

可自定义属性

实现与使用

基本用法示例

完整示例

应用接口

Components

VideoView

allowsPictureInPicture

allowsVideoFrameAnalysis

buttonOptions

contentFit

contentPosition

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

loop

已知问题
Android

`useEvent` 钩

`useEventListener` 钩

`Player.addListener` 方法

`VideoView`

`allowsPictureInPicture`

`allowsVideoFrameAnalysis`

`buttonOptions`

`contentFit`

`contentPosition`

`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`

`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`

`nativeRefType`

`requestedTime`