Configuration Options

This page documents all available configuration options for the VIDTREO SDK across all packages.

Core Options

These options are available in all packages (React, Web Component, and Core SDK).

apiKey

Type: string (required)

Your VIDTREO API key for authentication.

<VidtreoRecorder apiKey="vt_live_xxxxxxxxxxxx" />

backendUrl / apiUrl

Type: string Default: "https://core.vidtreo.com"

Custom API endpoint URL. Useful for proxying requests or using a custom backend.

<VidtreoRecorder
  apiKey="..."
  backendUrl="https://your-proxy.com/api"
/>

Recording Options

maxRecordingTime

Type: number Default: undefined (unlimited)

Maximum recording duration in milliseconds. Recording automatically stops when this limit is reached.

// 5 minutes max
<VidtreoRecorder maxRecordingTime={300000} />

// 30 seconds max
<VidtreoRecorder maxRecordingTime={30000} />

countdownDuration

Type: number Default: 3000

Duration of the pre-recording countdown in milliseconds. Set to 0 to disable.

// 5 second countdown
<VidtreoRecorder countdownDuration={5000} />

// No countdown
<VidtreoRecorder countdownDuration={0} />

Feature Toggles

enableSourceSwitching

Type: boolean Default: true

Allow users to switch between camera and screen recording during a session.

<VidtreoRecorder enableSourceSwitching={true} />

enableMute

Type: boolean Default: true

Show the mute/unmute button and allow audio toggling.

<VidtreoRecorder enableMute={true} />

enablePause

Type: boolean Default: true

Allow pausing and resuming recording.

<VidtreoRecorder enablePause={true} />

enableDeviceChange

Type: boolean Default: true

Allow users to select different cameras and microphones.

<VidtreoRecorder enableDeviceChange={true} />

Tab Visibility

enableTabVisibilityOverlay

Type: boolean Default: false

Show an overlay when the browser tab becomes hidden during recording.

<VidtreoRecorder enableTabVisibilityOverlay={true} />

tabVisibilityOverlayText

Type: string Default: "Recording paused - return to this tab"

Custom text for the tab visibility overlay.

<VidtreoRecorder
  enableTabVisibilityOverlay={true}
  tabVisibilityOverlayText="Please return to continue recording"
/>

Mobile Mode

Control how the recorder behaves on mobile devices.

Web Component (`mobile-mode` attribute)

Type: "overlay" | "embed" | "native" Default: "overlay"

Value	Behavior	SDK Controls
`overlay`	Fullscreen modal	Yes
`embed`	Embedded inline	Yes
`native`	Native camera app	No (file input)

<!-- Fullscreen modal (default) -->
<vidtreo-recorder mobile-mode="overlay"></vidtreo-recorder>

<!-- Inline recorder -->
<vidtreo-recorder mobile-mode="embed"></vidtreo-recorder>

<!-- Use device's native camera -->
<vidtreo-recorder mobile-mode="native"></vidtreo-recorder>

React (`nativeCamera` prop)

Type: boolean Default: true

// Use device's native camera (default)
<VidtreoRecorder nativeCamera={true} />

// Use SDK overlay UI on mobile
<VidtreoRecorder nativeCamera={false} />

On iOS Safari, the native mode is recommended for best compatibility as it uses the device's built-in camera interface.

Metadata

userMetadata

Type: Record<string, unknown> Default: undefined

Custom metadata to attach to the recording. This data is stored with the video and can be retrieved via the API.

<VidtreoRecorder
  userMetadata={{
    userId: 'user-123',
    sessionId: 'session-456',
    department: 'support',
    customField: 'any-value'
  }}
/>

Metadata is useful for organizing recordings and integrating with your own systems. You can search and filter recordings by metadata in the dashboard.

Internationalization

lang

Type: string Default: "en"

UI language. Supported values: "en", "es", "pt".

<VidtreoRecorder lang="es" />

texts

Type: object Default: undefined

Custom text overrides for UI elements.

<VidtreoRecorder
  lang="en"
  texts={{
    record: 'Start Capture',
    stop: 'End Capture',
    pause: 'Hold',
    resume: 'Continue',
    mute: 'Silence',
    unmute: 'Sound On'
  }}
/>

Demo Mode

demo

Type: boolean Default: false

Enable demo mode. In demo mode, recordings are not uploaded to the server. Useful for testing and development.

<VidtreoRecorder demo={true} />

Default Configuration

Here's the complete default configuration:

const defaultConfig = {
  apiUrl: 'https://core.vidtreo.com',
  enableSourceSwitching: true,
  enableMute: true,
  enablePause: true,
  enableDeviceChange: true,
  countdownDuration: 3000,
  maxRecordingTime: undefined,
  userMetadata: undefined,
  enableTabVisibilityOverlay: false,
  tabVisibilityOverlayText: 'Recording paused - return to this tab',
  lang: 'en',
  texts: undefined,
  demo: false
};

Environment Variables

Configuration can also be set via environment variables:

Vite

VITE_VIDTREO_API_KEY=vt_live_xxxxxxxxxxxx

Next.js

NEXT_PUBLIC_VIDTREO_API_KEY=vt_live_xxxxxxxxxxxx

Node.js

VIDTREO_API_KEY=vt_live_xxxxxxxxxxxx

Package-Specific Options

React Package

The React package (@vidtreo/recorder-react) accepts all core options plus:

Option	Type	Description
`className`	`string`	CSS class for the container
`style`	`object`	Inline styles for the container

Web Component

The Web Component uses kebab-case for all attributes:

Attribute	Core Option
`api-key`	`apiKey`
`backend-url`	`backendUrl`
`max-recording-time`	`maxRecordingTime`
`countdown-duration`	`countdownDuration`
`enable-source-switching`	`enableSourceSwitching`
`enable-mute`	`enableMute`
`enable-pause`	`enablePause`
`enable-device-change`	`enableDeviceChange`
`mobile-mode`	`mobileMode`
`user-metadata`	`userMetadata` (JSON string)
`texts`	`texts` (JSON string)

Next Steps

Callbacks — Handle events
Customization — Styling and theming
API Reference — Complete API docs

Configuration Options

On this page