Twilio Flutter Video SDK

A Flutter plugin for integrating Twilio Programmable Video SDK, providing video conferencing capabilities with features like mute/unmute, camera switching, video toggle, and meeting management.

Features

✅ Join/Leave video rooms
✅ Mute/Unmute audio
✅ Toggle video on/off
✅ Switch between front and back camera
✅ End meeting/disconnect
✅ Real-time participant events
✅ Connection status monitoring
✅ Error handling
✅ Native video rendering via PlatformView
✅ Multiple remote participant support
✅ Video track enabled/disabled handling
✅ Automatic handling of existing participants when joining rooms

Platform Support

✅ Android (API 24+, Twilio Video SDK 7.9.1)
✅ iOS (13.0+, Twilio Video SDK 5.3.0)

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  twilio_flutter_video_sdk:
    path: ../twilio_flutter_video_sdk

Or if published:

dependencies:
  twilio_flutter_video_sdk: ^1.0.0

Android Setup

The plugin requires the following permissions in your AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.BLUETOOTH" />

The Twilio Video SDK dependency (version 7.9.1) is automatically included via Maven Central.

iOS Setup

Add the following permissions to your Info.plist:

<key>NSCameraUsageDescription</key>
<string>This app needs access to the camera for video calls</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs access to the microphone for video calls</string>
<key>io.flutter.embedded_views_preview</key>
<true/>

The Twilio Video SDK dependency (version 5.3.0) is automatically included via CocoaPods.

Run pod install in the ios/ directory after adding the plugin.

Usage

Quick Start with VideoRoomScreen (Recommended)

The easiest way to use the plugin is with the built-in VideoRoomScreen widget:

import 'package:twilio_flutter_video_sdk/twilio_flutter_video_sdk.dart';
import 'package:permission_handler/permission_handler.dart';

// Request permissions first
await [Permission.camera, Permission.microphone].request();

// Navigate to video room screen
Navigator.push(
  context,
  MaterialPageRoute(
    builder: (context) => VideoRoomScreen(
      options: VideoRoomScreenOptions(
        accessToken: 'YOUR_ACCESS_TOKEN',
        roomName: 'my-room',
        enableAudio: true,
        enableVideo: true,
        enableFrontCamera: true,
        onConnected: () {
          print('Connected to room!');
        },
        onDisconnected: () {
          print('Disconnected from room');
        },
        onConnectionFailure: (error) {
          print('Connection failed: $error');
        },
      ),
    ),
  ),
);

Custom VideoRoomScreen

You can customize the video room screen with your own widgets:

VideoRoomScreen(
  options: VideoRoomScreenOptions(
    accessToken: 'YOUR_ACCESS_TOKEN',
    roomName: 'my-room',
    // Custom local video widget
    localVideoBuilder: (context) => Container(
      height: 200,
      child: TwilioVideoView(viewId: "0"),
    ),
    // Custom remote video widget
    remoteVideoBuilder: (context, participantSid) => Container(
      height: 150,
      child: TwilioVideoView(viewId: participantSid),
    ),
    // Custom controls
    controlsBuilder: (context, controller) => Row(
      mainAxisAlignment: MainAxisAlignment.spaceEvenly,
      children: [
        IconButton(
          icon: Icon(controller.isMuted ? Icons.mic_off : Icons.mic),
          onPressed: controller.toggleMute,
        ),
        IconButton(
          icon: Icon(controller.isVideoEnabled ? Icons.videocam : Icons.videocam_off),
          onPressed: controller.toggleVideo,
        ),
        IconButton(
          icon: Icon(Icons.cameraswitch),
          onPressed: controller.switchCamera,
        ),
        IconButton(
          icon: Icon(Icons.call_end),
          onPressed: controller.disconnect,
        ),
      ],
    ),
  ),
)

Basic Example (Manual Implementation)

import 'package:twilio_flutter_video_sdk/twilio_flutter_video_sdk.dart';
import 'package:permission_handler/permission_handler.dart';

// Request permissions
await [Permission.camera, Permission.microphone].request();

// Create video controller
final videoController = TwilioVideoController();

// Create a room instance
final room = videoController.createRoom();

// Listen to events
room.events.listen((event) {
  print('Event: $event');
  if (event == TwilioVideoEvent.connected) {
    print('Connected to room');
  }
});

room.errors.listen((error) {
  print('Error: $error');
});

// Listen to participant events
room.participantEvents.listen((participant) {
  print('Participant: ${participant.identity} connected');
});

// Listen to video track events
room.videoTrackEvents.listen((track) {
  print('Video track: ${track.participantSid}, enabled: ${track.isEnabled}');
});

// Join a room
await room.joinRoom(
  RoomOptions(
    accessToken: 'YOUR_ACCESS_TOKEN',
    roomName: 'my-room',
    enableAudio: true,
    enableVideo: true,
    enableFrontCamera: true,
  ),
);

// Mute/Unmute
await room.toggleMute();

// Toggle video
await room.toggleVideo();

// Switch camera
await room.switchCamera();

// Disconnect
await room.disconnect();

Displaying Video Views

The plugin provides TwilioVideoView widget for rendering native video:

import 'package:twilio_flutter_video_sdk/twilio_flutter_video_sdk.dart';

// Local video view (viewId: 0)
TwilioVideoView(viewId: 0)

// Remote participant video view (viewId: participantSid)
TwilioVideoView(viewId: participantSid)

Complete Example with Video Views

class VideoRoomScreen extends StatefulWidget {
  @override
  _VideoRoomScreenState createState() => _VideoRoomScreenState();
}

class _VideoRoomScreenState extends State<VideoRoomScreen> {
  TwilioVideoController? _controller;
  TwilioVideoRoom? _room;
  Set<String> _remoteParticipantSids = {};
  bool _isConnected = false;

  @override
  void initState() {
    super.initState();
    _controller = TwilioVideoController();
    _room = _controller!.createRoom();
    
    // Listen to video track events
    _room!.videoTrackEvents.listen((track) {
      setState(() {
        if (track.isEnabled && track.nativeViewReady) {
          _remoteParticipantSids.add(track.participantSid);
        } else {
          _remoteParticipantSids.remove(track.participantSid);
        }
      });
    });
    
    // Listen to connection events
    _room!.events.listen((event) {
      if (event == TwilioVideoEvent.connected) {
        setState(() => _isConnected = true);
      } else if (event == TwilioVideoEvent.disconnected) {
        setState(() {
          _isConnected = false;
          _remoteParticipantSids.clear();
        });
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: Column(
        children: [
          // Local video
          SizedBox(
            height: 200,
            child: TwilioVideoView(viewId: 0),
          ),
          
          // Remote videos
          Expanded(
            child: _remoteParticipantSids.isEmpty
                ? Center(child: Text('Waiting for participants...'))
                : GridView.builder(
                    gridDelegate: SliverGridDelegateWithFixedCrossAxisCount(
                      crossAxisCount: 2,
                    ),
                    itemCount: _remoteParticipantSids.length,
                    itemBuilder: (context, index) {
                      final participantSid = _remoteParticipantSids.elementAt(index);
                      return TwilioVideoView(viewId: participantSid);
                    },
                  ),
          ),
        ],
      ),
    );
  }

  @override
  void dispose() {
    _room?.disconnect();
    _controller?.dispose();
    super.dispose();
  }
}

Complete Example

See the example/ directory for a complete working example with UI.

API Reference

TwilioVideoController

Main controller for managing video rooms.

final controller = TwilioVideoController();
final room = controller.createRoom();
controller.dispose(); // Clean up resources

TwilioVideoRoom

Represents a video room connection.

Methods

Future<void> joinRoom(RoomOptions options) - Join a video room
Future<void> disconnect() - Disconnect from the room
Future<void> setMuted(bool muted) - Mute or unmute audio
Future<void> toggleMute() - Toggle mute state
Future<void> setVideoEnabled(bool enabled) - Enable or disable video
Future<void> toggleVideo() - Toggle video on/off
Future<void> switchCamera() - Switch between front and back camera
void dispose() - Dispose resources

Properties

bool isConnected - Whether currently connected
bool isMuted - Whether audio is muted
bool isVideoEnabled - Whether video is enabled
bool isFrontCamera - Whether using front camera

Streams

Stream<TwilioVideoEvent> events - Video events stream
Stream<ParticipantInfo> participantEvents - Participant updates
Stream<VideoTrackInfo> videoTrackEvents - Video track updates
Stream<String> errors - Error messages

VideoRoomScreen

Ready-to-use video room screen widget with built-in UI and controls.

VideoRoomScreen({
  required VideoRoomScreenOptions options,
  VideoRoomScreenController? controller,
})

Features:

Complete UI with local and remote video views
Built-in controls (mute, video toggle, camera switch, disconnect)
Automatic handling of video tracks and participants
Customizable with builder functions
Optional controller for programmatic control

VideoRoomScreenOptions

Configuration for VideoRoomScreen.

VideoRoomScreenOptions({
  required String accessToken,        // Twilio access token
  required String roomName,           // Room name to join
  bool enableAudio = true,            // Enable audio by default
  bool enableVideo = true,            // Enable video by default
  bool enableFrontCamera = true,      // Use front camera by default
  bool showInputFields = false,      // Show token/room input fields
  String? appBarTitle,                // Custom app bar title
  VoidCallback? onConnected,          // Called when connected
  VoidCallback? onDisconnected,       // Called when disconnected
  Function(String)? onConnectionFailure, // Called on connection failure
  Widget Function(BuildContext)? localVideoBuilder,  // Custom local video widget
  Widget Function(BuildContext, String)? remoteVideoBuilder, // Custom remote video widget
  Widget Function(BuildContext, VideoRoomScreenController)? controlsBuilder, // Custom controls
})

VideoRoomScreenController

Controller for programmatically controlling VideoRoomScreen.

final controller = VideoRoomScreenController();

// Properties
controller.isConnected      // Whether connected to room
controller.isMuted          // Whether audio is muted
controller.isVideoEnabled   // Whether video is enabled
controller.isFrontCamera   // Whether using front camera
controller.room            // Access to TwilioVideoRoom instance

// Methods
await controller.toggleMute();     // Toggle mute state
await controller.toggleVideo();    // Toggle video on/off
await controller.switchCamera();   // Switch camera
await controller.disconnect();     // Disconnect from room

TwilioVideoView

Widget for displaying native video views.

TwilioVideoView({
  required String viewId,  // "0" for local, participantSid for remote
})

Important Notes:

Local video always uses viewId: "0"
Remote participant videos use viewId: participantSid
Only create TwilioVideoView widgets when track.isEnabled && track.nativeViewReady is true
The widget automatically handles platform-specific rendering (AndroidView on Android, UiKitView on iOS)

RoomOptions

Configuration for joining a room.

RoomOptions(
  accessToken: 'YOUR_ACCESS_TOKEN',  // Required
  roomName: 'room-name',              // Required
  enableAudio: true,                  // Optional, default: true
  enableVideo: true,                  // Optional, default: true
  enableFrontCamera: true,            // Optional, default: true
)

TwilioVideoEvent

Video events emitted by the room.

class TwilioVideoEvent {
  final String event;
  final Map<String, dynamic> data;
}

Event types:

connected - Successfully connected to room
disconnected - Disconnected from room
connectionFailure - Failed to connect
participantConnected - Remote participant joined
participantDisconnected - Remote participant left
videoTrackAdded - Video track added (local or remote)
videoTrackRemoved - Video track removed
audioTrackAdded - Audio track added
audioTrackRemoved - Audio track removed

VideoTrackInfo

Information about a video track.

class VideoTrackInfo {
  final String trackSid;
  final String participantSid;
  final bool isEnabled;
  final bool nativeViewReady;  // Whether native VideoView is ready
}

Important: Only create TwilioVideoView widgets when both isEnabled and nativeViewReady are true. This ensures the native view exists before Flutter tries to access it.

ParticipantInfo

Information about a participant.

class ParticipantInfo {
  final String sid;
  final String identity;
  final bool isAudioEnabled;
  final bool isVideoEnabled;
  final bool isConnected;
}

Video Track Lifecycle

The plugin handles video tracks as follows:

When a participant joins with video:
- videoTrackAdded event is sent with isEnabled: true and nativeViewReady: true
- Create TwilioVideoView widget with the participant's SID
When a participant disables video:
- videoTrackAdded event is sent with isEnabled: false
- Remove the participant from your UI or show a placeholder
- The native view is kept for reuse when video is enabled again
When a participant enables video again:
- videoTrackAdded event is sent with isEnabled: true and nativeViewReady: true
- Re-add the participant to your UI
When a participant leaves:
- videoTrackRemoved event is sent
- Remove the participant from your UI

Handling Existing Participants

When you join a room where other participants are already present:

The plugin automatically detects existing participants
Video tracks for existing participants are handled automatically
videoTrackAdded events are sent for all existing subscribed tracks
No special handling needed - just listen to videoTrackEvents and create views as tracks are added

Getting Access Tokens

To use this plugin, you need Twilio access tokens. You can generate them using the Twilio Video Access Token Generator or by creating a backend service.

Important: Never embed your Twilio credentials in your mobile app. Always use a backend service to generate access tokens.

Example backend endpoint (Node.js):

const express = require('express');
const twilio = require('twilio');

const app = express();
const AccessToken = twilio.jwt.AccessToken;
const VideoGrant = AccessToken.VideoGrant;

app.post('/token', (req, res) => {
  const { identity, roomName } = req.body;
  
  const token = new AccessToken(
    process.env.TWILIO_ACCOUNT_SID,
    process.env.TWILIO_API_KEY,
    process.env.TWILIO_API_SECRET,
    { identity }
  );
  
  const videoGrant = new VideoGrant({ room: roomName });
  token.addGrant(videoGrant);
  
  res.json({ token: token.toJwt() });
});

Permissions

The plugin requires camera and microphone permissions. Make sure to request these permissions before joining a room:

import 'package:permission_handler/permission_handler.dart';

final statuses = await [
  Permission.camera,
  Permission.microphone,
].request();

if (statuses[Permission.camera]?.isGranted == true &&
    statuses[Permission.microphone]?.isGranted == true) {
  // Permissions granted, proceed to join room
} else {
  // Handle permission denial
}

Troubleshooting

Android Issues

Build errors with Twilio SDK:
- Ensure mavenCentral() is in your settings.gradle.kts repositories
- Verify Twilio Video SDK version 7.9.1 is being used
- Clean and rebuild: ./gradlew clean build
Camera not working:
- Ensure minSdk is 24 or higher
- Check that all permissions are declared in AndroidManifest.xml
- Verify camera permission is granted before joining room
Video views not showing:
- Ensure you're only creating TwilioVideoView when nativeViewReady is true
- Check that viewId matches the participant SID for remote videos
- Verify PlatformView is properly registered

iOS Issues

Build errors:
- Ensure iOS deployment target is 13.0 or higher
- Run pod install in the iOS directory after adding the plugin
- Clean build folder in Xcode: Product → Clean Build Folder
Camera/Microphone not working:
- Check that camera and microphone permissions are in Info.plist
- Verify io.flutter.embedded_views_preview is set to true in Info.plist
- Request permissions before joining room
Video views not showing:
- Ensure you're only creating TwilioVideoView when nativeViewReady is true
- Check that viewId matches the participant SID for remote videos
- Verify PlatformView factory is properly registered

Common Issues

"Waiting for video..." message:
- This appears when Flutter tries to create a PlatformView before the native view is ready
- Solution: Only create TwilioVideoView when track.nativeViewReady is true
Frozen video when participant turns off video:
- Fixed in version 1.0.0: The plugin now properly removes renderers when video is disabled
- Ensure you're handling isEnabled: false events and hiding/showing placeholders
Remote videos not appearing when joining active room:
- Fixed in version 1.0.0: The plugin automatically detects and handles existing participants
- Just listen to videoTrackEvents and create views as tracks are added

Version History

1.0.0+1

Initial release
Support for Android (SDK 7.9.1) and iOS (SDK 5.3.0)
Native video rendering via PlatformView
Multiple remote participant support
Video track enabled/disabled handling
Automatic handling of existing participants
Proper cleanup when video is disabled (prevents frozen frames)
VideoRoomScreen widget - Ready-to-use video room screen with built-in UI and controls

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Twilio Video SDK for the native SDKs
Flutter team for the plugin architecture