react-mse-player

React MSE Player

React components for low-latency video streaming via MSE and WebRTC. Designed for go2rtc.

Features

• MSEVideoStream — low-latency streaming over WebSocket using Media Source Extensions.
• WebRTCVideoStream — ultra-low-latency streaming via WebRTC with WebSocket signalling.
• Automatic reconnection with stall detection and smart backoff.
• Full TypeScript support with comprehensive type definitions.
• Smart buffering — internal queue and automatic memory trimming to prevent quota errors (MSE).
• Broad codec support — H.264, H.265 (HEVC), AAC, FLAC, Opus negotiated automatically.
• ManagedMediaSource — iOS 17+ support (MSE).
• TCP-only ICE — optional restriction for WebRTC in firewall-heavy environments.
• Translatable UI — override all user-facing strings via the labels prop.

Installation

npm install react-mse-player
# or
yarn add react-mse-player

Usage

MSE

import { MSEVideoStream } from 'react-mse-player';

<MSEVideoStream src="ws://localhost:1984/api/ws?src=camera1" />

WebRTC

import { WebRTCVideoStream } from 'react-mse-player';

<WebRTCVideoStream src="ws://localhost:1984/api/ws?src=camera1" />

Both components accept a ws:// or wss:// URL. HTTP/HTTPS URLs are converted automatically. Relative paths (/api/ws?src=...) are also supported.

Choosing between MSE and WebRTC

	MSE	WebRTC
Latency	~1–3 s	< 500 ms
Safari iOS	17+ only	11+
Firewall-friendly	Yes (WS)	Needs STUN/TURN
Audio/Video sync	Good	Excellent

Use WebRTC when latency matters most. Use MSE as a fallback for broader compatibility.

Advanced example

import { WebRTCVideoStream, MSEVideoStream } from 'react-mse-player';

// WebRTC with custom ICE servers and TCP-only mode
<WebRTCVideoStream
  src="ws://localhost:1984/api/ws?src=camera1"
  mode="webrtc/tcp"
  pcConfig={{
    iceServers: [{ urls: 'turn:my-turn-server.com', username: 'user', credential: 'pass' }],
  }}
  media="video,audio"
  onStatus={(s) => console.log(s)}
  onError={(e) => console.error(e)}
  debug
/>

// MSE with stall detection timeout
<MSEVideoStream
  src="ws://localhost:1984/api/ws?src=camera1"
  dataTimeout={5000}
  media="video,audio"
  onStatus={(s) => console.log(s)}
  onError={(e) => console.error(e)}
  debug
/>

Props

Shared props (both components)

Prop	Type	Default	Description
src	string	Required	WebSocket URL (ws://, wss://, relative / path, or http(s):// auto-converted).
width	string | number	'100%'	Container width.
height	string | number	'100%'	Container height.
autoPlay	boolean	true	Start playback automatically.
controls	boolean	false	Show native video controls.
media	string	'video,audio'	Requested tracks: 'video', 'audio', or 'video,audio'.
objectFit	string	'contain'	CSS object-fit for the video element.
onStatus	(status: string) => void	—	Status change callback.
onError	(error: any) => void	—	Error callback.
className	string	''	CSS class for the container.
style	CSSProperties	{}	Inline styles for the container.
labels	VideoLabels	see below	Override user-facing strings (for translation).
debug	boolean	false	Log connection events to the console.

MSEVideoStream-only props

Prop	Type	Default	Description
dataTimeout	number	10000	Milliseconds without data before triggering a reconnect.

WebRTCVideoStream-only props

Prop	Type	Default	Description
mode	'webrtc' | 'webrtc/tcp'	'webrtc'	Use 'webrtc/tcp' to restrict ICE candidates to TCP only.
pcConfig	RTCConfiguration	Cloudflare + Google STUN	Override ICE servers or bundle policy.

VideoLabels

All fields are optional — omit any key to keep the English default.

Key	Default
streamNotFound	"Stream not found"
connectionFailed	"Connection failed"
reconnecting	"Reconnecting..."

import type { VideoLabels } from 'react-mse-player';

const labels: VideoLabels = {
  streamNotFound: "Flux introuvable",
  connectionFailed: "Connexion échouée",
  reconnecting: "Reconnexion...",
};

<WebRTCVideoStream src={url} labels={labels} />

Status values

Status	Description
connecting	Opening the WebSocket connection.
open	WebSocket connected, negotiating stream.
streaming	(MSE) Data flowing, buffer active.
connected	(WebRTC) Peer connection established.
reconnecting	Connection lost, waiting to retry.
closed	Connection closed.
error	Unrecoverable error.

Browser Support

Browser	MSE	WebRTC
Chrome / Edge / Brave	✅	✅
Firefox	✅	✅
Safari 17+	✅ (ManagedMediaSource)	✅
Safari < 17	❌	✅ (11+)
Android (Chrome)	✅	✅
iOS Safari 17.1+	✅	✅
iOS Safari < 17	❌	✅

License

MIT