Join Room

Overview

To join and interact with others in audio or video call, the user needs to join a room.

When a user indicates that they want to join the room, your app should have -

User Name - The name which should be displayed to other peers in the room.
Auth Token - The Client side Authentication Token generated by the Token Service.

You can also optionally pass these fields -

Track Settings - Such as joining a Room with Muted Audio or Video using the HMSTrackSetting object. More information available here
User Metadata - This can be used to pass any additional metadata associated with the user using metadata of HMSConfig object. For Eg: user-id mapping at the application side. More information is available here.

Join a Room

This section will take you through a sample code to join a room and receive room updates:


class Meeting implements HMSUpdateListener{

    late HMSSDK hmsSDK;

    Meeting() {
        initHMSSDK();
    }

    void initHMSSDK() async {
        hmsSDK = HMSSDK();
        await hmsSDK.build(); // ensure to await while invoking the `build` method
        hmsSDK.addUpdateListener(listener: this);
        HMSConfig config = HMSConfig(authToken: 'eyJH5c', // client-side token generated from your token service
                                userName: 'John Appleseed');
        hmsSDK.join(config: config);
    }


    @override
    void onJoin({required HMSRoom room}) async {
       /// The User has joined the Room successfully. Among other operations, you can now start rendering Videos now: https://www.100ms.live/docs/flutter/v2/how-to-guides/set-up-video-conferencing/render-video/overview
    }

    @override
    void onRoomUpdate(
        {required HMSRoom room,
        required HMSRoomUpdate update}) {
            /// Room updates: https://www.100ms.live/docs/flutter/v2/features/update-listener-enums#hms-room-update
    }

    @override
    void onPeerUpdate(
        {required HMSPeer peer,
        required HMSPeerUpdate update}) async {
            /// Peer updates: https://www.100ms.live/docs/flutter/v2/features/update-listener-enums#hms-peer-update
    }

    @override
    void onTrackUpdate(
        {required HMSTrack track,
        required HMSTrackUpdate trackUpdate,
        required HMSPeer peer}) {
            /// Track updates: https://www.100ms.live/docs/flutter/v2/features/update-listener-enums#hms-track-update
    }

    @override
    void onHMSError(
        {required HMSException error}) {
            /// Error updates: https://www.100ms.live/docs/flutter/v2/features/error-handling#hms-exception
    }


    @override
    void onMessage(
        {required HMSMessage message}) {
            /// Message updates: https://www.100ms.live/docs/flutter/v2/features/chat#receiving-chat-messages
    }

    @override
    void onRoleChangeRequest(
        {required HMSRoleChangeRequest roleChangeRequest}) {
            /// Role Change Request: https://www.100ms.live/docs/flutter/v2/features/change-role#accept-role-change-request
    }

    @override
    void onUpdateSpeakers(
        {required List<HMSSpeaker> updateSpeakers}) {
            /// This is triggered every second with a list of speakers who are currently speaking.
    }

    @override
    void onReconnecting() {
        /// Reconnection callback: https://www.100ms.live/docs/flutter/v2/features/reconnection-handling#reconnecting-and-reconnected-callbacks
    }

    @override
    void onReconnected() {
        /// Reconnection callback: https://www.100ms.live/docs/flutter/v2/features/reconnection-handling#reconnecting-and-reconnected-callbacks
    }

    @override
    void onChangeTrackStateRequest(
        {required HMSTrackChangeRequest hmsTrackChangeRequest}) {
            /// Getting mute-unmute callback: https://www.100ms.live/docs/flutter/v2/features/remote-mute-unmute#handling-an-unmute-callback
    }

    @override
    void onRemovedFromRoom(
        {required HMSPeerRemovedFromPeer hmsPeerRemovedFromPeer}) {
            /// Handle peer removal case: https://www.100ms.live/docs/flutter/v2/features/remove-peer#handling-the-remove-peer-callback
    }

    @override
    void onAudioDeviceChanged(
        {HMSAudioDevice? currentAudioDevice,
        List<HMSAudioDevice>? availableAudioDevice}) {
            /// Get notified when the audio device is changed: https://www.100ms.live/docs/flutter/v2/features/audio-output-routing#adding-audio-device-change-event-listener-android-only
    }

    @override
    void onSessionStoreAvailable(
        {HMSSessionStore? hmsSessionStore}) {
            /// Get notified when the Session Store is available for usage. Read more about Session Store here: https://www.100ms.live/docs/flutter/v2/how-to-guides/interact-with-room/room/session-store
    }

    @override
    void onPeerListUpdate(
        {required List<HMSPeer> addedPeers, required List<HMSPeer> removedPeers}) {
        /// Get notified when the Peer List is updated in Large Rooms. Read more about Peer List here: https://www.100ms.live/docs/flutter/v2/how-to-guides/interact-with-room/peer/large-room
    }
}

Step-by-step guide

This section will take you through the join journey step by step :

Create a class implementing HMSUpdateListener

Let's create a class that implements HMSUpdateListener and acts as a data source for our UI


class Meeting implements HMSUpdateListener{}

Create HMSSDK instance

Now, create an instance of HMSSDK using the build method. The build should always be called with await to ensure correct initialization & setup of the 100ms SDK.


HMSSDK hmsSDK = HMSSDK();
await hmsSDK.build(); // ensure to await while invoking the `build` method

Attach HMSUpdateListener

The methods of HMSUpdateListener are invoked to notify updates happening in the room like as soon as join is successful we get onJoin callback. So, to get these updates we need to attach the listener as:


//`this` value corresponds to the instance implementing HMSUpdateListener
hmsSDK.addUpdateListener(listener: this);

Create HMSConfig object

Next, create an object of HMSConfig class using the available join configurations.


HMSConfig config = HMSConfig(authToken: 'eyJH5c', // client-side token generated from your token service
                            userName: 'John Appleseed');

Invoke Join

Now, we are primed to join the room. All you have to do is call join by passing the config object.


hmsSDK.join(config: config);

The methods of HMSUpdateListener are invoked to notify updates happening in the room like a peer joins/leaves, a track mute/unmute, etc.

After calling join your app will be provided an update from the 100ms SDK.

✅ If successful, the onJoin({required HMSRoom room}) method of HMSUpdateListener will be invoked with information about the room encapsulated in the HMSRoom object.

❌ If failure, the onHMSError({required HMSException error}) method will be invoked with exact failure reason.

Once you get onJoin callback you have joined a room successfully 🥳

Join with Muted Audio / Video

Joining with Muted Audio / Video is a customization that sets the microphone and camera state before joining the room.

By default HMSSDK keeps the microphone and camera ON but by using this feature you can decide their state according to your use case.

This can be achieved using the hmsVideoTrackInitState property for Video and hmsAudioTrackInitState for Audio in the hmsTrackSetting parameter of the HMSSDK constructor.

Here trackInitialState property of HMSVideoTrackSetting and HMSAudioTrackSetting is an Enum of type HMSTrackInitState which has the possible values as:


enum HMSTrackInitState {

    /// If the track needs to be kept mute while joining
    MUTED,

    /// If the track needs to be kept unmute while joining
    UNMUTED,
}

Let's see how this can be achieved in the following steps.

First, for joining a room with muted audio/video, these values need to be set in the hmsTrackSetting property as -


HMSTrackSetting trackSettings = HMSTrackSetting(
        /// This is for joining with muted audio(mic off) and muted video(camera off)
        audioTrackSetting: HMSAudioTrackSetting(trackInitialState: HMSTrackInitState.MUTED),
        videoTrackSetting: HMSVideoTrackSetting(trackInitialState: HMSTrackInitState.MUTED));

Now, create the HMSSDK object by passing the HMSTrackSetting object created above :


class Meeting implements HMSUpdateListener{

    late HMSSDK hmsSDK;
    Meeting(){
        // pass the trackSettings while constructing the HMSSDK instance
         ̶h̶m̶s̶S̶D̶K̶ ̶=̶ ̶H̶M̶S̶S̶D̶K̶(̶)̶;̶
        HMSSDK hmsSDK = HMSSDK(hmsTrackSetting: trackSettings);
        setupHMSSDK();
    }

    void setupHMSSDK() async{
        await hmsSDK.build(); // ensure to await while invoking the `build` method
        hmsSDK.addUpdateListener(listener: this);
        HMSConfig config = HMSConfig(authToken: 'eyJH5c', // client-side token generated from your token service
                                    userName: 'John Appleseed');
        hmsSDK.join(config: config);
    }
}

Rest all the steps are same as above.

Now, the user joins the room with the microphone and the camera turned off.

Integrating The SDK Leave Room

Have a suggestion? Recommend changes ->