0
# Video Reference Methods
1

2
The VideoRef interface provides imperative control methods for programmatic video manipulation including playback control, seeking, fullscreen management, and Picture-in-Picture functionality.
3

4
## Capabilities
5

6
### VideoRef Interface
7

8
Reference interface providing imperative control methods for the Video component.
9

10
```typescript { .api }
11
/**
12
 * Reference interface for imperative video control
13
 * Access through React ref on Video component
14
 */
15
interface VideoRef {
16
  seek: (time: number, tolerance?: number) => void;
17
  resume: () => void;
18
  pause: () => void;
19
  setVolume: (volume: number) => void;
20
  presentFullscreenPlayer: () => void;
21
  dismissFullscreenPlayer: () => void;
22
  setFullScreen: (fullScreen: boolean) => void;
23
  enterPictureInPicture: () => void;
24
  exitPictureInPicture: () => void;
25
  save: (options: object) => Promise<VideoSaveData> | void;
26
  getCurrentPosition: () => Promise<number>;
27
  setSource: (source?: ReactVideoSource) => void;
28
  restoreUserInterfaceForPictureInPictureStopCompleted: (restore: boolean) => void;
29
  nativeHtmlVideoRef?: RefObject<HTMLVideoElement | null>; // Web only
30
}
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
import React, { useRef, useEffect } from "react";
37
import Video, { VideoRef } from "react-native-video";
38

39
function VideoPlayer() {
40
  const videoRef = useRef<VideoRef>(null);
41

42
  useEffect(() => {
43
    // Seek to 30 seconds after component mounts
44
    setTimeout(() => {
45
      videoRef.current?.seek(30);
46
    }, 1000);
47
  }, []);
48

49
  const handlePlayPause = () => {
50
    // Toggle play/pause state
51
    if (paused) {
52
      videoRef.current?.resume();
53
    } else {
54
      videoRef.current?.pause();
55
    }
56
  };
57

58
  return (
59
    <Video
60
      ref={videoRef}
61
      source={{ uri: "https://example.com/video.mp4" }}
62
      // ... other props
63
    />
64
  );
65
}
66
```
67

68
### Playback Control Methods
69

70
Core playback control functionality.
71

72
```typescript { .api }
73
/**
74
 * Seek to a specific time position in the video
75
 * @param time - Target time in seconds
76
 * @param tolerance - Seek tolerance in seconds (optional)
77
 */
78
seek: (time: number, tolerance?: number) => void;
79

80
/**
81
 * Resume video playback
82
 */
83
resume: () => void;
84

85
/**
86
 * Pause video playback
87
 */
88
pause: () => void;
89

90
/**
91
 * Set audio volume
92
 * @param volume - Volume level between 0.0 and 1.0
93
 */
94
setVolume: (volume: number) => void;
95
```
96

97
**Usage Examples:**
98

99
```typescript
100
const videoRef = useRef<VideoRef>(null);
101

102
// Seek with precision
103
videoRef.current?.seek(120.5); // Seek to 2 minutes 30 seconds
104
videoRef.current?.seek(60, 2); // Seek to 1 minute with 2 second tolerance
105

106
// Playback control
107
videoRef.current?.pause();
108
videoRef.current?.resume();
109

110
// Volume control
111
videoRef.current?.setVolume(0.5); // 50% volume
112
videoRef.current?.setVolume(0.0); // Mute
113
videoRef.current?.setVolume(1.0); // Full volume
114
```
115

116
### Fullscreen Management
117

118
Methods for controlling fullscreen presentation.
119

120
```typescript { .api }
121
/**
122
 * Present video in fullscreen mode
123
 */
124
presentFullscreenPlayer: () => void;
125

126
/**
127
 * Dismiss fullscreen presentation
128
 */
129
dismissFullscreenPlayer: () => void;
130

131
/**
132
 * Set fullscreen state programmatically
133
 * @param fullScreen - True to enter fullscreen, false to exit
134
 */
135
setFullScreen: (fullScreen: boolean) => void;
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
const videoRef = useRef<VideoRef>(null);
142

143
// Enter fullscreen
144
videoRef.current?.presentFullscreenPlayer();
145

146
// Exit fullscreen
147
videoRef.current?.dismissFullscreenPlayer();
148

149
// Toggle fullscreen
150
const toggleFullscreen = (isFullscreen: boolean) => {
151
  videoRef.current?.setFullScreen(!isFullscreen);
152
};
153
```
154

155
### Picture-in-Picture Control
156

157
Methods for managing Picture-in-Picture mode (iOS and Android).
158

159
```typescript { .api }
160
/**
161
 * Enter Picture-in-Picture mode
162
 * Platform: iOS, Android
163
 */
164
enterPictureInPicture: () => void;
165

166
/**
167
 * Exit Picture-in-Picture mode
168
 * Platform: iOS, Android
169
 */
170
exitPictureInPicture: () => void;
171

172
/**
173
 * Complete Picture-in-Picture restoration
174
 * @param restore - Whether restoration was successful
175
 * Platform: iOS
176
 */
177
restoreUserInterfaceForPictureInPictureStopCompleted: (restore: boolean) => void;
178
```
179

180
**Usage Examples:**
181

182
```typescript
183
const videoRef = useRef<VideoRef>(null);
184

185
// Enter PiP mode
186
const enterPiP = async () => {
187
  try {
188
    videoRef.current?.enterPictureInPicture();
189
  } catch (error) {
190
    console.log("PiP not available");
191
  }
192
};
193

194
// Exit PiP mode
195
const exitPiP = () => {
196
  videoRef.current?.exitPictureInPicture();
197
};
198

199
// Handle PiP restoration (iOS)
200
const handlePiPRestore = (restored: boolean) => {
201
  videoRef.current?.restoreUserInterfaceForPictureInPictureStopCompleted(restored);
202
};
203
```
204

205
### Source Management
206

207
Methods for dynamically changing video source.
208

209
```typescript { .api }
210
/**
211
 * Set a new video source
212
 * @param source - New video source configuration or undefined to clear
213
 */
214
setSource: (source?: ReactVideoSource) => void;
215
```
216

217
**Usage Examples:**
218

219
```typescript
220
const videoRef = useRef<VideoRef>(null);
221

222
// Change video source
223
const changeVideo = () => {
224
  videoRef.current?.setSource({
225
    uri: "https://example.com/new-video.mp4",
226
    headers: { "Authorization": "Bearer new-token" }
227
  });
228
};
229

230
// Clear video source
231
const clearVideo = () => {
232
  videoRef.current?.setSource(undefined);
233
};
234
```
235

236
### Information & Utility Methods
237

238
Methods for getting video information and saving content.
239

240
```typescript { .api }
241
/**
242
 * Get current playback position
243
 * @returns Promise resolving to current time in seconds
244
 */
245
getCurrentPosition: () => Promise<number>;
246

247
/**
248
 * Save video to device (iOS only)
249
 * @param options - Save options
250
 * @returns Promise resolving to save data or void on other platforms
251
 */
252
save: (options: object) => Promise<VideoSaveData> | void;
253
```
254

255
**Usage Examples:**
256

257
```typescript
258
const videoRef = useRef<VideoRef>(null);
259

260
// Get current position
261
const getCurrentTime = async () => {
262
  try {
263
    const position = await videoRef.current?.getCurrentPosition();
264
    console.log("Current position:", position);
265
  } catch (error) {
266
    console.error("Error getting position:", error);
267
  }
268
};
269

270
// Save video (iOS only)
271
const saveVideo = async () => {
272
  try {
273
    if (Platform.OS === 'ios') {
274
      const result = await videoRef.current?.save({});
275
      console.log("Video saved:", result?.uri);
276
    }
277
  } catch (error) {
278
    console.error("Error saving video:", error);
279
  }
280
};
281
```
282

283
### Web-Specific Access
284

285
Web platform specific reference access.
286

287
```typescript { .api }
288
/**
289
 * Native HTML video element reference (Web only)
290
 * Access to underlying HTMLVideoElement for web-specific functionality
291
 */
292
nativeHtmlVideoRef?: RefObject<HTMLVideoElement | null>;
293
```
294

295
**Usage Examples:**
296

297
```typescript
298
const videoRef = useRef<VideoRef>(null);
299

300
// Access HTML video element on web
301
const getWebVideoElement = () => {
302
  if (Platform.OS === 'web') {
303
    const htmlVideo = videoRef.current?.nativeHtmlVideoRef?.current;
304
    if (htmlVideo) {
305
      // Direct access to HTML video API
306
      htmlVideo.playbackRate = 1.5;
307
      htmlVideo.addEventListener('timeupdate', handleTimeUpdate);
308
    }
309
  }
310
};
311
```
312

313
## Types
314

315
```typescript { .api }
316
/**
317
 * Video save result data (iOS only)
318
 */
319
interface VideoSaveData {
320
  uri: string;
321
}
322

323
/**
324
 * Video source configuration for setSource method
325
 */
326
interface ReactVideoSource {
327
  uri?: string | NodeRequire;
328
  headers?: Record<string, string>;
329
  drm?: Drm;
330
  textTracks?: TextTracks;
331
  startPosition?: number;
332
  cropStart?: number;
333
  cropEnd?: number;
334
  contentStartTime?: number;
335
  metadata?: VideoMetadata;
336
  ad?: AdConfig;
337
  cmcd?: boolean | CmcdConfiguration;
338
  bufferConfig?: BufferConfig;
339
  minLoadRetryCount?: number;
340
  textTracksAllowChunklessPreparation?: boolean;
341
}
342
```