100ms SDK Android Quickstart Guide

Overview

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

Here are some sample apps demonstrating this.

Simplest implementation.

Most full-featured implementation.

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

• Get Auth Token
• Add the sdk dependencies.
• Create a login token to authenticate the user.
• Add permissions
• Create an instance of the HMSSDK.

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

• Call hmssdk.join with the video call link to join the call.
• Know when people join or leave
• How to render audio/video
• Listening to updates effectively

  ---

Prerequisites

Familiarity with Android Studio and the fundamentals of android apps.

Supported Android API Levels

100ms' Android SDK supports Android API level 21 and higher. It is built for armeabi-v7a, arm64-v8a, x86, and x86_64 architectures.

Get Auth Token

Before we proceed we need to obtain the room-code for your room. In case you are not sure how to do this here is a quick guide about room-codes: Room Code Setup Guide

To join a video call you need an authentication token. You can generate token on the sdk using hmsInstance.getAuthTokenByRoomCode() method. The token generation requires room-code and an optional user-id parameter.

Minimum Requirements

• SDK version 2.5.9 or higher

func generateToken() {
   val hmsInstance = HMSSDK
    .Builder(application)
    .build()
 
   hmsInstance.getAuthTokenByRoomCode(TokenRequest(#room-code, #user-id), null , object :
      HMSTokenListener {
      override fun onError(error: HMSException) {}

      override fun onTokenSuccess(string: String) {
        //here's the token !
      }

    })
}

Add SDK dependencies

The latest SDK version is:

dependencies {
 // See the version in the badge above.
 // There are separate libraries for the sdk, virtual background and hls-player-stats.
 //     add just the ones you need.
 def hmsVersion = "x.x.x"
 implementation "live.100ms:android-sdk:$hmsVersion"    // Essential
 implementation "live.100ms:video-view:$hmsVersion" // Essential
 implementation "live.100ms:virtual-background:$hmsVersion" // Optional
 implementation "live.100ms:hls-player-stats:$hmsVersion"   // Optional
 implementation "live.100ms:hls-player:$hmsVersion"   // Optional
}

dependencyResolutionManagement {
 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
 repositories {
 google()
 mavenCentral()
 jcenter() // Warning: this repository is going to shut down soon
 maven { url 'https://jitpack.io' }
    }
}
rootProject.name = "MyVideoCallApp"
include ':app'

dependencies {
 def hmsVersion = "x.x.x"
 // See the version in the jitpack badge above.
 implementation "com.github.100mslive.android-sdk:lib:$hmsVersion"          // Essential
 implementation "com.github.100mslive.android-sdk:virtualBackground:$hmsVersion" // Optional
 implementation "com.github.100mslive.android-sdk:stats:$hmsVersion"            // Optional

}

Permissions

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

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

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.

Instantiate HMSSDK

Instantiate the HMSSDK like this:

    val hmsSdk = HMSSDK
        .Builder(application)
        .build()

 HMSSDK hmssdk = new HMSSDK
                        .Builder(application)
                        .build();

Join a Video Call

To join a video call, call the join method of hmssdk with the config and appropriate listeners.

The main ones to know are:

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

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.

val config = HMSConfig("user display name", authToken)

hmsSdk.join(config, MyHmsUpdateListener())

class MyHmsUpdateListener : HMSUpdateListener {
    override fun onJoin(room: HMSRoom) {}
    override fun onTrackUpdate(type: HMSTrackUpdate, track: HMSTrack, peer: HMSPeer) {}
    override fun onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer) {}
    override fun onMessageReceived(message: HMSMessage) {}
    override fun onRoleChangeRequest(request: HMSRoleChangeRequest) {}
    override fun onRoomUpdate(type: HMSRoomUpdate, hmsRoom: HMSRoom) {}
    override fun onError(error: HMSException) {}
}

HMSConfig config = new HMSConfig("user display name", authToken);

hmsSdk.join(config, new MyHmsUpdateListener());

class MyHmsUpdateListener implements HMSUpdateListener {
    @Override public void onJoin(@NonNull HMSRoom hmsRoom) {}
    @Override public void onMessageReceived(@NonNull HMSMessage hmsMessage) {}
    @Override public void onPeerUpdate(@NonNull HMSPeerUpdate hmsPeerUpdate, @NonNull HMSPeer hmsPeer) {}
    @Override public void onReconnected() {}
    @Override public void onReconnecting(@NonNull HMSException e) {}
    @Override public void onRoleChangeRequest(@NonNull HMSRoleChangeRequest hmsRoleChangeRequest) {}
    @Override public void onRoomUpdate(@NonNull HMSRoomUpdate hmsRoomUpdate, @NonNull HMSRoom hmsRoom) {}
    @Override public void onTrackUpdate(@NonNull HMSTrackUpdate hmsTrackUpdate, @NonNull HMSTrack hmsTrack, @NonNull HMSPeer hmsPeer) {}
    @Override public void onError(@NonNull HMSException e) {}
}

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).

How to render audio and video

See how to set up video

Listening to Updates Effectively

Each time there's a an onJoin, onPeerUpdate, or onTrackUpdate, you can add all the peers from hmsSdk.getPeers() into the adapter. Since peers can have both their own videos and screen shares it's possible for a peer to have more than one video track.

Note that peers with no video tracks will never have onTrackUpdate called with a video (so they should be watched for in onPeerUpdate) and peers with video tracks should be watched for in onTrackUpdate since tracks will come a few milliseconds after the first time a peer appears in onPeerUpdate.

Where to go from here

Checkout the simple sample app.

Also a full featured advanced sample app.

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.