` object with optional `component` and `render` fields. You can fully replace the default implementation or wrap it while forwarding props.
#### Layout & control surfaces
| Key | Default component | Typical use |
| --- | --- | --- |
| `mainContainer` | `MainContainerComponent` | Inject theming providers or dashboard layouts. |
| `mainAspect` | `MainAspectComponent` | Tune how the main region splits space. |
| `mainScreen` | `MainScreenComponent` | Orchestrate hero video + gallery interplay. |
| `mainGrid` | `MainGridComponent` | Modify layout or layering of primary participants. |
| `subAspect` | `SubAspectComponent` | Restyle fixed control strips in webinar/conference modes. |
| `otherGrid` | `OtherGridComponent` | Change presentation of off-stage attendees. |
| `flexibleGrid`, `flexibleGridAlt` | `FlexibleGrid` | Implement AI-driven or branded array layouts. |
| `flexibleVideo` | `FlexibleVideo` | Add captions, watermarks, or overlays to highlighted speakers. |
| `audioGrid` | `AudioGrid` | Customise audio-only attendee presentation. |
| `pagination` | `Pagination` | Introduce infinite scroll or auto-cycling carousels. |
| `controlButtons` | `ControlButtonsComponent` | Rebrand the primary action bar. |
| `controlButtonsAlt` | `ControlButtonsAltComponent` | Control secondary button clusters. |
| `controlButtonsTouch` | `ControlButtonsComponentTouch` | Deliver mobile-first controls (used heavily by `MediasfuChat`). |
#### Participant cards & widgets
| Key | Default component | Typical use |
| --- | --- | --- |
| `videoCard` | `VideoCard` | Add host badges, reactions, or CRM overlays. |
| `audioCard` | `AudioCard` | Swap avatars or expose spoken-language info. |
| `miniCard` | `MiniCard` | Customize thumbnails in picture-in-picture modes. |
| `miniAudio` | `MiniAudio` | Re-style the audio-only mini indicators. |
| `meetingProgressTimer` | `MeetingProgressTimer` | Replace the elapsed-time widget with countdowns or milestones. |
| `miniAudioPlayer` | `MiniAudioPlayer` | Provide alternative UI for recorded clip playback. |
#### Modals, dialogs, and collaboration surfaces
| Key | Default component | Typical use |
| --- | --- | --- |
| `loadingModal` | `LoadingModal` | Show branded skeletons while connecting. |
| `alert` | `AlertComponent` | Route alerts through your notification system. |
| `menuModal` | `MenuModal` | Redesign quick-action trays. |
| `eventSettingsModal` | `EventSettingsModal` | Extend host tools with your own settings. |
| `requestsModal` | `RequestsModal` | Build moderation queues tailored to your workflows. |
| `waitingRoomModal` | `WaitingRoomModal` | Deliver custom waiting-room experiences. |
| `coHostModal` | `CoHostModal` | Manage co-hosts with bespoke UX. |
| `mediaSettingsModal` | `MediaSettingsModal` | Embed device tests or instructions. |
| `participantsModal` | `ParticipantsModal` | Introduce advanced filters, search, or notes. |
| `messagesModal` | `MessagesModal` | Drop in your full-featured chat module. |
| `displaySettingsModal` | `DisplaySettingsModal` | Let users pick layouts, themes, or captions. |
| `confirmExitModal` | `ConfirmExitModal` | Meet compliance wording requirements. |
| `confirmHereModal` | `ConfirmHereModal` | Customize attendance confirmations for webinars. |
| `shareEventModal` | `ShareEventModal` | Add referral codes or QR sharing. |
| `recordingModal` | `RecordingModal` | Tailor recording confirmation flows. |
| `pollModal` | `PollModal` | Integrate your polling/quiz engine. |
| `backgroundModal` | `BackgroundModal` | Hook AI background replacement or brand presets. |
| `breakoutRoomsModal` | `BreakoutRoomsModal` | Implement drag-and-drop or AI room suggestions. |
| `configureWhiteboardModal` | `ConfigureWhiteboardModal` | Adjust collaboration permissions before launch. |
| `whiteboard` | `Whiteboard` | Replace with your whiteboard provider. |
| `screenboard` | `Screenboard` | Modify shared-screen annotation layers. |
| `screenboardModal` | `ScreenboardModal` | Reimagine how users enable shared annotations. |
#### Entry flows & custom renderers
| Key | Default component | Typical use |
| --- | --- | --- |
| `welcomePage` | `WelcomePage` | Provide a fully branded welcome/marketing splash. |
| `preJoinPage` | `PrejoinPage` | Override the wizard used before joining live sessions. |
| `customMenuButtonsRenderer` | `ControlButtonsAltComponent` | Supply a bespoke renderer for menu button groups without overriding each button. |
#### Function overrides
| Key | Default function | Typical use |
| --- | --- | --- |
| `consumerResume` | `consumerResume` | Wrap errors, capture analytics, or rate-limit consumer resume behavior. |
| `addVideosGrid` | `addVideosGrid` | Replace participant ordering or layout heuristics on the fly. |
> Function overrides support `{ implementation, wrap }`. Provide `implementation` for a full replacement, or `wrap` to intercept the default behavior before/after it runs.
### Example: swap the chat modal and theme the controls
```tsx
import { MediasfuGeneric } from "mediasfu-reactjs";
import { MyChatModal } from "./ui/MyChatModal";
import { MyControls } from "./ui/MyControls";
const uiOverrides = {
messagesModal: {
component: MyChatModal,
},
controlButtons: {
render: (props) =>
Important:
You must obtain an API key from mediasfu.com to use this package with MediaSFU Cloud. You do not need the API Key if self-hosting.
## **Self-Hosting MediaSFU**
If you plan to self-host MediaSFU or use it without MediaSFU Cloud services, you don't need an API key. You can access the open-source version of MediaSFU from the [MediaSFU Open Repository](https://github.com/MediaSFU/MediaSFUOpen).
This setup allows full flexibility and customization while bypassing the need for cloud-dependent credentials.
---
# 📘 ReactJS SDK Guide
{/* Your custom UI */}
{sourceParameters && (
sourceParameters.clickVideo({ parameters: sourceParameters })}>
Toggle Video
sourceParameters.clickAudio({ parameters: sourceParameters })}>
Toggle Audio
)}
);
}
```
**When to use:**
- ✅ Need complete control over UI/UX
- ✅ Building a custom branded experience
- ✅ Integrating into existing app design
##### Mode 3: Component Replacement (Balanced)
Replace specific MediaSFU components while keeping the rest of the infrastructure.
```javascript
import { MediasfuGeneric, FlexibleVideo, FlexibleGrid } from 'mediasfu-reactjs';
function CustomMainScreen({ parameters }) {
return (
{/* Custom header */}
{parameters.roomName}
{parameters.participants.length} participants
{/* Use MediaSFU's components in your layout */}
{/* Custom footer */}
parameters.clickVideo({ parameters })}>
{parameters.videoAlreadyOn ? 'Stop Video' : 'Start Video'}
{/* Main video area */}
{/* Participant grid */}
{/* Audio-only participants */}
);
}
```
### 2. Control Components: User Interactions
**ControlButtonsComponent** - Standard control bar
```javascript
import { ControlButtonsComponent } from 'mediasfu-reactjs';
parameters.updateIsParticipantsModalVisible(true)}>
Show Participants ({parameters.participants.length})
parameters.updateIsMessagesModalVisible(true)}>
Open Chat
parameters.launchPoll.launchPoll({ parameters })}>
Create Poll
);
}
```
### 4. Video Cards: Individual Participant Display
**VideoCard** - Individual participant video element
```javascript
import { VideoCard } from 'mediasfu-reactjs';
{
if (videoRef && stream) {
videoRef.srcObject = stream;
videoRef.play();
}
}}
style={{ width: '100%', height: '100%', objectFit: 'cover' }}
autoPlay
muted
/>
{participant.name} {participant.muted && '🔇'}
);
}
// Use it
{
parameters.switchUserVideo({
videoPreference: e.target.value,
parameters
});
}}>
{cameras.map(camera => (
{camera.label}
))}
{
parameters.switchUserAudio({
audioPreference: e.target.value,
parameters
});
}}>
{microphones.map(mic => (
{mic.label}
))}
);
}
```
### Participant Management Methods
```javascript
// Get all participants
const participants = parameters.participants;
const participantCount = parameters.participantsCounter;
// Filter participants
const videoParticipants = participants.filter(p => p.videoOn);
const audioOnlyParticipants = participants.filter(p => !p.videoOn);
const mutedParticipants = participants.filter(p => p.muted);
// Find specific participant
const participant = participants.find(p => p.name === 'John Doe');
// Remove participant from room (host only)
parameters.disconnectUserInitiate({
member: participantId,
roomName: parameters.roomName,
socket: parameters.socket
});
// Change participant role (host only)
parameters.updateParticipant({
participantId: 'participant-id',
islevel: '2', // '2' = host, '1' = co-host, '0' = participant
parameters
});
// Request to unmute participant (sends request)
parameters.requestScreenShare({ parameters });
```
### Chat & Messaging Methods
```javascript
// Send a group message
parameters.sendMessage({
message: 'Hello everyone!',
type: 'group',
parameters
});
// Send direct message
parameters.sendMessage({
message: 'Private message',
type: 'direct',
receivers: ['participant-id'],
parameters
});
// Access message history
const messages = parameters.messages;
// Listen for new messages (via update function)
parameters.updateMessages = (newMessages) => {
console.log('New messages:', newMessages);
};
// Example: Custom chat component
function CustomChat({ parameters }) {
const [message, setMessage] = useState('');
const sendMessage = () => {
parameters.sendMessage({
message,
type: 'group',
parameters
});
setMessage('');
};
return (
{parameters.messages.map((msg, index) => (
{msg.sender}: {msg.message}
))}
setMessage(e.target.value)}
onKeyPress={(e) => e.key === 'Enter' && sendMessage()}
/>
Send
);
}
```
### Recording Methods
```javascript
// Start recording
parameters.startRecording({ parameters });
// Stop recording
parameters.stopRecording({ parameters });
// Pause recording
parameters.pauseRecording({ parameters });
// Resume recording
parameters.resumeRecording({ parameters });
// Configure recording settings
parameters.updateRecording({
recordingMediaOptions: 'video', // or 'audio'
recordingAudioOptions: 'all', // or 'host'
recordingVideoOptions: 'all', // or 'host'
recordingVideoType: 'fullDisplay', // or 'bestDisplay', 'all'
recordingDisplayType: 'video', // 'media', 'video', 'all'
recordingBackgroundColor: '#000000',
recordingNameTagsColor: '#ffffff',
recordingOrientationVideo: 'landscape', // or 'portrait'
recordingNameTags: true,
recordingAddHLS: false,
parameters
});
// Check recording state
const isRecording = parameters.recordStarted;
const isPaused = parameters.recordPaused;
const recordingTime = parameters.recordElapsedTime;
```
### Polls & Surveys Methods
```javascript
// Create a poll
parameters.handleCreatePoll({
poll: {
question: 'What time works best?',
type: 'multiple', // or 'single'
options: ['10 AM', '2 PM', '5 PM']
},
parameters
});
// Vote on a poll
parameters.handleVotePoll({
pollId: 'poll-id',
optionIndex: 1,
parameters
});
// End a poll
parameters.handleEndPoll({
pollId: 'poll-id',
parameters
});
// Access poll data
const polls = parameters.polls;
const activePoll = polls.find(p => p.status === 'active');
// Example: Custom poll component
function CustomPoll({ parameters }) {
const activePoll = parameters.polls.find(p => p.status === 'active');
if (!activePoll) return null;
return (
{activePoll.question}
{activePoll.options.map((option, index) => (
{
parameters.handleVotePoll({
pollId: activePoll.id,
optionIndex: index,
parameters
});
}}
>
{option} ({activePoll.votes?.[index] || 0} votes)
))}
);
}
```
### Breakout Rooms Methods
```javascript
// Create breakout rooms
parameters.createBreakoutRooms({
numberOfRooms: 3,
participants: parameters.participants,
parameters
});
// Assign participant to room
parameters.assignParticipantToRoom({
participantId: 'participant-id',
roomIndex: 0,
parameters
});
// Start breakout rooms
parameters.startBreakoutRooms({ parameters });
// Stop breakout rooms
parameters.stopBreakoutRooms({ parameters });
// Access breakout room data
const breakoutRooms = parameters.breakoutRooms;
const currentRoom = parameters.currentBreakoutRoom;
```
### Whiteboard Methods
```javascript
// Show/hide whiteboard
parameters.updateWhiteboardStarted(true);
parameters.updateWhiteboardEnded(false);
// Configure whiteboard
parameters.launchConfigureWhiteboard.launchConfigureWhiteboard({ parameters });
// Access whiteboard state
const isWhiteboardActive = parameters.whiteboardStarted;
const whiteboardData = parameters.whiteboardUsers;
```
### Utility Methods
```javascript
// Check permissions
const hasPermission = await parameters.checkPermission({
permissionType: 'video', // or 'audio'
parameters
});
// Format large numbers
const formatted = parameters.formatNumber(1250000); // Returns "1.25M"
// Sleep/delay
await parameters.sleep({ ms: 1000 });
// Update display settings
parameters.updateMainWindow(true); // Show/hide main window
// Trigger layout recalculation
parameters.onScreenChanges({ changed: true, parameters });
// Get room information
const roomInfo = {
name: parameters.roomName,
host: parameters.host,
capacity: parameters.capacity,
eventType: parameters.eventType,
duration: parameters.duration
};
```
**Complete method documentation:** Visit [mediasfu.com/reactjs](https://www.mediasfu.com/reactjs/) for detailed documentation on all 200+ methods.
---
## Media Streams & Participants
{participantName}'s Video
👥 {parameters.participantsCounter} participants
🎥 {parameters.participants.filter(p => p.videoOn).length} with video
🔇 {parameters.participants.filter(p => p.muted).length} muted
);
}
```
### Advanced Stream Management
```javascript
// Custom grid with specific participants
function CustomParticipantGrid({ parameters }) {
const [selectedParticipants, setSelectedParticipants] = useState([]);
const renderParticipantVideo = (participant) => {
if (!participant.videoID) return null;
const stream = parameters.allVideoStreams.find(
s => s.producerId === participant.videoID
);
return (
{
if (videoRef && stream?.stream) {
videoRef.srcObject = stream.stream;
videoRef.play();
}
}}
autoPlay
playsInline
muted
style={{ width: '200px', height: '150px' }}
/>
);
};
return (
{selectedParticipants.map(participant => (
{renderParticipantVideo(participant)}
{participant.name}
))}
{/* Video button */}
parameters.clickVideo({ parameters })}
style={{
width: 60,
height: 60,
borderRadius: '50%',
border: 'none',
background: parameters.videoAlreadyOn ? '#4CAF50' : '#f44336',
color: 'white',
fontSize: 24,
cursor: 'pointer'
}}
>
📹
{/* Audio button */}
parameters.clickAudio({ parameters })}
style={{
width: 60,
height: 60,
borderRadius: '50%',
border: 'none',
background: parameters.audioAlreadyOn ? '#4CAF50' : '#f44336',
color: 'white',
fontSize: 24,
cursor: 'pointer'
}}
>
{parameters.audioAlreadyOn ? '🎤' : '🔇'}
{/* Screen share button */}
parameters.clickScreenShare({ parameters })}
style={{
width: 60,
height: 60,
borderRadius: '50%',
border: 'none',
background: parameters.screenAlreadyOn ? '#2196F3' : '#666',
color: 'white',
fontSize: 24,
cursor: 'pointer'
}}
>
🖥️
{/* Leave button */}
parameters.launchConfirmExit({ parameters })}
style={{
width: 60,
height: 60,
borderRadius: '50%',
border: 'none',
background: '#f44336',
color: 'white',
fontSize: 24,
cursor: 'pointer'
}}
>
📞
);
}
```
### 3. Themed Application
Apply your app's theme to MediaSFU:
```javascript
import { MediasfuGeneric } from 'mediasfu-reactjs';
import './custom-theme.css';
function App() {
return (
);
}
// custom-theme.css
/*
.themed-app {
--primary-color: #6c5ce7;
--secondary-color: #a29bfe;
--background-color: #1a1a2e;
--text-color: #ffffff;
}
.themed-app button {
background: var(--primary-color);
color: var(--text-color);
border: none;
border-radius: 8px;
padding: 10px 20px;
cursor: pointer;
transition: all 0.3s ease;
}
.themed-app button:hover {
background: var(--secondary-color);
transform: translateY(-2px);
}
*/
```
### 4. Complete Custom UI Example
Here's a complete example combining everything:
```javascript
import React, { useState } from 'react';
import {
MediasfuGeneric,
FlexibleVideo,
FlexibleGrid,
AudioGrid
} from 'mediasfu-reactjs';
function CompleteCustomInterface({ parameters }) {
return (
{/* Custom Header */}
{/* Main Content */}
{/* Video Area */}
{/* Sidebar */}
Participants
{parameters.participants.map(participant => (
{participant.name}
{participant.muted && ' 🔇'}
{participant.videoOn && ' 📹'}
))}
{/* Custom Controls */}
parameters.clickVideo({ parameters })}>
{parameters.videoAlreadyOn ? '📹 Stop Video' : '📹 Start Video'}
parameters.clickAudio({ parameters })}>
{parameters.audioAlreadyOn ? '🎤 Mute' : '🎤 Unmute'}
parameters.clickScreenShare({ parameters })}>
🖥️ Share Screen
parameters.updateIsMessagesModalVisible(true)}>
💬 Chat
parameters.launchConfirmExit({ parameters })} style={{ background: '#f44336' }}>
📞 Leave
{
if (video && stream) {
video.srcObject = stream;
video.play();
}
}} style={{ width: '100%' }} autoPlay muted />
{name} ✨
);
mediasfuFunctions.clickVideo?.(mediasfuFunctions)}>
Toggle My Video
mediasfuFunctions.clickAudio?.(mediasfuFunctions)}>
Toggle My Audio
);
};
```
That's it! **No complex setup, no config files** - just pass a prop and customize away. 🚀
---
### Programmatically Fetching Tokens
If you want to fetch the required tokens programmatically without visiting MediaSFU's website, you can use the `PreJoinPage` component and pass your credentials as props:
```javascript
import { MediasfuGeneric, PreJoinPage } from 'mediasfu-reactjs';
const App = () => {
const credentials = { apiUserName: "yourAPIUserName", apiKey: "yourAPIKey" };
return (
### Preview of Welcome Page
### Preview of Prejoin Page
= ({
localLink = "",
connectMediaSFU = true,
parameters,
credentials = user_credentials,
returnUI = false,
noUIPreJoinOptions,
createMediaSFURoom = createRoomOnMediaSFU,
joinMediaSFURoom = joinRoomOnMediaSFU,
}) => {
const [isCreateMode, setIsCreateMode] = useState(false);
const [name, setName] = useState("");
const [duration, setDuration] = useState("");
const [eventType, setEventType] = useState("");
const [capacity, setCapacity] = useState("");
const [eventID, setEventID] = useState("");
const [error, setError] = useState("");
const pending = useRef(false);
const localConnected = useRef(false);
const localData = useRef(undefined);
const initSocket = useRef(undefined);
const {
showAlert,
updateIsLoadingModalVisible,
connectLocalSocket,
updateSocket,
updateValidated,
updateApiUserName,
updateApiToken,
updateLink,
updateRoomName,
updateMember,
} = parameters;
const handleCreateRoom = async () => {
if (pending.current) {
return;
}
pending.current = true;
let payload = {} as CreateMediaSFURoomOptions;
if (returnUI) {
if (!name || !duration || !eventType || !capacity) {
setError("Please fill all the fields.");
return;
}
payload = {
action: "create",
duration: parseInt(duration),
capacity: parseInt(capacity),
eventType: eventType as "chat" | "broadcast" | "webinar" | "conference",
userName: name,
recordOnly: false,
};
} else {
if (
noUIPreJoinOptions &&
"action" in noUIPreJoinOptions &&
noUIPreJoinOptions.action === "create"
) {
payload = noUIPreJoinOptions as CreateMediaSFURoomOptions;
} else {
pending.current = false;
throw new Error(
"Invalid options provided for creating a room without UI."
);
}
}
updateIsLoadingModalVisible(true);
if (localLink.length > 0) {
const secureCode =
Math.random().toString(30).substring(2, 14) +
Math.random().toString(30).substring(2, 14);
let eventID =
new Date().getTime().toString(30) +
new Date().getUTCMilliseconds() +
Math.floor(10 + Math.random() * 99).toString();
eventID = "m" + eventID;
const eventRoomParams = localData.current?.meetingRoomParams_;
eventRoomParams!.type = eventType as
| "chat"
| "broadcast"
| "webinar"
| "conference";
const createData: CreateLocalRoomParameters = {
eventID: eventID,
duration: parseInt(duration),
capacity: parseInt(capacity),
userName: payload.userName,
scheduledDate: new Date(),
secureCode: secureCode,
waitRoom: false,
recordingParams: localData.current?.recordingParams_,
eventRoomParams: eventRoomParams,
videoPreference: null,
audioPreference: null,
audioOutputPreference: null,
mediasfuURL: "",
};
// socket in main window is required and for no local room, no use of initSocket
// for local room, initSocket becomes the local socket, and localSocket is the connection to MediaSFU (if connectMediaSFU is true)
// else localSocket is the same as initSocket
if (
connectMediaSFU &&
initSocket.current &&
localData.current &&
localData.current.apiUserName &&
localData.current.apiKey
) {
payload.recordOnly = true; // allow production to mediasfu only; no consumption
const response = await roomCreator({
payload,
apiUserName: localData.current.apiUserName,
apiKey: localData.current.apiKey,
validate: false,
});
if (
response &&
response.success &&
response.data &&
"roomName" in response.data
) {
createData.eventID = response.data.roomName;
createData.secureCode = response.data.secureCode || "";
createData.mediasfuURL = response.data.publicURL;
await createLocalRoom({
createData: createData,
link: response.data.link,
});
} else {
pending.current = false;
updateIsLoadingModalVisible(false);
setError(`Unable to create room on MediaSFU.`);
try {
updateSocket(initSocket.current);
await createLocalRoom({ createData: createData });
pending.current = false;
} catch (error) {
pending.current = false;
updateIsLoadingModalVisible(false);
setError(`Unable to create room. ${error}`);
}
}
} else {
try {
updateSocket(initSocket.current!);
await createLocalRoom({ createData: createData });
pending.current = false;
} catch (error) {
pending.current = false;
updateIsLoadingModalVisible(false);
setError(`Unable to create room. ${error}`);
}
}
} else {
await roomCreator({
payload,
apiUserName: credentials.apiUserName,
apiKey: credentials.apiKey,
validate: true,
});
pending.current = false;
}
};
const handleJoinRoom = async () => {
if (pending.current) {
return;
}
pending.current = true;
let payload = {} as JoinMediaSFURoomOptions;
if (returnUI) {
if (!name || !eventID) {
setError("Please fill all the fields.");
return;
}
payload = {
action: "join",
meetingID: eventID,
userName: name,
};
} else {
if (
noUIPreJoinOptions &&
"action" in noUIPreJoinOptions &&
noUIPreJoinOptions.action === "join"
) {
payload = noUIPreJoinOptions as JoinMediaSFURoomOptions;
} else {
throw new Error(
"Invalid options provided for joining a room without UI."
);
}
}
if (localLink.length > 0 && !localLink.includes("mediasfu.com")) {
const joinData: JoinLocalEventRoomParameters = {
eventID: eventID,
userName: payload.userName,
secureCode: "",
videoPreference: null,
audioPreference: null,
audioOutputPreference: null,
};
await joinLocalRoom({ joinData: joinData });
pending.current = false;
return;
}
updateIsLoadingModalVisible(true);
const response = await joinMediaSFURoom({
payload,
apiUserName: credentials.apiUserName,
apiKey: credentials.apiKey,
localLink: localLink,
});
if (response.success && response.data && "roomName" in response.data) {
await checkLimitsAndMakeRequest({
apiUserName: response.data.roomName,
apiToken: response.data.secret,
link: response.data.link,
userName: payload.userName,
parameters: parameters,
});
pending.current = false;
} else {
pending.current = false;
updateIsLoadingModalVisible(false);
setError(
`Unable to join room. ${
response.data
? "error" in response.data
? response.data.error
: ""
: ""
}`
);
}
};
const joinLocalRoom = async ({
joinData,
link = localLink,
}: JoinLocalEventRoomOptions) => {
initSocket.current?.emit(
"joinEventRoom",
joinData,
(response: CreateJoinLocalRoomResponse) => {
if (response.success) {
updateSocket(initSocket.current!);
updateApiUserName(localData.current?.apiUserName || "");
updateApiToken(response.secret);
updateLink(link);
updateRoomName(joinData.eventID);
updateMember(joinData.userName);
updateIsLoadingModalVisible(false);
updateValidated(true);
} else {
updateIsLoadingModalVisible(false);
setError(`Unable to join room. ${response.reason}`);
}
}
);
};
const createLocalRoom = async ({
createData,
link = localLink,
}: CreateLocalRoomOptions) => {
initSocket.current?.emit(
"createRoom",
createData,
(response: CreateJoinLocalRoomResponse) => {
if (response.success) {
updateSocket(initSocket.current!);
updateApiUserName(localData.current?.apiUserName || "");
updateApiToken(response.secret);
updateLink(link);
updateRoomName(createData.eventID);
// local needs islevel updated from here
// we update member as `userName` + "_2" and split it in the room
updateMember(createData.userName + "_2");
updateIsLoadingModalVisible(false);
updateValidated(true);
} else {
updateIsLoadingModalVisible(false);
setError(`Unable to create room. ${response.reason}`);
}
}
);
};
const roomCreator = async ({
payload,
apiUserName,
apiKey,
validate = true,
}: {
payload: any;
apiUserName: string;
apiKey: string;
validate?: boolean;
}) => {
const response = await createMediaSFURoom({
payload,
apiUserName: apiUserName,
apiKey: apiKey,
localLink: localLink,
});
if (response.success && response.data && "roomName" in response.data) {
await checkLimitsAndMakeRequest({
apiUserName: response.data.roomName,
apiToken: response.data.secret,
link: response!.data.link,
userName: payload.userName,
parameters: parameters,
validate: validate,
});
return response;
} else {
updateIsLoadingModalVisible(false);
setError(
`Unable to create room. ${
response.data
? "error" in response.data
? response.data.error
: ""
: ""
}`
);
}
};
const checkProceed = async ({
returnUI,
noUIPreJoinOptions,
}: {
returnUI: boolean;
noUIPreJoinOptions: CreateMediaSFURoomOptions | JoinMediaSFURoomOptions;
}) => {
if (!returnUI && noUIPreJoinOptions) {
if (
"action" in noUIPreJoinOptions &&
noUIPreJoinOptions.action === "create"
) {
// update all the required parameters and call
const createOptions: CreateMediaSFURoomOptions =
noUIPreJoinOptions as CreateMediaSFURoomOptions;
if (
!createOptions.userName ||
!createOptions.duration ||
!createOptions.eventType ||
!createOptions.capacity
) {
throw new Error(
"Please provide all the required parameters: userName, duration, eventType, capacity"
);
}
await handleCreateRoom();
} else if (
"action" in noUIPreJoinOptions &&
noUIPreJoinOptions.action === "join"
) {
// update all the required parameters and call
const joinOptions: JoinMediaSFURoomOptions =
noUIPreJoinOptions as JoinMediaSFURoomOptions;
if (!joinOptions.userName || !joinOptions.meetingID) {
throw new Error(
"Please provide all the required parameters: userName, meetingID"
);
}
await handleJoinRoom();
} else {
throw new Error(
"Invalid options provided for creating/joining a room without UI."
);
}
}
};
useEffect(() => {
if (
localLink.length > 0 &&
!localConnected.current &&
!initSocket.current
) {
try {
connectLocalSocket?.({ link: localLink })
.then((response: ResponseLocalConnection | undefined) => {
localData.current = response!.data;
initSocket.current = response!.socket;
localConnected.current = true;
if (!returnUI && noUIPreJoinOptions) {
checkProceed({ returnUI, noUIPreJoinOptions });
}
})
.catch((error) => {
showAlert?.({
message: `Unable to connect to ${localLink}. ${error}`,
type: "danger",
duration: 3000,
});
});
} catch {
showAlert?.({
message: `Unable to connect to ${localLink}. Something went wrong.`,
type: "danger",
duration: 3000,
});
}
} else if (localLink.length === 0 && !initSocket.current) {
if (!returnUI && noUIPreJoinOptions) {
checkProceed({ returnUI, noUIPreJoinOptions });
}
}
}, []);
const handleToggleMode = () => {
setIsCreateMode(!isCreateMode);
setError("");
};
if (!returnUI) {
return <>;
}
return (
// your JSX Element
);
export default PreJoinPage;
```
### IP Blockage Warning And Local UI Development
Entering the event room without the correct credentials may result in IP blockage, as the page automatically attempts to connect with MediaSFU servers, which rate limit bad requests based on IP address.
If users attempt to enter the event room without valid credentials or tokens, it may lead to IP blockage due to MediaSFU servers' rate limiting mechanism. To avoid unintentional connections to MediaSFU servers during UI development, users can pass the `useLocalUIMode` parameter as `true`.
In this mode, the module will operate locally without making requests to MediaSFU servers. However, to render certain UI elements such as messages, participants, requests, etc., users may need to provide seed data. They can achieve this by importing random data generators and passing the generated data to the event room component.
### Example for Broadcast Room
```typescript
import { MediasfuBroadcast, generateRandomParticipants, generateRandomMessages } from 'mediasfu-reactjs';
/**
* App Component
*
* This component demonstrates how to:
* - Configure credentials for MediaSFU Cloud and/or Community Edition (CE).
* - Use MediaSFU with or without a custom server.
* - Integrate a pre-join page.
* - Return no UI and manage state through sourceParameters, allowing a fully custom frontend.
*
* Basic instructions:
* 1. Set `localLink` to your CE server if you have one, or leave it blank to use MediaSFU Cloud.
* 2. Set `connectMediaSFU` to determine whether you're connecting to MediaSFU Cloud services.
* 3. Provide credentials if using MediaSFU Cloud (dummy credentials are acceptable in certain scenarios).
* 4. If you prefer a custom UI, set `returnUI` to false and handle all interactions via `sourceParameters` and `updateSourceParameters`.
* 5. For secure production usage, consider using custom `createMediaSFURoom` and `joinMediaSFURoom` functions to forward requests through your backend.
*/
const App = () => {
// =========================================================
// API CREDENTIALS CONFIGURATION
// =========================================================
//
// Scenario A: Not using MediaSFU Cloud at all.
// - No credentials needed. Just set localLink to your CE server.
// Example:
/*
const credentials = {};
const localLink = 'http://your-ce-server.com'; // http://localhost:3000 for local testing
const connectMediaSFU = localLink.trim() !== '';
*/
// Scenario B: Using MediaSFU CE + MediaSFU Cloud for Egress only.
// - Use dummy credentials (8 chars for userName, 64 chars for apiKey).
// - Your CE backend will forward requests with your real credentials.
/*
const credentials = {
apiUserName: 'dummyUsr',
apiKey: '1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
};
const localLink = 'http://your-ce-server.com'; // http://localhost:3000 for local testing
const connectMediaSFU = localLink.trim() !== '';
*/
// Scenario C: Using MediaSFU Cloud without your own server.
// - For development, use your actual or dummy credentials.
// - In production, securely handle credentials server-side and use custom room functions.
const credentials = {
apiUserName: 'yourDevUser', // 8 chars recommended for dummy
apiKey: 'yourDevApiKey1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef', // 64 chars
};
const localLink = ''; // Leave empty if not using your own server
const connectMediaSFU = true; // Set to true if using MediaSFU Cloud since localLink is empty
// =========================================================
// UI RENDERING OPTIONS
// =========================================================
//
// If you want a fully custom UI (e.g., a custom layout inspired by WhatsApp):
// 1. Set `returnUI = false` to prevent the default MediaSFU UI from rendering.
// 2. Provide `noUIPreJoinOptions` to simulate what would have been entered on a pre-join page.
// 3. Use `sourceParameters` and `updateSourceParameters` to access and update state/actions.
// 4. No need for any of the above if you're using the default MediaSFU UI.
//
// Example noUIPreJoinOptions:
const noUIPreJoinOptions: CreateMediaSFURoomOptions | JoinMediaSFURoomOptions = {
action: 'create',
capacity: 10,
duration: 15,
eventType: 'broadcast',
userName: 'Prince',
};
// Example for joining a room:
// const noUIPreJoinOptions: CreateMediaSFURoomOptions | JoinMediaSFURoomOptions = {
// action: 'join',
// userName: 'Prince',
// meetingID: 'yourMeetingID'
// };
const [sourceParameters, setSourceParameters] = useState<{ [key: string]: any }>({});
const updateSourceParameters = (data: { [key: string]: any }) => {
setSourceParameters(data);
};
// =========================================================
// CUSTOM ROOM FUNCTIONS (OPTIONAL)
// =========================================================
//
// To securely forward requests to MediaSFU:
// - Implement custom `createMediaSFURoom` and `joinMediaSFURoom` functions.
// - These functions send requests to your server, which then communicates with MediaSFU Cloud.
//
// Already imported `createRoomOnMediaSFU` and `joinRoomOnMediaSFU` are examples.
//
// If using MediaSFU CE backend, ensure your server endpoints:
// - Validate dummy credentials.
// - Forward requests to mediasfu.com with real credentials.
// =========================================================
// DEPRECATED FEATURES (SEED DATA)
// =========================================================
//
// Deprecated Feature: useLocalUIMode
// This feature is deprecated due to updates for strong typing.
// It is no longer required and should not be used in new implementations.
//
// Uncomment and configure the following section if you intend to use seed data
// for generating random participants and messages.
//
// Note: This is deprecated and maintained only for legacy purposes.
/*
const useSeed = false;
let seedData = {};
if (useSeed) {
const memberName = 'Prince';
const hostName = 'Fred';
const participants_ = generateRandomParticipants({
member: memberName,
coHost: '',
host: hostName,
forChatBroadcast: eventType === 'broadcast' || eventType === 'chat',
});
const messages_ = generateRandomMessages({
participants: participants_,
member: memberName,
host: hostName,
forChatBroadcast: eventType === 'broadcast' || eventType === 'chat',
});
const requests_ = generateRandomRequestList({
participants: participants_,
hostName: memberName,
coHostName: '',
numberOfRequests: 3,
});
const waitingList_ = generateRandomWaitingRoomList();
seedData = {
participants: participants_,
messages: messages_,
requests: requests_,
waitingList: waitingList_,
member: memberName,
host: hostName,
eventType: eventType,
};
}
*/
// =========================================================
// CHOOSE A USE CASE / COMPONENT
// =========================================================
//
// Multiple components are available depending on your event type:
// MediasfuBroadcast, MediasfuChat, MediasfuWebinar, MediasfuConference
//
// By default, we'll use MediasfuBroadcast with custom settings.
/**
* **MediasfuBroadcast Component**
*
* Uncomment to use the broadcast event type.
*/
/*
return (
{/* Your completely custom UI */}
sourceParameters.clickVideo?.(sourceParameters)}>
Toggle Video
sourceParameters.clickAudio?.(sourceParameters)}>
Toggle Audio
{/* Access any MediaSFU function through sourceParameters */}
);
};
```
### **2. Custom Card Components**
**Perfect for:** Keeping MediaSFU's layout but styling individual video/audio cards your way.
```javascript
import { MediasfuGeneric } from 'mediasfu-reactjs';
const CustomVideoCard = (options) => {
const { participant, stream, width, height, name } = options;
return (
{stream && (
{
if (video && stream) {
video.srcObject = stream;
video.play().catch(() => {});
}
}}
style={{ width: '100%', height: '100%', objectFit: 'cover' }}
autoPlay
muted={participant?.muted}
playsInline
/>
)}
{name} ✨
{stream && (
{
if (video && stream) {
video.srcObject = stream;
video.play().catch(() => {});
}
}}
style={{ width: '100%', height: '100%' }}
autoPlay
muted
playsInline
/>
)}
{name}
(useLocalUIMode); // Validated state as boolean
const confirmedToRecord = useRef(false); // True if the user has confirmed to record as boolean
const meetingDisplayType = useRef("media"); // Meeting display type as string
// Sample control button configurations
const controlBroadcastButtons = [/* define your control buttons here */];
const recordButton = [/* define your record button here */];
const recordButtons = [/* define your record buttons here */];
// Sample component sizes
const componentSizes = useRef({
// Component sizes as ComponentSizes
mainHeight: 0,
otherHeight: 0,
mainWidth: 0,
otherWidth: 0,
}); // Component sizes
// Sample function to update component sizes
const updateComponentSizes = (sizes: ComponentSizes) => {
componentSizes.current = sizes;
};
// Sample function to update validation state
const updateValidated = (value: boolean) => {
setValidated(value);
};
// Sample credentials
const credentials = {
apiUserName: "yourAPIUserName",
apiKey: "yourAPIKey"
};
// Sample socket
const socket = useRef({} as Socket); // Socket for the media server, type Socket
// Sample meeting progress time
const [meetingProgressTime, setMeetingProgressTime] =
useState("00:00:00"); // Meeting progress time as string
// Sample record state
const [recordState, setRecordState] = useState("green"); // Recording state with specific values
// Sample main grid and other grid elements
const mainGridStream = useRef([]); // Array of main grid streams as React.JSX.Element[]
const [otherGridStreams, setOtherGridStreams] = useState([
[],
[],
]); // Other grid streams as 2D array of React.JSX.Element[]
// Sample audio only streams
const audioOnlyStreams = useRef([]); // Array of audio-only streams
// Sample main height and width
const [mainHeightWidth, setMainHeightWidth] = useState(100); // Main height and width as number
// Render the PrejoinPage if not validated, otherwise render the main components
return (
{!validated ? (
) : (
{/* Main aspect component containsa ll but the control buttons (as used for webinar and conference) */}
{/* MainScreenComponent contains the main grid view and the minor grid view */}
{/* MainGridComponent shows the main grid view - not used at all in chat event type and conference event type when screenshare is not active*/}
{/* MainGridComponent becomes the dominant grid view in broadcast and webinar event types */}
{/* MainGridComponent becomes the dominant grid view in conference event type when screenshare is active */}
0 ? true : false}
timeBackgroundColor={recordState}
meetingProgressTime={meetingProgressTime}
>
0 &&
!(whiteboardStarted.current && !whiteboardEnded.current)
}
/>
)}
updateIsParticipantsModalVisible(false)}
participantsCounter={participantsCounter.current}
onParticipantsFilterChange={onParticipantsFilterChange}
parameters={{
updateParticipants: updateParticipants,
updateIsParticipantsModalVisible: updateIsParticipantsModalVisible,
updateDirectMessageDetails,
updateStartDirectMessage,
updateIsMessagesModalVisible,
showAlert: showAlert,
filteredParticipants: filteredParticipants.current,
participants: filteredParticipants.current,
roomName: roomName.current,
islevel: islevel.current,
member: member.current,
coHostResponsibility: coHostResponsibility.current,
coHost: coHost.current,
eventType: eventType.current,
startDirectMessage: startDirectMessage.current,
directMessageDetails: directMessageDetails.current,
socket: socket.current,
getUpdatedAllParams: getAllParams,
}}
/>
updateIsRecordingModalVisible(false)}
startRecording={startRecording}
confirmRecording={confirmRecording}
parameters={{
...getAllParams(),
...mediaSFUFunctions(),
}}
/>
updateIsMessagesModalVisible(false)}
messages={messages.current}
eventType={eventType.current}
member={member.current}
islevel={islevel.current}
coHostResponsibility={coHostResponsibility.current}
coHost={coHost.current}
startDirectMessage={startDirectMessage.current}
directMessageDetails={directMessageDetails.current}
updateStartDirectMessage={updateStartDirectMessage}
updateDirectMessageDetails={updateDirectMessageDetails}
showAlert={showAlert}
roomName={roomName.current}
socket={socket.current}
chatSetting={chatSetting.current}
/>
updateIsConfirmExitModalVisible(false)}
member={member.current}
roomName={roomName.current}
socket={socket.current}
islevel={islevel.current}
/>
updateIsConfirmHereModalVisible(false)}
member={member.current}
roomName={roomName.current}
socket={socket.current}
/>
updateIsShareEventModalVisible(false)}
roomName={roomName.current}
islevel={islevel.current}
adminPasscode={adminPasscode.current}
eventType={eventType.current}
/>
setAlertVisible(false)}
textColor={"#ffffff"}
/>
{recordingProgressTime}
),
show: true,
},
{
icon: faDotCircle,
active: false,
onPress: () => console.log("Status pressed"),
activeColor: "black",
inActiveColor: recordPaused.current === false ? "red" : "yellow",
show: true,
},
{
icon: faCog,
active: false,
onPress: () => {
launchRecording({
updateIsRecordingModalVisible: updateIsRecordingModalVisible,
isRecordingModalVisible: isRecordingModalVisible,
showAlert: showAlert,
stopLaunchRecord: stopLaunchRecord.current,
canLaunchRecord: canLaunchRecord.current,
recordingAudioSupport: recordingAudioSupport.current,
recordingVideoSupport: recordingVideoSupport.current,
updateCanRecord: updateCanRecord,
updateClearedToRecord: updateClearedToRecord,
recordStarted: recordStarted.current,
recordPaused: recordPaused.current,
localUIMode: localUIMode.current,
});
},
activeColor: "green",
inActiveColor: "black",
show: true,
},
];
const controlBroadcastButtons: ButtonTouch[] = [
// control buttons for broadcast
//Replace or remove any of the buttons as you wish
//Refer to ControlButtonsComponentTouch for more details on how to add custom buttons
{
icon: faUsers,
active: true,
alternateIcon: faUsers,
onPress: () => {
launchParticipants({
updateIsParticipantsModalVisible: updateIsParticipantsModalVisible,
isParticipantsModalVisible: isParticipantsModalVisible,
});
},
activeColor: "black",
inActiveColor: "black",
show: islevel.current === "2",
},
{
icon: faShareAlt,
active: true,
alternateIcon: faShareAlt,
onPress: () => updateIsShareEventModalVisible(!isShareEventModalVisible),
activeColor: "black",
inActiveColor: "black",
show: true,
},
{
customComponent: (
{/* Your icon */}
{/* Conditionally render a badge */}
{showMessagesBadge && (
)}
{participantsCounter.current}
),
show: true,
},
{
icon: faPhone,
active: endCallActive,
onPress: () =>
launchConfirmExit({
updateIsConfirmExitModalVisible: updateIsConfirmExitModalVisible,
isConfirmExitModalVisible: isConfirmExitModalVisible,
}),
activeColor: "green",
inActiveColor: "red",
show: true,
},
{
icon: faPhone,
active: endCallActive,
onPress: () => console.log("End Call pressed"), //not in use
activeColor: "transparent",
inActiveColor: "transparent",
backgroundColor: { default: "transparent" },
show: false,
},
];
```
This sample code defines arrays `recordButtons` and `controlBroadcastButtons`, each containing configuration objects for different control buttons. These configurations include properties such as icon, active state, onPress function, activeColor, inActiveColor, and show flag to control the visibility of each button.
You can customize these configurations according to your requirements, adding, removing, or modifying buttons as needed. Additionally, you can refer to the relevant component files (`ControlButtonsAltComponent` and `ControlButtonsComponentTouch`) for more details on how to add custom buttons.
Preview of Broadcast Page
Preview of Conference Page
### Preview of Conference Page's Mini Grids
`**
Returns a list of available media devices filtered by type.
- **Parameters:**
- `kind`: `"videoinput"` | `"audioinput"` - Type of media device to enumerate
- **Returns:** `Promise` - Array of media device information objects
**`getParticipantMedia({ id?, name, kind }: { id?: string, name: string, kind: "video" | "audio" }): Promise`**
Retrieves the media stream of a specific participant.
- **Parameters:**
- `id` (optional): `string` - Participant ID to search by (takes priority over name)
- `name`: `string` - Participant's display name (used if ID not provided or not found)
- `kind`: `"video"` | `"audio"` - Type of media stream to retrieve
- **Returns:** `Promise` - The participant's media stream or null if not found
### Common Use Cases
1. **Device Selection UI**: Build custom device picker components that allow users to switch between cameras and microphones
2. **Advanced UI Components**: Create sophisticated media display components with direct stream access
3. **Media Processing**: Implement custom audio/video processing pipelines
4. **Accessibility Features**: Build features that enhance accessibility with custom media handling
5. **Analytics & Monitoring**: Track and analyze media streams for quality monitoring
### Example: Custom Device Selector Component
```typescript
import React, { useState, useEffect } from 'react';
function DeviceSelector({ sourceParameters }) {
const [videoDevices, setVideoDevices] = useState([]);
const [audioDevices, setAudioDevices] = useState([]);
const { getMediaDevicesList } = sourceParameters;
useEffect(() => {
const loadDevices = async () => {
const cameras = await getMediaDevicesList("videoinput");
const microphones = await getMediaDevicesList("audioinput");
setVideoDevices(cameras);
setAudioDevices(microphones);
};
loadDevices();
}, []);
return (
Select Camera
{videoDevices.map(device => (
{device.label || `Camera ${device.deviceId.slice(0, 5)}`}
))}
Select Microphone
{audioDevices.map(device => (
{device.label || `Microphone ${device.deviceId.slice(0, 5)}`}
))}
);
}
```
### Example: Display Specific Participant Stream
```typescript
import React, { useEffect, useRef } from 'react';
function ParticipantVideo({ participantName, sourceParameters }) {
const videoRef = useRef(null);
const { getParticipantMedia } = sourceParameters;
useEffect(() => {
const loadStream = async () => {
const stream = await getParticipantMedia({
name: participantName,
kind: "video"
});
if (stream && videoRef.current) {
videoRef.current.srcObject = stream;
}
};
loadStream();
}, [participantName]);
return (
{participantName}'s Video
