Construye experiencias de grabación de video personalizadas con el Core SDK de VIDTREO.

JavaScript Vanilla

El paquete @vidtreo/recorder proporciona el Core SDK para construir experiencias de grabación de video completamente personalizadas.

Instalación

npm install @vidtreo/recorder

Uso Básico

import { VidtreoRecorder } from '@vidtreo/recorder';

// Inicializar el grabador
const recorder = new VidtreoRecorder({
  apiKey: 'tu-api-key',
  onUploadComplete: (result) => {
    console.log('URL del Video:', result.uploadUrl);
  },
  onError: (error) => {
    console.error('Error:', error);
  }
});

// Inicializar y comenzar preview
await recorder.initialize();
const stream = await recorder.startPreview();

// Conectar al elemento video
const video = document.querySelector('video');
video.srcObject = stream;

// Iniciar grabación
await recorder.startRecording();

// Detener y subir
const result = await recorder.stopRecording();
console.log('Grabación completa:', result);

Opciones de Configuración

interface VidtreoRecorderConfig {
  // Requerido
  apiKey: string;

  // Opcional
  apiUrl?: string;                        // Por defecto: 'https://core.vidtreo.com'
  enableSourceSwitching?: boolean;        // Por defecto: true
  enableMute?: boolean;                   // Por defecto: true
  enablePause?: boolean;                  // Por defecto: true
  enableDeviceChange?: boolean;           // Por defecto: true
  maxRecordingTime?: number;              // Duración máxima en ms
  countdownDuration?: number;             // Cuenta regresiva en ms
  userMetadata?: Record<string, unknown>; // Metadatos personalizados
  enableTabVisibilityOverlay?: boolean;   // Mostrar overlay al ocultar pestaña
  tabVisibilityOverlayText?: string;      // Texto del overlay personalizado

  // Callbacks
  onUploadComplete?: (result: UploadResult) => void;
  onUploadProgress?: (progress: number) => void;
  onUploadError?: (error: Error) => void;
  onRecordingStart?: () => void;
  onRecordingStop?: () => void;
  onError?: (error: Error) => void;
}

Métodos Principales

Inicialización

// Inicializar el grabador
await recorder.initialize();

Preview

// Iniciar preview de cámara
const stream = await recorder.startPreview('camera');

// Iniciar preview de pantalla
const stream = await recorder.startPreview('screen');

Grabación

// Iniciar grabación con opciones
await recorder.startRecording({
  video: {
    width: 1920,
    height: 1080,
    frameRate: 30
  },
  audio: true
}, 'camera'); // o 'screen'

// Detener grabación
const result = await recorder.stopRecording();
// result: { recordingId, uploadUrl, blob }

Control de Audio

// Silenciar audio
recorder.muteAudio();

// Activar audio
recorder.unmuteAudio();

// Alternar silencio
recorder.toggleMute();

// Verificar estado de silencio
const isMuted = recorder.isMuted();

Pausar/Reanudar

// Pausar grabación
recorder.pauseRecording();

// Reanudar grabación
recorder.resumeRecording();

// Verificar estado de pausa
const isPaused = recorder.isPaused();

Cambio de Fuente

// Cambiar a grabación de pantalla
await recorder.switchSource('screen');

// Volver a cámara
await recorder.switchSource('camera');

Gestión de Dispositivos

// Obtener dispositivos disponibles
const devices = await recorder.getAvailableDevices();
// devices: { video: MediaDeviceInfo[], audio: MediaDeviceInfo[] }

Estado

// Obtener estado actual de grabación
const state = recorder.getRecordingState();
// state: 'idle' | 'countdown' | 'recording'

// Obtener stream actual
const stream = recorder.getStream();

Limpieza

// Limpiar recursos
recorder.cleanup();

Ejemplo Completo

import { VidtreoRecorder } from '@vidtreo/recorder';

class VideoRecorderApp {
  private recorder: VidtreoRecorder;
  private videoElement: HTMLVideoElement;
  private recordButton: HTMLButtonElement;
  private stopButton: HTMLButtonElement;
  private muteButton: HTMLButtonElement;

  constructor() {
    this.videoElement = document.getElementById('preview') as HTMLVideoElement;
    this.recordButton = document.getElementById('record') as HTMLButtonElement;
    this.stopButton = document.getElementById('stop') as HTMLButtonElement;
    this.muteButton = document.getElementById('mute') as HTMLButtonElement;

    this.recorder = new VidtreoRecorder({
      apiKey: 'tu-api-key',
      maxRecordingTime: 300000, // 5 minutos
      countdownDuration: 3000,
      userMetadata: {
        userId: 'user-123'
      },
      onRecordingStart: () => {
        this.updateUI('recording');
      },
      onRecordingStop: () => {
        this.updateUI('processing');
      },
      onUploadProgress: (progress) => {
        this.showProgress(progress);
      },
      onUploadComplete: (result) => {
        this.showResult(result);
      },
      onError: (error) => {
        this.showError(error);
      }
    });

    this.bindEvents();
    this.init();
  }

  async init() {
    await this.recorder.initialize();
    const stream = await this.recorder.startPreview();
    this.videoElement.srcObject = stream;
    this.updateUI('ready');
  }

  bindEvents() {
    this.recordButton.addEventListener('click', () => this.startRecording());
    this.stopButton.addEventListener('click', () => this.stopRecording());
    this.muteButton.addEventListener('click', () => this.toggleMute());
  }

  async startRecording() {
    await this.recorder.startRecording();
  }

  async stopRecording() {
    await this.recorder.stopRecording();
  }

  toggleMute() {
    this.recorder.toggleMute();
    this.muteButton.textContent = this.recorder.isMuted() ? 'Activar Audio' : 'Silenciar';
  }

  updateUI(state: string) {
    // Actualizar UI basado en estado
    this.recordButton.disabled = state !== 'ready';
    this.stopButton.disabled = state !== 'recording';
  }

  showProgress(progress: number) {
    console.log(`Subida: ${Math.round(progress * 100)}%`);
  }

  showResult(result: { uploadUrl: string; recordingId: string }) {
    console.log('Video listo:', result.uploadUrl);
  }

  showError(error: Error) {
    console.error('Error:', error);
  }
}

// Inicializar cuando el DOM esté listo
document.addEventListener('DOMContentLoaded', () => {
  new VideoRecorderApp();
});

Plantilla HTML

<!DOCTYPE html>
<html>
<head>
  <title>Grabador de Video</title>
  <style>
    .recorder {
      max-width: 640px;
      margin: 0 auto;
    }
    video {
      width: 100%;
      background: #000;
      border-radius: 8px;
    }
    .controls {
      margin-top: 1rem;
      display: flex;
      gap: 0.5rem;
    }
    button {
      padding: 0.5rem 1rem;
      border-radius: 4px;
      border: none;
      cursor: pointer;
    }
    button:disabled {
      opacity: 0.5;
      cursor: not-allowed;
    }
  </style>
</head>
<body>
  <div class="recorder">
    <video id="preview" autoplay muted playsinline></video>
    <div class="controls">
      <button id="record">Grabar</button>
      <button id="stop" disabled>Detener</button>
      <button id="mute">Silenciar</button>
    </div>
  </div>

  <script type="module" src="./recorder.ts"></script>
</body>
</html>

Avanzado: Usando Módulos Individuales

Para máximo control, importa módulos individuales:

import {
  RecorderController,
  DeviceManager,
  AudioLevelAnalyzer,
  UploadService,
  StorageManager,
  VideoTranscoder
} from '@vidtreo/recorder';

// Gestión de dispositivos
const deviceManager = new DeviceManager();
const devices = await deviceManager.enumerateDevices();

// Visualización de audio
const analyzer = new AudioLevelAnalyzer(audioTrack);
analyzer.start((level) => {
  // level: 0-1
  updateAudioMeter(level);
});

// Transcodificación manual
const transcoder = new VideoTranscoder();
const mp4Blob = await transcoder.transcode(webmBlob, {
  format: 'mp4',
  fps: 30,
  width: 1920,
  height: 1080
});

// Subida personalizada
const uploadService = new UploadService({
  apiKey: 'tu-api-key',
  apiUrl: 'https://core.vidtreo.com'
});
const result = await uploadService.upload(mp4Blob, {
  onProgress: (progress) => console.log(progress)
});

Definiciones de Tipos

// Estados de grabación
type RecordingState = 'idle' | 'countdown' | 'recording';
type SourceType = 'camera' | 'screen';

// Resultado de grabación
interface RecordingStopResult {
  recordingId: string;
  uploadUrl: string;
  blob: Blob;
}

// Info de dispositivos
interface AvailableDevices {
  video: MediaDeviceInfo[];
  audio: MediaDeviceInfo[];
}

// Opciones de grabación
interface RecordingStartOptions {
  video?: {
    width?: number;
    height?: number;
    frameRate?: number;
  };
  audio?: boolean | MediaTrackConstraints;
}

El Core SDK es la base para los paquetes de React y Web Component. Todas las características disponibles en los paquetes wrapper están construidas sobre estas APIs.

Próximos Pasos

Referencia de API — Documentación completa de la API
Referencia de Tipos — Todos los tipos de TypeScript
Ejemplo de UI Personalizada — Construye interfaces personalizadas

JavaScript Puro