mebius

Live video for Flutter — broadcast and watch real-time streams through the Mebius gateway with one simple API.

mebius gives you a tiny, stable API for publishing a camera/microphone stream and for watching live streams, with two playback profiles: latency-optimized and scale-optimized. All transport is handled for you behind the Mebius gateway.

2. Requirements

• Flutter: >= 3.22.0
• Dart: >= 3.4.0 < 4.0.0
• iOS: 13.0+ (camera & microphone usage descriptions required)
• Android: minSdkVersion 24+ (camera, microphone & internet permissions required)

iOS — Info.plist

<key>NSCameraUsageDescription</key>
<string>This app uses the camera to broadcast live video.</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app uses the microphone to broadcast live audio.</string>

Android — AndroidManifest.xml

<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.MODIFY_AUDIO_SETTINGS" />

3. Install

Add mebius from pub.dev:

flutter pub add mebius

or add it manually to your pubspec.yaml and run flutter pub get:

dependencies:
  mebius: ^0.1.0

Then import it:

import 'package:mebius/mebius.dart';

dependencies:
  mebius:
    git:
      url: https://github.com/russimobiledroidx/mebius-flutter-sdk.git
      ref: v0.1.0

4. Platform setup

iOS

Set the platform floor and enable the required capabilities in ios/Podfile:

platform :ios, '13.0'

Add the usage descriptions shown in Requirements to ios/Runner/Info.plist. If you target a background broadcasting use case, also enable the relevant Background Modes in Xcode (Audio).

Android

In android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 24
    }
}

Add the permissions shown in Requirements to android/app/src/main/AndroidManifest.xml. Camera and microphone are runtime permissions on Android 6.0+, so request them before broadcasting (see Troubleshooting).

5. Quick Start

Auth

The SDK never holds your app secret. Your backend mints a short-lived token (a JWT derived from your appId + appSecret) and your app passes that token to Mebius.connect. When the token expires the client emits an error event with code TOKEN_EXPIRED; refresh the token from your backend and reconnect.

Initialize and connect

import 'package:mebius/mebius.dart';

void main() {
  Mebius.init(
    appId: 'your-app-id',
    gateway: 'https://gateway.mebius.example',
  );
  runApp(const MyApp());
}

// Later, after fetching a token from your backend. The same response carries a
// `deliveries` list — pass it through as-is and Mebius picks the best route for
// each viewer, falling back on its own if one stops delivering frames.
final body = jsonDecode(response.body) as Map<String, dynamic>;
final client = Mebius.connect(
  token: body['token'] as String,
  deliveries: MebiusDelivery.listFromJson(body['deliveries']),
);

client.events.listen((event) {
  switch (event.type) {
    case MebiusClientEventType.connected:
      // Ready.
    case MebiusClientEventType.disconnected:
      // Session ended.
    case MebiusClientEventType.error:
      if (event.error?.code == MebiusErrorCode.tokenExpired) {
        // Refresh the token and reconnect.
      }
  }
});

Broadcast

class BroadcastPage extends StatefulWidget {
  const BroadcastPage({required this.client, super.key});
  final MebiusClient client;

  @override
  State<BroadcastPage> createState() => _BroadcastPageState();
}

class _BroadcastPageState extends State<BroadcastPage> {
  late final MebiusBroadcaster _broadcaster =
      widget.client.createBroadcaster(video: true, audio: true);

  @override
  void dispose() {
    _broadcaster.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Expanded(child: MebiusView(broadcaster: _broadcaster)),
        Row(
          children: [
            ElevatedButton(
              onPressed: () => _broadcaster.start('my-stream'),
              child: const Text('Start'),
            ),
            ElevatedButton(
              onPressed: _broadcaster.stop,
              child: const Text('Stop'),
            ),
            IconButton(
              onPressed: _broadcaster.switchCamera,
              icon: const Icon(Icons.cameraswitch),
            ),
            IconButton(
              onPressed: () => _broadcaster.setMicEnabled(enabled: false),
              icon: const Icon(Icons.mic_off),
            ),
          ],
        ),
      ],
    );
  }
}

Watch

class WatchPage extends StatefulWidget {
  const WatchPage({required this.client, super.key});
  final MebiusClient client;

  @override
  State<WatchPage> createState() => _WatchPageState();
}

class _WatchPageState extends State<WatchPage> {
  late final MebiusPlayer _player =
      widget.client.createPlayer();

  @override
  void initState() {
    super.initState();
    _player.play('my-stream');
  }

  @override
  void dispose() {
    _player.dispose();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        Expanded(child: MebiusView.player(player: _player)),
        Slider(
          value: 1,
          onChanged: (v) => _player.setVolume(v),
        ),
        ElevatedButton(
          onPressed: _player.stop,
          child: const Text('Stop'),
        ),
      ],
    );
  }
}

Playback modes

To switch, dispose the current player and create a new one:

client.createPlayer();                                  // auto
client.createPlayer(mode: MebiusPlayerMode.scale);      // scale

Watching the other side of a co-broadcast

final monitor = client.createMonitor();
await monitor.play(opponentStreamId);

Same API as a player, different delay budget: it starts on the real-time route and moves to another by itself if no frame arrives within 8 seconds.

deliveries

Mebius.connect accepts the deliveries list your backend returned with the token. Pass it through untouched — kind and path are opaque, and Mebius decides the ordering. It is optional, but without it every viewer is served from Mebius origin instead of the nearest edge, and on mobile that is billed per viewer.

A full, copy-paste example with both screens, camera switching, mute, mode-toggling and a volume slider lives in example/lib/main.dart.

6. API Reference

7. Events

All events are delivered through Dart Streams. Subscribe with listen and remember to keep the subscription only as long as the object lives.

Client events

client.events.listen((MebiusClientEvent event) {
  // event.type : MebiusClientEventType { connected, disconnected, error }
  // event.error: MebiusError?  (set only for `error`)
});

Broadcaster events

broadcaster.events.listen((MebiusBroadcasterEvent event) {
  // event.type : MebiusBroadcasterEventType { started, stopped, stats }
  // event.stats: MebiusBroadcastStats?  (set only for `stats`)
  //   - outboundBitrateKbps: double
  //   - frameRate:           double
  //   - packetsSent:         int
});

Player events

player.events.listen((MebiusPlayerEvent event) {
  // event.type : MebiusPlayerEventType { playing, buffering, ended, stats }
  // event.stats: MebiusPlaybackStats?  (set only for `stats`)
  //   - inboundBitrateKbps: double
  //   - frameRate:          double
  //   - bufferedMs:         int
});

8. Error handling

Every failure is a MebiusError with a stable code (MebiusErrorCode) and a human-readable message. The codes are identical across all Mebius client SDKs.

try {
  await broadcaster.start('my-stream');
} on MebiusError catch (e) {
  switch (e.code) {
    case MebiusErrorCode.permissionDenied:
      // Ask the user to grant camera/mic access.
    case MebiusErrorCode.tokenExpired:
      // Refresh token and reconnect.
    default:
      // Show e.message.
  }
}

9. Troubleshooting

• Runtime permissions (Android/iOS): declaring permissions in the manifest / Info.plist is not enough. On Android 6.0+ and iOS, the OS prompts the user the first time the camera/microphone is accessed. A denial surfaces as MebiusErrorCode.permissionDenied. Use a package such as permission_handler to request them up front for a smoother flow.
• Background: broadcasting in the background requires the appropriate OS capabilities (iOS Background Modes → Audio; Android foreground service). By default, expect publishing to pause when the app is backgrounded.
• Dispose lifecycle: always dispose() your MebiusBroadcaster and MebiusPlayer (typically in State.dispose), and disconnect() the MebiusClient when you are done. MebiusView releases its own renderer, but it does not own the broadcaster/player you pass in. Failing to dispose leaks camera/microphone and network resources.
• Black video surface: the surface stays black until media arrives. Listen for the playing (player) or started (broadcaster) event to know when it is live.

10. Versioning & changelog

This package follows Semantic Versioning. The public API is stable within a major version; any breaking change to the contract is a major version bump. See CHANGELOG.md for the full history.

11. License

Released under the MIT License.