0
# React Native Video
1

2
React Native Video is a comprehensive video player component that provides native video playback capabilities across iOS, Android, Windows, and Web platforms. It offers advanced streaming features including HLS, DASH, and SmoothStreaming protocols, integrated DRM support, Picture-in-Picture functionality, and professional-grade video controls with extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: react-native-video
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-video`
10
- **Platform Support**: iOS, Android, Windows, Web (via react-native-web)
11

12
## Core Imports
13

14
```typescript
15
import Video, { VideoRef } from "react-native-video";
16
```
17

18
For specific types:
19

20
```typescript
21
import type { 
22
  ReactVideoProps, 
23
  ReactVideoSource, 
24
  OnLoadData,
25
  DRMType 
26
} from "react-native-video";
27
```
28

29
CommonJS:
30

31
```javascript
32
const Video = require("react-native-video").default;
33
```
34

35
## Basic Usage
36

37
```typescript
38
import React, { useRef } from "react";
39
import { View } from "react-native";
40
import Video, { VideoRef } from "react-native-video";
41

42
export default function VideoPlayer() {
43
  const videoRef = useRef<VideoRef>(null);
44

45
  return (
46
    <View style={{ flex: 1 }}>
47
      <Video
48
        ref={videoRef}
49
        source={{
50
          uri: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
51
        }}
52
        style={{ width: "100%", height: 200 }}
53
        controls={true}
54
        resizeMode="contain"
55
        onLoad={(data) => {
56
          console.log("Video loaded:", data.duration);
57
        }}
58
        onError={(error) => {
59
          console.error("Video error:", error);
60
        }}
61
      />
62
    </View>
63
  );
64
}
65
```
66

67
## Architecture
68

69
React Native Video is built around several key components:
70

71
- **Video Component**: Main React Native component providing declarative video playback interface
72
- **VideoRef Interface**: Imperative API for programmatic video control (seek, play, pause, etc.)
73
- **Platform Implementations**: Native iOS (AVPlayer), Android (ExoPlayer), Windows (MediaPlayerElement), and Web (HTML5 video) backends
74
- **Type System**: Comprehensive TypeScript definitions covering all video functionality and platform-specific features
75
- **Expo Integration**: Built-in Expo Config Plugins for seamless native feature configuration
76

77
## Capabilities
78

79
### Video Component & Props
80

81
The main Video component with comprehensive props for all video functionality including playback control, styling, audio configuration, and platform-specific features.
82

83
```typescript { .api }
84
declare const Video: React.ForwardRefExoticComponent<
85
  ReactVideoProps & React.RefAttributes<VideoRef>
86
>;
87

88
interface ReactVideoProps extends ReactVideoEvents, ViewProps {
89
  source?: ReactVideoSource;
90
  style?: StyleProp<ViewStyle>;
91
  paused?: boolean;
92
  rate?: number;
93
  volume?: number;
94
  muted?: boolean;
95
  controls?: boolean;
96
  resizeMode?: "none" | "contain" | "cover" | "stretch";
97
}
98
```
99

100
[Video Component & Props](./video-component.md)
101

102
### Video Reference Methods
103

104
Imperative API for programmatic video control including playback, seeking, fullscreen, and Picture-in-Picture functionality.
105

106
```typescript { .api }
107
interface VideoRef {
108
  seek: (time: number, tolerance?: number) => void;
109
  resume: () => void;
110
  pause: () => void;
111
  setVolume: (volume: number) => void;
112
  presentFullscreenPlayer: () => void;
113
  dismissFullscreenPlayer: () => void;
114
  enterPictureInPicture: () => void;
115
  exitPictureInPicture: () => void;
116
}
117
```
118

119
[Video Reference Methods](./video-ref-methods.md)
120

121
### Video Sources & Configuration
122

123
Comprehensive video source configuration supporting local files, network streams, DRM-protected content, and advanced features like text tracks and metadata.
124

125
```typescript { .api }
126
interface ReactVideoSource {
127
  uri?: string | NodeRequire;
128
  headers?: Record<string, string>;
129
  drm?: Drm;
130
  textTracks?: TextTracks;
131
  startPosition?: number;
132
  metadata?: VideoMetadata;
133
}
134

135
interface Drm {
136
  type?: "widevine" | "playready" | "clearkey" | "fairplay";
137
  licenseServer?: string;
138
  headers?: Record<string, string>;
139
  getLicense?: (spcBase64: string, contentId: string, licenseUrl: string, loadedLicenseUrl: string) => string | Promise<string>;
140
}
141
```
142

143
[Video Sources & Configuration](./video-sources.md)
144

145
### Event Handling
146

147
Comprehensive event system covering playback events, state changes, track information, buffering, and error handling.
148

149
```typescript { .api }
150
interface ReactVideoEvents {
151
  onLoad?: (e: OnLoadData) => void;
152
  onProgress?: (e: OnProgressData) => void;
153
  onError?: (e: OnVideoErrorData) => void;
154
  onEnd?: () => void;
155
  onBuffer?: (e: OnBufferData) => void;
156
  onPlaybackStateChanged?: (e: OnPlaybackStateChangedData) => void;
157
}
158

159
interface OnLoadData {
160
  currentTime: number;
161
  duration: number;
162
  naturalSize: { width: number; height: number; orientation: "landscape" | "portrait" };
163
  audioTracks: AudioTrack[];
164
  textTracks: TextTrack[];
165
  videoTracks: VideoTrack[];
166
}
167
```
168

169
[Event Handling](./event-handling.md)
170

171
### Platform-Specific Features
172

173
Android decoder utilities and platform-specific functionality including codec support detection and Widevine security level queries.
174

175
```typescript { .api }
176
declare const VideoDecoderProperties: {
177
  getWidevineLevel(): Promise<number>;
178
  isCodecSupported(mimeType: string, width?: number, height?: number): Promise<boolean>;
179
  isHEVCSupported(): Promise<boolean>;
180
};
181
```
182

183
[Platform-Specific Features](./platform-features.md)
184

185
### Expo Configuration
186

187
Expo Config Plugins for configuring native features like Picture-in-Picture, background audio, advertisement integration, and ExoPlayer extensions.
188

189
```typescript { .api }
190
interface ConfigProps {
191
  enableNotificationControls?: boolean;
192
  enableAndroidPictureInPicture?: boolean;
193
  enableBackgroundAudio?: boolean;
194
  enableADSExtension?: boolean;
195
  enableCacheExtension?: boolean;
196
  androidExtensions?: {
197
    useExoplayerRtsp?: boolean;
198
    useExoplayerSmoothStreaming?: boolean;
199
    useExoplayerDash?: boolean;
200
    useExoplayerHls?: boolean;
201
  };
202
}
203
```
204

205
[Expo Configuration](./expo-configuration.md)
206

207
## Types
208

209
```typescript { .api }
210
// Main default export
211
export default Video;
212

213
// Named exports
214
export { Video, VideoDecoderProperties };
215
export * from "./types"; // All type definitions
216

217
// Core component type
218
declare const Video: React.ForwardRefExoticComponent<
219
  ReactVideoProps & React.RefAttributes<VideoRef>
220
>;
221

222
// Utility exports (Android only)
223
declare const VideoDecoderProperties: {
224
  getWidevineLevel(): Promise<number>;
225
  isCodecSupported(mimeType: string, width?: number, height?: number): Promise<'unsupported' | 'hardware' | 'software'>;
226
  isHEVCSupported(): Promise<'unsupported' | 'hardware' | 'software'>;
227
};
228

229
// Main prop interface extending events and view props
230
interface ReactVideoProps extends ReactVideoEvents, ViewProps {
231
  source?: ReactVideoSource;
232
  style?: StyleProp<ViewStyle>;
233
  // ... see sub-docs for complete prop definitions
234
}
235

236
// Reference interface for imperative control
237
interface VideoRef {
238
  seek: (time: number, tolerance?: number) => void;
239
  resume: () => void;
240
  pause: () => void;
241
  setVolume: (volume: number) => void;
242
  presentFullscreenPlayer: () => void;
243
  dismissFullscreenPlayer: () => void;
244
  setFullScreen: (fullScreen: boolean) => void;
245
  enterPictureInPicture: () => void;
246
  exitPictureInPicture: () => void;
247
  save: (options: object) => Promise<VideoSaveData> | void;
248
  getCurrentPosition: () => Promise<number>;
249
  setSource: (source?: ReactVideoSource) => void;
250
  restoreUserInterfaceForPictureInPictureStopCompleted: (restore: boolean) => void;
251
  nativeHtmlVideoRef?: RefObject<HTMLVideoElement | null>; // Web only
252
}
253

254
// Video source configuration
255
interface ReactVideoSource {
256
  uri?: string | NodeRequire;
257
  headers?: Record<string, string>;
258
  drm?: Drm;
259
  textTracks?: TextTracks;
260
  startPosition?: number;
261
  cropStart?: number;
262
  cropEnd?: number;
263
  contentStartTime?: number;
264
  metadata?: VideoMetadata;
265
  ad?: AdConfig;
266
  cmcd?: boolean | CmcdConfiguration;
267
  bufferConfig?: BufferConfig;
268
  minLoadRetryCount?: number;
269
  textTracksAllowChunklessPreparation?: boolean;
270
}
271

272
// Key enum exports
273
declare enum ResizeMode {
274
  NONE = "none",
275
  CONTAIN = "contain", 
276
  COVER = "cover",
277
  STRETCH = "stretch"
278
}
279

280
declare enum ViewType {
281
  TEXTURE = 0,
282
  SURFACE = 1,
283
  SURFACE_SECURE = 2
284
}
285

286
declare enum FilterType {
287
  NONE = "",
288
  INVERT = "CIColorInvert",
289
  MONOCHROME = "CIColorMonochrome",
290
  CHROME = "CIPhotoEffectChrome",
291
  SEPIA = "CISepiaTone",
292
  INSTANT = "CIPhotoEffectInstant",
293
  NOIR = "CIPhotoEffectNoir",
294
  PROCESS = "CIPhotoEffectProcess",
295
  TRANSFER = "CIPhotoEffectTransfer",
296
  TONAL = "CIPhotoEffectTonal",
297
  FADE = "CIPhotoEffectFade",
298
  MONO = "CIColorMonochrome",
299
  POSTERIZE = "CIColorPosterize",
300
  FALSE_COLOR = "CIFalseColor",
301
  MAXIMIZE_COMPONENT = "CIMaximumComponent",
302
  MINIMIZE_COMPONENT = "CIMinimumComponent",
303
  CHROME_KEY = "CIChromaKey",
304
  BLOOM = "CIBloom",
305
  GLOOM = "CIGloom"
306
}
307

308
declare enum TextTrackType {
309
  SUBRIP = "application/x-subrip",
310
  TTML = "application/ttml+xml",
311
  VTT = "text/vtt"
312
}
313

314
declare enum Orientation {
315
  PORTRAIT = "portrait",
316
  LANDSCAPE = "landscape"
317
}
318

319
declare enum DRMType {
320
  WIDEVINE = "widevine",
321
  PLAYREADY = "playready",
322
  CLEARKEY = "clearkey",
323
  FAIRPLAY = "fairplay"
324
}
325

326
declare enum CmcdMode {
327
  MODE_REQUEST_HEADER = 0,
328
  MODE_QUERY_PARAMETER = 1
329
}
330

331
declare enum BufferingStrategyType {
332
  DEFAULT = "Default",
333
  DISABLE_BUFFERING = "DisableBuffering",
334
  DEPENDING_ON_MEMORY = "DependingOnMemory"
335
}
336

337
declare enum SelectedTrackType {
338
  SYSTEM = "system",
339
  DISABLED = "disabled",
340
  TITLE = "title",
341
  LANGUAGE = "language",
342
  INDEX = "index"
343
}
344

345
declare enum SelectedVideoTrackType {
346
  AUTO = "auto",
347
  DISABLED = "disabled",
348
  RESOLUTION = "resolution",
349
  INDEX = "index"
350
}
351

352
declare enum FullscreenOrientationType {
353
  ALL = "all",
354
  LANDSCAPE = "landscape",
355
  PORTRAIT = "portrait"
356
}
357

358
declare enum IgnoreSilentSwitchType {
359
  INHERIT = "inherit",
360
  IGNORE = "ignore",
361
  OBEY = "obey"
362
}
363

364
declare enum MixWithOthersType {
365
  INHERIT = "inherit",
366
  MIX = "mix",
367
  DUCK = "duck"
368
}
369

370
declare enum AudioOutput {
371
  SPEAKER = "speaker",
372
  EARPIECE = "earpiece"
373
}
374

375
// Complete AdEvent enum (32 events)
376
declare enum AdEvent {
377
  AD_BREAK_ENDED = "AD_BREAK_ENDED",
378
  AD_BREAK_READY = "AD_BREAK_READY",
379
  AD_BREAK_STARTED = "AD_BREAK_STARTED",
380
  AD_BUFFERING = "AD_BUFFERING",
381
  AD_CAN_PLAY = "AD_CAN_PLAY",
382
  AD_METADATA = "AD_METADATA",
383
  AD_PERIOD_ENDED = "AD_PERIOD_ENDED",
384
  AD_PERIOD_STARTED = "AD_PERIOD_STARTED",
385
  AD_PROGRESS = "AD_PROGRESS",
386
  ALL_ADS_COMPLETED = "ALL_ADS_COMPLETED",
387
  CLICKED = "CLICKED",
388
  COMPLETED = "COMPLETED",
389
  CONTENT_PAUSE_REQUESTED = "CONTENT_PAUSE_REQUESTED",
390
  CONTENT_RESUME_REQUESTED = "CONTENT_RESUME_REQUESTED",
391
  CUEPOINTS_CHANGED = "CUEPOINTS_CHANGED",
392
  DURATION_CHANGE = "DURATION_CHANGE",
393
  ERROR = "ERROR",
394
  FIRST_QUARTILE = "FIRST_QUARTILE",
395
  IMPRESSION = "IMPRESSION",
396
  INTERACTION = "INTERACTION",
397
  LINEAR_CHANGED = "LINEAR_CHANGED",
398
  LOADED = "LOADED",
399
  LOG = "LOG", 
400
  MIDPOINT = "MIDPOINT",
401
  PAUSED = "PAUSED",
402
  RESUMED = "RESUMED",
403
  SKIPPABLE_STATE_CHANGED = "SKIPPABLE_STATE_CHANGED",
404
  SKIPPED = "SKIPPED",
405
  STARTED = "STARTED",
406
  TAPPED = "TAPPED",
407
  THIRD_QUARTILE = "THIRD_QUARTILE",
408
  USER_CLOSE = "USER_CLOSE",
409
  VIDEO_CLICKED = "VIDEO_CLICKED",
410
  VIDEO_ICON_CLICKED = "VIDEO_ICON_CLICKED",
411
  VOLUME_CHANGED = "VOLUME_CHANGED",
412
  VOLUME_MUTED = "VOLUME_MUTED"
413
}
414

415
// Language support
416
type ISO639_1 = "aa" | "ab" | "ae" | "af" | "ak" | "am" | "an" | "ar" | "as" | "av" | "ay" | "az" | "ba" | "be" | "bg" | "bh" | "bi" | "bm" | "bn" | "bo" | "br" | "bs" | "ca" | "ce" | "ch" | "co" | "cr" | "cs" | "cu" | "cv" | "cy" | "da" | "de" | "dv" | "dz" | "ee" | "el" | "en" | "eo" | "es" | "et" | "eu" | "fa" | "ff" | "fi" | "fj" | "fo" | "fr" | "fy" | "ga" | "gd" | "gl" | "gn" | "gu" | "gv" | "ha" | "he" | "hi" | "ho" | "hr" | "ht" | "hu" | "hy" | "hz" | "ia" | "id" | "ie" | "ig" | "ii" | "ik" | "io" | "is" | "it" | "iu" | "ja" | "jv" | "ka" | "kg" | "ki" | "kj" | "kk" | "kl" | "km" | "kn" | "ko" | "kr" | "ks" | "ku" | "kv" | "kw" | "ky" | "la" | "lb" | "lg" | "li" | "ln" | "lo" | "lt" | "lu" | "lv" | "mg" | "mh" | "mi" | "mk" | "ml" | "mn" | "mr" | "ms" | "mt" | "my" | "na" | "nb" | "nd" | "ne" | "ng" | "nl" | "nn" | "no" | "nr" | "nv" | "ny" | "oc" | "oj" | "om" | "or" | "os" | "pa" | "pi" | "pl" | "ps" | "pt" | "qu" | "rm" | "rn" | "ro" | "ru" | "rw" | "sa" | "sc" | "sd" | "se" | "sg" | "si" | "sk" | "sl" | "sm" | "sn" | "so" | "sq" | "sr" | "ss" | "st" | "su" | "sv" | "sw" | "ta" | "te" | "tg" | "th" | "ti" | "tk" | "tl" | "tn" | "to" | "tr" | "ts" | "tt" | "tw" | "ty" | "ug" | "uk" | "ur" | "uz" | "ve" | "vi" | "vo" | "wa" | "wo" | "xh" | "yi" | "yo" | "za" | "zh" | "zu";
417

418
// Utility types
419
type Headers = Record<string, string>;
420
type EnumValues<T> = T[keyof T];
421

422
interface VideoMetadata {
423
  title?: string;
424
  subtitle?: string;
425
  description?: string;
426
  artist?: string;
427
  imageUri?: string;
428
}
429

430
interface DebugConfig {
431
  enable?: boolean;
432
  thread?: boolean;
433
}
434

435
type TextTracks = {
436
  title: string;
437
  language: ISO639_1;
438
  type: TextTrackType;
439
  uri: string;
440
}[];
441

442
type Chapters = {
443
  title: string;
444
  startTime: number;
445
  endTime: number;
446
  uri?: string;
447
}[];
448

449
interface VideoSaveData {
450
  uri: string;
451
}
452
```