mediasfu_sdk 2.2.8

Flutter WebRTC SDK for video conferencing, webinars, live streaming, chat, whiteboards, recording, translation, and AI-powered meeting apps with MediaSFU.

MediaSFU Flutter SDK

mediasfu_sdk is the official Flutter WebRTC SDK for building MediaSFU-powered video conferencing, webinar, broadcast, live streaming, chat, whiteboard, recording, translation, and AI-assisted meeting experiences across Android, iOS, Web, macOS, Windows, and Linux.

Why Teams Choose MediaSFU

• Start with a prebuilt room UI, then move to headless or deeply customized layouts when your product matures.
• Use MediaSFU Cloud for managed infrastructure or localLink for self-hosted MediaSFU Open and proxy-backed deployments.
• Ship one SDK for voice, video, chat, screen sharing, whiteboard, breakout rooms, recording, real-time translation, and AI-adjacent meeting workflows.
• Lean on public docs, generated API docs, sandbox tools, and the MediaSFU community forum when integration questions come up.

Search-Friendly Use Cases

Developers usually arrive here looking for one or more of these real use cases:

• Flutter video conferencing SDK
• Flutter WebRTC SDK
• Flutter webinar SDK
• Flutter broadcast or live streaming SDK
• Flutter chat and meeting room SDK
• Flutter whiteboard and collaboration SDK
• Flutter real-time translation SDK
• Flutter headless video room SDK
• Flutter AI meeting or AI notes integration surface

The package is designed for three integration styles:

Integration style	Use this when	Main APIs
Prebuilt UI	You want a complete room UI quickly	MediasfuGeneric, MediasfuConference, MediasfuWebinar, MediasfuBroadcast, MediasfuChat, ModernMediasfuGeneric
Headless runtime	You want MediaSFU connection/media logic but your own UI	returnUI: false, updateSourceParameters, MediasfuParameters
Custom UI with SDK components	You want to replace selected cards, modals, or layouts	custom builders, MediasfuUICustomOverrides, exported components

For the full long-form guide, see README_DETAILED.md. For native permissions and platform setup, see PLATFORM_SETUP.md.

Table Of Contents

• Install
• Why Teams Choose MediaSFU
• Search-Friendly Use Cases
• Backend Model
• Quick Start: Prebuilt Room
• Try The UI Without A Live Room
• Choose A Room Widget
• Headless Mode
• Create And Join Rooms Programmatically
• Self-Hosted MediaSFU Open
• Platform Setup
• Common Options
• Customization
• Feature Map
• Troubleshooting
• Docs, Support, And Search Map
• LLM And Code Search Hints

Install

flutter pub add mediasfu_sdk

Minimum package requirements:

Requirement	Version
Dart	>=3.3.3 <4.0.0
Flutter	>=1.17.0

Use the package barrel import in application code:

import 'package:mediasfu_sdk/mediasfu_sdk.dart';

Optional features may need extra dependencies in your app:

# Android / iOS virtual backgrounds
google_mlkit_selfie_segmentation: ^0.10.0

# Web whiteboard and capture helpers
web: ^1.1.1
dart_webrtc: ^1.4.6

Backend Model

MediaSFU is not a standalone offline video widget. The Flutter package needs a MediaSFU-compatible backend for room creation, signaling, media routing, and runtime coordination.

Backend	Best for	What the Flutter app passes
MediaSFU Cloud	Managed production rooms with minimal infrastructure	Credentials(apiUserName, apiKey)
MediaSFU Open / self-hosted	On-premise, private, or custom backend deployments	localLink, and optional local auth fields such as localAppKey, localApiUserName, localApiKey, localSubUserName
Your backend proxy	Production apps that should not expose privileged API keys	App-specific token/room data returned by your backend, then passed into SDK options

The built-in helper endpoints are:

Helper	MediaSFU Cloud endpoint	Self-hosted endpoint when localLink is not a MediaSFU domain
createRoomOnMediaSFU	https://mediasfu.com/v1/rooms	${localLink}/createRoom
joinRoomOnMediaSFU	https://mediasfu.com/v1/rooms/	${localLink}/joinRoom

Security note: avoid embedding privileged production credentials in public clients unless that is an intentional part of your architecture. A backend proxy is usually safer for production mobile and web apps.

Quick Start: Prebuilt Room

This is the fastest working path for MediaSFU Cloud.

import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: MediasfuGeneric(
        options: MediasfuGenericOptions(
          credentials: Credentials(
            apiUserName: 'your-api-username',
            apiKey: 'your-64-character-api-key',
          ),
        ),
      ),
    );
  }
}

Run it:

flutter run

The default MediasfuGeneric flow shows the pre-join page, lets the user create or join a room, then renders the meeting experience with media controls, chat, participants, recording controls, polls, whiteboard, and related modals.

Try The UI Without A Live Room

Use local UI mode when you want to test layouts, demos, screenshots, or custom components without connecting to a live room.

MediasfuGeneric(
  options: MediasfuGenericOptions(
    useLocalUIMode: true,
    useSeed: true,
    seedData: SeedData(
      member: 'Demo User',
      eventType: EventType.conference,
    ),
  ),
)

This is useful for frontend work, visual QA, and rapid prototyping. It does not replace a real backend validation pass before release.

Choose A Room Widget

Start with MediasfuGeneric or ModernMediasfuGeneric when you are still shaping the product. Move to the event-specific widgets when the room type is fixed.

Widget	Use case
MediasfuGeneric	General room experience that can support multiple event types
ModernMediasfuGeneric	Modern UI path with extra translation, fixed-link, and navigation options
MediasfuConference	Meeting and team collaboration rooms
MediasfuWebinar	Host, panelist, and attendee workflows
MediasfuBroadcast	Broadcast and one-to-many streaming experiences
MediasfuChat	Chat-first rooms with optional media workflows

Example:

MediasfuConference(
  options: MediasfuConferenceOptions(
    credentials: Credentials(
      apiUserName: 'your-api-username',
      apiKey: 'your-64-character-api-key',
    ),
  ),
)

Modern UI example:

ModernMediasfuGeneric(
  options: ModernMediasfuGenericOptions(
    credentials: Credentials(
      apiUserName: 'your-api-username',
      apiKey: 'your-64-character-api-key',
    ),
    initialMeetingId: 'optional-room-id',
    onBack: () {
      // Route back with your app router.
    },
  ),
)

Headless Mode

Set returnUI: false when your app should own the visual interface while MediaSFU owns connection setup, room state, media state, and helper methods.

import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';

class HeadlessMeeting extends StatefulWidget {
  const HeadlessMeeting({super.key});

  @override
  State<HeadlessMeeting> createState() => _HeadlessMeetingState();
}

class _HeadlessMeetingState extends State<HeadlessMeeting> {
  MediasfuParameters? parameters;

  @override
  Widget build(BuildContext context) {
    return Stack(
      children: [
        MediasfuGeneric(
          options: MediasfuGenericOptions(
            credentials: Credentials(
              apiUserName: 'your-api-username',
              apiKey: 'your-64-character-api-key',
            ),
            returnUI: false,
            updateSourceParameters: (nextParameters) {
              setState(() => parameters = nextParameters);
            },
          ),
        ),
        if (parameters == null)
          const Center(child: CircularProgressIndicator())
        else
          MyMeetingSurface(parameters: parameters!),
      ],
    );
  }
}

class MyMeetingSurface extends StatelessWidget {
  final MediasfuParameters parameters;

  const MyMeetingSurface({super.key, required this.parameters});

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Text('Room: ${parameters.roomName}'),
        Text('Participants: ${parameters.participants.length}'),
        ElevatedButton(
          onPressed: () => parameters.updateIsMessagesModalVisible(true),
          child: const Text('Open chat'),
        ),
      ],
    );
  }
}

For headless mode you usually provide one of these pre-join payloads:

MediasfuGeneric(
  options: MediasfuGenericOptions(
    returnUI: false,
    credentials: credentials,
    noUIPreJoinOptionsCreate: CreateMediaSFURoomOptions(
      action: 'create',
      duration: 60,
      capacity: 25,
      userName: 'Host User',
      eventType: EventType.conference,
    ),
    updateSourceParameters: (parameters) {
      // Store parameters in app state.
    },
  ),
)

or:

MediasfuGeneric(
  options: MediasfuGenericOptions(
    returnUI: false,
    credentials: credentials,
    noUIPreJoinOptionsJoin: JoinMediaSFURoomOptions(
      action: 'join',
      meetingID: 'room-id',
      userName: 'Guest User',
    ),
    updateSourceParameters: (parameters) {
      // Store parameters in app state.
    },
  ),
)

Create And Join Rooms Programmatically

You can call the room helpers directly when your app has its own lobby, schedule screen, or invite flow.

final createResult = await createRoomOnMediaSFU(
  CreateMediaSFUOptions(
    apiUserName: 'your-api-username',
    apiKey: 'your-64-character-api-key',
    payload: CreateMediaSFURoomOptions(
      action: 'create',
      duration: 60,
      capacity: 25,
      userName: 'Host User',
      eventType: EventType.conference,
      supportTranslation: true,
    ),
  ),
);

if (createResult.success) {
  final room = createResult.data as CreateJoinRoomResponse;
  debugPrint('Created ${room.roomName}: ${room.link}');
} else {
  final error = createResult.data as CreateJoinRoomError;
  debugPrint('Room creation failed: ${error.error}');
}

Join an existing room:

final joinResult = await joinRoomOnMediaSFU(
  JoinMediaSFUOptions(
    apiUserName: 'your-api-username',
    apiKey: 'your-64-character-api-key',
    payload: JoinMediaSFURoomOptions(
      action: 'join',
      meetingID: 'room-id',
      userName: 'Guest User',
    ),
  ),
);

if (joinResult.success) {
  final room = joinResult.data as CreateJoinRoomResponse;
  debugPrint('Joined ${room.roomName}');
}

Self-Hosted MediaSFU Open

Use localLink for self-hosted or proxy-backed deployments.

MediasfuGeneric(
  options: MediasfuGenericOptions(
    localLink: 'https://media.example.com',
    connectMediaSFU: true,
    credentials: Credentials(
      apiUserName: 'proxy-or-local-user',
      apiKey: 'your-64-character-api-key',
    ),
  ),
)

Modern self-hosted example with local socket handshake fields:

ModernMediasfuGeneric(
  options: ModernMediasfuGenericOptions(
    localLink: 'https://media.example.com',
    connectMediaSFU: true,
    credentials: credentials,
    localAppKey: 'your-app-key',
    localApiUserName: 'local-api-user',
    localApiKey: 'local-api-key',
    localSubUserName: 'team-member',
    useFixedLink: true,
    initialMeetingId: 'room-id',
  ),
)

When localLink is set to a non-MediaSFU domain, createRoomOnMediaSFU uses ${localLink}/createRoom and joinRoomOnMediaSFU uses ${localLink}/joinRoom.

Platform Setup

Most media failures are caused by missing host-app permissions. Configure each target platform before testing production flows.

Platform	Required setup
Android	Camera, microphone, internet permissions; min SDK and ProGuard rules as needed
iOS	NSCameraUsageDescription, NSMicrophoneUsageDescription, local network permissions if applicable
macOS	Camera, microphone, and network entitlements
Web	HTTPS in production, browser media permissions, CORS for self-hosted servers
Windows	Flutter desktop setup and camera/microphone device permissions
Linux	Flutter desktop setup plus system media dependencies

See PLATFORM_SETUP.md for copy-ready native configuration snippets.

Common Options

These options appear across the prebuilt room widgets.

Option	Type	Purpose
credentials	Credentials?	MediaSFU Cloud or backend auth values
localLink	String?	Self-hosted/proxy server base URL
connectMediaSFU	bool?	Whether the SDK should connect to MediaSFU services
returnUI	bool?	true renders the prebuilt UI; false runs headless
updateSourceParameters	Function(MediasfuParameters?)?	Receives the runtime helper/state bundle
noUIPreJoinOptionsCreate	CreateMediaSFURoomOptions?	Create-room payload for headless mode
noUIPreJoinOptionsJoin	JoinMediaSFURoomOptions?	Join-room payload for headless mode
createMediaSFURoom	CreateRoomOnMediaSFUType?	Replace the create-room helper
joinMediaSFURoom	JoinRoomOnMediaSFUType?	Replace the join-room helper
useLocalUIMode	bool?	Run the UI without live room connections
seedData / useSeed	SeedData? / bool?	Seed demo participant and room data
customVideoCard	VideoCardType?	Replace video cards
customAudioCard	AudioCardType?	Replace audio cards
customMiniCard	MiniCardType?	Replace mini participant cards
customComponent	CustomComponentType?	Replace the whole room workspace
containerStyle	ContainerStyleOptions?	Style the room container
uiOverrides	MediasfuUICustomOverrides?	Wrap or replace specific SDK widgets/functions

Modern-only extras include useFixedLink, localAppKey, localApiUserName, localApiKey, localSubUserName, initialMeetingId, canUsePersonalTranslation, personalTranslationUsername, userVoiceClones, onBack, and optimizeVideoRecord.

Customization

Replace common media cards

MediasfuGeneric(
  options: MediasfuGenericOptions(
    credentials: credentials,
    customVideoCard: ({
      required participant,
      required stream,
      required width,
      required height,
      imageSize,
      doMirror,
      showControls,
      showInfo,
      name,
      backgroundColor,
      onVideoPress,
      parameters,
    }) {
      return SizedBox(
        width: width,
        height: height,
        child: DecoratedBox(
          decoration: BoxDecoration(
            color: backgroundColor ?? Colors.black,
            border: Border.all(color: Colors.blueAccent, width: 2),
            borderRadius: BorderRadius.circular(12),
          ),
          child: Center(
            child: Text(
              name ?? participant.name,
              style: const TextStyle(color: Colors.white),
            ),
          ),
        ),
      );
    },
  ),
)

The exact builder signatures are exported by the package types. Use your editor autocomplete from package:mediasfu_sdk/mediasfu_sdk.dart for the required parameters.

Wrap one SDK component with MediasfuUICustomOverrides

final overrides = MediasfuUICustomOverrides(
  participantsModal: ComponentOverride<ParticipantsModalOptions>(
    render: (context, options, defaultBuilder) {
      return Theme(
        data: Theme.of(context).copyWith(
          colorScheme: ColorScheme.fromSeed(seedColor: Colors.indigo),
        ),
        child: defaultBuilder(context, options),
      );
    },
  ),
);

MediasfuGeneric(
  options: MediasfuGenericOptions(
    credentials: credentials,
    uiOverrides: overrides,
  ),
)

Frequently overridden slots include mainContainer, mainGrid, controlButtons, participantsModal, messagesModal, recordingModal, pollModal, breakoutRoomsModal, configureWhiteboardModal, backgroundModal, preJoinPage, and welcomePage.

Replace the full workspace

MediasfuGeneric(
  options: MediasfuGenericOptions(
    credentials: credentials,
    customComponent: ({required parameters}) {
      return MyFullMeetingWorkspace(parameters: parameters);
    },
  ),
)

Use this when you want MediaSFU to provide the runtime state and methods while your app owns the complete room UI.

Custom icons and Font Awesome v11

The package uses font_awesome_flutter v11. When rendering Font Awesome icons directly, use FaIcon:

import 'package:font_awesome_flutter/font_awesome_flutter.dart';

const FaIcon(FontAwesomeIcons.xmark)

For SDK share button options, both Flutter IconData values and Font Awesome FaIconData values are supported:

ShareButtonOptions(
  icon: FontAwesomeIcons.whatsapp,
  action: () {},
)

Feature Map

Feature area	SDK surface
Audio/video rooms	MediasfuGeneric, MediasfuConference, MediasfuParameters, media card builders
Webinars and panelists	MediasfuWebinar, panelist methods, modern panelist modal
Broadcasts	MediasfuBroadcast
Chat rooms	MediasfuChat, messages modal, message methods
Screen sharing	screen-share methods, screen producer helpers, screenboard components
Recording	recording modal and recording methods
Polls	poll modal and poll methods
Breakout rooms	breakout room modal and launch methods
Whiteboard	whiteboard, screenboard, configure whiteboard modal, capture helpers
Virtual backgrounds	background modal, processor service, platform-specific ML dependency
Waiting rooms	waiting modal and waiting methods
Co-hosts	co-host modal and co-host methods
Permissions	permission methods and modern permissions modal
Translation	modern translation settings, translation room config, personal translation options
SIP / telephony-ready rooms	CreateMediaSFURoomOptions.supportSIP, directionSIP, preferPCMA
AI notes and agents	configure from the MediaSFU dashboard/docs, then use room/runtime features in the SDK

Troubleshooting

Symptom	Check
Pre-join shows credential errors	apiUserName must not be a placeholder and apiKey must be a valid 64-character key
Camera or microphone does not open	Native platform permissions, HTTPS on web, and OS privacy settings
Web works locally but not in production	HTTPS, browser permission prompts, CORS for self-hosted APIs, and TURN/STUN reachability
Self-hosted create/join fails	Verify localLink, /createRoom, /joinRoom, TLS, CORS, and backend auth headers
Headless mode renders no UI	This is expected with returnUI: false; render your own widgets from MediasfuParameters
Demo mode connects unexpectedly	Use useLocalUIMode: true with seed data and avoid live credentials for visual-only demos
Font Awesome compile error with Icon(FontAwesomeIcons.xmark)	Use FaIcon(FontAwesomeIcons.xmark) with font_awesome_flutter v11
Analyzer reports only info-level lints	The package may still build; clean those lints separately if your CI treats infos as fatal

Docs, Support, And Search Map

Current MediaSFU documentation and support entry points:

Need	Link
Flutter SDK docs	mediasfu.com/flutter
Developer docs portal	mediasfu.com/docs
Quick start guide	mediasfu.com/docs/usage/quickstart
Headless guide	mediasfu.com/docs/usage/headless
Documentation map	mediasfu.com/docs/guide-map
Generated API docs	mediasfu.com/docs/api
Developer console / API configuration	mediasfu.com/documentation
Dashboard user guide	mediasfu.com/user-guide
Sandbox	mediasfu.com/sandbox
Widget Studio	mediasfu.com/widget-studio
AI agents	mediasfu.com/agents
AI notes	mediasfu.com/ai-notes-guide
Translation	mediasfu.com/translation
SIP / telephony	mediasfu.com/telephony
Community support	mediasfu.com/forums
Contact	mediasfu.com/contact
GitHub organization	github.com/MediaSFU

Community forum categories include General Help, Deployment Issues, Mobile SDK, Web SDK, Integrations, Announcements, and Feature Requests. For Flutter package questions, use the Mobile SDK category and include your platform, Flutter version, package version, backend mode, and the smallest reproducible snippet.

LLM And Code Search Hints

This section intentionally repeats the canonical names that developers and AI coding tools should use when searching or generating integrations.

• Package name: mediasfu_sdk
• Import: package:mediasfu_sdk/mediasfu_sdk.dart
• Main prebuilt Flutter widgets: MediasfuGeneric, MediasfuConference, MediasfuWebinar, MediasfuBroadcast, MediasfuChat, ModernMediasfuGeneric
• Main options classes: MediasfuGenericOptions, MediasfuConferenceOptions, MediasfuWebinarOptions, MediasfuBroadcastOptions, MediasfuChatOptions, ModernMediasfuGenericOptions
• Credentials class: Credentials(apiUserName, apiKey)
• Room helper payloads: CreateMediaSFURoomOptions, JoinMediaSFURoomOptions
• Room helper functions: createRoomOnMediaSFU, joinRoomOnMediaSFU
• Runtime state and methods: MediasfuParameters
• UI override type: MediasfuUICustomOverrides
• Demo mode types: SeedData, EventType
• Backend keywords: MediaSFU Cloud, MediaSFU Open, self-hosted, localLink, /createRoom, /joinRoom
• Feature keywords: Flutter video conferencing, Flutter WebRTC meeting SDK, Flutter webinar SDK, Flutter broadcast SDK, Flutter whiteboard, Flutter breakout rooms, Flutter live translation, Flutter AI meeting notes, Flutter SIP room, Flutter headless video SDK

When asking an AI assistant for help, include the package version, the selected widget, whether you use MediaSFU Cloud or localLink, the target platform, and the exact error text.

Related SDKs

Platform/framework	Package or docs
Flutter	pub.dev/packages/mediasfu_sdk
React	mediasfu.com/reactjs
Angular	mediasfu.com/angular
Vue	mediasfu.com/vue
React Native CLI	mediasfu.com/reactnative
React Native Expo	mediasfu.com/reactnativeexpo
JavaScript	mediasfu.com/javascript

License

MIT. See LICENSE.