@vidtreo/recorder-react

React components and hooks for the Vidtreo video recording SDK. This package provides a ready-to-use React component and a flexible hook for building custom recording interfaces.

Installation

``bash
npm install @vidtreo/recorder-react
`

Peer Dependencies:
- @vidtreo/recorder >=1.0.5
- react >=18.0.0
- react-dom >=18.0.0

Quick Start

$3

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';

apiKey="your-api-key"
/>
`

$3

Set VIDTREO_API_KEY in your environment:

`bash


.env

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';


`

Component API

$3

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| apiKey | string | No* | - | API key for authentication. Required if VIDTREO_API_KEY env var not set. |
| countdownDuration | number | No | - | Countdown duration in milliseconds before recording starts |
| maxRecordingTime | number | No | - | Maximum recording time in milliseconds |
| userMetadata | Record | No | - | Custom metadata to attach to recordings |
| enableSourceSwitching | boolean | No | true | Enable switching between camera and screen |
| enableMute | boolean | No | true | Enable mute/unmute functionality |
| enablePause | boolean | No | true | Enable pause/resume functionality |
| enableDeviceChange | boolean | No | true | Enable camera/microphone selection |
| enableTabVisibilityOverlay | boolean | No | true | Show overlay when user switches to another tab |
| nativeCamera | boolean | No | true | Use native camera UI on mobile devices (set to false to use custom UI) |
| maxFileSize | number | No | 2560 | Maximum file size in megabytes (default: 2.5GB) |
| lang | string | No | "en" | Language code for UI text ("en" or "es") |
| texts | PartialTranslations | No | - | Custom text overrides for localization |
| onUploadComplete | (result: { recordingId: string; uploadUrl: string }) => void | No | - | Callback when upload completes |
| onUploadProgress | (progress: number) => void | No | - | Callback for upload progress (0-1) |
| onUploadError | (error: Error) => void | No | - | Callback when upload fails |
| onRecordingStart | () => void | No | - | Callback when recording starts |
| onRecordingStop | () => void | No | - | Callback when recording stops |
| onTranscodingProgress | (progress: number) => void | No | - | Callback for transcoding progress (0-100) |
| onError | (error: Error) => void | No | - | Callback for any errors |

$3

`tsx
apiKey="your-api-key"
onUploadComplete={(result) => {
console.log('Recording uploaded:', result.recordingId);
console.log('View at:', result.uploadUrl);
}}
onUploadProgress={(progress) => {
console.log(Upload: ${Math.round(progress * 100)}%);
}}
onError={(error) => {
console.error('Error:', error.message);
}}
/>
`

Hook API

For custom implementations, use the useVidtreoRecorder hook:

`tsx
import { useVidtreoRecorder } from '@vidtreo/recorder-react';

function CustomRecorder() {
const { state, actions, audioLevel } = useVidtreoRecorder({
apiKey: 'your-api-key',
onUploadComplete: (result) => {
console.log('Upload complete:', result);
},
});

return (


`typescript
{
recordingState: 'idle' | 'countdown' | 'recording';
stream: MediaStream | null;
isMuted: boolean;
isPaused: boolean;
error: string | null;
countdown: number | null;
timer: string;
uploadProgress: number | null;
devices: {
cameras: MediaDeviceInfo[];
microphones: MediaDeviceInfo[];
selectedCamera: string | null;
selectedMic: string | null;
};
}
`

$3

- startRecording(sourceType?: 'camera' | 'screen') - Start recording
- stopRecording() - Stop recording and upload
- pauseRecording() - Pause recording
- resumeRecording() - Resume recording
- toggleMute() - Toggle mute state
- switchSource(sourceType: 'camera' | 'screen') - Switch between camera and screen
- changeCamera(deviceId: string) - Change camera device
- changeMic(deviceId: string) - Change microphone device
- startPreview(sourceType?: 'camera' | 'screen') - Start preview stream
- cleanup() - Clean up resources

$3

The hook also returns audioLevel (0-100) for audio visualization.

Environment Variables

The package supports reading the API key from environment variables:

- Vite/Client-side: import.meta.env.VIDTREO_API_KEY
- Node/SSR: process.env.VIDTREO_API_KEY

For Vite projects, prefix with VITE_:

`bash


.env

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';

function App() {
return (
apiKey="your-api-key"
/>
);
}
`

$3

`tsx
import { useVidtreoRecorder } from '@vidtreo/recorder-react';

function CustomRecorder() {
const { state, actions } = useVidtreoRecorder({
apiKey: 'your-api-key',
});

return (


This package contains:
- React component (VidtreoRecorder)
- React hook (useVidtreoRecorder)
- UI sub-components
- TypeScript types

The core SDK functionality is provided by the @vidtreo/recorder package.

Internationalization (i18n)

The React component supports multiple languages and custom text overrides, making it easy to localize the recorder interface for your users.

$3

- English (en) - Default
- Spanish (es)

$3

#### Using Built-in Languages

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';

// English (default)
function App() {
return (
apiKey="your-api-key"
/>
);
}

// Spanish
function App() {
return (
apiKey="your-api-key"
lang="es"
/>
);
}
`

#### Custom Text Overrides

Override any text by passing an object to the texts prop:

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';

function App() {
return (
apiKey="your-api-key"
lang="en"
texts={{
record: 'Start Recording',
stop: 'End Recording',
settings: 'Options'
}}
/>
);
}
`

#### Complete Custom Translations (e.g., French)

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';

function App() {
const frenchTranslations = {
initializingCamera: 'Initialisation de la caméra...',
grantPermissions: 'Accordez les autorisations de caméra et de microphone',
switchingDevice: 'Changement d\'appareil...',
recordingStartsIn: 'L\'enregistrement commence dans...',
switchingSource: 'Changement de source...',
rec: 'ENREG',
settings: 'Paramètres',
record: 'Enregistrer',
stop: 'Arrêter',
pause: 'Pause',
resume: 'Reprendre',
mute: 'Muet',
unmute: 'Activer le son',
switchSource: 'Changer de Source',
camera: 'Caméra',
microphone: 'Microphone',
uploading: 'Téléchargement...',
};

return (
apiKey="your-api-key"
lang="fr"
texts={frenchTranslations}
/>
);
}
`

$3

`tsx
import { useState } from 'react';
import VidtreoRecorder from '@vidtreo/recorder-react';

function App() {
const [language, setLanguage] = useState('en');

return (


| Key | English Default | Spanish Default |
|-----|----------------|-----------------|
| initializingCamera | Initializing camera... | Inicializando cámara... |
| grantPermissions | Grant camera and microphone permissions when prompted | Otorga permisos de cámara y micrófono cuando se solicite |
| switchingDevice | Switching device... | Cambiando dispositivo... |
| recordingStartsIn | Recording starts in... | La grabación comienza en... |
| switchingSource | Switching source... | Cambiando fuente... |
| rec | REC | GRAB |
| settings | Settings | Configuración |
| record | Record | Grabar |
| stop | Stop | Detener |
| pause | Pause | Pausar |
| resume | Resume | Reanudar |
| mute | Mute | Silenciar |
| unmute | Unmute | Activar sonido |
| switchSource | Switch Source | Cambiar Fuente |
| camera | Camera | Cámara |
| microphone | Microphone | Micrófono |
| uploading | Uploading... | Subiendo... |

$3

The package exports types for better type safety:

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';
import type { PartialTranslations } from '@vidtreo/recorder-react';

function App() {
const customTexts: PartialTranslations = {
record: 'Start Capture',
stop: 'End Capture',
};

return (
apiKey="your-api-key"
texts={customTexts}
/>
);
}
`

$3

`tsx
import { createContext, useContext, useState } from 'react';
import VidtreoRecorder from '@vidtreo/recorder-react';

const LanguageContext = createContext({
language: 'en',
setLanguage: (lang: string) => {}
});

function LanguageProvider({ children }: { children: React.ReactNode }) {
const [language, setLanguage] = useState('en');

return (

{children}

);
}

function RecorderComponent() {
const { language } = useContext(LanguageContext);

return (
apiKey="your-api-key"
lang={language}
/>
);
}

function LanguageSelector() {
const { language, setLanguage } = useContext(LanguageContext);

return (
setLanguage(e.target.value)}>
English
Español

);
}

function App() {
return (




);
}
`

$3

Use a base language but override specific texts:

`tsx
import VidtreoRecorder from '@vidtreo/recorder-react';

function App() {
return (
apiKey="your-api-key"
lang="en"
texts={{
record: '🔴 Start Capture',
stop: '⏹️ End Capture',
settings: 'Options'
}}
/>
);
}
`

$3

`tsx
import { useState, useEffect } from 'react';
import VidtreoRecorder from '@vidtreo/recorder-react';
import type { PartialTranslations } from '@vidtreo/recorder-react';

function App() {
const [language, setLanguage] = useState('en');
const [translations, setTranslations] = useState({});

useEffect(() => {
// Load translations from your API
fetch(/api/translations/${language})
.then(res => res.json())
.then(data => setTranslations(data));
}, [language]);

return (
apiKey="your-api-key"
lang={language}
texts={translations}
/>
);
}
``

License

MIT