HomeGuidesReferenceLearn

Reference version

ArchiveExpo SnackDiscord and ForumsNewsletter

Expo Video

GitHub

npm

A library that provides an API to implement video playback in apps.

Android
iOS
Web

expo-video is a new, experimental library that aims to replace the Video component from expo-av with a more modern and reliable implementation. If you are looking for a more stable API, use expo-av until this library has stabilized.

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

Installation

Terminal
- npx expo install expo-video

If you're installing this in a bare React Native app, you should also follow these additional installation instructions.

Usage

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

Video
import { useVideoPlayer, VideoView } from 'expo-video';
import { useEffect, useRef, useState } from 'react';
import { PixelRatio, StyleSheet, View, Button } from 'react-native';

const videoSource =
  'https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4';

export default function VideoScreen() {
  const ref = useRef(null);
  const [isPlaying, setIsPlaying] = useState(true);
  const player = useVideoPlayer(videoSource, (player) => {
    player.loop = true;
    player.play();
  });

  useEffect(() => {
    const subscription = player.addListener('playingChange', (isPlaying) => {
      setIsPlaying(isPlaying);
    });

    return () => {
      subscription.remove();
    };
  }, [player]);

  return (
    <View style={styles.contentContainer}>
      <VideoView
        ref={ref}
        style={styles.video}
        player={player}
        allowsFullscreen
        allowsPictureInPicture
      />
      <View style={styles.controlsContainer}>
        <Button
          title={isPlaying ? 'Pause' : 'Play'}
          onPress={() => {
            if (isPlaying) {
              player.pause();
            } else {
              player.play();
            }
            setIsPlaying(!isPlaying);
          }}
        />
      </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,
  },
});

API

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

Component

VideoView

Type: React.PureComponent<VideoViewProps>

Props

allowsFullscreen

Optional • Type: boolean • Default: true

Determines whether fullscreen mode is allowed or not.

Only for: 
iOS 14+

allowsPictureInPicture

Optional • Type: boolean • Default: false

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

contentFit

Optional • Type: VideoContentFit • Default: 'contain'

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

Only for: 
iOS

contentPosition

Optional • Type: { dx: number, dy: number }

Determines the position offset of the video inside the container.

nativeControls

Optional • Type: boolean • Default: true

Determines whether native controls should be displayed or not.

Only for: 
Android
iOS 14+

onPictureInPictureStart

Optional • Type: () => void

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

Only for: 
Android
iOS 14+

onPictureInPictureStop

Optional • Type: () => void

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

player

Type: VideoPlayer

A player instance – use useVideoPlayer() to create one.

Only for: 
Android
iOS

requiresLinearPlayback

Optional • Type: boolean • Default: false

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

Only for: 
iOS

showsTimecodes

Optional • Type: boolean • Default: true

Determines whether the timecodes should be displayed or not.

Only for: 
Android 12+
iOS 14.2+

startsPictureInPictureAutomatically

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.

Inherited Props

  • ViewProps

Component Methods

enterFullscreen()

Enters fullscreen mode.

Returns

  • void

exitFullscreen()

Exits fullscreen mode.

Returns

  • void

Only for: 
Android
iOS 14+

startPictureInPicture()

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.

Returns

  • void

Only for: 
Android
iOS 14+

stopPictureInPicture()

Exits Picture in Picture (PiP) mode.

Returns

  • void

Hooks

useVideoPlayer(source, setup)

NameTypeDescription
sourceVideoSource

A video source to initialize the player with

setup
(optional)
(player: VideoPlayer) => void

A function that allows setting up the player. It will run after the player is created.


Creates a VideoPlayer, which will be automatically cleaned up when the component is unmounted.

Returns

  • VideoPlayer

Classes

VideoPlayer

Type: Class extends SharedObject<VideoPlayerEvents>

A class that represents an instance of the video player.

VideoPlayer Properties

loop

Type: boolean

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

muted

Type: boolean

Boolean value whether the player is currently muted.

playbackRate

Type: number

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

playing

Type: boolean

Boolean value whether the player is currently playing.

This property is get-only, use play and pause methods to control the playback.

Only for: 
Android
iOS

preservesPitch

Type: boolean

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

On web, changing this property is not supported, the player will always correct the pitch.

status

Type: VideoPlayerStatus

Indicates the current status of the player.

This property is get-only

Only for: 
iOS
Android

staysActiveInBackground

Type: boolean

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

volume

Type: number

Float value between 0 and 1 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

addListener(eventName, listener)

NameTypeDescription
eventNameEventName-
listenerVideoPlayerEvents['undefined']-

Adds a listener for the given event name.

Returns

  • EventSubscription

emit(eventName, args)

NameTypeDescription
eventNameEventName-
argsParameters<VideoPlayerEvents['undefined']>-

Synchronously calls all of the listeners attached to that specific event. The event can include any number of arguments that will be passed to the listeners.

Returns

  • void

pause()

Pauses the player.

Returns

  • void

play()

Resumes the player.

Returns

  • void

release()

A function that detaches the JS and native objects to let the native object deallocate before the JS object gets deallocated by the JS garbagge collector. Any subsequent calls to native functions of the object will throw an error as it is no longer associated with its native counterpart.

Returns

  • void

removeAllListeners(eventName)

NameTypeDescription
eventNamekeyof-

Removes all listeners for the given event name.

Returns

  • void

removeListener(eventName, listener)

NameTypeDescription
eventNameEventName-
listenerVideoPlayerEvents['undefined']-

Removes a listener for the given event name.

Returns

  • void

replace(source)

NameTypeDescription
sourceVideoSource-

Replaces the current source with a new one.

Returns

  • void

replay()

Seeks the playback to the beginning.

Returns

  • void

seekBy(seconds)

NameTypeDescription
secondsnumber-

Seeks the playback by the given number of seconds.

Returns

  • void

Methods

Only for: 
Android
iOS

Video.isPictureInPictureSupported()

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

Returns

  • Promise<boolean>

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

Types

VideoContentFit

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'

VideoPlayerEvents

Handlers for events which can be emitted by the player.

NameTypeDescription
playToEnd() => void

Handler for an event emitted when the player plays to the end of the current source.

playbackRateChange(newPlaybackRate: number, oldPlaybackRate: number) => void

Handler for an event emitted when the playbackRate property of the player changes.

playingChange(newIsPlaying: boolean, oldIsPlaying: boolean) => void

Handler for an event emitted when the player starts or stops playback.

sourceChange(newSource: VideoSource, previousSource: VideoSource) => void

Handler for an event emitted when the current media source of the player changes.

statusChange(newStatus: VideoPlayerStatus, oldStatus: VideoPlayerStatus, error: PlayerError) => void

Handler for an event emitted when the status of the player changes.

volumeChange(newVolume: VolumeEvent, oldVolume: VolumeEvent) => void

Handler for an event emitted when the volume property of the player changes.

VideoPlayerStatus

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'

VideoSource

string or object shaped as below:


NameTypeDescription
drm
(optional)
DRMOptions-
uristring-