MediaSFUOpen

September 29, 2025 · View on GitHub

MediaSFU ecosystem

A unified real‑time stack for telephony and multimodal agents with production SDKs across mobile and web.

Telephony agents and apps/SDKs: VOIP reference suite → github.com/MediaSFU/VOIP
Multimodal (vision, audio, text) non‑telephony agents and apps/SDKs → github.com/MediaSFU/Agents
Agents workspace (bring your own API keys) → agents.mediasfu.com/playground
Agents workspace (MediaSFU keys, limited) → agentsmediasfu.com

SDKs at a glance

React Native Expo: npm mediasfu-reactnative-expo • GitHub MediaSFU-ReactNative-Expo
React Native CLI: npm mediasfu-reactnative • GitHub MediaSFU-ReactNative
Flutter: pub.dev mediasfu_sdk • GitHub MediaSFU_SDK_Flutter
React.js: npm mediasfu-reactjs • GitHub MediaSFU-ReactJS
Angular: npm mediasfu-angular • GitHub MediaSFU-Angular

🚨 BREAKING: AI Phone Agents at $0.10 per 1,000 minutes

📞 Call our live AI demos right now:

🇺🇸 +1 (785) 369-1724 - Mixed Support Demo
🇬🇧 +44 7445 146575 - AI Conversation Demo
🇨🇦 +1 (587) 407-1990 - Technical Support Demo
🇨🇦 +1 (647) 558-6650 - Friendly AI Chat Demo

Traditional providers charge $0.05 per minute. We charge $0.10 per 1,000 minutes. That's 500x cheaper.

✅ Deploy AI phone agents in 30 minutes
✅ Works with ANY SIP provider (Twilio, Telnyx, Zadarma, etc.)
✅ Seamless AI-to-human handoffs
✅ Real-time call analytics & transcription

📖 Complete SIP/PSTN Documentation →

🔴 Critical note: If create/join room fails or behavior is unexpected

If you experience any issue creating or joining a meeting, or notice unexpected behavior:

If you run index.js (production), switch to the fully tested backup: index_backup.js.
If you run index_localhost.js (local SSL), switch to: index_localhost_backup.js.

Why this matters: the backup files intentionally keep some additional await statements. While they may look redundant, they have been fully validated in production flows and are safer than the cleaned non-_backup variants, which could have missed awaits in rare paths.

Quick ways to run backups (non-destructive):

# Production
node index_backup.js

# With PM2 (recommended on servers)
pm2 start index_backup.js --name mediasfu

# Localhost (SSL)
nodemon index_localhost_backup.js
# or
node index_localhost_backup.js

You can revert to the non-_backup files anytime. The backups are provided as the safe default if you hit any instability.

Cloud/NAT users (AWS/GCP/Azure): After setting your public ip, ensure mediasoup transports advertise it by setting announcedIp in listenIps (see the installation step for the exact before/after snippet).

MediaSFU offers a cutting-edge streaming experience that empowers users to customize their recordings and engage their audience with high-quality streams. Whether you're a content creator, educator, or business professional, MediaSFU provides the tools you need to elevate your streaming game.

Features

MediaSFU's Community Edition comes packed with a host of powerful features:

Screen Sharing with Annotation Support: Share your screen and annotate in real-time for enhanced presentations and collaborations.
Collaborative Whiteboards: Create and share whiteboards for real-time drawing and brainstorming sessions.
Breakout Rooms: Organize multiple sub-meetings within a single session to boost collaboration and focus.
Pagination: Efficiently manage large participant lists with seamless pagination.
Polls: Conduct real-time polls to gather instant feedback.
Media Access Requests Management: Easily handle media access requests to ensure smooth operations.
Video Effects: Enhance the visual experience with various video effects, including virtual backgrounds.
Chat (Direct & Group): Facilitate communication with both direct and group chat options.
Cloud Recording (Track-Based): Customize recordings with track-based options like watermarks, name tags, and background colors.
Managed Events: Handle abandoned and inactive participants, and enforce time and capacity limits.
Event Scheduling: Schedule events effortlessly, including recurring events and reminders.
Waiting Room: Manage participant entry to ensure a smooth start to meetings and events.
Custom Branding: Personalize your interface with custom logos, colors, and branding for a consistent corporate identity.
Security Features: Ensure secure meetings with password protection, end-to-end encryption, and user authentication.
Performance Analytics: Access detailed analytics and performance reports to gain insights into participant engagement and meeting effectiveness.
Integration with Third-Party Applications: Seamlessly integrate with other tools and applications to enhance functionality and streamline workflows.
Multi-Device Support: Enjoy a consistent experience across desktops, tablets, and smartphones, ensuring flexibility and convenience for all participants.

https://github.com/user-attachments/assets/310cb87c-dade-445d-aee7-dea1889d6dc4

Getting Started with MediaSFU Community Edition

Elevate your streaming experience to new heights with MediaSFU. Enjoy the freedom to customize your recordings with unlimited pausing and resuming, ensuring you have complete control over your content. Immerse yourself in simulcasted high-quality streams featuring lightning-fast 30ms latency, providing a seamless and immersive viewing experience for your audience.

Installation Guide

Installation on Ubuntu
Running on Localhost
Cloud Recording & Egress
Connecting Your MediaSFU SDKs to the Community Edition Server
Additional Resources

🔴 Critical note: If create/join room actions fail or behavior is unexpected

If you experience any issue creating or joining a meeting, or notice unexpected behavior:

If you run index.js (production), switch to the fully tested backup: index_backup.js.
If you run index_localhost.js (local SSL), switch to: index_localhost_backup.js.

Quick ways to run backups (non-destructive):

# Production
node index_backup.js

# With PM2 (recommended on servers)
pm2 start index_backup.js --name mediasfu

# Localhost (SSL)
nodemon index_localhost_backup.js
# or
node index_localhost_backup.js

You can revert to the non-_backup files anytime. The backups are provided as the safe default if you hit any instability.

Note: If you're setting up MediaSFU for production, follow the Installation on Ubuntu steps. For local development or testing, refer directly to the Running on Localhost section to bypass production configurations.

MediaSFU Community Edition is freely available for use.

Assumption: Production Environment on Linux

Note: The following instructions assume a production environment running on a Linux server (e.g., Ubuntu). For local development or testing on macOS or Windows, please refer to the additional guides linked at the end of this document. Those guides will help you set up the necessary environment, firewall rules, ports, and SSL configuration for your operating system.

🚀 Guide to Install MediaSFUOpen

For a detailed step-by-step guide on how to install MediaSFUOpen, check out our installation video:
🎥 Watch the MediaSFUOpen Installation Guide

This video covers everything from server setup to SSL configuration, ensuring you can get MediaSFU up and running with ease.

Installation on Ubuntu

Follow these steps to install MediaSFU on Ubuntu:

Update package lists and upgrade existing packages:

sudo DEBIAN_FRONTEND=noninteractive \
  apt-get update \
  -o Dpkg::Options::=--force-confold \
  -o Dpkg::Options::=--force-confdef \
  -y --allow-downgrades --allow-remove-essential --allow-change-held-packages

sudo DEBIAN_FRONTEND=noninteractive \
  apt-get upgrade \
  -o Dpkg::Options::=--force-confold \
  -o Dpkg::Options::=--force-confdef \
  -y --allow-downgrades --allow-remove-essential --allow-change-held-packages

Install Node.js 18.x:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Install Nginx:
```
sudo apt install nginx -y
```
Allow OpenSSH through the firewall:
```
sudo ufw allow OpenSSH
```
Enable the firewall:
```
sudo ufw --force enable
```

Allow necessary ports through the firewall:

sudo ufw allow 40000:49999/udp 
sudo ufw allow 40000:49999/tcp
sudo ufw allow http
sudo ufw allow https
sudo ufw allow 3000

Adjust the port if needed. By default, MediaSFU runs on port 3000.

Clone the MediaSFU repository and navigate into the directory:

git clone https://github.com/MediaSFU/MediaSFUOpen
cd MediaSFUOpen

Remove existing Node.js modules and package-lock.json file, then install dependencies:
```
sudo rm -rf node_modules package-lock.json
sudo npm install
```

Install Certbot:

sudo apt-get install certbot python3-certbot-nginx -y

Set up basic Nginx configuration:

Before obtaining SSL certificates, set up a basic Nginx configuration file. Replace example.com and demo.example.com with your domain details.

server {
    root /var/www/html;
    server_name example.com demo.example.com; #your domain details

    location / {
        proxy_pass http://localhost:3000; #whatever port your app runs on
        proxy_set_header X-Real-IP $remote_addr; # Capture client's real IP
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # Capture client's forwarded IP(s)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

You can find the Nginx configuration file at /etc/nginx/sites-available/default. Replace the existing configuration with the new configuration.

Obtain SSL certificates using Certbot:

sudo certbot --nginx -d example.mediasfu.com

Final Nginx configuration:

The final Nginx configuration should look like this:

server {
    root /var/www/html;
    server_name example.com demo.example.com; #your domain details

    location / {
        proxy_pass http://localhost:3000; #whatever port your app runs on
        proxy_set_header X-Real-IP $remote_addr; # Capture client's real IP
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; # Capture client's forwarded IP(s)
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}

server {
    if ($host = example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80;
    server_name example.com demo.example.com;
    return 404; # managed by Certbot
}

Restart Nginx:

  sudo systemctl restart nginx

Note: Replace example.com with your domain details. You may need to enable the Nginx service to start on boot:

 sudo systemctl enable nginx

Install PM2 globally:
```
sudo npm install pm2 -g
```

Edit the index.js file to specify your server's IP address:

Open the index.js file located in the root directory of your MediaSFUOpen installation.

Find the section of code where the IP address is specified, usually near the beginning of the file.

Change the IP address to your server's public IP address.

Save the changes and close the file.

// Example: Change this line to your server's public IP address
// If on AWS/GCP/Azure behind NAT, use your Elastic/Public IP (not a private 10.x/172.31.x)
const ip = 'your_server_public_ip';

If you're deploying on AWS/GCP/Azure (NAT/Elastic IP), also update your mediasoup transport config so the announced public IP is used by clients:

```javascript
// BEFORE
listenIps: [
    {
        ip: ip,
        announcedIp: null,
    },
],

// AFTER (cloud/NAT)
listenIps: [
    {
        ip: '0.0.0.0',
        announcedIp: ip, // your Elastic/Public IP here
    },
],
```

Updating the IP address ensures that MediaSFUOpen binds to the correct network interface and listens on the appropriate IP address.

🛡️ Edit the index.js file to specify safe origins for secure Socket.IO Connections

To restrict Socket.IO connections to specific origins for enhanced security, follow these steps:

Open the index.js file located in your Node.js application's directory.

Find the section of code where the safe origins are specified.

Add the origins you want to allow to the safeOrigins array.

Save the changes and close the file.
```
// Example: Define safe origins
const safeOrigins = [`https://localhost:${PORT}`];
```
Replace with the origins you want to allow. You can add as many origins as needed to the array. Example:
```
const safeOrigins = ['https://example.com', 'http://localhost:3000'];
```
Start the MediaSFU application using PM2:
```
sudo pm2 start index.js
```
Access the application:

You can access your MediaSFU application at /meeting/start on your domain. Starting a meeting is straightforward and easy. If you need help, refer to the documentation for a guide and full feature access.
Replace images and HTML files:

If needed, you can replace the images located in the public and public_alt folders with your own images. Additionally, update the HTML files in the project to match your brand.
Maximum Participants:

MediaSFU recommends a maximum of 100 participants on HD or 200 on SD video.

Once the installation is complete, your MediaSFU application will be running with SSL enabled, providing a secure streaming environment.

Running on Localhost

To run MediaSFU on localhost with SSL, follow these additional steps:

Generate SSL Certificates:

Generate self-signed SSL certificates for localhost. This is required for WebRTC and HTTPS. You can create a bash script or use openssl commands to generate the certificates. To create a script, create a file named localssl.sh (in the root directory) with the following content:
```
openssl genrsa -out local.com.key 2048
openssl req -new -x509 -key local.com.key -out local.com.pem -days 365 \
-subj "/C=US/ST=State/L=City/O=Organization/OU=OrgUnit/CN=localhost"

mkdir -p ssl
mv local.com.key local.com.pem ssl/
```
You may need to change the file permissions to make the script executable:
```
chmod +x localssl.sh
```
Run the script:
```
./localssl.sh
```
The script generates local.com.key and local.com.pem files in the ssl directory. These files are used for HTTPS.
Run the Localhost Server:

Use the following command to run the MediaSFU application on localhost:
```
npm run dev:local
```
Note: This runs the index_localhost.js file instead of index.js to use the local SSL certificates. You must therefore make any changes like the IP address in index_localhost.js instead of index.js.

Ensure that you access the application using https to utilize the SSL certificates.

Running on macOS or Windows (Local Development)

For local development or testing on macOS or Windows environments, please see the following additional guides:

These guides will cover:

Installing Node.js and dependencies on macOS or Windows.
Adjusting firewall settings or using system tools to open necessary ports.
Obtaining or creating SSL certificates and configuring your application to run securely.
Setting up reverse proxies (if needed) and local web servers.
Using PM2 or platform-specific process managers.
Any platform-specific instructions that differ from the Ubuntu production setup.

Cloud Recording & Egress

Cloud Recording and Egress are powerful features provided by MediaSFU.com as part of their MediaSFU Cloud services. These features enable functionalities such as cloud recording, capturing audio buffers, real-time image processing for machine learning (ML) applications (e.g., Large Language Models), and other egress purposes.

By default, MediaSFU is configured to support these egress capabilities. However, to utilize these features effectively, you need to perform specific configurations. This section provides detailed instructions on enabling cloud recording and configuring your client applications to connect securely to your MediaSFU server.

Overview

Enable Cloud Recording:
- Configure environment variables.
- Provide necessary API credentials.
- Set the operational mode (sandbox or production).
Connect Client Applications to MediaSFU Server:
- Configure safeOrigins for each client framework.
- Utilize MediaSFU Keys for enhanced security.
- Refer to Quickstart Guides for specific frameworks.
Security Best Practices:
- Implement authentication methods.
- Restrict cross-origin requests.
- Use SSL/TLS for encrypted communication.

1. Enable Cloud Recording

Cloud recording is a premium feature that allows you to record media streams for later playback, analysis, or processing.

Steps to Enable Cloud Recording:

Edit the .env File:

Open the .env file located in the root directory of your MediaSFU installation.
Set ALLOWRECORD to true:

Enable recording by modifying the ALLOWRECORD environment variable.
```
ALLOWRECORD=true
```
Provide API Credentials:

Obtain a valid username and API key from MediaSFU.com. These credentials are essential for authenticating recording requests.
```
APIUSERNAME=your_mediasfu_username
APIKEY=your_mediasfu_apikey
```
Set the Operational Mode:

MediaSFU offers different modes to suit your development and production needs.
- sandbox: Ideal for development and testing. It allows requests from non-registered domains but comes with usage limitations.
- production: Designed for live deployments. It restricts requests to registered domains and offers unlimited usage.
```
MODE=sandbox
```
or
```
MODE=production
```
Note: After editing the .env file, save the changes and restart your MediaSFU server to apply the new configurations.

Sample .env file:
- Edit the .env file:
  
  Open the .env file located in the root directory of your MediaSFU installation.
- Set ALLOWRECORD to true:
  
  Change the value of ALLOWRECORD to true.
```
ALLOWRECORD=true
```
- Provide API credentials:
  
  You need a valid username and API key from MediaSFU.com to enable recording. You can obtain these credentials from MediaSFU.com.
  - APIUSERNAME: Your MediaSFU username
  - APIKEY: Your MediaSFU API key
```
APIUSERNAME=your_mediasu_username
APIKEY=your_mediasfu_apikey
```
- Set the mode:
  
  MediaSFU provides demo, sandbox, and production keys. You may use either the sandbox or production mode.
  - MODE: Choose either sandbox or production mode based on your needs.
    - sandbox: Allows requests from non-registered domains but is limited.
    - production: Only allows requests from registered domains and is unlimited.
```
MODE=sandbox
```
  Make sure to save the changes after editing the .env file and restart.
Subscription Plans:

For detailed information about available subscription plans, visit MediaSFU Subscription Info.

Note:
The majority of subscription fees are designed to support large organizations and institutions that manage numerous users under a single profile. This structure allows for the efficient handling of sub-users, ensuring seamless scalability and robust support. The fees help cover the overhead costs associated with maintaining and servicing extensive client bases, providing reliable performance and dedicated resources to meet the needs of large-scale deployments.

Additional Note:
If your organization does not require support for a large number of users, please contact our support team. We can credit your account and adjust your subscription to accommodate a reduced number of sub-user limits, ensuring you only pay for the resources you need.