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