mediasfu-shared

This guide gives you the public setup path for the mediasfu-shared package and points to generated API references when you need exact signatures or types.

Quick start

• Best for: Shared core logic across frameworks
• Package/artifact: mediasfu-shared
• Install: npm i mediasfu-shared socket.io-client mediasoup-client

---

Start in 60 seconds

1. Install the package and peer dependencies: npm i mediasfu-shared socket.io-client mediasoup-client
2. Pick backend mode: MediaSFU Cloud or self-hosted MediaSFU Open.
3. Follow the first setup section below for your framework.

Before you continue

• Best for: Shared core logic across frameworks
• New to MediaSFU? Start at /sdks to compare frameworks quickly.

Copy/paste starter

Use this minimal setup to validate your backend and socket path quickly.

import { connectSocket, SocketManager } from 'mediasfu-shared';

async function boot() {
  const socket = await connectSocket({
    apiUserName: process.env.MEDIASFU_API_USERNAME ?? '',
    apiKey: process.env.MEDIASFU_API_KEY ?? '',
    apiToken: process.env.MEDIASFU_API_TOKEN ?? '',
    link: process.env.MEDIASFU_SOCKET_URL ?? 'https://mediasfu.com/socket',
  });

  const socketManager = new SocketManager({ socket });
  return socketManager;
}

Keep credentials in environment variables and avoid committing secrets.

Do not skip this order

1. Decide backend mode first: MediaSFU Cloud or your self-hosted deployment.
2. Validate the socket and auth path with one minimal happy-path request before wrapping the shared layer in framework code.
3. Add product-specific orchestration only after the backend and transport path are confirmed.
4. Use the generated API reference only when you need exact method or type signatures.

This order keeps connection and credential issues separate from wrapper or app-shell bugs.

Choose your backend mode

Mode	Best for	What you must provide
MediaSFU Cloud	Fastest onboarding, managed infrastructure, less operational work	Cloud credentials stored in secure runtime or build configuration.
MediaSFU Open / self-hosted	Private infrastructure, local control, custom deployment requirements	A self-hosted MediaSFU-compatible endpoint plus the connection details your wrapper passes into the shared layer.

If you have not made this choice yet, make it before going deeper into customization or API reference material.

API reference

• Start with the portal overview at /api-reference.
• Use the mediasfu-shared entry on that page to open the staged TypeDoc site for this package at /api/shared/.

Use the SDK guide for workflow guidance and the staged TypeDoc site for exact package details, generated symbols, and signatures.

Common setup mistakes

• Skipping peer dependencies (socket.io-client, mediasoup-client).
• Using browser-only APIs in server contexts without guards.
• Hard-coding secrets in source instead of environment variables.
• Backend endpoint unreachable (Cloud credentials invalid or self-hosted server offline).
• Credentials committed directly in source files instead of secure environment configuration.

If setup fails, verify install → backend mode → credentials/local link in that order.

Troubleshooting quick checks

Check	Symptom	Quick fix
Backend mode mismatch	Requests fail or hang	Confirm Cloud credentials or self-hosted URL, then re-test socket connection.
Credentials not loaded	Auth/connect errors	Verify env loading and pass credentials explicitly to SDK config.
Dependency mismatch	Build/install warnings	Reinstall dependencies and avoid force-install flags unless absolutely required.

Use this table first before diving into deeper API sections.

Production readiness checklist

• Backend mode decided (Cloud vs self-hosted) and documented.
• Credentials/keys sourced from secure environment config (not hard-coded).
• Peer dependencies installed and locked in package manager lockfile.
• Happy-path join/create flow validated end-to-end.
• Release build passes cleanly in the target app environment.

Mark all items before release.

---

📦 About

mediasfu-shared is the universal shared library that powers all MediaSFU framework-specific SDKs (React, Vue, Angular, etc.). It provides the core WebRTC functionality, media handling, socket communication, and state management that enables real-time video conferencing, screen sharing, recording, and interactive features across all MediaSFU implementations.

This package contains framework-agnostic implementations of:

• Media Consumers - WebRTC transport and stream management
• Core Methods - Room creation, participant handling, recording controls
• Socket Management - Real-time communication with MediaSFU servers
• Type Definitions - Comprehensive TypeScript types for all MediaSFU features
• Utility Functions - Helper methods for media processing and state management

🎯 Key Features

• ✅ Framework Agnostic - Pure TypeScript/JavaScript implementation
• ✅ WebRTC Integration - Full mediasoup-client support for advanced WebRTC features
• ✅ Type-Safe - Complete TypeScript definitions for all APIs
• ✅ Real-Time Communication - Socket.io integration for instant updates
• ✅ Modular Architecture - Import only what you need for optimal bundle size
• ✅ Production Ready - Battle-tested in MediaSFU's production environment

📥 Installation

npm install mediasfu-shared

Peer Dependencies

This package requires the following peer dependencies:

npm install socket.io-client mediasoup-client

🚀 Usage

Importing Core Functions

import { 
  connectSocket,
  joinRoomClient,
  updateRoomParametersClient,
  createDeviceClient,
  SocketManager 
} from 'mediasfu-shared';

// Initialize socket connection
const socket = await connectSocket({
  apiUserName: 'your-api-username',
  apiKey: 'your-api-key',
  apiToken: 'your-api-token',
  link: 'https://mediasfu.com/socket'
});

// Create SocketManager instance
const socketManager = new SocketManager({ socket });

Using Consumers

import { 
  consumerResume,
  addVideosGrid,
  prepopulateUserMedia 
} from 'mediasfu-shared';

// Resume a paused consumer
await consumerResume({
  id: 'consumer-id',
  parameters: roomParameters,
  socket: socketManager.socket
});

// Add video streams to grid
await addVideosGrid({
  consumers: activeConsumers,
  parameters: roomParameters
});

Type Definitions

import type { 
  Participant,
  Transport,
  Stream,
  EventType,
  ShowAlert,
  CoHostResponsibility,
  Settings
} from 'mediasfu-shared';

const participant: Participant = {
  id: 'participant-123',
  name: 'John Doe',
  audioID: 'audio-stream-id',
  videoID: 'video-stream-id',
  islevel: '1'
};

🏗️ Package Structure

mediasfu-shared/
├── consumers/          # WebRTC consumer management
│   ├── addVideosGrid
│   ├── consumerResume
│   └── prepopulateUserMedia
├── methods/           # Core functionality methods
│   ├── breakoutRoomsMethods/
│   ├── recordingMethods/
│   ├── participantsMethods/
│   ├── messageMethods/
│   ├── mediaMethods/
│   └── utils/
├── producers/         # Producer client implementations
├── sockets/          # Socket.io management
├── types/            # TypeScript type definitions
└── index.ts          # Main entry point

📚 Documentation

For detailed documentation on specific methods and types, please visit:

• Main Documentation: https://mediasfu.com/documentation
• API Reference: https://mediasfu.com/docs
• React SDK: mediasfu-reactjs
• Vue SDK: mediasfu-vue

You can also generate package-local API docs directly from the canonical shared source with:

npm run build-docs

The shared package now uses typedoc.json with src/index.ts as the documentation entrypoint, so exported JSDoc on the shared implementations becomes the generated API reference.

🔗 Related Packages

mediasfu-shared is used by all MediaSFU framework-specific packages:

• mediasfu-reactjs - React components and hooks
• mediasfu-vue - Vue 3 components and composables
• mediasfu-angular - Angular components and services

🤝 Integration with MediaSFU Community Edition (CE)

This package is designed to work seamlessly with MediaSFU CE, our open-source community edition server. MediaSFU CE provides:

• Complete WebRTC SFU server implementation
• Recording and streaming capabilities
• Breakout rooms and advanced features
• Free for self-hosting

💬 Support

Need help? We're here for you!

• GitHub Issues: Report bugs or request features
• Email Support: info@mediasfu.com

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by the MediaSFU Team