@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

npm install @vidtreo/recorder-react

Peer Dependencies:

• react >=18.0.0
• react-dom >=18.0.0

Quick Start

Using the Component (2 lines of code)

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

<VidtreoRecorder
  apiKey="your-api-key"
/>

Using Environment Variables

Set VIDTREO_API_KEY in your environment:

# .env
VIDTREO_API_KEY=your-api-key

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

<VidtreoRecorder />

Component API

Props

| 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<string, unknown> | 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 |

Example with Callbacks

<VidtreoRecorder
  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:

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 (
    <div>
      {state.stream && (
        <video srcObject={state.stream} autoPlay muted />
      )}
      <button onClick={() => actions.startRecording()}>
        Start Recording
      </button>
      {state.recordingState === 'recording' && (
        <button onClick={() => actions.stopRecording()}>
          Stop
        </button>
      )}
      <div>Timer: {state.timer}</div>
      {state.error && <div>Error: {state.error}</div>}
    </div>
  );
}

Hook State

{
  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;
  };
}

Hook Actions

• 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

Hook Return

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_:

# .env
VITE_VIDTREO_API_KEY=your-api-key

Server-Side Rendering (SSR)

SSR support is planned for a future release. The architecture is prepared for SSR with service wrappers that can route through proxy endpoints.

Examples

Basic Usage

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

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

Custom UI with Hook

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

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

  return (
    <div>
      <video srcObject={state.stream} autoPlay muted />
      <div>
        {state.recordingState === 'idle' ? (
          <button onClick={() => actions.startRecording()}>
            Start
          </button>
        ) : (
          <button onClick={() => actions.stopRecording()}>
            Stop
          </button>
        )}
      </div>
      {state.timer && <div>{state.timer}</div>}
    </div>
  );
}

Package Structure

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.

Supported Languages

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

Basic Usage

Using Built-in Languages

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

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

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

Custom Text Overrides

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

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

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

Complete Custom Translations (e.g., French)

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 (
    <VidtreoRecorder
      apiKey="your-api-key"
      lang="fr"
      texts={frenchTranslations}
    />
  );
}

Dynamic Language Change

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

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

  return (
    <div>
      <select value={language} onChange={(e) => setLanguage(e.target.value)}>
        <option value="en">English</option>
        <option value="es">Español</option>
      </select>

      <VidtreoRecorder
        apiKey="your-api-key"
        lang={language}
      />
    </div>
  );
}

Available Translation Keys

| 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... |

TypeScript Support

The package exports types for better type safety:

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 (
    <VidtreoRecorder
      apiKey="your-api-key"
      texts={customTexts}
    />
  );
}

Multilingual Application with Context

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 (
    <LanguageContext.Provider value={{ language, setLanguage }}>
      {children}
    </LanguageContext.Provider>
  );
}

function RecorderComponent() {
  const { language } = useContext(LanguageContext);
  
  return (
    <VidtreoRecorder
      apiKey="your-api-key"
      lang={language}
    />
  );
}

function LanguageSelector() {
  const { language, setLanguage } = useContext(LanguageContext);
  
  return (
    <select value={language} onChange={(e) => setLanguage(e.target.value)}>
      <option value="en">English</option>
      <option value="es">Español</option>
    </select>
  );
}

function App() {
  return (
    <LanguageProvider>
      <LanguageSelector />
      <RecorderComponent />
    </LanguageProvider>
  );
}

Partial Override Example

Use a base language but override specific texts:

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

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

Loading Translations from API

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<PartialTranslations>({});

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

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

License

MIT