VideoConfig

Configuration type for video sources including URI, headers, DRM, and subtitles

VideoConfig

The main configuration object for video sources. This type defines how videos are loaded and configured in React Native Video.

type VideoConfig = {
  uri: VideoSource;
  headers?: Record<string, string>;
  drm?: DrmParams;
  bufferConfig?: BufferConfig;
  metadata?: CustomVideoMetadata;
  externalSubtitles?: ExternalSubtitle[];
  initializeOnCreation?: boolean;
};

Properties

uri · VideoSource · required

The URI of the video. Can be a remote URL (string) or a local asset (number from require()).

// Remote URL
uri: 'https://example.com/video.mp4'

// Local asset
uri: require('./assets/video.mp4')

headers · Record<string, string>

Custom HTTP headers to send with the video request.

headers: {
  'Authorization': 'Bearer token123',
  'Custom-Header': 'value'
}

drm · DrmParams

DRM (Digital Rights Management) configuration. See DrmParams for details.

bufferConfig · BufferConfig

Player buffer configuration. See BufferConfig for details.

metadata · CustomVideoMetadata

Custom metadata associated with the video for display in native players.

Show CustomVideoMetadata properties

title · string

The title of the video

subtitle · string

The subtitle of the video

description · string

Description of the video content

artist · string

Artist or creator name

imageUri · string

URI to the video thumbnail or poster image

externalSubtitles · ExternalSubtitle[]

Array of external subtitle tracks to load with the video.

On iOS, only WebVTT (.vtt) subtitles are supported for HLS streams and MP4 files. The label property may be overridden by the iOS player.

externalSubtitles: [
  {
    uri: 'https://example.com/subtitles_en.vtt',
    label: 'English',
    type: 'vtt',
    language: 'en'
  },
  {
    uri: 'https://example.com/subtitles_es.vtt',
    label: 'Español',
    type: 'vtt',
    language: 'es'
  }
]

Show ExternalSubtitle properties

uri · string · required

The URI of the subtitle file. When type is not specified, the URI must end with a valid subtitle extension (.vtt, .srt, .ssa, .ass).

label · string · required

Display label for the subtitle track

type · SubtitleType

The subtitle format type. One of: 'vtt', 'srt', 'ssa', 'ass', or 'auto'.

When not specified, the type is inferred from the URI extension.

'auto' is not available when the URI has no extension.

language · string

ISO 639-1 or ISO 639-2 language code (e.g., ‘en’, ‘es’, ‘fr’, ‘zh-CN’).

Default: 'und' (undefined)

initializeOnCreation · boolean · default: true

Determines if the native player should be initialized immediately when created.

• true: Player initializes as soon as it’s created
• false: Player must be initialized manually later

VideoSource

The video source can be either a string URL or a number from require().

type VideoSource = number | string;

Examples

Remote video

const config: VideoConfig = {
  uri: 'https://example.com/video.mp4'
};

Local video asset

const config: VideoConfig = {
  uri: require('./assets/video.mp4')
};

Video with headers and DRM

const config: VideoConfig = {
  uri: 'https://example.com/protected-video.mp4',
  headers: {
    'Authorization': 'Bearer token123'
  },
  drm: {
    type: 'widevine',
    licenseUrl: 'https://drm.example.com/license'
  }
};

Video with subtitles

const config: VideoConfig = {
  uri: 'https://example.com/video.mp4',
  externalSubtitles: [
    {
      uri: 'https://example.com/subs/en.vtt',
      label: 'English',
      type: 'vtt',
      language: 'en'
    },
    {
      uri: 'https://example.com/subs/es.vtt',
      label: 'Spanish',
      type: 'vtt',
      language: 'es'
    }
  ],
  metadata: {
    title: 'Sample Video',
    artist: 'Creator Name',
    imageUri: 'https://example.com/poster.jpg'
  }
};

SubtitleType

Supported subtitle format types:

type SubtitleType = 'vtt' | 'srt' | 'ssa' | 'ass' | 'auto';

• 'vtt' - WebVTT format
• 'srt' - SubRip format
• 'ssa' - SubStation Alpha format
• 'ass' - Advanced SubStation Alpha format
• 'auto' - Auto-detect from file extension (not available when URI has no extension)