Callbacks

VIDTREO provides callbacks to handle recording events, upload progress, and errors. This enables you to build responsive UIs and integrate with your application logic.

Recording Lifecycle

onRecordingStart

Fired when recording begins (after countdown completes).

<VidtreoRecorder
  onRecordingStart={() => {
    console.log('Recording started');
    setIsRecording(true);
    // Hide other UI elements
    // Start a timer
    // Log analytics event
  }}
/>

onRecordingStop

Fired when recording ends (before upload begins).

<VidtreoRecorder
  onRecordingStop={() => {
    console.log('Recording stopped');
    setIsRecording(false);
    setIsProcessing(true);
    // Show processing indicator
  }}
/>

Upload Events

onUploadProgress

Fired periodically during upload with progress value (0-1).

<VidtreoRecorder
  onUploadProgress={(progress) => {
    // progress is between 0 and 1
    const percent = Math.round(progress * 100);
    console.log(`Upload progress: ${percent}%`);
    setUploadProgress(percent);
  }}
/>

Progress Bar Example:

function Recorder() {
  const [progress, setProgress] = useState(0);
  const [isUploading, setIsUploading] = useState(false);

  return (
    <>
      <VidtreoRecorder
        onRecordingStop={() => setIsUploading(true)}
        onUploadProgress={(p) => setProgress(Math.round(p * 100))}
        onUploadComplete={() => setIsUploading(false)}
      />

      {isUploading && (
        <div className="progress-bar">
          <div
            className="progress-fill"
            style={{ width: `${progress}%` }}
          />
          <span>{progress}%</span>
        </div>
      )}
    </>
  );
}

onUploadComplete

Fired when upload completes successfully.

<VidtreoRecorder
  onUploadComplete={(result) => {
    console.log('Video URL:', result.uploadUrl);
    console.log('Recording ID:', result.recordingId);

    // Save to your database
    saveVideoToDatabase({
      url: result.uploadUrl,
      id: result.recordingId
    });

    // Show success message
    showNotification('Video uploaded successfully!');

    // Navigate to video page
    router.push(`/videos/${result.recordingId}`);
  }}
/>

Result Object:

interface UploadCompleteResult {
  uploadUrl: string;    // Direct URL to the video file
  recordingId: string;  // Unique identifier for the recording
}

onUploadError

Fired when upload fails.

<VidtreoRecorder
  onUploadError={(error) => {
    console.error('Upload failed:', error.message);

    // Show error to user
    showNotification('Upload failed. Please try again.', 'error');

    // Log to error tracking service
    errorTracker.capture(error);

    // Offer retry option
    setShowRetryButton(true);
  }}
/>

Error Handling

onError

Fired for any error during the recording process.

<VidtreoRecorder
  onError={(error) => {
    console.error('Recorder error:', error);

    // Handle specific error types
    if (error.message.includes('permission')) {
      showNotification('Please allow camera access');
    } else if (error.message.includes('NotSupported')) {
      showNotification('Your browser does not support recording');
    } else {
      showNotification('An error occurred');
    }
  }}
/>

Common Errors:

Error	Cause	Solution
`NotAllowedError`	User denied camera/mic permission	Prompt user to allow access
`NotFoundError`	No camera or microphone found	Check device connections
`NotSupportedError`	Browser doesn't support WebCodecs	Use a supported browser
`OverconstrainedError`	Requested constraints not satisfiable	Use default constraints
`Upload failed`	Network error during upload	Retry with exponential backoff

Complete Example

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

function VideoRecorderWithCallbacks() {
  const [status, setStatus] = useState<'idle' | 'recording' | 'uploading' | 'complete' | 'error'>('idle');
  const [progress, setProgress] = useState(0);
  const [videoUrl, setVideoUrl] = useState<string | null>(null);
  const [error, setError] = useState<string | null>(null);

  return (
    <div className="recorder-container">
      <VidtreoRecorder
        apiKey={import.meta.env.VITE_VIDTREO_API_KEY}
        onRecordingStart={() => {
          setStatus('recording');
          setError(null);
        }}
        onRecordingStop={() => {
          setStatus('uploading');
        }}
        onUploadProgress={(p) => {
          setProgress(Math.round(p * 100));
        }}
        onUploadComplete={(result) => {
          setStatus('complete');
          setVideoUrl(result.uploadUrl);
          setProgress(0);
        }}
        onUploadError={(err) => {
          setStatus('error');
          setError(`Upload failed: ${err.message}`);
        }}
        onError={(err) => {
          setStatus('error');
          setError(err.message);
        }}
      />

      {/* Status indicator */}
      <div className="status">
        {status === 'idle' && <span>Ready to record</span>}
        {status === 'recording' && <span className="recording">● Recording</span>}
        {status === 'uploading' && <span>Uploading: {progress}%</span>}
        {status === 'complete' && <span className="success">✓ Complete</span>}
        {status === 'error' && <span className="error">✗ {error}</span>}
      </div>

      {/* Video result */}
      {videoUrl && (
        <div className="result">
          <video src={videoUrl} controls />
          <a href={videoUrl} download>Download Video</a>
        </div>
      )}
    </div>
  );
}

Web Component Events

For Web Components, use addEventListener:

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

recorder.addEventListener('recording-start', () => {
  console.log('Recording started');
});

recorder.addEventListener('recording-stop', () => {
  console.log('Recording stopped');
});

recorder.addEventListener('upload-progress', (e) => {
  console.log('Progress:', e.detail.progress);
});

recorder.addEventListener('upload-complete', (e) => {
  console.log('URL:', e.detail.uploadUrl);
});

recorder.addEventListener('upload-error', (e) => {
  console.log('Error:', e.detail.error);
});

recorder.addEventListener('error', (e) => {
  console.log('Error:', e.detail.error);
});

Hook Callbacks

When using useVidtreoRecorder, pass callbacks to the config:

const { state, actions } = useVidtreoRecorder({
  apiKey: '...',
  onRecordingStart: () => console.log('Started'),
  onRecordingStop: () => console.log('Stopped'),
  onUploadProgress: (p) => console.log(`${p * 100}%`),
  onUploadComplete: (result) => console.log(result.uploadUrl),
  onUploadError: (error) => console.error(error),
  onError: (error) => console.error(error),
});

Callbacks are optional. The SDK handles all recording and upload logic automatically. Use callbacks to update your UI or integrate with your application.

Next Steps

Configuration Options — All settings
Customization — Styling
Examples — Working examples

Callbacks

On this page