Connecting to a Session

This page walks through the complete flow for joining an EnableX video session from a Flutter app — selecting an audio output device, joining the room via EnxRtc.joinRoom(), handling connection events, and disconnecting cleanly. Follow the steps in order; each depends on the previous one completing successfully.

Joining an EnableX session from Flutter involves these steps in sequence:

1. Optionally query audio devices — find out which output devices are available and let the user choose one.
2. Assign all callback handlers — register your response functions on EnxRtc before connecting so no early events are missed.
3. Call EnxRtc.joinRoom() — pass the session token, local stream settings, room settings, and advanced options to initiate the connection.
4. Handle onRoomConnected — confirm the connection succeeded and proceed to publish your local stream.
5. Publish your local stream — covered in detail in Stream Management.
6. Call EnxRtc.disconnect() — cleanly end the session when the user leaves.

Before joining, you can query which audio output devices are currently available on the device and allow the user to select their preferred route. This is especially useful when multiple devices are connected — for example, when a Bluetooth headset is paired alongside the built-in speaker.

The Flutter SDK exposes two methods for this:

• EnxRtc.getDevices() — returns a List<dynamic> of all available audio output devices.
• EnxRtc.getSelectedDevice() — returns the currently active device as a String.

Possible device values returned by getDevices():

• SPEAKER_PHONE — built-in loudspeaker
• WIRED_HEADSET — wired headphones or headset
• EARPIECE — phone earpiece (quiet, held-to-ear)
• BLUETOOTH — Bluetooth audio device
• NONE — no audio device available

// Get all available audio output devices
List<dynamic> devices = EnxRtc.getDevices();
print('Available devices: $devices');

// Get the currently active audio output device
String currentDevice = await EnxRtc.getSelectedDevice();
print('Active device: $currentDevice');

Register Callbacks First

The EnableX Flutter SDK communicates all connection events through callbacks assigned directly on the EnxRtc class. Because some callbacks — such as onRoomConnected — fire immediately when the connection is established, you must register all handlers before calling joinRoom().

EnxRtc.joinRoom()

EnxRtc.joinRoom() is the single call that connects your Flutter app to an EnableX video session. It authenticates with the JWT token, negotiates the WebRTC connection, and prepares the local media stack. The call is async — your app receives the outcome through the onRoomConnected or onRoomError callbacks.

The method accepts four parameters:

• token — the JWT session token issued by your server.
• localInfo — a map describing the local stream: which media tracks to capture and the participant's display name.
• roomInfo — a map controlling reconnection behaviour and audio-only mode.
• advanceOptions — a list of optional feature flags (pass an empty list if unused).

Method Signature

static Future<void> joinRoom(
  String token,
  Map<String, dynamic> localInfo,
  Map<String, dynamic> roomInfo,
  List<dynamic> advanceOptions
)

localInfo — Configuring the Local Stream

The localInfo map tells the SDK what media to capture from the device and how to identify this participant in the room.

Map<String, dynamic> localInfo = {
  'audio': true,
  'video': true,
  'data': true,
  'name': 'Alice',
  'audioMuted': false,
  'videoMuted': false,
};

roomInfo — Reconnection and Audio-Only Settings

The roomInfo map controls how the SDK handles network disruptions and whether video should be active at all.

Map<String, dynamic> roomInfo = {
  'allow_reconnect': true,
  'number_of_attempts': 3,
  'timeout_interval': 20,
  'audio_only': false,
  'forceTurn': false,
};

Full Join Example

The example below shows a complete Flutter StatefulWidget that registers all necessary callbacks in initState() and then calls joinRoom(). This is the recommended pattern — it guarantees that no early events are missed.

import 'package:enx_flutter_plugin/enx_flutter_plugin.dart';

class VideoSessionPage extends StatefulWidget {
  final String token;
  const VideoSessionPage({required this.token, super.key});

  @override
  State<VideoSessionPage> createState() => _VideoSessionPageState();
}

class _VideoSessionPageState extends State<VideoSessionPage> {

  @override
  void initState() {
    super.initState();
    _registerCallbacks();
    _joinRoom();
  }

  void _registerCallbacks() {
    EnxRtc.onRoomConnected = (Map<dynamic, dynamic> map) {
      print('Room connected: $map');
      // Proceed to publish local stream here
    };

    EnxRtc.onRoomError = (Map<dynamic, dynamic> map) {
      print('Room error: ${map['msg']}');
    };

    EnxRtc.onUserConnected = (Map<dynamic, dynamic> map) {
      print('User joined: ${map['name']}');
    };

    EnxRtc.onUserDisConnected = (Map<dynamic, dynamic> map) {
      print('User left: ${map['clientId']}');
    };

    EnxRtc.onRoomDisConnected = (Map<dynamic, dynamic> map) {
      print('Disconnected from room');
    };
  }

  Future<void> _joinRoom() async {
    Map<String, dynamic> localInfo = {
      'audio': true,
      'video': true,
      'data': true,
      'name': 'Alice',
      'audioMuted': false,
      'videoMuted': false,
    };

    Map<String, dynamic> roomInfo = {
      'allow_reconnect': true,
      'number_of_attempts': 3,
      'timeout_interval': 20,
      'audio_only': false,
      'forceTurn': false,
    };

    await EnxRtc.joinRoom(widget.token, localInfo, roomInfo, []);
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Video Session')),
      body: Container(), // Add EnxPlayerWidget here for video
    );
  }
}

Callbacks Fired on Connection

Once joinRoom() is called, the SDK fires the following callbacks to report the outcome and participant activity:

When the user ends the session — by tapping a leave button, navigating away, or closing the app — your app should call EnxRtc.disconnect(). This method stops local media capture, closes the WebRTC peer connection, and signals the server to remove this participant from the room. The SDK confirms the teardown through the onRoomDisConnected callback.

EnxRtc.disconnect()

// Disconnect when the user taps "End Call"
void endSession() {
  EnxRtc.disconnect();
}

Listen for onRoomDisConnected to confirm the teardown is complete, then navigate away from the video screen:

EnxRtc.onRoomDisConnected = (Map<dynamic, dynamic> map) {
  // Session fully ended — navigate back to the previous screen
  Navigator.of(context).pop();
};

When allow_reconnect: true is set in roomInfo, the SDK automatically attempts to restore the connection if the network drops — without any additional code required from your app. Your job is to listen to the reconnection lifecycle callbacks and update the UI accordingly so the user knows what is happening.

The SDK fires the following callbacks during a reconnection sequence:

A typical pattern is to show a status message while reconnecting and clear it once the SDK reports success:

EnxRtc.onConnectionLost = (Map<dynamic, dynamic> map) {
  setState(() {
    _status = 'Reconnecting...';
  });
};

EnxRtc.onConnectionInterrupted = (Map<dynamic, dynamic> map) {
  setState(() {
    _status = 'Connection interrupted. Trying to restore...';
  });
};

EnxRtc.onReconnect = (Map<dynamic, dynamic> map) {
  // Fired for each reconnection attempt — useful for showing attempt count
  print('Reconnection attempt in progress');
};

EnxRtc.onUserReconnectSuccess = (Map<dynamic, dynamic> map) {
  setState(() {
    _status = 'Connected';
  });
};

The EnableX server continuously monitors the network quality of all participants. When available bandwidth degrades to the point where it can no longer support the current number of active video streams, the SDK notifies your app through onRoomBandwidthAlert.

This callback is your signal to adapt the experience — for example, reducing the number of visible video panels, switching the session to audio-only mode, or informing the user that their connection quality is low.

onRoomBandwidthAlert

EnxRtc.onRoomBandwidthAlert = (Map<dynamic, dynamic> map) {
  // The map contains details about the current bandwidth condition
  print('Bandwidth alert: $map');

  // Example adaptive response: switch to audio-only mode
  // or reduce the active talker count in your UI
};