React WebRTC Viewer

A React component for WebRTC live streaming with WHEP (WebRTC-HTTP Egress Protocol) support, featuring built-in zoom/pan functionality and customizable UI components.

Installation

npm install react-webrtc-viewer

Dependencies

This package requires the following peer dependencies:

npm install react react-dom video.js whip-whep

Basic Usage

import WhepPlayer from "react-webrtc-viewer";

function App() {
  return (
    <WhepPlayer
      url="https://example.com/live/stream/whep"
      onReady={(player) => console.log("Player ready:", player)}
      onError={(error) => console.error("Stream error:", error)}
    />
  );
}

Features

• WebRTC WHEP streaming with automatic error handling and reconnection
• Zoom and Pan functionality for interactive video viewing
• Customizable UI components for loading, error, and reconnecting states
• Event callbacks for stream lifecycle management
• TypeScript support with full type definitions

Props

Basic Props

| Prop | Type | Default | Description | | ----------- | -------- | ------------ | ------------------------- | | url | string | required | WHEP stream URL | | options | object | {} | Video.js player options | | className | string | "" | Additional CSS class name |

Event Callbacks

| Prop | Type | Description | | ---------------------- | ------------------ | ------------------------------ | | onReady | (player) => void | Called when player is ready | | onError | (error) => void | Called on general errors | | onStreamNotFound | (event) => void | Called when stream returns 404 | | onStreamRecovered | (event) => void | Called when stream recovers | | onStreamConnected | (event) => void | Called when stream connects | | onStreamDisconnected | (event) => void | Called when stream disconnects | | onForbidden | (event) => void | Called on 403 errors | | onServerError | (event) => void | Called on 500 errors |

Zoom/Pan Props

| Prop | Type | Default | Description | | --------------- | --------- | ------- | --------------------------------- | | enableZoomPan | boolean | false | Enable zoom and pan functionality | | maxZoom | number | 10 | Maximum zoom level | | zoomStep | number | 0.05 | Zoom step per scroll |

Custom UI Props

| Prop | Type | Description | | -------------------- | ----------------------------------- | ---------------------------------------- | | renderLoading | () => ReactNode | Custom loading spinner component | | renderError | ({ error, onRetry }) => ReactNode | Custom error display component | | renderReconnecting | () => ReactNode | Custom reconnecting display component | | customSpinnerCSS | string | Custom CSS for Video.js internal spinner | | messages | object | Custom messages for internationalization |

Advanced Usage

With Zoom/Pan

<WhepPlayer
  url="https://example.com/live/stream/whep"
  enableZoomPan={true}
  maxZoom={5}
  zoomStep={0.1}
  onReady={(player) => console.log("Player ready")}
/>

With Custom UI Components

<WhepPlayer
  url="https://example.com/live/stream/whep"
  renderLoading={() => <div>Custom loading...</div>}
  renderError={({ error, onRetry }) => (
    <div>
      <h3>Oops! {error}</h3>
      <button onClick={onRetry}>Try Again</button>
    </div>
  )}
  renderReconnecting={() => <div>Reconnecting to stream...</div>}
/>

With Custom Video.js Spinner

Customize the internal Video.js loading spinner:

<WhepPlayer
  url="https://example.com/live/stream/whep"
  customSpinnerCSS={`
    .video-js .vjs-custom-spinner::after {
      border: 6px solid #f3f3f3;
      border-top: 6px solid #ff6b6b;
      width: 60px;
      height: 60px;
      animation: vjs-spin 1s linear infinite;
    }
    
    .video-js .vjs-custom-spinner {
      width: 60px;
      height: 60px;
    }
    
    @keyframes vjs-pulse {
      0% { opacity: 1; }
      50% { opacity: 0.5; }
      100% { opacity: 1; }
    }
    
    /* Add pulsing effect */
    .video-js .vjs-custom-spinner::before {
      content: '📺';
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
      font-size: 20px;
      animation: vjs-pulse 1.5s ease-in-out infinite;
    }
  `}
/>

With Internationalization (i18n)

Customize all text messages for different languages:

// English (default)
const englishMessages = {
  loading: "Loading stream...",
  reconnecting: "Reconnecting...",
  streamError: "Stream Error",
  retry: "Retry",
  accessForbidden: "Stream access forbidden (403)",
  serverError: "Server error (500)",
  whepUrlRequired: "WHEP URL is required",
  failedToInitialize: "Failed to initialize WHEP stream",
};

// Spanish
const spanishMessages = {
  loading: "Cargando transmisión...",
  reconnecting: "Reconectando...",
  streamError: "Error de Transmisión",
  retry: "Reintentar",
  accessForbidden: "Acceso a la transmisión prohibido (403)",
  serverError: "Error del servidor (500)",
  whepUrlRequired: "Se requiere URL WHEP",
  failedToInitialize: "Error al inicializar transmisión WHEP",
};

// French
const frenchMessages = {
  loading: "Chargement du flux...",
  reconnecting: "Reconnexion...",
  streamError: "Erreur de Flux",
  retry: "Réessayer",
  accessForbidden: "Accès au flux interdit (403)",
  serverError: "Erreur du serveur (500)",
  whepUrlRequired: "URL WHEP requise",
  failedToInitialize: "Échec de l'initialisation du flux WHEP",
};

function App() {
  return (
    <WhepPlayer
      url="https://example.com/live/stream/whep"
      messages={spanishMessages}
    />
  );
}

Integration with i18n Libraries

import { useTranslation } from "react-i18next";
import WhepPlayer from "react-webrtc-viewer";

function I18nPlayer() {
  const { t } = useTranslation();

  const messages = {
    loading: t("player.loading"),
    reconnecting: t("player.reconnecting"),
    streamError: t("player.streamError"),
    retry: t("player.retry"),
    accessForbidden: t("player.accessForbidden"),
    serverError: t("player.serverError"),
  };

  return (
    <WhepPlayer url="http://localhost/live/stream1/whep" messages={messages} />
  );
}

Dynamic Language Switching

import { useState } from "react";
import WhepPlayer from "react-webrtc-viewer";

const translations = {
  en: {
    loading: "Loading stream...",
    reconnecting: "Reconnecting...",
    streamError: "Stream Error",
    retry: "Retry",
  },
  es: {
    loading: "Cargando transmisión...",
    reconnecting: "Reconectando...",
    streamError: "Error de Transmisión",
    retry: "Reintentar",
  },
  fr: {
    loading: "Chargement du flux...",
    reconnecting: "Reconnexion...",
    streamError: "Erreur de Flux",
    retry: "Réessayer",
  },
};

function MultiLanguagePlayer() {
  const [language, setLanguage] = useState("en");

  return (
    <div>
      <select
        value={language}
        onChange={(e) => setLanguage(e.target.value)}
        style={{ marginBottom: "10px" }}
      >
        <option value="en">English</option>
        <option value="es">Español</option>
        <option value="fr">Français</option>
      </select>

      <WhepPlayer
        url="https://example.com/live/stream/whep"
        messages={translations[language]}
      />
    </div>
  );
}

RTL Language Support

const arabicMessages = {
  loading: "جاري تحميل البث...",
  reconnecting: "إعادة الاتصال...",
  streamError: "خطأ في البث",
  retry: "إعادة المحاولة",
  accessForbidden: "الوصول للبث محظور (403)",
  serverError: "خطأ في الخادم (500)",
};

function ArabicPlayer() {
  return (
    <div dir="rtl">
      <WhepPlayer
        url="http://localhost/live/stream1/whep"
        messages={arabicMessages}
        className="rtl-player"
      />
    </div>
  );
}

Full Event Handling

<WhepPlayer
  url="https://example.com/live/stream/whep"
  onStreamConnected={() => console.log("Stream started")}
  onStreamNotFound={() => console.log("Stream not available")}
  onStreamRecovered={() => console.log("Stream is back online")}
  onStreamDisconnected={() => console.log("Stream disconnected")}
  onForbidden={() => console.log("Access denied")}
  onServerError={() => console.log("Server error")}
/>

Available Message Keys

For internationalization, you can customize the following message keys:

| Key | Default Value | Description | | -------------------- | ---------------------------------- | -------------------------- | | loading | "Loading stream..." | Loading spinner text | | reconnecting | "Reconnecting..." | Reconnecting state text | | streamError | "Stream Error" | Error dialog title | | retry | "Retry" | Retry button text | | accessForbidden | "Stream access forbidden (403)" | 403 error message | | serverError | "Server error (500)" | 500 error message | | whepUrlRequired | "WHEP URL is required" | Missing URL error | | failedToInitialize | "Failed to initialize WHEP stream" | Initialization error | | videoPlayerError | "Video player error" | General player error | | connectionLost | "Connection lost" | Connection failure message |

Default Components

The library exports default components that you can use independently:

import { DefaultLoadingSpinner, DefaultErrorDisplay } from 'react-webrtc-viewer';

// Use the default components in your own layouts
<DefaultLoadingSpinner message="Please wait..." />
<DefaultErrorDisplay
  error="Connection failed"
  onRetry={() => window.location.reload()}
/>

License

MIT