mediasfu_sdk 2.0.0 
mediasfu_sdk: ^2.0.0 copied to clipboard
mediasfu.comMediaSFU SDK for Flutter provides powerful streaming capabilities for creating high-performance cross-platform applications.
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.
MediaSFU Flutter Package Documentation #
Unlock the Power of MediaSFU Community Edition #
MediaSFU Community Edition is free and open-source—perfect for developers who want to run their own media server without upfront costs. With robust features and simple setup, you can launch your media solution in minutes. Ready to scale? Upgrade seamlessly to MediaSFU Cloud for enterprise-grade performance and global scalability.
Table of Contents #
- Features
- Getting Started
- Basic Usage Guide
- Intermediate Usage Guide
- Advanced Usage Guide
- API Reference
- Troubleshooting
- Contributing
Features #
MediaSFU's Flutter SDK comes with a host of powerful features out of the box:
- Breakout Rooms: Create multiple sub-meetings within a single session to enhance collaboration and focus.
- Pagination: Efficiently handle large participant lists with seamless pagination.
- Polls: Conduct real-time polls to gather instant feedback from participants.
- Media Access Requests Management: Manage media access requests with ease to ensure smooth operations
- Chat (Direct & Group): Facilitate communication with direct and group chat options.
- Cloud Recording (track-based): Customize recordings with track-based options, including watermarks, name tags, background colors, and more.
- Managed Events: Manage events with features to handle abandoned and inactive participants, as well as enforce time and capacity limits.
Getting Started #
This section will guide users through the initial setup and installation of the Flutter package.
Documentation Reference #
For comprehensive documentation on the available methods, components, and functions, please visit mediasfu.com. This resource provides detailed information for this guide and additional documentation.
Installation #
To install the package using Flutter, follow the instructions below:
1. Add the mediasfu_sdk package to your project by running the following command: #
```bash
flutter pub add mediasfu_sdk
```
2. Obtain an API Key (If Required) #
You can get your API key by signing up or logging into your account at mediasfu.com.
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.
3. 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.
This setup allows full flexibility and customization while bypassing the need for cloud-dependent credentials.
4. Configure Your Project #
To ensure that your Flutter app has the necessary permissions and configurations for camera, microphone, and network access on both iOS and Android platforms, follow the detailed steps below.
iOS Setup
-
Minimum iOS Platform Version
-
Navigate to your
ios/Podfilelocated in your project's iOS directory. -
Find the line specifying the iOS platform version.
-
Update the minimum iOS platform version to
12.0:platform :ios, '12.0'
-
-
Info.plist Updates
-
Open your
Info.plistfile located at<project root>/ios/Runner/Info.plist. -
Add the following entries to allow camera and microphone usage:
<key>NSCameraUsageDescription</key> <string>$(PRODUCT_NAME) Camera Usage</string> <key>NSMicrophoneUsageDescription</key> <string>$(PRODUCT_NAME) Microphone Usage</string>
-
macOS Setup (Optional)
-
Minimum macOS Version
-
Navigate to your
macos/Podfilelocated in your project's macOS directory. -
Find the line specifying the macOS platform version.
-
Update the minimum macOS platform version to
10.15(Catalina) or higher:platform :osx, '10.15'
-
-
Info.plist Updates
-
Open your
macos/Runner/Info.plistfile located at<project root>/macos/Runner/Info.plist. -
Add the following entries to allow camera and microphone usage:
<key>NSCameraUsageDescription</key> <string>Camera access is required for video calls</string> <key>NSMicrophoneUsageDescription</key> <string>Microphone access is required for audio calls</string>
-
-
Entitlements Configuration
-
Create a new file named
Release.entitlementsin yourmacos/Runnerdirectory if it doesn't already exist. -
Add the following entries to
Release.entitlementsto allow your app to access the camera, microphone, and open outgoing network connections:<key>com.apple.security.network.server</key> <true/> <key>com.apple.security.network.client</key> <true/> <key>com.apple.security.device.camera</key> <true/> <key>com.apple.security.device.microphone</key> <true/>
-
Android Setup
-
Update Gradle Configuration
-
Open the
build.gradlefile located at<project root>/android/app/build.gradle. -
Ensure the following SDK versions are set:
android { compileSdkVersion 33 defaultConfig { minSdkVersion 23 targetSdkVersion 33 // Other configurations... } compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } }
-
-
AndroidManifest Permissions
-
Open the
AndroidManifest.xmlfile located at<project root>/android/app/src/main/AndroidManifest.xml. -
Add the following permissions to allow camera, microphone, and network access:
<uses-permission android:name="android.permission.INTERNET" /> <uses-permission android:name="android.permission.CAMERA" /> <uses-permission android:name="android.permission.RECORD_AUDIO" /> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" /> <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" /> <uses-permission android:name="android.permission.FOREGROUND_SERVICE"/> <uses-permission android:name="android.permission.WAKE_LOCK" /> -
If your app requires Bluetooth functionality, add these permissions:
<uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
-
-
Enable Java 8 Compatibility
-
Ensure your app is compatible with Java 8 by adding the following code block to the
androidsection of yourbuild.gradle:android { //... compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 } }
-
Web Setup (Optional)
If you are targeting Flutter Web, ensure you have proper configurations for camera and microphone access:
-
Secure Context
- Use a secure context (HTTPS) to ensure that browser permissions for camera and microphone are handled correctly.
-
Browser Permissions
- Ensure that your web application requests and handles the necessary permissions for camera and microphone access.
By following these steps, you ensure that your Flutter app has the necessary permissions and configurations for camera, microphone, and network access on both iOS and Android platforms.
Basic Usage Guide #
A basic guide on how to use the package for common tasks.
This section will guide users through the initial setup and installation of the Flutter package.
This guide provides a basic overview of how to set up and use the mediasfu_sdk module for common tasks across platforms.
Initial Setup and Installation #
-
Add Dependency
Add
mediasfu_sdkto yourpubspec.yaml:dependencies: flutter: sdk: flutter mediasfu_sdk: ^2.0.0 -
Install Packages
Run the following command to install the dependencies:
flutter pub get
Post-Installation #
After installing the dependencies, ensure that you have configured your project correctly for both iOS and Android platforms. Follow the Configuration section below to set up the necessary permissions and settings.
Introduction #
MediaSFU is a 2-page application consisting of a prejoin/welcome page and the main events room page. This guide will walk you through the basic usage of the module for setting up these pages.
Documentation Reference #
For comprehensive documentation on the available methods, components, and functions, please visit mediasfu.com. This resource provides detailed information for this guide and additional documentation.
Prebuilt Event Rooms #
MediaSFU provides prebuilt event rooms for various purposes. These rooms are rendered as full pages and can be easily imported and used in your application. Here are the available prebuilt event rooms:
- MediasfuGeneric: A generic event room suitable for various types of events.
- MediasfuBroadcast: A room optimized for broadcasting events.
- MediasfuWebinar: Specifically designed for hosting webinars.
- MediasfuConference: Ideal for hosting conferences.
- MediasfuChat: A room tailored for interactive chat sessions.
Users can easily pick an interface and render it in their app.
If no API credentials are provided, a default home page will be displayed where users can scan or manually enter the event details.
To use these prebuilt event rooms, simply import them into your application:
import 'package:mediasfu_sdk/mediasfu_sdk.dart';
Simplest Usage #
The simplest way to use MediaSFU is by directly rendering a predefined event room component, such as MediasfuGeneric. This allows you to quickly integrate real-time communication features without extensive configuration.
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) {
// Pass the MediasfuGenericOptions to the MediasfuGeneric component
final MediasfuGenericOptions options = MediasfuGenericOptions(
);
return MaterialApp(
title: 'Mediasfu Generic',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuGeneric(options: options),
);
}
}
Programmatically Fetching Tokens #
If you prefer to fetch the required tokens programmatically without visiting MediaSFU's website, you can use the PreJoinPage component and pass your credentials as part of the options.
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) {
// Mediasfu account credentials
// Replace 'your_api_username' and 'your_api_key' with your actual credentials
final credentials = Credentials(
apiUserName: 'your_api_username',
apiKey: 'your_api_key',
);
final MediasfuGenericOptions options = MediasfuGenericOptions(
credentials: credentials,
);
return MaterialApp(
title: 'Mediasfu Generic',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuGeneric(options: options),
);
}
}
Custom Welcome/Prejoin Page #
Alternatively, you can design your own welcome/prejoin page to tailor the user experience to your application's needs. The primary function of this page is to fetch user tokens from MediaSFU's API and establish a connection using the returned link if the credentials are valid.
Passing a Custom Widget #
MediaSFU allows you to pass a custom widget to replace the default prejoin page. This flexibility enables you to design a personalized interface that aligns with your app's branding and user flow.
Implementing a Custom Prejoin Page #
To implement a custom prejoin page, follow these steps:
Step 1: Define Your Custom Prejoin Page Widget
Create a custom widget that defines the UI and behavior of your prejoin page. This widget should interact with the provided parameters to handle user input and establish connections.
import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';
/// A custom pre-join page widget that can be used instead of the default Mediasfu pre-join page.
///
/// This widget displays a personalized welcome message and includes a button to proceed to the session.
///
/// **Note:** Ensure this widget is passed to [MediasfuGenericOptions] only when you intend to use a custom pre-join page.
Widget myCustomPreJoinPage({
PreJoinPageOptions? options,
required Credentials credentials,
}) {
return Scaffold(
appBar: AppBar(
title: const Text('Welcome to Mediasfu'),
),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text(
'Hello, ${credentials.apiUserName}!',
style: const TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
),
const SizedBox(height: 20),
const Text(
'Get ready to join your session.',
style: TextStyle(fontSize: 18),
),
const SizedBox(height: 40),
ElevatedButton(
onPressed: () {
// Proceed to the session by updating the validation status
options?.parameters.updateValidated(true);
},
child: const Text('Join Now'),
),
],
),
),
);
}
Step 2: Integrate the Custom Prejoin Page into Your Application
Update your main application widget to utilize the custom prejoin page by passing it to the MediasfuGenericOptions.
import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';
void main() {
runApp(const MyApp());
}
/// The main application widget for MediaSFU.
///
/// This widget initializes the necessary credentials and configuration for the MediaSFU application,
/// including options for using seed data to generate random participants and messages.
/// It allows selecting different event types such as broadcast, chat, webinar, and conference.
class MyApp extends StatelessWidget {
/// Constructs a new instance of [MyApp].
const MyApp({super.key});
@override
Widget build(BuildContext context) {
// MediaSFU account credentials
// Replace 'your_api_username' and 'your_api_key' with your actual credentials
final credentials = Credentials(
apiUserName: 'your_api_username',
apiKey: 'your_api_key',
);
// === Main Activated Example ===
// Default to MediasfuGeneric with credentials
// This will render the pre-join page requiring credentials
final MediasfuGenericOptions options = MediasfuGenericOptions(
credentials: credentials,
preJoinPageWidget: (
{PreJoinPageOptions? options, required Credentials credentials}) {
return myCustomPreJoinPage(
options: options,
credentials: credentials,
);
},
);
return MaterialApp(
title: 'Mediasfu Generic',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuGeneric(options: options),
);
}
}
Mediasfu Prejoin Page Core Parts #
The default prejoin page included in the mediasfu_sdk package implements the logic for:
- Connection Validation:
- Ensures valid credentials are provided.
- Implements rate-limiting to prevent abuse.
- Room Creation & Joining:
- Supports creating new rooms or joining existing ones.
- Makes requests to MediaSFU’s backend API.
- Socket Connection:
- Establishes a socket connection to MediaSFU servers upon successful validation.
- Alerts & Error Handling:
- Displays alerts for invalid credentials, rate limits, and other errors.
Core logic within the default PreJoinPage includes:
class PreJoinPage extends StatelessWidget {
final PreJoinPageOptions? options;
final Credentials credentials;
PreJoinPage({required this.options, required this.credentials});
@override
Widget build(BuildContext context) {
// Core logic and integration
// Includes validation, API calls, and socket connection
return Container(); // Default UI, replaceable with a custom widget
}
}
By passing your own widget as shown earlier, you can override this default behavior while retaining the logic and functionality provided by the PreJoinPageOptions and MediasfuGenericOptions. This ensures your app's custom design seamlessly integrates with MediaSFU's backend.
IP Blockage Warning And Local UI Development #
Note: Local UI Development Mode is deprecated. Rather use your own Community Edition (CE) server for UI development and testing. You can later switch to MediaSFU Cloud for production. Nothing changes in the codebase, and you can use the same code for both environments.
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 package 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 #
// ignore_for_file: unused_shown_name, unused_import
import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';
void main() {
runApp(const MyApp());
}
/// A custom pre-join page widget that can be used instead of the default Mediasfu pre-join page.
///
/// This widget displays a personalized welcome message and includes a button to proceed to the session.
///
/// **Note:** Ensure this widget is passed to [MediasfuWebinarOptions] only when you intend to use a custom pre-join page.
// Uncomment the following lines to use a custom pre-join page
Widget myCustomPreJoinPage({
PreJoinPageOptions? options,
required Credentials credentials,
}) {
return Scaffold(
appBar: AppBar(
title: const Text('Welcome to Mediasfu'),
),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text(
'Hello, ${credentials.apiUserName}!',
style: const TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
),
const SizedBox(height: 20),
const Text(
'Get ready to join your session.',
style: TextStyle(fontSize: 18),
),
const SizedBox(height: 40),
ElevatedButton(
onPressed: () {
// Proceed to the session by updating the validation status
options!.parameters.updateValidated(true);
},
child: const Text('Join Now'),
),
],
),
),
);
}
/// The main application widget for MediaSFU.
///
/// This widget initializes the necessary configuration and credentials for the MediaSFU application.
/// Users can specify their own Community Edition (CE) server, utilize MediaSFU Cloud by default, or enable MediaSFU Cloud for egress features.
///
/// **Remarks:**
/// - **Using Your Own Community Edition (CE) Server**: Set the `localLink` to point to your CE server.
/// - **Using MediaSFU Cloud by Default**: If not using a custom server (`localLink` is empty), the application connects to MediaSFU Cloud.
/// - **MediaSFU Cloud Egress Features**: To enable cloud recording, capturing, and returning real-time images and audio buffers,
/// set `connectMediaSFU` to `true` in addition to specifying your `localLink`.
/// - **Credentials Requirement**: If not using your own server, provide `apiUserName` and `apiKey`. The same applies when using MediaSFU Cloud for egress.
/// - **Deprecated Feature**: `useLocalUIMode` is deprecated due to updates for strong typing and improved configuration options.
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
// ========================
// ====== CONFIGURATION ======
// ========================
// Mediasfu account credentials
// Replace 'your_api_username' and 'your_api_key' with your actual credentials
// Not needed if using a custom server with no MediaSFU Cloud Egress (recording, ...)
// Note: If not even using the credentials, modify the apiKey part from 'your_api_key' to say 'your_api' or something else
// If not, the Prejoin page will not be able to be used for your own server
final Credentials credentials = Credentials(
apiUserName: 'your_api_username',
apiKey: 'your_api_key',
);
// Specify your Community Edition (CE) server link or leave as an empty string if not using a custom server
const String localLink =
'http://localhost:3000'; // Set to '' if not using your own server
/**
* Automatically set `connectMediaSFU` to `true` if `localLink` is provided,
* indicating the use of MediaSFU Cloud by default.
*
* - If `localLink` is not empty, MediaSFU Cloud will be used for additional features.
* - If `localLink` is empty, the application will connect to MediaSFU Cloud by default.
*/
final bool connectMediaSFU = localLink.trim().isNotEmpty;
// ========================
// ====== USE CASES ======
// ========================
// 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 bool useSeed = false;
SeedData? seedData;
if (useSeed) {
const String memberName = 'Prince';
const String hostName = 'Fred';
final participants = generateRandomParticipants(
GenerateRandomParticipantsOptions(
member: memberName,
coHost: '',
host: hostName,
forBroadcastBroadcast:
eventType == EventType.Broadcast || eventType == EventType.broadcast,
),
);
final messages = generateRandomMessages(
GenerateRandomMessagesOptions(
participants: participants,
member: memberName,
host: hostName,
forBroadcastBroadcast:
eventType == EventType.Broadcast || eventType == EventType.broadcast,
),
);
final requests = generateRandomRequestList(
GenerateRandomRequestListOptions(
participants: participants,
hostName: memberName,
coHostName: '',
numberOfRequests: 3,
),
);
final waitingList = generateRandomWaitingRoomList();
seedData = SeedData(
participants: participants,
messages: messages,
requests: requests,
waitingList: waitingList,
member: memberName,
host: hostName,
eventType: eventType,
);
}
*/
// ========================
// ====== COMPONENT SELECTION ======
// ========================
/**
* Choose the Mediasfu component based on the event type and use case.
* Uncomment the component corresponding to your specific use case.
*/
// ------------------------
// ====== SIMPLE USE CASE ======
// ------------------------
/**
* **Simple Use Case (Welcome Page)**
*
* Renders the default welcome page.
* No additional inputs required.
*/
// return MaterialApp(
// title: 'Mediasfu Broadcast',
// theme: ThemeData(
// primarySwatch: Colors.blue,
// ),
// home: MediasfuBroadcast(),
// );
// ------------------------
// ====== PRE-JOIN USE CASE ======
// ------------------------
/**
* **Use Case with Pre-Join Page (Credentials Required)**
*
* Uses a pre-join page that requires users to enter credentials.
*/
// final MediasfuBroadcastOptions options = MediasfuBroadcastOptions(
// preJoinPageWidget: PreJoinPage(),
// credentials: credentials,
// );
// return MaterialApp(
// title: 'Mediasfu Broadcast with Pre-Join',
// theme: ThemeData(
// primarySwatch: Colors.blue,
// ),
// home: MediasfuBroadcast(options: options),
// );
// ------------------------
// ====== SEED DATA USE CASE ======
// ------------------------
/**
* **Use Case with Local UI Mode (Seed Data Required)**
*
* Runs the application in local UI mode using seed data.
*
* @deprecated Due to updates for strong typing, this feature is deprecated.
*/
// final MediasfuBroadcastOptions options = MediasfuBroadcastOptions(
// useLocalUIMode: true,
// useSeed: true,
// seedData: seedData!,
// );
// return MaterialApp(
// title: 'Mediasfu Broadcast with Seed Data',
// theme: ThemeData(
// primarySwatch: Colors.blue,
// ),
// home: MediasfuBroadcast(options: options),
// );
// ------------------------
// ====== Broadcast EVENT TYPE ======
// ------------------------
/**
* **MediasfuBroadcast Component**
*
* Uncomment to use the Broadcast event type.
*/
/*
final MediasfuBroadcastOptions options = MediasfuBroadcastOptions(
credentials: credentials,
localLink: localLink,
connectMediaSFU: connectMediaSFU,
// seedData: useSeed ? seedData : null,
);
return MaterialApp(
title: 'Mediasfu Broadcast',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuBroadcast(options: options),
);
*/
// ========================
// ====== DEFAULT COMPONENT ======
// ========================
/**
* **Default to MediasfuBroadcast with Updated Configuration**
*
* Renders the welcome page with specified server and cloud connection settings.
*/
final MediasfuBroadcastOptions options = MediasfuBroadcastOptions(
// Uncomment the following lines to use a custom pre-join page
/*
preJoinPageWidget: ({PreJoinPageOptions? options}) {
return myCustomPreJoinPage(
credentials: credentials,
);
},
*/
// Uncomment the following lines to enable local UI mode with seed data; deprecated
/*
useLocalUIMode: useLocalUIMode,
useSeed: useSeed,
seedData: seedData,
*/
// Uncomment the following lines to use your own Mediasfu server
localLink: localLink,
// Uncomment the following lines to pass your Credentials if not using MediaSFU Cloud (primarily or secondarily)
// MediaSFU Cloud handles recording and other egress processes for MediaSFU Community Edition
// You need to pass your own Mediasfu server link if you are using MediaSFU Community Edition
// Pass your credentials if you will be using MediaSFU Cloud for recording and other egress processes or as your primary server
credentials: credentials,
// Uncomment the following lines to use your own Mediasfu server with MediaSFU Cloud (for recording and other egress purposes)
// If you are using MediaSFU Cloud for recording and other egress processes, set connectMediaSFU to true
connectMediaSFU: connectMediaSFU,
);
return MaterialApp(
title: 'Mediasfu Broadcast',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuBroadcast(options: options),
);
}
}
Example for Generic View #
// ignore_for_file: unused_shown_name, unused_import
import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';
void main() {
runApp(const MyApp());
}
/// A custom pre-join page widget that can be used instead of the default Mediasfu pre-join page.
///
/// This widget displays a personalized welcome message and includes a button to proceed to the session.
///
/// **Note:** Ensure this widget is passed to [MediasfuWebinarOptions] only when you intend to use a custom pre-join page.
// Uncomment the following lines to use a custom pre-join page
Widget myCustomPreJoinPage({
PreJoinPageOptions? options,
required Credentials credentials,
}) {
return Scaffold(
appBar: AppBar(
title: const Text('Welcome to Mediasfu'),
),
body: Padding(
padding: const EdgeInsets.all(16.0),
child: Column(
mainAxisAlignment: MainAxisAlignment.center,
children: [
Text(
'Hello, ${credentials.apiUserName}!',
style: const TextStyle(fontSize: 24, fontWeight: FontWeight.bold),
),
const SizedBox(height: 20),
const Text(
'Get ready to join your session.',
style: TextStyle(fontSize: 18),
),
const SizedBox(height: 40),
ElevatedButton(
onPressed: () {
// Proceed to the session by updating the validation status
options!.parameters.updateValidated(true);
},
child: const Text('Join Now'),
),
],
),
),
);
}
/// The main application widget for MediaSFU.
///
/// This widget initializes the necessary configuration and credentials for the MediaSFU application.
/// Users can specify their own Community Edition (CE) server, utilize MediaSFU Cloud by default, or enable MediaSFU Cloud for egress features.
///
/// **Remarks:**
/// - **Using Your Own Community Edition (CE) Server**: Set the `localLink` to point to your CE server.
/// - **Using MediaSFU Cloud by Default**: If not using a custom server (`localLink` is empty), the application connects to MediaSFU Cloud.
/// - **MediaSFU Cloud Egress Features**: To enable cloud recording, capturing, and returning real-time images and audio buffers,
/// set `connectMediaSFU` to `true` in addition to specifying your `localLink`.
/// - **Credentials Requirement**: If not using your own server, provide `apiUserName` and `apiKey`. The same applies when using MediaSFU Cloud for egress.
/// - **Deprecated Feature**: `useLocalUIMode` is deprecated due to updates for strong typing and improved configuration options.
class MyApp extends StatelessWidget {
const MyApp({super.key});
@override
Widget build(BuildContext context) {
// ========================
// ====== CONFIGURATION ======
// ========================
// Mediasfu account credentials
// Replace 'your_api_username' and 'your_api_key' with your actual credentials
// Not needed if using a custom server with no MediaSFU Cloud Egress (recording, ...)
// Note: If not even using the credentials, modify the apiKey part from 'your_api_key' to say 'your_api' or something else
// If not, the Prejoin page will not be able to be used for your own server
final Credentials credentials = Credentials(
apiUserName: 'your_api_username',
apiKey: 'your_api',
);
// Specify your Community Edition (CE) server link or leave as an empty string if not using a custom server
const String localLink =
'http://localhost:3000'; // Set to '' if not using your own server
/**
* Automatically set `connectMediaSFU` to `true` if `localLink` is provided,
* indicating the use of MediaSFU Cloud by default.
*
* - If `localLink` is not empty, MediaSFU Cloud will be used for additional features.
* - If `localLink` is empty, the application will connect to MediaSFU Cloud by default.
*/
final bool connectMediaSFU = localLink.trim().isNotEmpty;
// ========================
// ====== USE CASES ======
// ========================
// 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 bool useSeed = false;
SeedData? seedData;
if (useSeed) {
const String memberName = 'Prince';
const String hostName = 'Fred';
final participants = generateRandomParticipants(
GenerateRandomParticipantsOptions(
member: memberName,
coHost: '',
host: hostName,
forChatBroadcast:
eventType == EventType.chat || eventType == EventType.broadcast,
),
);
final messages = generateRandomMessages(
GenerateRandomMessagesOptions(
participants: participants,
member: memberName,
host: hostName,
forChatBroadcast:
eventType == EventType.chat || eventType == EventType.broadcast,
),
);
final requests = generateRandomRequestList(
GenerateRandomRequestListOptions(
participants: participants,
hostName: memberName,
coHostName: '',
numberOfRequests: 3,
),
);
final waitingList = generateRandomWaitingRoomList();
seedData = SeedData(
participants: participants,
messages: messages,
requests: requests,
waitingList: waitingList,
member: memberName,
host: hostName,
eventType: eventType,
);
}
*/
// ========================
// ====== COMPONENT SELECTION ======
// ========================
/**
* Choose the Mediasfu component based on the event type and use case.
* Uncomment the component corresponding to your specific use case.
*/
// ------------------------
// ====== SIMPLE USE CASE ======
// ------------------------
/**
* **Simple Use Case (Welcome Page)**
*
* Renders the default welcome page.
* No additional inputs required.
*/
// return MaterialApp(
// title: 'Mediasfu Generic',
// theme: ThemeData(
// primarySwatch: Colors.blue,
// ),
// home: MediasfuGeneric(),
// );
// ------------------------
// ====== PRE-JOIN USE CASE ======
// ------------------------
/**
* **Use Case with Pre-Join Page (Credentials Required)**
*
* Uses a pre-join page that requires users to enter credentials.
*/
// final MediasfuGenericOptions options = MediasfuGenericOptions(
// preJoinPageWidget: PreJoinPage(),
// credentials: credentials,
// );
// return MaterialApp(
// title: 'Mediasfu Generic with Pre-Join',
// theme: ThemeData(
// primarySwatch: Colors.blue,
// ),
// home: MediasfuGeneric(options: options),
// );
// ------------------------
// ====== SEED DATA USE CASE ======
// ------------------------
/**
* **Use Case with Local UI Mode (Seed Data Required)**
*
* Runs the application in local UI mode using seed data.
*
* @deprecated Due to updates for strong typing, this feature is deprecated.
*/
// final MediasfuGenericOptions options = MediasfuGenericOptions(
// useLocalUIMode: true,
// useSeed: true,
// seedData: seedData!,
// );
// return MaterialApp(
// title: 'Mediasfu Generic with Seed Data',
// theme: ThemeData(
// primarySwatch: Colors.blue,
// ),
// home: MediasfuGeneric(options: options),
// );
// ------------------------
// ====== BROADCAST EVENT TYPE ======
// ------------------------
/**
* **MediasfuBroadcast Component**
*
* Uncomment to use the broadcast event type.
*/
/*
final MediasfuBroadcastOptions options = MediasfuBroadcastOptions(
credentials: credentials,
localLink: localLink,
connectMediaSFU: connectMediaSFU,
// seedData: useSeed ? seedData : null,
);
return MaterialApp(
title: 'Mediasfu Broadcast',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuBroadcast(options: options),
);
*/
// ------------------------
// ====== CHAT EVENT TYPE ======
// ------------------------
/**
* **MediasfuChat Component**
*
* Uncomment to use the chat event type.
*/
/*
final MediasfuChatOptions options = MediasfuChatOptions(
credentials: credentials,
localLink: localLink,
connectMediaSFU: connectMediaSFU,
// seedData: useSeed ? seedData : null,
);
return MaterialApp(
title: 'Mediasfu Chat',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuChat(options: options),
);
*/
// ------------------------
// ====== WEBINAR EVENT TYPE ======
// ------------------------
/**
* **MediasfuWebinar Component**
*
* Uncomment to use the webinar event type.
*/
/*
final MediasfuWebinarOptions options = MediasfuWebinarOptions(
credentials: credentials,
localLink: localLink,
connectMediaSFU: connectMediaSFU,
// seedData: useSeed ? seedData : null,
);
return MaterialApp(
title: 'Mediasfu Webinar',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuWebinar(options: options),
);
*/
// ------------------------
// ====== CONFERENCE EVENT TYPE ======
// ------------------------
/**
* **MediasfuConference Component**
*
* Uncomment to use the conference event type.
*/
/*
final MediasfuConferenceOptions options = MediasfuConferenceOptions(
credentials: credentials,
localLink: localLink,
connectMediaSFU: connectMediaSFU,
// seedData: useSeed ? seedData : null,
);
return MaterialApp(
title: 'Mediasfu Conference',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuConference(options: options),
);
*/
// ========================
// ====== DEFAULT COMPONENT ======
// ========================
/**
* **Default to MediasfuGeneric with Updated Configuration**
*
* Renders the welcome page with specified server and cloud connection settings.
*/
final MediasfuGenericOptions options = MediasfuGenericOptions(
// Uncomment the following lines to use a custom pre-join page
/*
preJoinPageWidget: ({PreJoinPageOptions? options}) {
return myCustomPreJoinPage(
credentials: credentials,
);
},
*/
// Uncomment the following lines to enable local UI mode with seed data; deprecated
/*
useLocalUIMode: useLocalUIMode,
useSeed: useSeed,
seedData: seedData,
*/
// Uncomment the following lines to use your own Mediasfu server
localLink: localLink,
// Uncomment the following lines to pass your Credentials if not using MediaSFU Cloud (primarily or secondarily)
// MediaSFU Cloud handles recording and other egress processes for MediaSFU Community Edition
// You need to pass your own Mediasfu server link if you are using MediaSFU Community Edition
// Pass your credentials if you will be using MediaSFU Cloud for recording and other egress processes or as your primary server
credentials: credentials,
// Uncomment the following lines to use your own Mediasfu server with MediaSFU Cloud (for recording and other egress purposes)
// If you are using MediaSFU Cloud for recording and other egress processes, set connectMediaSFU to true
connectMediaSFU: connectMediaSFU,
);
return MaterialApp(
title: 'Mediasfu Generic',
theme: ThemeData(
primarySwatch: Colors.blue,
),
home: MediasfuGeneric(options: options),
);
}
}
In the provided examples, users can set useLocalUIMode to true during UI development to prevent unwanted connections to MediaSFU servers. Additionally, they can generate seed data for rendering UI components locally by using random data generators provided by the package.
Local UI Development in MediaSFU #
Note: Local UI Development Mode is deprecated. Rather use your own Community Edition (CE) server for UI development and testing. You can later switch to MediaSFU Cloud for production. Nothing changes in the codebase, and you can use the same code for both environments.
During local UI development, the MediaSFU view is designed to be responsive to changes in screen size and orientation, adapting its layout accordingly. However, since UI changes are typically linked to communication with servers, developing the UI locally might result in less responsiveness due to the lack of real-time data updates. To mitigate this, users can force trigger changes in the UI by rotating the device, resizing the window, or simulating server responses by clicking on buttons within the page.
While developing locally, users may encounter occasional error warnings as the UI attempts to communicate with the server. These warnings can be safely ignored, as they are simply indicative of unsuccessful server requests in the local development environment.
Note: this mode is experimental and have numerous null values that may cause the application to crash but it is useful for testing purposes.
Intermediate Usage Guide #
Expands on the basic usage, covering more advanced features and scenarios.
Intermediate Usage Guide #
In the Intermediate Usage Guide, we'll explore the core components and functionalities of the MediaSFU package, focusing on media display, controls, and modal interactions. Click on any listed component/method to open the full documentation.
Core Components Overview
The main items displayed on an event page are media components (such as video, audio, and blank cards) and control components (for pagination, navigation, etc.).
Media Display Components:
Media Display Components
| Component Name | Description |
|---|---|
| MainAspectComponent | Serves as a container for the primary aspect of the user interface, typically containing the main content or focus of the application. |
| MainScreenComponent | Responsible for rendering the main screen layout of the application, providing the foundation for displaying various elements and content. |
| MainGridComponent | Crucial part of the user interface, organizing and displaying primary content or elements in a grid layout format. |
| SubAspectComponent | Acts as a secondary container within the user interface, often housing additional elements or controls related to the main aspect. |
| MainContainerComponent | Primary container for the application's content, encapsulating all major components and providing structural organization. |
| OtherGridComponent | Complements the Main Grid Component by offering additional grid layouts, typically used for displaying secondary or auxiliary content. |
Control Components
| Component Name | Description |
|---|---|
| ControlButtonsComponent | Comprises a set of buttons or controls used for navigating, interacting, or managing various aspects of the application's functionality. |
| ControlButtonsAltComponent | Provides alternative button configurations or styles for controlling different aspects of the application. |
| ControlButtonsComponent Touch | Specialized component designed for touch-enabled devices, offering floating buttons or controls for intuitive interaction with the application's features. |
These components collectively contribute to the overall user interface, facilitating navigation, interaction, and content display within the application.
Modal Components
| Modal Component | Description |
|---|---|
| LoadingModal | Modal for displaying loading indicator during data fetching or processing. |
| MainAspectComponent | Component responsible for displaying the main aspect of the event page. |
| ControlButtonsComponent | Component for displaying control buttons such as pagination controls. |
| ControlButtonsAltComponent | Alternate control buttons component for specific use cases. |
| ControlButtonsComponentTouch | Touch-enabled control buttons component for mobile devices. |
| OtherGridComponent | Component for displaying additional grid elements on the event page. |
| MainScreenComponent | Component for rendering the main screen content of the event. |
| MainGridComponent | Main grid component for displaying primary event content. |
| SubAspectComponent | Component for displaying secondary aspects of the event page. |
| MainContainerComponent | Main container component for the event page content. |
| AlertComponent | Modal for displaying alert messages to the user. |
| MenuModal | Modal for displaying a menu with various options. |
| RecordingModal | Modal for managing recording functionality during the event. |
| RequestsModal | Modal for handling requests from participants during the event. |
| WaitingRoomModal | Modal for managing waiting room functionality during the event. |
| DisplaySettingsModal | Modal for adjusting display settings during the event. |
| EventSettingsModal | Modal for configuring event settings. |
| CoHostModal | Modal for managing co-host functionality during the event. |
| ParticipantsModal | Modal for displaying participant information and controls. |
| MessagesModal | Modal for managing messages and chat functionality during the event. |
| MediaSettingsModal | Modal for adjusting media settings during the event. |
| ConfirmExitModal | Modal for confirming exit from the event. |
| ConfirmHereModal | Modal for confirming certain actions or selections. |
| ShareEventModal | Modal for sharing the event with others. |
| PollModal | Modal for conducting polls or surveys during the event. |
| WelcomePage | Serves as the initial page displayed to users upon entering the application for an event. It provides a welcoming interface with relevant information about the event. |
| PreJoinPage | The PreJoinPage represents the page where users prepare to join the event. It includes functionalities for creating or joining a room, validating credentials, and initializing the connection for the event. |
| BreakoutRoomsModal | Modal for managing breakout rooms during the event. |
Modal Interactions
Each modal has corresponding functions to trigger its usage:
launchMenuModal: Launches the menu modal for settings and configurations.launchRecording: Initiates the recording modal for recording functionalities.startRecording: Starts the recording process.confirmRecording: Confirms and finalizes the recording.launchWaiting: Opens the waiting room modal for managing waiting room interactions.launchCoHost: Opens the co-host modal for managing co-host functionalities.launchMediaSettings: Launches the media settings modal for adjusting media-related configurations.launchDisplaySettings: Opens the display settings modal for adjusting display configurations.launchSettings: Initiates the settings modal for general event settings and configurations.launchRequests: Opens the requests modal for managing user requests.launchParticipants: Displays the participants modal for viewing and managing event participants.launchMessages: Opens the messages modal for communication through chat messages.launchConfirmExit: Prompts users to confirm before exiting the event.launchPoll: Opens the poll modal for conducting polls or surveys.launchBreakoutRooms: Initiates the breakout rooms modal for managing breakout room functionalities.
Media Display and Controls
These components facilitate media display and control functionalities:
- Pagination: Handles pagination and page switching.
- FlexibleGrid: Renders flexible grid layouts for media display.
- FlexibleVideo: Displays videos in a flexible manner within the grid.
- AudioGrid: Renders audio components within the grid layout.
These components enable seamless media presentation and interaction within the event environment, providing users with a rich and immersive experience.
| UI Media Component | Description |
|---|---|
| MeetingProgressTimer | Component for displaying a timer indicating the progress of a meeting or event. |
| MiniAudio | Component for rendering a compact audio player with basic controls. |
| MiniCard | Component for displaying a minimized card view with essential information. |
| AudioCard | Component for displaying audio content with control elements, details, and audio decibels. |
| VideoCard | Component for displaying video content with control elements, details, and audio decibels. |
| CardVideoDisplay | Video player component for displaying embedded videos with controls and details. |
| MiniAudioPlayer | Utility method for playing audio and rendering a mini audio modal when the user is not actively displayed on the page. |
With the Intermediate Usage Guide, users can explore and leverage the core components and functionalities of the MediaSFU Package to enhance their event hosting and participation experiences.
Here's a sample import and usage code for a Broadcast screen:
import 'package:flutter/material.dart';
import 'package:mediasfu_sdk/mediasfu_sdk.dart';
class MediasfuBroadcast extends StatefulWidget {
final MediasfuBroadcastOptions options;
const MediasfuBroadcast({
super.key,
required this.options,
});
@override
_MediasfuBroadcastState createState() => _MediasfuBroadcastState();
}
class _MediasfuBroadcastState extends State<MediasfuBroadcast> {
//sample details
bool validated = false;
void updateValidated(bool value) {
setState(() {
validated = value;
});
if (validated) {
joinAndUpdate().then((value) => null);
}
}
// Room Details
final ValueNotifier<String> roomName = ValueNotifier(''); // Room name
final ValueNotifier<String> member = ValueNotifier(''); // Member name
final ValueNotifier<String> adminPasscode =
ValueNotifier(''); // Admin passcode
final ValueNotifier<String> islevel = ValueNotifier("0"); // Level
//others ...
//Record Button
List<ButtonTouch> recordButton = [];
void initializeRecordButton() {
recordButton = [
// Record Button
ButtonTouch(
icon: Icons.fiber_manual_record,
active: false,
onPress: () {
// Action for the Record button
launchRecording(
LaunchRecordingOptions(
updateIsRecordingModalVisible: updateIsRecordingModalVisible,
isRecordingModalVisible: isRecordingModalVisible.value,
stopLaunchRecord: stopLaunchRecord.value,
canLaunchRecord: canLaunchRecord.value,
recordingAudioSupport: recordingAudioSupport.value,
recordingVideoSupport: recordingVideoSupport.value,
updateCanRecord: updateCanRecord,
updateClearedToRecord: updateClearedToRecord,
recordStarted: recordStarted.value,
recordPaused: recordPaused.value,
localUIMode: widget.options.useLocalUIMode == true),
);
},
activeColor: const Color.fromARGB(255, 244, 3, 3),
inActiveColor: const Color.fromARGB(255, 251, 9, 9),
show: true,
size: 24,
),
];
}
// Record Buttons
List<ButtonTouch> recordButtonsTouch = [];
//Control Buttons Broadcast Events
List<ButtonTouch> controlBroadcastButtons = [];
Widget buildEventRoom(BuildContext context) {
initializeRecordButton();
initializeRecordButtons();
initializeControlBroadcastButtons();
@override
Widget build(BuildContext context) {
return SafeArea(
// Top: true adjusts for iOS status bar, ignores for other platforms
top: true,
child: AnnotatedRegion<SystemUiOverlayStyle>(
value: const SystemUiOverlayStyle(
statusBarColor: Colors.transparent, // Makes status bar transparent
statusBarIconBrightness:
Brightness.light, // Sets status bar icons to light color
),
child: OrientationBuilder(
builder: (BuildContext context, Orientation orientation) {
// Check if the device is in landscape mode
isPortrait.value = orientation == Orientation.portrait;
return Scaffold(
body: _buildRoomInterface(),
resizeToAvoidBottomInset: false,
);
},
),
),
);
}
return validated
? MainContainerComponent(
options: MainContainerComponentOptions(
backgroundColor: const Color.fromRGBO(217, 227, 234, 0.99),
children: [
MainAspectComponent(
options: MainAspectComponentOptions(
backgroundColor: const Color.fromRGBO(217, 227, 234, 0.99),
updateIsWideScreen: updateIsWideScreen,
updateIsMediumScreen: updateIsMediumScreen,
updateIsSmallScreen: updateIsSmallScreen,
defaultFraction: 1 - controlHeight.value,
showControls: eventType.value == EventType.webinar ||
eventType.value == EventType.conference,
children: [
ValueListenableBuilder<ComponentSizes>(
valueListenable: componentSizes,
builder: (context, componentSizes, child) {
return MainScreenComponent(
options: MainScreenComponentOptions(
doStack: true,
mainSize: mainHeightWidth,
updateComponentSizes: updateComponentSizes,
defaultFraction: 1 - controlHeight.value,
showControls:
eventType.value == EventType.webinar ||
eventType.value == EventType.conference,
children: [
ValueListenableBuilder<GridSizes>(
valueListenable: gridSizes,
builder: (context, gridSizes, child) {
return MainGridComponent(
options: MainGridComponentOptions(
height: componentSizes.mainHeight,
width: componentSizes.mainWidth,
backgroundColor: const Color.fromRGBO(
217, 227, 234, 0.99),
mainSize: mainHeightWidth,
showAspect: mainHeightWidth > 0,
timeBackgroundColor:
recordState == 'green'
? Colors.green
: recordState == 'yellow'
? Colors.yellow
: Colors.red,
meetingProgressTime:
meetingProgressTime.value,
showTimer: true,
children: [
FlexibleVideo(
options: FlexibleVideoOptions(
backgroundColor:
const Color.fromRGBO(
217, 227, 234, 0.99),
customWidth:
componentSizes.mainWidth,
customHeight:
componentSizes.mainHeight,
rows: 1,
columns: 1,
componentsToRender:
mainGridStream,
showAspect:
mainGridStream.isNotEmpty,
)),
ControlButtonsComponentTouch(
options:
ControlButtonsComponentTouchOptions(
buttons: controlBroadcastButtons,
direction: 'vertical',
showAspect: eventType.value ==
EventType.broadcast,
location: 'bottom',
position: 'right',
)),
ControlButtonsComponentTouch(
options:
ControlButtonsComponentTouchOptions(
buttons: recordButton,
direction: 'horizontal',
showAspect: eventType.value ==
EventType.broadcast &&
!showRecordButtons.value &&
islevel.value == '2',
location: 'bottom',
position: 'middle',
)),
ControlButtonsComponentTouch(
options:
ControlButtonsComponentTouchOptions(
buttons: recordButtonsTouch,
direction: 'horizontal',
showAspect: eventType.value ==
EventType.broadcast &&
showRecordButtons.value &&
islevel.value == '2',
location: 'bottom',
position: 'middle',
)),
AudioGrid(
options: AudioGridOptions(
componentsToRender:
audioOnlyStreams.value,
)),
ValueListenableBuilder<String>(
valueListenable:
meetingProgressTime,
builder: (context,
meetingProgressTime,
child) {
return MeetingProgressTimer(
options:
MeetingProgressTimerOptions(
meetingProgressTime:
meetingProgressTime,
initialBackgroundColor:
recordState == 'green'
? Colors.green
: recordState ==
'yellow'
? Colors.yellow
: Colors.red,
showTimer: true,
));
}),
],
),
);
},
),
],
),
);
}),
],
),
),
],
),
)
: widget.options.credentials != null &&
widget.options.credentials!.apiKey.isNotEmpty &&
widget.options.credentials!.apiKey != 'your_api_key'
? renderpreJoinPageWidget() ?? renderWelcomePage()
: renderWelcomePage();
}
Widget _buildRoomInterface() {
return Stack(
children: [
buildEventRoom(context),
_buildShareEventModal(), // Add Share Event Modal
_buildRecordingModal(), // Add Recording Modal
_buildParticipantsModal(), // Add Participants Modal
_buildMessagesModal(), // Add Messages Modal
_buildConfirmExitModal(), // Add Confirm Exit Modal
_buildAlertModal(), // Add Alert Modal
_buildConfirmHereModal(), // Add Confirm Here Modal
_buildLoadingModal(), // Add Loading Modal
],
);
}
Widget _buildParticipantsModal() {
return ValueListenableBuilder<bool>(
valueListenable: isParticipantsModalVisible,
builder: (context, isParticipantsVisible, child) {
return ValueListenableBuilder<List<dynamic>>(
valueListenable: filteredParticipants,
builder: (context, filteredParticipants, child) {
return ParticipantsModal(
options: ParticipantsModalOptions(
backgroundColor: const Color.fromRGBO(217, 227, 234, 0.99),
isParticipantsModalVisible: isParticipantsVisible,
onParticipantsClose: () {
updateIsParticipantsModalVisible(false);
},
participantsCounter: participantsCounter.value,
onParticipantsFilterChange: onParticipantsFilterChange,
parameters: mediasfuParameters,
),
);
},
);
},
);
}
Widget _buildConfirmExitModal() {
return ValueListenableBuilder<bool>(
valueListenable: isConfirmExitModalVisible,
builder: (context, isConfirmExitVisible, child) {
return ConfirmExitModal(
options: ConfirmExitModalOptions(
backgroundColor: const Color.fromRGBO(181, 233, 229, 0.97),
isVisible: isConfirmExitVisible,
onClose: () {
updateIsConfirmExitModalVisible(false);
},
islevel: islevel.value,
roomName: roomName.value,
member: member.value,
socket: socket.value,
),
);
},
);
}
//other widgets for the modals
}
This sample code demonstrates the import and usage of various components and features for a Broadcast screen, including rendering different UI components based on the validation state, handling socket connections, displaying video streams, controlling recording, and managing component sizes.
Here's a sample usage of the control button components as used above:
void initializeRecordButtons() {
recordButtons = [
// Play/Pause Button
AltButton(
// name: Pause,
icon: Icons.play_circle_filled,
active: !recordPaused.value,
onPress: () => updateRecording(UpdateRecordingOptions(
parameters: mediasfuParameters,
)),
activeColor: Colors.black,
inActiveColor: Colors.black,
alternateIcon: Icons.pause_circle_filled,
show: true,
),
// Stop Button
AltButton(
// name: Stop,
icon: Icons.stop_circle,
active: false,
onPress: () => stopRecording(
StopRecordingOptions(
parameters: mediasfuParameters,
),
),
activeColor: Colors.green,
inActiveColor: Colors.black,
show: true,
),
// Timer Display
AltButton(
customComponent: Container(
color: Colors.transparent,
padding: const EdgeInsets.all(0),
margin: const EdgeInsets.all(2),
child: Text(
recordingProgressTime.value,
style: const TextStyle(
color: Colors.black,
backgroundColor: Colors.transparent,
),
),
),
show: true,
),
// Status Button
AltButton(
// name: Status,
icon: Icons.circle,
active: false,
onPress: () => (),
activeColor: Colors.black,
inActiveColor: recordPaused.value == false ? Colors.red : Colors.yellow,
show: true,
),
// Settings Button
AltButton(
// name: Settings,
icon: Icons.settings,
active: false,
onPress: () => launchRecording(
LaunchRecordingOptions(
updateIsRecordingModalVisible: updateIsRecordingModalVisible,
isRecordingModalVisible: isRecordingModalVisible.value,
stopLaunchRecord: stopLaunchRecord.value,
canLaunchRecord: canLaunchRecord.value,
recordingAudioSupport: recordingAudioSupport.value,
recordingVideoSupport: recordingVideoSupport.value,
updateCanRecord: updateCanRecord,
updateClearedToRecord: updateClearedToRecord,
recordStarted: recordStarted.value,
recordPaused: recordPaused.value,
localUIMode: widget.options.useLocalUIMode == true),
),
activeColor: Colors.green,
inActiveColor: Colors.black,
show: true,
)
];
}
// Initialize Control Buttons Broadcast Events
void initializeControlBroadcastButtons() {
controlBroadcastButtons = [
// Users button
ButtonTouch(
icon: Icons.group_outlined,
active: participantsActive,
onPress: () => launchParticipants(
LaunchParticipantsOptions(
updateIsParticipantsModalVisible: updateIsParticipantsModalVisible,
isParticipantsModalVisible: isParticipantsModalVisible.value,
),
),
activeColor: Colors.black,
inActiveColor: Colors.black,
show: true,
),
// Share button
ButtonTouch(
icon: Icons.share,
alternateIcon: Icons.share,
active: true,
onPress: () =>
updateIsShareEventModalVisible(!isShareEventModalVisible.value),
activeColor: Colors.black,
inActiveColor: Colors.black,
show: true,
),
// Custom component
ButtonTouch(
customComponent: Stack(
children: [
// Your icon
const Icon(
Icons.comment,
size: 20,
color: Colors.black,
),
// Conditionally render a badge
if (showMessagesBadge.value)
Positioned(
top: -2,
right: -2,
child: Container(
decoration: BoxDecoration(
color: Colors.red,
borderRadius: BorderRadius.circular(12),
),
padding:
const EdgeInsets.symmetric(horizontal: 4, vertical: 4),
child: const Text(
'',
style: TextStyle(
color: Colors.white,
fontSize: 12,
fontWeight: FontWeight.bold,
),
),
),
),
],
),
onPress: () => launchMessages(
LaunchMessagesOptions(
updateIsMessagesModalVisible: updateIsMessagesModalVisible,
isMessagesModalVisible: isMessagesModalVisible.value,
),
),
show: true,
),
// Switch camera button
ButtonTouch(
icon: Icons.sync,
alternateIcon: Icons.sync,
active: true,
onPress: () => switchVideoAlt(
SwitchVideoAltOptions(
parameters: mediasfuParameters,
),
),
activeColor: Colors.black,
inActiveColor: Colors.black,
show: islevel.value == '2',
),
// Video button
ButtonTouch(
icon: Icons.video_call,
alternateIcon: Icons.video_call,
active: videoActive,
onPress: () => clickVideo(
ClickVideoOptions(
parameters: mediasfuParameters,
),
),
activeColor: Colors.green,
inActiveColor: Colors.red,
show: islevel.value == '2',
),
// Microphone button
ButtonTouch(
icon: Icons.mic,
alternateIcon: Icons.mic,
active: micActive,
onPress: () => clickAudio(
ClickAudioOptions(parameters: mediasfuParameters),
),
activeColor: Colors.green,
inActiveColor: Colors.red,
show: islevel.value == '2',
),
ButtonTouch(
customComponent: Container(
margin: const EdgeInsets.all(5),
padding: const EdgeInsets.all(0),
decoration: BoxDecoration(
color: Colors.transparent,
border: Border.all(color: Colors.transparent),
),
child: Row(
mainAxisAlignment: MainAxisAlignment.center,
crossAxisAlignment: CrossAxisAlignment.center,
children: [
const Icon(Icons.bar_chart, size: 20, color: Colors.black),
const SizedBox(width: 5),
Text(
participantsCounter.value.toString(),
style: const TextStyle(
backgroundColor: Colors.transparent,
color: Colors.black,
fontSize: 12,
),
),
],
),
),
show: true,
),
// End call button
ButtonTouch(
icon: Icons.call_end,
active: endCallActive,
onPress: () => launchConfirmExit(
LaunchConfirmExitOptions(
updateIsConfirmExitModalVisible: updateIsConfirmExitModalVisible,
isConfirmExitModalVisible: isConfirmExitModalVisible.value,
),
),
activeColor: Colors.green,
inActiveColor: Colors.red,
show: true,
),
];
}
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 (control_buttons_alt_component.dart and control_buttons_component_touch.dart) for more details on how to add custom buttons.
Advanced Usage Guide #
In-depth documentation for advanced users, covering complex functionalities and customization options.
Introduction to Advanced Media Control Functions:
In advanced usage scenarios, users often encounter complex tasks related to media control, connectivity, and streaming management within their applications. To facilitate these tasks, a comprehensive set of functions is provided, offering granular control over various aspects of media handling and communication with servers.
These advanced media control functions encompass a wide range of functionalities, including connecting to and disconnecting from WebSocket servers, joining and updating room parameters, managing device creation, switching between different media streams, handling permissions, processing consumer transports, managing screen sharing, adjusting layouts dynamically, and much more.
This robust collection of functions empowers developers to tailor their applications to specific requirements, whether it involves intricate media streaming setups, real-time communication protocols, or sophisticated user interface interactions. With these tools at their disposal, developers can create rich and responsive media experiences that meet the demands of their users and applications.
Here's a tabulated list of advanced control functions along with brief explanations (click the function(link) for full usage guide):
| Function | Explanation |
|---|---|
| connectSocket | Connects to the WebSocket server. |
| disconnectSocket | Disconnects from the WebSocket server. |
| joinRoomClient | Joins a room as a client. |
| updateRoomParametersClient | Updates room parameters as a client. |
| createDeviceClient | Creates a device as a client. |
| switchVideoAlt | Switches video/camera streams. |
| clickVideo | Handles clicking on video controls. |
| clickAudio | Handles clicking on audio controls. |
| clickScreenShare | Handles clicking on screen share controls. |
| streamSuccessVideo | Handles successful video streaming. |
| streamSuccessAudio | Handles successful audio streaming. |
| streamSuccessScreen | Handles successful screen sharing. |
| streamSuccessAudioSwitch | Handles successful audio switching. |
| checkPermission | Checks for media access permissions. |
| producerClosed | Handles the closure of a producer. |
| newPipeProducer | Creates receive transport for a new piped producer. |
| updateMiniCardsGrid | Updates the mini-grids (mini cards) grid. |
| mixStreams | Mixes streams and prioritizes interesting ones together. |
| dispStreams | Displays streams (media). |
| stopShareScreen | Stops screen sharing. |
| checkScreenShare | Checks for screen sharing availability. |
| startShareScreen | Starts screen sharing. |
| requestScreenShare | Requests permission for screen sharing. |
| reorderStreams | Reorders streams (based on interest level). |
| prepopulateUserMedia | Populates user media (for main grid). |
| getVideos | Retrieves videos that are pending. |
| rePort | Handles re-porting (updates of changes in UI when recording). |
| trigger | Triggers actions (reports changes in UI to backend for recording). |
| consumerResume | Resumes consumers. |
| connectSendTransportAudio | Connects send transport for audio. |
| connectSendTransportVideo | Connects send transport for video. |
| connectSendTransportScreen | Connects send transport for screen sharing. |
| processConsumerTransports | Processes consumer transports to pause/resume based on the current active page. |
| resumePauseStreams | Resumes or pauses streams. |
| readjust | Readjusts display elements. |
| checkGrid | Checks the grid sizes to display. |
| getEstimate | Gets an estimate of grids to add. |
| calculateRowsAndColumns | Calculates rows and columns for the grid. |
| addVideosGrid | Adds videos to the grid. |
| onScreenChanges | Handles screen changes (orientation and resize). |
| sleep | Pauses execution for a specified duration. |
| changeVids | Changes videos. |
| compareActiveNames | Compares active names (for recording UI changes reporting). |
| compareScreenStates | Compares screen states (for recording changes in grid sizes reporting). |
| createSendTransport | Creates a send transport. |
| resumeSendTransportAudio | Resumes a send transport for audio. |
| receiveAllPipedTransports | Receives all piped transports. |
| disconnectSendTransportVideo | Disconnects send transport for video. |
| disconnectSendTransportAudio | Disconnects send transport for audio. |
| disconnectSendTransportScreen | Disconnects send transport for screen sharing. |
| connectSendTransport | Connects a send transport. |
| getPipedProducersAlt | Gets piped producers. |
| signalNewConsumerTransport | Signals a new consumer transport. |
| connectRecvTransport | Connects a receive transport. |
| reUpdateInter | Re-updates the interface based on audio decibels. |
| updateParticipantAudioDecibels | Updates participant audio decibels. |
| closeAndResize | Closes and resizes the media elements. |
| autoAdjust | Automatically adjusts display elements. |
| switchUserVideoAlt | Switches user video (alternate) (back/front). |
| switchUserVideo | Switches user video (specific video id). |
| switchUserAudio | Switches user audio. |
| receiveRoomMessages | Receives room messages. |
| formatNumber | Formats a number (for broadcast viewers). |
| connectIps | Connects IPs (connect to consuming servers). |
| startMeetingProgressTimer | Starts the meeting progress timer. |
| updateRecording | Updates the recording status. |
| stopRecording | Stops the recording process. |
| pollUpdated | Handles updated poll data. |
| handleVotePoll | Handles voting in a poll. |
| handleCreatePoll | Handles creating a poll. |
| handleEndPoll | Handles ending a poll. |
| breakoutRoomUpdated | Handles updated breakout room data. |
| resumePauseAudioStreams | Resumes or pauses audio streams. |
| processConsumerTransportsAudio | Processes consumer transports for audio. |
Room Socket Events #
In the context of a room's real-time communication, various events occur, such as user actions, room management updates, media controls, and meeting status changes. To effectively handle these events and synchronize the application's state with the server, specific functions are provided. These functions act as listeners for socket events, allowing the application to react accordingly.
Provided Socket Event Handling Functions:
| Function | Explanation |
|---|---|
| userWaiting | Triggered when a user is waiting. |
| personJoined | Triggered when a person joins the room. |
| allWaitingRoomMembers | Triggered when information about all waiting room members is received. |
| roomRecordParams | Triggered when room recording parameters are received. |
| banParticipant | Triggered when a participant is banned. |
| updatedCoHost | Triggered when the co-host information is updated. |
| participantRequested | Triggered when a participant requests access. |
| screenProducerId | Triggered when the screen producer ID is received. |
| updateMediaSettings | Triggered when media settings are updated. |
| producerMediaPaused | Triggered when producer media is paused. |
| producerMediaResumed | Triggered when producer media is resumed. |
| producerMediaClosed | Triggered when producer media is closed. |
| controlMediaHost | Triggered when media control is hosted. |
| meetingEnded | Triggered when the meeting ends. |
| disconnectUserSelf | Triggered when a user disconnects. |
| receiveMessage | Triggered when a message is received. |
| meetingTimeRemaining | Triggered when meeting time remaining is received. |
| meetingStillThere | Triggered when the meeting is still active. |
| startRecords | Triggered when recording starts. |
| reInitiateRecording | Triggered when recording needs to be re-initiated. |
| getDomains | Triggered when domains are received. |
| updateConsumingDomains | Triggered when consuming domains are updated. |
| RecordingNotice | Triggered when a recording notice is received. |
| timeLeftRecording | Triggered when time left for recording is received. |
| stoppedRecording | Triggered when recording stops. |
| hostRequestResponse | Triggered when the host request response is received. |
| allMembers | Triggered when information about all members is received. |
| allMembersRest | Triggered when information about all members is received (rest of the members). |
| disconnect | Triggered when a disconnect event occurs. |
| pollUpdated | Triggered when a poll is updated. |
| breakoutRoomUpdated | Triggered when a breakout room is updated. |
Sample Usage:
// Example usage of provided socket event handling functions
import 'package:mediasfu_sdk/mediasfu_sdk.dart'show participantRequested, screenProducerId, participantRequestedOptions, screenProducerIdOptions, Request;
socket.value!.on('participantRequested', (data) async {
try {
// Convert userRequest data to Request object
Request request = Request.fromMap(data['userRequest']);
// Handle 'participantRequested' event
participantRequested(
ParticipantRequestedOptions(
userRequest: request,
requestList: requestList.value,
waitingRoomList: waitingRoomList.value,
updateRequestList: updateRequestList,
updateTotalReqWait: updateTotalReqWait,
),
);
} catch (error) {
if (kDebugMode) {
// print('Error handling participantRequested event: $error');
}
}
});
socket.value!.on('screenProducerId', (data) async {
// Handle 'screenProducerId' event
try {
screenProducerId(ScreenProducerIdOptions(
producerId: data['producerId'],
screenId: screenId.value,
membersReceived: membersReceived.value,
shareScreenStarted: shareScreenStarted.value,
deferScreenReceived: deferScreenReceived.value,
participants: participants.value,
updateScreenId: updateScreenId,
updateShareScreenStarted: updateShareScreenStarted,
updateDeferScreenReceived: updateDeferScreenReceived,
));
} catch (error) {
if (kDebugMode) {
// print('Error handling screenProducerId event: $error');
}
}
});
These functions enable seamless interaction with the server and ensure that the application stays synchronized with the real-time events occurring within the room.
Customizing Media Display in MediaSFU #
By default, media display in MediaSFU is handled by the following key functions:
prepopulateUserMedia: This function controls the main media grid, such as the host's video in webinar or broadcast views (MainGrid).addVideosGrid: This function manages the mini grid's media, such as participants' media in MiniGrid views (MiniCards, AudioCards, VideoCards).
Customizing the Media Display
If you want to modify the default content displayed by MediaSFU components, such as the MiniCard, AudioCard, or VideoCard, you can replace the default UI with your own custom components.
To implement your custom UI for media display:
-
Custom MainGrid (Host's Video):
- Modify the UI in the
prepopulateUserMediafunction. - Example link to MediaSFU's default implementation:
prepopulateUserMedia.
- Modify the UI in the
-
Custom MiniGrid (Participants' Media):
- Modify the UI in the
addVideosGridfunction. - Example link to MediaSFU's default implementation:
addVideosGrid.
- Modify the UI in the
To create a custom UI, you can refer to existing MediaSFU implementations like:
Once your custom components are built, modify the imports of prepopulateUserMedia and addVideosGrid to point to your custom implementations instead of the default MediaSFU ones.
This allows for full flexibility in how media is displayed in both the main and mini grids, giving you the ability to tailor the user experience to your specific needs.
API Reference #
For detailed information on the API methods and usage, please refer to the MediaSFU API Documentation.
If you need further assistance or have any questions, feel free to ask!
For sample codes and practical implementations, visit the MediaSFU Sandbox.
Troubleshooting #
Encountering issues while integrating MediaSFU into your Flutter application? Below are common problems and their solutions to help you get back on track.
1. Interactive Testing with MediaSFU's Frontend #
Issue: Difficulty in verifying if events or media transmissions are functioning correctly within your application.
Solution: Utilize MediaSFU's frontend to join the same room as your Flutter application. This allows you to interactively monitor and analyze event handling and media streams.
Steps:
- Open MediaSFU's Frontend: Navigate to the MediaSFU Frontend in your web browser.
- Join the Same Room: Use the same room credentials in the frontend that your Flutter app is using.
- Monitor Interactions: Perform actions in your Flutter app (e.g., start a call, share media) and observe the corresponding changes in the frontend. Similarly, perform actions in the frontend and verify their effects in your Flutter app.
This method helps ensure that interactions between users and media streams are functioning as expected.
2. Reducing Terminal Log Clutter #
Issue: Excessive Java logs cluttering the terminal output when running your Flutter application in debug mode, making it difficult to identify relevant Flutter logs.
Solution: Filter out irrelevant logs using command-line tools to display only Flutter-related logs, enhancing readability and debugging efficiency.
For Unix-based Systems (Linux/macOS): Use the following command to run your Flutter app while filtering logs:
flutter run | sed '/^.\// { /^\(V\|I\|W\|E\)\/flutter/!d }'
Explanation:
flutter run: Starts your Flutter application.|: Pipes the output to the next command.sed '/^.\// { /^\(V\|I\|W\|E\)\/flutter/!d }': Filters the logs to display only those that start with Flutter's log tags (V for Verbose, I for Info, W for Warning, E for Error).
For Windows Users: Use PowerShell to achieve similar log filtering:
flutter run | Select-String "flutter/"
Note: Ensure you have the necessary command-line tools installed and configured for your operating system.
3. Issues with Remote Streams on Web #
Issue: Remote streams not appearing when testing your Flutter application on the web, potentially due to localhost-related issues.
Solution: Follow these recommendations to ensure a reliable testing environment:
a. Build and Deploy
-
Build for Production: Create a production build of your Flutter web application using:
flutter build web -
Deploy to a Staging or Live Environment: Deploy the build to a web server or hosting service to test in a real-world scenario, which can bypass localhost limitations related to browser security and network configurations.
b. Use a Different Browser
-
Test Across Multiple Browsers: Some browsers handle WebRTC and media streams differently. Test your application on various browsers (e.g., Chrome, Firefox, Edge) to identify if the issue is browser-specific.
-
Check Browser Permissions: Ensure that the browser has granted the necessary permissions for camera and microphone access.
c. Verify Network Configurations
-
Firewall and Network Settings: Ensure that your network allows WebRTC traffic and that firewalls are not blocking necessary ports.
-
Use HTTPS: Browsers enforce stricter security policies for WebRTC on non-secure (HTTP) connections. Deploy your application over HTTPS to ensure proper functionality.
4. Additional Common Issues #
a. Unable to Connect to MediaSFU Server
Solution:
- Check Credentials: Ensure that your
apiUserNameandapiKeyare correctly set and valid. - Network Connectivity: Verify that your device has a stable internet connection.
- Server Status: Confirm that MediaSFU servers are operational by checking the MediaSFU Status Page.
b. Application Crashes or Freezes During Media Transmission
Solution:
-
Update Dependencies: Ensure that all Flutter dependencies are up-to-date by running:
flutter pub get flutter pub upgrade -
Review Logs: Use the filtered logs (as described in section 2) to identify any errors or warnings that could indicate the cause.
-
Device Resources: Ensure that the device running the application has sufficient resources (CPU, memory) to handle media transmissions.
c. UI Elements Not Displaying Correctly
Solution:
- Hot Reload: Use Flutter's hot reload feature to apply code changes without restarting the application.
- Check Widget Tree: Ensure that your widgets are properly nested and there are no conflicts in the UI hierarchy.
- Responsive Design: Verify that your UI is responsive and adapts to different screen sizes and orientations.
Key Points to Remember #
- Interactive Testing: Utilize MediaSFU's frontend to verify event handling and media streams.
- Log Filtering: Use command-line tools to filter out non-Flutter logs for a cleaner debugging experience.
- Web Testing: Deploy your app to a live environment and test across multiple browsers to resolve remote stream issues.
- Stay Updated: Regularly update your dependencies and monitor server statuses to prevent common issues.
- Responsive UI: Ensure your application's UI is responsive and correctly structured to avoid display problems.
-
Interactive Testing with MediaSFU's Frontend: Users can interactively join MediaSFU's frontend in the same room to analyze if various events or media transmissions are happening as expected. For example, adding a user there to check changes made by the host and vice versa.
-
Reducing Terminal Log Clutter: When running your Flutter application on a physical device in debug mode, you might encounter excessive logs from Java that clutter the terminal output. To address this issue, you can use the following command to filter out irrelevant logs:
flutter run | sed '/^.\// { /^\(V\|I\|W\|E\)\/flutter/!d }'This command will only display logs related to Flutter, excluding unnecessary logs from other sources. It helps in maintaining a cleaner terminal output for better debugging experience.
-
Issues with Remote Streams on Web: If you have issues seeing remote streams on the web, it might be due to problems related to localhost. Testing on localhost can sometimes lead to issues due to various factors, such as browser security settings or network configurations. To ensure a more reliable testing environment, it is recommended to:
- Build and Deploy: Make a production build of your application and deploy it to a staging or live environment. This will help you test the application in a real-world scenario, bypassing potential issues related to localhost.
- Use a Different Browser: Sometimes, different browsers handle local streams differently. Testing on multiple browsers can help identify if the issue is browser-specific. These troubleshooting steps should help users address common issues and optimize their experience with MediaSFU. If the issues persist or additional assistance is needed, users can refer to the documentation or reach out to the support team for further assistance.
Contributing #
We welcome contributions from the community to improve the project! If you'd like to contribute, please check out our GitHub repository and follow the guidelines outlined in the README.
If you encounter any issues or have suggestions for improvement, please feel free to open an issue on GitHub.
We appreciate your interest in contributing to the project!
If you need further assistance or have any questions, feel free to ask!
Metadata
Publisher
Weekly Downloads
Metadata
MediaSFU SDK for Flutter provides powerful streaming capabilities for creating high-performance cross-platform applications.
Homepage
Repository (GitHub)
View/report issues
License
unknown (license)
Dependencies
audioplayers, clipboard, collection, flutter, flutter_colorpicker, flutter_webrtc, font_awesome_flutter, http, intl, mediasfu_mediasoup_client, shared_preferences, socket_io_client, url_launcher
