Expo 视频 (expo-video)

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

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

¥expo-video is a cross-platform, performant video component for React Native and Expo with Web support.

安装

¥Installation

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

应用配置中的配置

¥Configuration in app config

如果你在项目中使用配置插件（EAS 构建 或 npx expo run:[android|ios]），则可以使用其内置的 配置插件 配置 expo-video。该插件允许你配置无法在运行时设置的各种属性，并且需要构建新的应用二进制文件才能生效。如果你的应用不使用 EAS Build，则你需要手动配置包。

¥You can configure expo-video using its built-in config plugin if you use config plugins in your project (EAS Build or npx expo run:[android|ios]). 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 EAS Build, then you'll need to manually configure the package.

Example app.json with config plugin

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

Configurable properties

用法

¥Usage

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

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

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} allowsFullscreen 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,
},
});

推荐资源

¥Receiving events

VideoPlayer 属性中的更改不会更新 React 状态。因此，要显示有关 VideoPlayer 当前状态的信息，必须监听它发出的 events。事件系统基于 expo 包中的 EventEmitter 类和 hooks。有几种方法可以监听事件：

¥The changes in properties of the VideoPlayer do not update the React state. Therefore, to display the information about the current state of the VideoPlayer, it is necessary to listen to the events it emits. The event system is based on the EventEmitter class and hooks from the expo package. There are a few ways to listen to events:

useEvent 钩

¥useEvent hook

创建一个监听器，该监听器将返回可在组件中使用的状态值。它还会在组件卸载时自动清理。

¥Creates a listener that will return a stateful value that can be used in a component. It also cleans up automatically when the component unmounts.

import { useEvent } from 'expo';
// ... Other imports, definition of the component, creating the player etc.

const { status, error } = useEvent(player, 'statusChange', { status: player.status });
// Rest of the component...

useEventListener 钩

¥useEventListener hook

围绕 Player.addListener 和 Player.removeListener 方法构建，创建具有自动清理功能的事件监听器。

¥Built around the Player.addListener and Player.removeListener methods, creates an event listener with automatic cleanup.

import { useEventListener } from 'expo';
// ...Other imports, definition of the component, creating the player etc.

useEventListener(player, 'statusChange', ({ status, error }) => {
  setPlayerStatus(status);
  setPlayerError(error);
  console.log('Player status changed: ', status);
});
// Rest of the component...

Player.addListener 方法

¥Player.addListener method

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

¥Most flexible way to listen to events, but requires manual cleanup and more boilerplate code.

// ...Imports, definition of the component, creating the player etc.

useEffect(() => {
  const subscription = player.addListener('statusChange', ({ status, error }) => {
    setPlayerStatus(status);
    setPlayerError(error);
    console.log('Player status changed: ', status);
  });

  return () => {
    subscription.remove();
  };
}, []);
// Rest of the component...

从资源目录播放本地媒体

¥Playing local media from the assets directory

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

¥expo-video supports playing local media loaded using the require function. You can use the result as a source directly, or assign it to the assetId parameter of a VideoSource if you also want to configure other properties.

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

预加载视频

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

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.

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

在 Android 上，由于 平台限制 的存在，无法同时将多个 VideoView 组件挂载到同一个 VideoPlayer 实例上。

缓存视频

¥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 保护的视频。

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

管理缓存

¥Managing the cache

• 可以使用 setVideoCacheSizeAsync 函数定义首选缓存大小（以字节为单位）。默认缓存大小为 1GB。

  ¥The preferred cache size in bytes can be defined using the setVideoCacheSizeAsync function. The default cache size is 1GB.

• getCurrentVideoCacheSize 可用于获取缓存当前占用的存储空间（以字节为单位）。

  ¥The getCurrentVideoCacheSize can be used to get the current storage occupied by the cache in bytes.

• 所有缓存的视频都可以使用 clearVideoCacheAsync 函数清除。

  ¥All cached videos can be cleared using the clearVideoCacheAsync function.

API

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

Component

Component Methods

Hooks

Classes

Methods

Types