Red5 Conference SDK — Multi-Party Video Conferencing

Build multi-party video conferencing with the Red5 Conference SDK. Covers room join flow, media controls, virtual backgrounds, local recording, and chat.

The Red5 Pro Conference SDK is a JavaScript toolkit for building multi-party video conferencing applications on Red5 Cloud and Red5 Pro. It manages room lifecycle, WHIP/WHEP media publishing and subscribing, WebRTC statistics monitoring, and interactive features including virtual backgrounds, local recording, screen sharing, and PubNub-powered chat — all from a single ConferenceClient object.

Installation

npm install red5pro-conference-sdk

Key concepts

• Room — a named session identified by a roomId. Multiple users join the same room to exchange audio and video.
• Participant — a user in the room, identified by a userId. Each participant can publish audio/video (role: publisher) or receive only (role: subscriber).
• Media tracks — participants publish their local MediaStream via WHIP, and subscribe to each other’s streams via WHEP. You receive a MediaStream for each subscribed participant to attach to a <video> element.

Joining a room

1. Create a ConferenceClient

   Pass your server details and optional PubNub keys for chat.

   import { ConferenceClient, ConferenceEvents } from 'red5pro-conference-sdk';
   
   const client = new ConferenceClient({
     host: 'your-red5-pro-host',
     nodeGroup: 'your-node-group',
     iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
     pubnubPublishKey: 'your-pubnub-publish-key',
     pubnubSubscribeKey: 'your-pubnub-subscribe-key',
   });
   
2. Subscribe to new participants

   Listen for NEW_PARTICIPANT and subscribe automatically so you receive their video as soon as they join.

   client.addEventListener(ConferenceEvents.NEW_PARTICIPANT, async (e) => {
     const user = e.detail;
     try {
       const info = await client.subscribe(user);
       if (info?.mediaStream) {
         const videoEl = document.createElement('video');
         videoEl.srcObject = info.mediaStream;
         videoEl.autoplay = true;
         document.getElementById('participants').appendChild(videoEl);
       }
     } catch (err) {
       console.error('Subscribe failed', err);
     }
   });
   
3. Acquire local media and join

   const localStream = await navigator.mediaDevices.getUserMedia({
     video: true,
     audio: true,
   });
   
   await client.join(
     'my-room-id',   // roomId
     'user-123',     // userId
     'auth-token',   // token from your backend
     'publisher',    // role: 'publisher' or 'subscriber'
     localStream,    // MediaStream
     true,           // videoEnabled
     true            // audioEnabled
   );
   
   console.log('Joined room successfully');
   
4. Leave the room

   await client.leave();
   

Media controls

Mute and unmute your local audio and video without leaving the room.

// Mute/unmute audio
await client.muteAudio();
await client.unmuteAudio();

// Mute/unmute video
await client.muteVideo();
await client.unmuteVideo();

// Listen for state changes
client.addEventListener(ConferenceEvents.AUDIO_MUTED, () => {
  console.log('Audio is muted');
});

Switch device without dropping the connection:

// Switch to a different camera
await client.switchVideoDeviceWithTrackReplacement(newCameraDeviceId);

// Switch to a different microphone
await client.switchAudioDeviceWithTrackReplacement(newMicDeviceId);

Screen sharing

// Start sharing your screen
await client.startScreenShare({
  includeAudio: true,
  metaData: { type: 'presentation' },
});

// Stop sharing
await client.stopScreenShare();

Virtual backgrounds

Virtual backgrounds use @mediapipe/selfie_segmentation to replace or blur the area behind your camera feed.

1. Initialize the background processor

   await client.initializeVirtualBackground();
   
2. Apply a background

   // Blur background
   await client.enableVirtualBackground('blur', { blurAmount: 10 });
   
   // Image replacement
   await client.enableVirtualBackground('image', {
     imageUrl: 'path/to/background.jpg',
   });
   
3. Remove the background

   await client.disableVirtualBackground();
   

Available background types:

Type	Description
VirtualBackgroundTypes.NONE	No background processing
VirtualBackgroundTypes.BLUR	Strong blur
VirtualBackgroundTypes.SLIGHT_BLUR	Light blur
VirtualBackgroundTypes.IMAGE	Image replacement
VirtualBackgroundTypes.COLOR	Solid color replacement

Local recording

Record participant streams directly in the browser. The recording is stored locally and downloaded as a ZIP file.

// Download the local recording
await client.downloadLocalRecording('my-conference-2026-05-21');

// Or get a ZIP blob to handle yourself
const zipBlob = await client.generateLocalRecordingZip();

Chat

Send and receive text messages within the room using PubNub. Pass your PubNub keys in the ConferenceClient config.

// Listen for incoming messages
client.addEventListener(ConferenceEvents.CHAT_MESSAGE, (e) => {
  const message = e.detail;
  console.log('New message:', message.text);
});

// Send a message
client.sendChatMessage('Hello everyone!');

Configuration reference

Property	Type	Default	Description
host	string	Required	Red5 Pro server address
nodeGroup	string	undefined	Target node group for scaling
iceServers	RTCIceServer[]	undefined	STUN/TURN server configurations
reconnectionEnabled	boolean	false	Enable automatic reconnection
maxVideoBitrateKbps	number	undefined	Maximum video bitrate for publishing
statsPollingInterval	number	undefined	WebRTC stats polling interval in ms
pubnubPublishKey	string	undefined	PubNub key for chat
pubnubSubscribeKey	string	undefined	PubNub key for chat
enableNoiseCancellation	boolean	false	Enable RNNoise noise suppression

API reference highlights

Room management

Method	Returns	Description
join(roomId, userId, token, role, mediaStream, videoEnabled, audioEnabled)	Promise<boolean>	Join a conference room
leave()	Promise<void>	Leave the conference room
getRoomUsers()	Object	Get all current room users
getIsJoined()	boolean	true if currently in a room
getIsPublishing()	boolean	true if currently publishing

Subscribing

Method	Returns	Description
subscribe(user: User)	Promise<{ subscriber, user, mediaStream }>	Subscribe to a participant’s stream
unsubscribe(userId: string)	Promise<void>	Stop subscribing to a participant

Events

Event	Description
USER_PUBLISHED	Local client published successfully
NEW_PARTICIPANT	A new participant joined the room
PARTICIPANT_DISCONNECTED	A participant left the room
SUBSCRIBE_SUCCESS	Successfully subscribed to a participant
ROOM_STATE_UPDATE	Room users, roles, or states changed
CHAT_MESSAGE	A chat message was received
ISSUES_DETECTED	Network or WebRTC issues detected
VIDEO_MUTED / AUDIO_MUTED	Video or audio muted successfully

Use the Backend SDK to generate the token parameter you pass to client.join(). This keeps your master credentials on the server and gives you control over user roles and token expiration.