0
# Video Sources & Configuration
1

2
Comprehensive video source configuration supporting local files, network streams, DRM-protected content, text tracks, metadata, advertisements, and advanced streaming features.
3

4
## Capabilities
5

6
### ReactVideoSource Interface
7

8
Main interface for configuring video sources with all available options.
9

10
```typescript { .api }
11
/**
12
 * Complete video source configuration interface
13
 * Supports local files, network streams, DRM, text tracks, and advanced features
14
 */
15
interface ReactVideoSource {
16
  uri?: string | NodeRequire;
17
  headers?: Record<string, string>;
18
  drm?: Drm;
19
  textTracks?: TextTracks;
20
  startPosition?: number;
21
  cropStart?: number;
22
  cropEnd?: number;
23
  contentStartTime?: number;
24
  metadata?: VideoMetadata;
25
  ad?: AdConfig;
26
  cmcd?: boolean | CmcdConfiguration;
27
  bufferConfig?: BufferConfig;
28
  minLoadRetryCount?: number;
29
  textTracksAllowChunklessPreparation?: boolean;
30
}
31
```
32

33
**Usage Examples:**
34

35
```typescript
36
// Basic network stream
37
const basicSource = {
38
  uri: "https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/BigBuckBunny.mp4"
39
};
40

41
// Local file (iOS/Android)
42
const localSource = {
43
  uri: "video.mp4" // File in bundle
44
};
45

46
// Require-based local file
47
const requireSource = {
48
  uri: require("./assets/video.mp4")
49
};
50

51
// Advanced network stream with headers
52
const advancedSource = {
53
  uri: "https://example.com/protected-video.m3u8",
54
  headers: {
55
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
56
    "User-Agent": "MyApp/1.0"
57
  },
58
  startPosition: 30, // Start at 30 seconds
59
  metadata: {
60
    title: "Protected Content",
61
    artist: "Content Creator",
62
    description: "DRM protected video stream"
63
  }
64
};
65
```
66

67
### DRM Configuration
68

69
Digital Rights Management configuration for protected content.
70

71
```typescript { .api }
72
/**
73
 * DRM configuration for protected content playback
74
 * Supports major DRM systems across platforms
75
 */
76
interface Drm {
77
  type?: "widevine" | "playready" | "clearkey" | "fairplay";
78
  licenseServer?: string;
79
  headers?: Record<string, string>;
80
  contentId?: string;
81
  certificateUrl?: string;
82
  base64Certificate?: boolean;
83
  multiDrm?: boolean;
84
  localSourceEncryptionKeyScheme?: string;
85
  getLicense?: (
86
    spcBase64: string,
87
    contentId: string,
88
    licenseUrl: string,
89
    loadedLicenseUrl: string
90
  ) => string | Promise<string>;
91
}
92

93
/**
94
 * DRM system types
95
 */
96
enum DRMType {
97
  WIDEVINE = "widevine",
98
  PLAYREADY = "playready", 
99
  CLEARKEY = "clearkey",
100
  FAIRPLAY = "fairplay"
101
}
102
```
103

104
**Usage Examples:**
105

106
```typescript
107
// Widevine DRM (Android)
108
const widevineSource = {
109
  uri: "https://storage.googleapis.com/wvmedia/clear/h264/tears/tears.mpd",
110
  drm: {
111
    type: "widevine",
112
    licenseServer: "https://proxy.uat.widevine.com/proxy?provider=widevine_test",
113
    headers: {
114
      "X-AxDRM-Message": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
115
    }
116
  }
117
};
118

119
// FairPlay DRM (iOS)
120
const fairplaySource = {
121
  uri: "https://devstreaming-cdn.apple.com/videos/streaming/examples/img_bipbop_adv_example_fmp4/master.m3u8",
122
  drm: {
123
    type: "fairplay",
124
    licenseServer: "https://fps.ezdrm.com/api/licenses/09cc0377-6dd4-40cb-b09d-b582236e70fe",
125
    certificateUrl: "https://fps.ezdrm.com/demo/video/eleisure.cer",
126
    contentId: "09cc0377-6dd4-40cb-b09d-b582236e70fe"
127
  }
128
};
129

130
// Custom license acquisition
131
const customLicenseSource = {
132
  uri: "https://example.com/drm-content.m3u8",
133
  drm: {
134
    type: "fairplay",
135
    getLicense: async (spcBase64, contentId, licenseUrl, loadedLicenseUrl) => {
136
      const response = await fetch(licenseUrl, {
137
        method: 'POST',
138
        headers: { 'Content-Type': 'application/octet-stream' },
139
        body: spcBase64
140
      });
141
      return await response.text();
142
    }
143
  }
144
};
145
```
146

147
### Text Tracks Configuration
148

149
Subtitle and caption track configuration.
150

151
```typescript { .api }
152
/**
153
 * Text track definitions for subtitles and captions
154
 */
155
type TextTracks = {
156
  title: string;
157
  language: string; // ISO639_1 language code
158
  type: "application/x-subrip" | "application/ttml+xml" | "text/vtt";
159
  uri: string;
160
}[];
161

162
/**
163
 * Text track types
164
 */
165
enum TextTrackType {
166
  SUBRIP = "application/x-subrip",
167
  TTML = "application/ttml+xml", 
168
  VTT = "text/vtt"
169
}
170
```
171

172
**Usage Examples:**
173

174
```typescript
175
// Multiple subtitle tracks
176
const sourceWithSubtitles = {
177
  uri: "https://example.com/video.mp4",
178
  textTracks: [
179
    {
180
      title: "English Subtitles",
181
      language: "en",
182
      type: "text/vtt",
183
      uri: "https://example.com/subtitles-en.vtt"
184
    },
185
    {
186
      title: "Spanish Subtitles", 
187
      language: "es",
188
      type: "text/vtt",
189
      uri: "https://example.com/subtitles-es.vtt"
190
    },
191
    {
192
      title: "French Subtitles",
193
      language: "fr", 
194
      type: "application/x-subrip",
195
      uri: "https://example.com/subtitles-fr.srt"
196
    }
197
  ]
198
};
199
```
200

201
### Video Metadata
202

203
Metadata information for media controls and notifications.
204

205
```typescript { .api }
206
/**
207
 * Video metadata for media controls and notifications
208
 */
209
interface VideoMetadata {
210
  title?: string;
211
  subtitle?: string;
212
  description?: string;
213
  artist?: string;
214
  imageUri?: string;
215
}
216
```
217

218
**Usage Examples:**
219

220
```typescript
221
// Rich metadata for media controls
222
const sourceWithMetadata = {
223
  uri: "https://example.com/video.mp4",
224
  metadata: {
225
    title: "Big Buck Bunny",
226
    subtitle: "Episode 1",
227
    description: "A large and lovable rabbit deals with three tiny bullies",
228
    artist: "Blender Foundation",
229
    imageUri: "https://example.com/poster.jpg"
230
  }
231
};
232
```
233

234
### Advertisement Configuration
235

236
Advertisement integration using IMA SDK.
237

238
```typescript { .api }
239
/**
240
 * Advertisement configuration for IMA SDK integration
241
 */
242
interface AdConfig {
243
  adTagUrl?: string;
244
  adLanguage?: string; // ISO639_1 language code
245
}
246
```
247

248
**Usage Examples:**
249

250
```typescript
251
// Video with pre-roll advertisement
252
const sourceWithAds = {
253
  uri: "https://example.com/main-video.mp4",
254
  ad: {
255
    adTagUrl: "https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/single_ad_samples&ciu_szs=300x250&impl=s&gdfp_req=1&env=vp&output=vast&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ct%3Dlinear&correlator=",
256
    adLanguage: "en"
257
  }
258
};
259
```
260

261
### CMCD Configuration
262

263
Common Media Client Data for streaming analytics.
264

265
```typescript { .api }
266
/**
267
 * CMCD (Common Media Client Data) configuration for streaming analytics
268
 * Platform: Android
269
 */
270
type Cmcd = boolean | CmcdConfiguration;
271

272
interface CmcdConfiguration {
273
  mode?: CmcdMode;
274
  request?: CmcdData;
275
  session?: CmcdData;
276
  object?: CmcdData;
277
  status?: CmcdData;
278
}
279

280
enum CmcdMode {
281
  MODE_REQUEST_HEADER = 0,
282
  MODE_QUERY_PARAMETER = 1
283
}
284

285
/**
286
 * Custom CMCD data with hyphenated prefix
287
 */
288
type CmcdData = Record<`${string}-${string}`, string | number>;
289
```
290

291
**Usage Examples:**
292

293
```typescript
294
// Basic CMCD enablement
295
const sourceWithBasicCMCD = {
296
  uri: "https://example.com/video.m3u8",
297
  cmcd: true // Uses default query parameter mode
298
};
299

300
// Advanced CMCD configuration
301
const sourceWithAdvancedCMCD = {
302
  uri: "https://example.com/video.m3u8", 
303
  cmcd: {
304
    mode: 1, // MODE_QUERY_PARAMETER
305
    session: {
306
      "com-example-sessionid": "abc123",
307
      "com-example-userid": "user456"
308
    },
309
    request: {
310
      "com-example-cdn": "cloudfront"
311
    }
312
  }
313
};
314
```
315

316
### Buffer Configuration
317

318
Fine-grained buffering behavior control.
319

320
```typescript { .api }
321
/**
322
 * Buffer configuration for streaming optimization
323
 */
324
interface BufferConfig {
325
  minBufferMs?: number;
326
  maxBufferMs?: number;
327
  bufferForPlaybackMs?: number;
328
  bufferForPlaybackAfterRebufferMs?: number;
329
  backBufferDurationMs?: number;
330
  maxHeapAllocationPercent?: number;
331
  minBackBufferMemoryReservePercent?: number;
332
  minBufferMemoryReservePercent?: number;
333
  initialBitrate?: number;
334
  cacheSizeMB?: number;
335
  live?: BufferConfigLive;
336
}
337

338
/**
339
 * Live streaming specific buffer configuration
340
 */
341
interface BufferConfigLive {
342
  maxPlaybackSpeed?: number;
343
  minPlaybackSpeed?: number;
344
  maxOffsetMs?: number;
345
  minOffsetMs?: number;
346
  targetOffsetMs?: number;
347
}
348
```
349

350
**Usage Examples:**
351

352
```typescript
353
// Optimized for low latency live streaming
354
const liveStreamSource = {
355
  uri: "https://example.com/live-stream.m3u8",
356
  bufferConfig: {
357
    minBufferMs: 1000,
358
    maxBufferMs: 3000,
359
    bufferForPlaybackMs: 500,
360
    live: {
361
      maxPlaybackSpeed: 1.1,
362
      minPlaybackSpeed: 0.9,
363
      targetOffsetMs: 2000
364
    }
365
  }
366
};
367

368
// Optimized for high quality VOD
369
const vodSource = {
370
  uri: "https://example.com/high-quality-video.mp4",
371
  bufferConfig: {
372
    minBufferMs: 5000,
373
    maxBufferMs: 30000,
374
    bufferForPlaybackMs: 2000,
375
    initialBitrate: 1000000,
376
    cacheSizeMB: 100
377
  }
378
};
379
```
380

381
### Advanced Source Options
382

383
Additional source configuration options for specific use cases.
384

385
```typescript { .api }
386
/**
387
 * Additional source configuration options
388
 */
389
interface ReactVideoSourceProperties {
390
  // Playback positioning
391
  startPosition?: number;
392
  cropStart?: number;
393
  cropEnd?: number;
394
  contentStartTime?: number;
395
  
396
  // Network configuration  
397
  minLoadRetryCount?: number;
398
  
399
  // Text track options
400
  textTracksAllowChunklessPreparation?: boolean;
401
  
402
  // Internal properties (typically auto-detected)
403
  isNetwork?: boolean;
404
  isAsset?: boolean;
405
  isLocalAssetFile?: boolean;
406
  shouldCache?: boolean;
407
  type?: string;
408
  mainVer?: number;
409
  patchVer?: number;
410
}
411
```
412

413
**Usage Examples:**
414

415
```typescript
416
// Video with precise timing control
417
const preciseTimingSource = {
418
  uri: "https://example.com/long-video.mp4",
419
  startPosition: 300, // Start at 5 minutes
420
  cropStart: 60,      // Skip first minute of content
421
  cropEnd: 3600,      // End at 1 hour mark
422
  minLoadRetryCount: 5 // Retry failed loads 5 times
423
};
424

425
// Optimized text track loading
426
const optimizedTextSource = {
427
  uri: "https://example.com/video.mp4",
428
  textTracks: [
429
    {
430
      title: "English",
431
      language: "en", 
432
      type: "text/vtt",
433
      uri: "https://example.com/subs-en.vtt"
434
    }
435
  ],
436
  textTracksAllowChunklessPreparation: true
437
};
438
```
439

440
## Platform Support
441

442
### Supported Protocols
443

444
- **HLS (HTTP Live Streaming)**: All platforms
445
- **DASH (Dynamic Adaptive Streaming)**: Android (ExoPlayer extension)
446
- **SmoothStreaming**: Android (ExoPlayer extension)
447
- **RTSP**: Android (ExoPlayer extension)
448
- **HTTP/HTTPS**: All platforms
449
- **Local files**: All platforms
450

451
### DRM Support Matrix
452

453
- **iOS**: FairPlay Streaming (FPS)
454
- **Android**: Widevine, PlayReady, ClearKey
455
- **Windows**: PlayReady
456
- **Web**: Widevine (Chrome), PlayReady (Edge), FairPlay (Safari)
457

458
### File Format Support
459

460
- **Video Codecs**: H.264, H.265/HEVC (platform dependent), VP8, VP9
461
- **Audio Codecs**: AAC, MP3, Opus, Vorbis
462
- **Containers**: MP4, MOV, AVI, MKV, WebM, M3U8, MPD