1# Migrating from expo-av to expo-video
2 
3## Imports
4 
5```tsx
6// Before
7import { Video, ResizeMode } from 'expo-av';
8 
9// After
10import { useVideoPlayer, VideoView, VideoSource } from 'expo-video';
11import { useEvent, useEventListener } from 'expo';
12```
13 
14## Video Playback
15 
16### Before (expo-av)
17 
18```tsx
19const videoRef = useRef<Video>(null);
20const [status, setStatus] = useState({});
21 
22<Video
23  ref={videoRef}
24  source={{ uri: 'https://example.com/video.mp4' }}
25  style={{ width: 350, height: 200 }}
26  resizeMode={ResizeMode.CONTAIN}
27  isLooping
28  onPlaybackStatusUpdate={setStatus}
29/>
30 
31// Control
32videoRef.current?.playAsync();
33videoRef.current?.pauseAsync();
34```
35 
36### After (expo-video)
37 
38```tsx
39const player = useVideoPlayer('https://example.com/video.mp4', player => {
40  player.loop = true;
41});
42 
43const { isPlaying } = useEvent(player, 'playingChange', { isPlaying: player.playing });
44 
45<VideoView
46  player={player}
47  style={{ width: 350, height: 200 }}
48  contentFit="contain"
49/>
50 
51// Control
52player.play();
53player.pause();
54```
55 
56## Status Updates
57 
58### Before (expo-av)
59 
60```tsx
61<Video
62  onPlaybackStatusUpdate={status => {
63    if (status.isLoaded) {
64      console.log(status.positionMillis, status.durationMillis, status.isPlaying);
65      if (status.didJustFinish) console.log('finished');
66    }
67  }}
68/>
69```
70 
71### After (expo-video)
72 
73```tsx
74// Reactive state
75const { isPlaying } = useEvent(player, 'playingChange', { isPlaying: player.playing });
76 
77// Side effects
78useEventListener(player, 'playToEnd', () => console.log('finished'));
79 
80// Direct access
81console.log(player.currentTime, player.duration, player.playing);
82```
83 
84## Local Files
85 
86### Before (expo-av)
87 
88```tsx
89<Video source={require('./video.mp4')} />
90```
91 
92### After (expo-video)
93 
94```tsx
95const player = useVideoPlayer({ assetId: require('./video.mp4') });
96```
97 
98## Fullscreen and PiP
99 
100```tsx
101<VideoView
102  player={player}
103  allowsFullscreen
104  allowsPictureInPicture
105  onFullscreenEnter={() => {}}
106  onFullscreenExit={() => {}}
107/>
108```
109 
110For PiP and background playback, add to app.json:
111 
112```json
113{
114  "expo": {
115    "plugins": [
116      ["expo-video", { "supportsBackgroundPlayback": true, "supportsPictureInPicture": true }]
117    ]
118  }
119}
120```
121 
122## API Mapping
123 
124| expo-av | expo-video |
125|---------|------------|
126| `<Video>` | `<VideoView>` |
127| `ref={videoRef}` | `player={useVideoPlayer()}` |
128| `source={{ uri }}` | Pass to `useVideoPlayer(uri)` |
129| `resizeMode={ResizeMode.CONTAIN}` | `contentFit="contain"` |
130| `isLooping` | `player.loop = true` |
131| `shouldPlay` | `player.play()` in setup |
132| `isMuted` | `player.muted = true` |
133| `useNativeControls` | `nativeControls={true}` |
134| `onPlaybackStatusUpdate` | `useEvent` / `useEventListener` |
135| `videoRef.current.playAsync()` | `player.play()` |
136| `videoRef.current.pauseAsync()` | `player.pause()` |
137| `videoRef.current.replayAsync()` | `player.replay()` |
138| `videoRef.current.setPositionAsync(ms)` | `player.currentTime = seconds` |
139| `status.positionMillis` | `player.currentTime` (seconds) |
140| `status.durationMillis` | `player.duration` (seconds) |
141| `status.didJustFinish` | `useEventListener(player, 'playToEnd')` |
142 
143## Key Differences
144 
145- **Separate player and view**: Player logic decoupled from the view—one player can be used across multiple views
146- **Time in seconds**: Uses seconds, not milliseconds
147- **Event system**: Uses `useEvent`/`useEventListener` from `expo` instead of callback props
148- **Video preloading**: Create a player without mounting a VideoView to preload for faster transitions
149- **Built-in caching**: Set `useCaching: true` in VideoSource for persistent offline caching
150 
151## Known Issues
152 
153- **Uninstall expo-av first**: On Android, having both expo-av and expo-video installed can cause VideoView to show a black screen. Uninstall expo-av before installing expo-video
154- **Android: Reusing players**: Mounting the same player in multiple VideoViews simultaneously can cause black screens on Android (works on iOS)
155- **Android: currentTime in setup**: Setting `player.currentTime` in the `useVideoPlayer` setup callback may not work on Android—set it after mount instead
156- **Changing source**: Use `player.replace(newSource)` to change videos without recreating the player
157 
158## API Reference
159 
160https://docs.expo.dev/versions/latest/sdk/video/
161