@vidtreo/recorder-wc

Web component package for the Vidtreo video recording SDK. This package provides a ready-to-use custom element (<vidtreo-recorder>) that can be embedded in any HTML page without a framework.

Installation

npm install @vidtreo/recorder-wc

Peer Dependencies:

• @vidtreo/recorder >=0.9.0

Quick Start

Using the Component (2 lines of code)

<script type="module" src="node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js"></script>

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
></vidtreo-recorder>

Via CDN (jsDelivr)

Specific Version (Recommended for Production)

<script type="module" src="https://cdn.jsdelivr.net/npm/@vidtreo/[email protected]/dist/vidtreo-recorder.js"></script>

<vidtreo-recorder
  api-key="your-api-key"
  <!-- backend-url is optional, defaults to https://api.vidtreo.com -->
></vidtreo-recorder>

Latest Version (Use with Caution)

<script type="module" src="https://cdn.jsdelivr.net/npm/@vidtreo/recorder-wc@latest/dist/vidtreo-recorder.js"></script>

Component API

Attributes

All attributes are optional except where noted. Attributes use kebab-case (e.g., api-key instead of apiKey).

| Attribute | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | api-key | string | No* | - | API key for authentication. Required if not set via JavaScript. | | backend-url | string | No | https://api.vidtreo.com | Backend API URL. Automatically adds https:// prefix if missing. | | countdown-duration | number | No | - | Countdown duration in milliseconds before recording starts (e.g., 3000 for 3 seconds) | | max-recording-time | number | No | - | Maximum recording time in milliseconds (e.g., 300000 for 5 minutes) | | user-metadata | string (JSON) | No | - | Custom metadata to attach to recordings. Must be valid JSON string. | | enable-source-switching | boolean | No | true | Enable switching between camera and screen during recording. Set to "false" to disable. | | enable-mute | boolean | No | true | Enable mute/unmute functionality. Set to "false" to disable. | | enable-pause | boolean | No | true | Enable pause/resume functionality. Set to "false" to disable. | | enable-device-change | boolean | No | true | Enable camera/microphone selection. Set to "false" to disable. | | lang | string | No | "en" | Language code for UI text ("en" or "es") | | texts | string (JSON) | No | - | Custom text overrides for localization. Must be valid JSON string. | | watermark | string (JSON) | No | - | Watermark configuration. Must be valid JSON string. |

Watermark JSON Structure:

{
  "url": "https://example.com/logo.png",
  "position": "bottom-right",
  "opacity": 0.5
}

Note: Boolean attributes are enabled by default. To disable them, set the attribute value to "false" (string).

Examples

Basic Usage

<script type="module" src="node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js"></script>

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
></vidtreo-recorder>

With Countdown and Max Recording Time

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
  countdown-duration="3000"
  max-recording-time="300000"
></vidtreo-recorder>

With Custom Metadata

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
  user-metadata='{"userId": "12345", "sessionId": "abc123"}'
></vidtreo-recorder>

Disable Features

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
  enable-source-switching="false"
  enable-mute="false"
  enable-pause="false"
  enable-device-change="false"
></vidtreo-recorder>

Minimal Configuration (Only Recording)

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
  enable-source-switching="false"
  enable-mute="false"
  enable-pause="false"
  enable-device-change="false"
></vidtreo-recorder>

Programmatic Access

The web component exposes methods and properties that can be accessed via JavaScript for advanced use cases.

Getting the Component Instance

const recorder = document.querySelector('vidtreo-recorder');

Available Methods

Recording Control

• startRecording() - Start recording (returns Promise)
• stopRecording() - Stop recording and upload (returns Promise)
• pauseRecording() - Pause the current recording
• resumeRecording() - Resume a paused recording
• processVideo() - Process the recorded video (returns Promise)

Source Control

• toggleSource() - Switch between camera and screen (returns Promise)
• toggleMute() - Toggle mute/unmute state
• toggleSettings() - Show/hide device settings panel

Device Management

• handleCameraChange(deviceId: string) - Change camera device (returns Promise)
• handleMicChange(deviceId: string) - Change microphone device (returns Promise)

Video Playback

• playVideo() - Play the processed video in a new window
• downloadVideo() - Download the processed video

Initialization

• startCamera() - Start camera preview (returns Promise)

Example: Programmatic Control

<vidtreo-recorder
  id="my-recorder"
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
></vidtreo-recorder>

<button onclick="startRecording()">Start Recording</button>
<button onclick="stopRecording()">Stop Recording</button>
<button onclick="toggleMute()">Toggle Mute</button>

<script type="module">
  import './node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js';

  const recorder = document.getElementById('my-recorder');

  function startRecording() {
    recorder.startRecording().catch(error => {
      console.error('Failed to start recording:', error);
    });
  }

  function stopRecording() {
    recorder.stopRecording().catch(error => {
      console.error('Failed to stop recording:', error);
    });
  }

  function toggleMute() {
    recorder.toggleMute();
  }
</script>

Example: Dynamic Attribute Updates

<vidtreo-recorder
  id="my-recorder"
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
></vidtreo-recorder>

<script type="module">
  import './node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js';

  const recorder = document.getElementById('my-recorder');

  // Update API key dynamically
  recorder.setAttribute('api-key', 'new-api-key');

  // Update backend URL
  recorder.setAttribute('backend-url', 'https://custom-backend.com');

  // Enable countdown
  recorder.setAttribute('countdown-duration', '5000');

  // Add metadata
  recorder.setAttribute('user-metadata', JSON.stringify({
    userId: '12345',
    sessionId: 'abc123'
  }));
</script>

Example: Accessing Internal State

<vidtreo-recorder
  id="my-recorder"
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
></vidtreo-recorder>

<script type="module">
  import './node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js';

  const recorder = document.getElementById('my-recorder');

  // Access recorded blob
  const blob = recorder.getRecordedBlob();
  if (blob) {
    console.log('Recorded video size:', blob.size);
  }

  // Access processed blob
  const processedBlob = recorder.getProcessedBlob();
  if (processedBlob) {
    console.log('Processed video size:', processedBlob.size);
  }

  // Check mute state
  const isMuted = recorder.getIsMuted();
  console.log('Is muted:', isMuted);

  // Check if processing
  const isProcessing = recorder.getIsProcessing();
  console.log('Is processing:', isProcessing);
</script>

Advanced Examples

Custom Styling

The web component uses Shadow DOM, so styles are encapsulated. However, you can style the container:

<style>
  vidtreo-recorder {
    display: block;
    max-width: 800px;
    margin: 0 auto;
  }
</style>

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://api.vidtreo.com"
></vidtreo-recorder>

Integration with Form Submission

<form id="recording-form">
  <vidtreo-recorder
    id="recorder"
    api-key="your-api-key"
    backend-url="https://api.vidtreo.com"
  ></vidtreo-recorder>

  <button type="submit">Submit Recording</button>
</form>

<script type="module">
  import './node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js';

  const form = document.getElementById('recording-form');
  const recorder = document.getElementById('recorder');

  form.addEventListener('submit', async (e) => {
    e.preventDefault();

    const blob = recorder.getProcessedBlob();
    if (!blob) {
      alert('Please record and process a video first');
      return;
    }

    // Upload to your server
    const formData = new FormData();
    formData.append('video', blob, 'recording.mp4');

    await fetch('/api/upload', {
      method: 'POST',
      body: formData
    });
  });
</script>

Environment Variables (Vite)

For Vite projects, you can use environment variables:

# .env
VITE_VIDTREO_API_KEY=your-api-key
VITE_VIDTREO_BACKEND_URL=https://api.vidtreo.com

<script type="module">
  import './node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js';

  const recorder = document.querySelector('vidtreo-recorder');

  if (import.meta.env.VITE_VIDTREO_API_KEY) {
    recorder.setAttribute('api-key', import.meta.env.VITE_VIDTREO_API_KEY);
  }

  if (import.meta.env.VITE_VIDTREO_BACKEND_URL) {
    recorder.setAttribute('backend-url', import.meta.env.VITE_VIDTREO_BACKEND_URL);
  }
</script>

<vidtreo-recorder></vidtreo-recorder>

Package Structure

This package contains:

• dist/vidtreo-recorder.js - The web component JavaScript bundle (includes inlined CSS for Shadow DOM support)
• dist/vidtreo-recorder.d.ts - TypeScript declaration files

Note: CSS is inlined in the JavaScript bundle to support Shadow DOM encapsulation. No separate stylesheet file is needed.

The core SDK functionality is provided by the @vidtreo/recorder package, which is automatically installed as a peer dependency.

Why Separate Packages?

• Smaller SDK Package: Users who only need the programmatic SDK don't download web component files
• CDN Optimization: Web component users can use jsDelivr CDN for faster loading
• Clear Separation: Web component and SDK have independent versioning and distribution
• Framework Agnostic: Web components work with any framework or vanilla JavaScript

Browser Support

The web component requires modern browser features:

• Custom Elements API
• Shadow DOM
• MediaStream API
• ES2022 JavaScript features

Supported browsers:

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+

Internationalization (i18n)

The web 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

<!-- English (default) -->
<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://your-backend.com"
></vidtreo-recorder>

<!-- Spanish -->
<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://your-backend.com"
  lang="es"
></vidtreo-recorder>

Custom Text Overrides

Override any text by passing a JSON string to the texts attribute:

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://your-backend.com"
  lang="en"
  texts='{"record": "Start Recording", "stop": "End Recording"}'
></vidtreo-recorder>

Complete Custom Translations (e.g., French)

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://your-backend.com"
  lang="fr"
  texts='{
    "title": "Enregistreur Vidéo",
    "subtitle": "Enregistrez une vidéo depuis votre caméra",
    "initializingCamera": "Initialisation de la caméra...",
    "grantPermissions": "Accordez les autorisations",
    "record": "Enregistrer",
    "stop": "Arrêter",
    "pause": "Pause",
    "resume": "Reprendre",
    "settings": "Paramètres",
    "camera": "Caméra",
    "microphone": "Microphone"
  }'
></vidtreo-recorder>

Dynamic Language Change

Change the language dynamically using JavaScript:

const recorder = document.querySelector('vidtreo-recorder');

// Change to Spanish
recorder.setAttribute('lang', 'es');

// Override specific texts
recorder.setAttribute('texts', JSON.stringify({
  record: 'Iniciar Grabación',
  stop: 'Finalizar'
}));

Available Translation Keys

| Key | English Default | Spanish Default | |-----|----------------|-----------------| | title | Video Recorder | Grabador de Video | | subtitle | Record video from your camera and transcode it to MP4 format | Graba video desde tu cámara y transcodifícalo a formato MP4 | | 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 | | retryCamera | Retry Camera | Reintentar Cámara | | 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 | | processVideo | Process Video | Procesar Video | | processing | Processing... | Procesando... | | uploading | Uploading... | Subiendo... | | switchingCamera | Switching camera... | Cambiando cámara... | | switchingMicrophone | Switching microphone... | Cambiando micrófono... | | failedToStartCamera | Failed to start camera | Error al iniciar la cámara |

Multilingual Application Example

<select id="languageSelector">
  <option value="en">English</option>
  <option value="es">Español</option>
</select>

<vidtreo-recorder
  id="recorder"
  api-key="your-api-key"
  backend-url="https://your-backend.com"
  lang="en"
></vidtreo-recorder>

<script type="module">
  import './node_modules/@vidtreo/recorder-wc/dist/vidtreo-recorder.js';
  
  const recorder = document.getElementById('recorder');
  const languageSelector = document.getElementById('languageSelector');
  
  languageSelector.addEventListener('change', (e) => {
    recorder.setAttribute('lang', e.target.value);
  });
</script>

Partial Override Example

Use a base language but override specific texts:

<vidtreo-recorder
  api-key="your-api-key"
  backend-url="https://your-backend.com"
  lang="en"
  texts='{"record": "🔴 Start Capture", "stop": "⏹️ End Capture"}'
></vidtreo-recorder>

License

MIT