MediaSFU Flutter

Essential next steps

• API and reference documentation
• Choose standard, hybrid, or fully headless UI
• Headless and hybrid implementation
• Starter projects and showcases
• Framework examples and recipes
• Current release and migration notes
• Troubleshooting and recovery

Build a MediaSFU room in a Flutter application with mediasfu_sdk. This guide targets the 2.3.6 API. Obtain that exact package version through your organisation's approved delivery process and pin it before copying the code. For an isolated local prototype, use only restricted, revocable development credentials and never commit them. Before sharing or releasing the app, move reusable Cloud credentials behind the production credential boundary.

Install

Add mediasfu_sdk version 2.3.6 through the package source approved for your application, then check the resolved version in pubspec.lock. Use the examples below only with 2.3.6.

dependencies:
  mediasfu_sdk: 2.3.6

The package declares Dart >=3.10.0 <4.0.0 and Flutter >=3.38.1.

Before you run a room, complete the camera, microphone, and display-capture permissions required by every platform you ship. On web, use HTTPS for real camera, microphone, and display-capture tests.

Build a room without client credentials

MediasfuGenericOptions accepts createMediaSFURoom and joinMediaSFURoom callbacks. Use them to send only the requested room payload to an authenticated application backend. Your backend applies room policy, holds any long-lived credential, and returns the SDK-compatible room result.

import 'package:mediasfu_sdk/mediasfu_sdk.dart';
import 'package:mediasfu_sdk/components/mediasfu_components/mediasfu_generic.dart'
    show MediasfuGenericOptions;
import 'package:mediasfu_sdk/methods/utils/create_join_room.dart'
    show CreateJoinRoomResult;
import 'package:mediasfu_sdk/methods/utils/create_room_on_media_sfu.dart'
    show CreateMediaSFUOptions;
import 'package:mediasfu_sdk/methods/utils/join_room_on_media_sfu.dart'
    show JoinMediaSFUOptions;

abstract interface class RoomBackend {
  Future<CreateJoinRoomResult> create(CreateMediaSFURoomOptions payload);
  Future<CreateJoinRoomResult> join(JoinMediaSFURoomOptions payload);
}

class RoomGateway {
  RoomGateway(this.backend);

  final RoomBackend backend;

  Future<CreateJoinRoomResult> create(CreateMediaSFUOptions request) {
    return backend.create(request.payload);
  }

  Future<CreateJoinRoomResult> join(JoinMediaSFUOptions request) {
    return backend.join(request.payload);
  }
}

MediasfuGeneric room(RoomBackend backend) {
  final gateway = RoomGateway(backend);

  return MediasfuGeneric(
    options: MediasfuGenericOptions(
      createMediaSFURoom: gateway.create,
      joinMediaSFURoom: gateway.join,
    ),
  );
}

The SDK calls these callbacks with CreateMediaSFUOptions or JoinMediaSFUOptions; the room intent is in request.payload. The gateway above deliberately ignores the request's credential fields. Do not forward those fields to your backend or use the built-in createRoomOnMediaSFU and joinRoomOnMediaSFU helpers for a production client.

Your backend adapter should return CreateJoinRoomResult with the room data expected by the SDK. A successful create or join lets the supplied room continue into its room flow. For an expired app session, denied room policy, or unavailable room, show the application error, let the person sign in or choose another room as appropriate, and retry only with a fresh backend response. See the secure backend pattern for the server boundary.

What the supplied room handles

Start with MediasfuGeneric for a complete room. Choose MediasfuConference, MediasfuWebinar, MediasfuBroadcast, MediasfuChat, or ModernMediasfuGeneric when the room shape is already fixed.

After joining, MediasfuParameters carries the current room state and runtime actions for custom UI. The supplied surface includes participant, waiting-room, request, co-host, message, poll, breakout, recording, whiteboard, and background-control components. A participant list is ready to render when the parameters callback gives your screen a non-null value; re-render it whenever the callback supplies newer parameters.

For a custom room surface, use returnUI: false and store updateSourceParameters. The state gives you the participant collection and the media actions rather than a React-style API.

void observeRoom(MediasfuParameters parameters) {
  final people = parameters.participants;
  final screenIsActive = parameters.shareScreenStarted;

  // Bind these values to your own participant list and controls.
  debugPrint('People: ${people.length}; screen share: $screenIsActive');
}

Start media and share a screen

The runtime exposes clickAudio, clickVideo, and clickScreenShare; lower-level functions include prepopulateUserMedia, processConsumerTransports, startShareScreen, and stopShareScreen. Start with the supplied controls. The media path is ready when permission is granted, the local microphone or camera is active, and a second participant can receive the selected media. If permission is denied, keep the person in the room, explain which permission is needed, and offer a retry after they change it in the operating system or browser.

Use clickScreenShare to request display capture. A successful share updates shareScreenStarted and shows the selected display to other eligible participants. Always offer a stop control: it must call the screen-share stop path and return the UI to its non-sharing state. If a browser or operating system rejects the picker, leave camera and microphone controls available and explain that no screen was shared.

Leave safely

For a participant exit, use the supplied ConfirmExitModal and confirmExit path. In a headless screen, use the current parameters and choose the host semantics explicitly:

final parameters = controller.parameters;
if (parameters == null) return;

final endRoom = await leaveRoom(parameters, endRoomOnHostExit: true);
final leaveAndKeepOpen = await leaveRoom(
  parameters,
  endRoomOnHostExit: false,
);

The option defaults to true. Use false only for a control labelled Leave and keep room open, await the result, and then clear app-owned state. A host returns through the normal authorized join flow. In a two-person test, verify that preserve-room leave keeps the other participant connected and that host end closes the room for everyone. Flutter does not provide a verified public host-end emitter separate from this role-aware leave path.

Release checklist

• Create and join work through your authenticated backend with no reusable MediaSFU Cloud credential in the app.
• Camera and microphone permissions work on every shipping platform.
• Two people can see the participant list and each other's media.
• Screen sharing starts and stops cleanly where your product offers it.
• Participant leave clears local UI state and is visible to another participant.
• Your app handles denied access, expired authorization, network loss, and cleanup.
• Host end and host leave-without-ending are labelled separately and produce the expected result for another participant.

The isolated Flutter room example for this guide exercises the secure create and join adapter with local fakes. It deliberately does not open a room, request a device, or contact a service.