100ms Logo

100ms

Docs

Search docs
/

100ms SDK Flutter Quickstart Guide

Overview

This overview shows the major steps involved in creating a Demo Flutter Project with the 100ms SDK. Each section links to extra detail.

A sample app demonstrating this is available here.

Jump to a section you're interested in or read top down to get the overview

  • Show an optional of the user's audio video with the 100ms hmssdk.preview.

Prerequisites

Familiarity with the fundamentals of Flutter apps.

HMSSDK requires flutter 2.10.x or above versions

To join a video call you need an authentication token and a room id. Or a server that will translate the link into them. The 100ms Dashboard is one way to generate these auth tokens. In production your own server will generate these and manage user authentication.

Links created by the dashboard will stop working after 10k minutes of video calls. You'll need to setup your own server after.

For the purposes of this quickstart you can rely on just the 100ms dashboard. Sign up for the 100ms Dashboard here.

From either the dashboard, or your own server once implemented, you need to generate a video call link. Video call links generated by the 100ms Dashboard look like https://myname.app.100ms.live/meeting/correct-horse-battery.

⚙️ For Production

With your own server for authentication and link generation, the format of the link is up to you.

Add SDK dependencies

Add the hmssdk_flutter plugin in dependencies of pubspec.yaml

#pubspec.yaml dependencies: flutter: sdk: flutter hmssdk_flutter:

Login

Request

Here's how to get an auth token with 100ms's demo authentication

  1. Sign up to the dashboard.
  2. Get your video call link. It should look like https://myname.app.100ms.live/meeting/correct-horse-battery
  3. Send an http post request to https://prod-in.100ms.live/hmsapi/get-token
  4. With the header "subdomain" set to myname.app.100ms.live if your link was https://myname.app.100ms.live/meeting/correct-horse-battery
  5. For a link of the type https://myname.app.100ms.live/meeting/correct-horse-battery The body is json with the format {"code": "correct-horse-battery", "user_id":"your-customer-id" } the user_id can be any random string as well and you can create it with UUID.randomUUID().toString(),.

⚙️ For Production

Maybe you won't use links at all. You will need to generate tokens on the backend, and rooms for users. Look up the Token Setup Guide here.

Response

The 100ms server will respond with an auth token like this {"token":"some-token-string"}.

Add Permissions

Android Permissions

Camera, Recording Audio and Internet permissions are required. Add them to your AndroidManifest.xml.

<uses-feature android:name="android.hardware.camera"/> <uses-feature android:name="android.hardware.camera.autofocus"/> <uses-permission android:name="android.permission.CAMERA"/> <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/> <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/> <uses-permission android:name="android.permission.RECORD_AUDIO"/> <uses-permission android:name="android.permission.BLUETOOTH"/> <uses-permission android:name="android.permission.INTERNET"/> <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview. Please follow Android Documentation for runtime permissions.

iOS Permissions

Add following permissions in iOS Info.plist file

<key>NSMicrophoneUsageDescription</key> <string>{YourAppName} wants to use your microphone</string> <key>NSCameraUsageDescription</key> <string>{YourAppName} wants to use your camera</string> <key>NSLocalNetworkUsageDescription</key> <string>{YourAppName} App wants to use your local network</string>

Join a Video Call

To join a video call, call join method on HMSSDK with the config settings. To listen the updates, call addUpdateListener on HMSSDK.

These are some listener's callback functions:

onJoin - called when the join was successful and you have entered the room.

💡 Audio will be automatically connected, video requires some work on your side.

onPeerUpdate - called when a person joins or leaves the call and when their audio/video mutes/unmutes.

onTrackUpdate - usually when a person joins the call, the listener will first call onPeerUpdate to notify about the join. Subsequently onTrackUpdate will be called with their actual video track.

💡 It's essential that this callback is listened to or you may have peers without video.

HMSConfig config = HMSConfig(userName: this.userName, authToken: this.authToken); hmsSDK = HMSSDK(); hmsSDK.build() hmsSDK.join(config: this.config); hmsSDK.addUpdateListener(listener);
/// 100ms SDK provides callbacks to the client app about any change or update happening in the room after a user has joined by implementing HMSUpdateListener. /// These updates can be used to render the video on screen or to display other info regarding the room. abstract class HMSUpdateListener { /// This will be called on a successful JOIN of the room by the user /// /// This is the point where applications can stop showing its loading state /// [room]: the room which was joined void onJoin({required HMSRoom room}); /// This is called when there is a change in any property of the Room /// /// [room]: the room which was joined /// [update]: the triggered update type. Should be used to perform different UI Actions void onRoomUpdate({required HMSRoom room, required HMSRoomUpdate update}); /// This will be called whenever there is an update on an existing peer /// or a new peer got added/existing peer is removed. /// /// This callback can be used to keep a track of all the peers in the room /// [peer]: the peer who joined/left or was updated /// [update]: the triggered update type. Should be used to perform different UI Actions void onPeerUpdate({required HMSPeer peer, required HMSPeerUpdate update}); /// This is called when there are updates on an existing track /// or a new track got added/existing track is removed /// /// This callback can be used to render the video on screen whenever a track gets added /// [track]: the track which was added, removed or updated /// [trackUpdate]: the triggered update type /// [peer]: the peer for which track was added, removed or updated void onTrackUpdate({required HMSTrack track, required HMSTrackUpdate trackUpdate, required HMSPeer peer}); /// This will be called when there is an error in the system /// and SDK has already retried to fix the error /// [error]: the error that occurred void onHMSError({required HMSException error}); /// This is called when there is a new broadcast message from any other peer in the room /// /// This can be used to implement chat is the room /// [message]: the received broadcast message void onMessage({required HMSMessage message}); /// This is called when someone asks for change or role /// /// for eg. admin can ask a peer to become host from guest. /// this triggers this call on peer's app void onRoleChangeRequest({required HMSRoleChangeRequest roleChangeRequest}); /// This is called every 1 second with list of active speakers /// /// ## A HMSSpeaker object contains - /// - peerId: the peer identifier of HMSPeer who is speaking /// - trackId: the track identifier of HMSTrack which is emitting audio /// - audioLevel: a number within range 1-100 indicating the audio volume /// /// A peer who is not present in the list indicates that the peer is not speaking /// /// This can be used to highlight currently speaking peers in the room /// [speakers] the list of speakers void onUpdateSpeakers({required List<HMSSpeaker> updateSpeakers}); ///when network or some other error happens it will be called void onReconnecting(); ///when you are back in the room after reconnection void onReconnected(); ///when someone requests for track change of yours be it video or audio this will be triggered /// [hmsTrackChangeRequest] request instance consisting of all the required info about track change void onChangeTrackStateRequest({required HMSTrackChangeRequest hmsTrackChangeRequest}); ///when someone kicks you out or when someone ends the room at that time it is triggered /// [hmsPeerRemovedFromPeer] it consists info about who removed you and why. void onRemovedFromRoom({required HMSPeerRemovedFromPeer hmsPeerRemovedFromPeer}); ///whenever a new audio device is plugged in or audio output is changed we ///get the onAudioDeviceChanged update ///This callback is only fired on Android devices. On iOS, this callback will not be triggered. /// - Parameters: /// - currentAudioDevice: Current audio output route /// - availableAudioDevice: List of available audio output devices void onAudioDeviceChanged( {HMSAudioDevice? currentAudioDevice, List<HMSAudioDevice>? availableAudioDevice}); }

How you know when people join or leave

The join method takes an interface called HMSUpdateListener. It lets you know when peers join and leave the call, mute/unmute their audio and video and lots more.

The HMSUpdateListener has a callback to notify about people joining or leaving. It is onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer).

💡 HMSPeer is object that represents a person in the call.


How to render audio and video

The SDK plays the audio for every person who joins the call. Audio will begin playing when join succeeds. To render the person's video you need to create an instance of HMSVideoView.

Showing Videos

A peer represents one person in the video call.

A peer's video track is in hmsPeer.videoTrack. ScreenShares can be found in auxilary tracks of peer i.e the auxiliary tracks is a list of tracks, one of which can be a ScreenShare if they have chosen to share their screen.

peer.auxiliaryTracks ?.where((each) => each.kind == HMSTrackKind.kHMSTrackKindVideo);

Mute/UnMute Audio

You can mute/unmute audio by calling switchAudio on HMSSDK. isOn is state variable. If isOn is true then audio will unmute and if its false then audio will mute.

/// audio unmute hmsSDK.switchAudio(isOn: true); /// audio mute hmsSDK.switchAudio(isOn: false);

Mute/UnMute Video

You can mute/unmute video by calling switchVideo on HMSSDK. isOn is state variable. If isOn is true then video will turn on and if its false then video will turn off.

/// video on hmsSDK.switchVideo(isOn: true); /// video off hmsSDK.switchVideo(isOn: false);

Leave a video call

To leave a video call, just call leave on HMSSDK.

hmsSDK.leave();

Glossary

  • Room: When you join a particular video call, all the peers said to be in a video call room
  • Track: Media. Can be the audio track or the video track.
  • Peer: One participant in the video call. Local peers are you, remote peers are others.
  • Broadcast: Chat messages are broadcasts.

Where to go from here

Checkout the simple version of the project.This uses provider as the state management library.

For implementations with other state management libraries visit :

100ms Flutter app

You can download & check out the 100ms Flutter app -

🤖 The Flutter Android app from Google Play Store here

📱 Flutter iOS app from Apple App Store here

Github Repo

You can checkout the 100ms Flutter SDK Github repo which also contains a fully fledged Example app implementation here