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.

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

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:

settings.gradle
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 }

Permissions

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

AndroidManifest.xml
<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()

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.

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

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) {} }

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

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.

Have a suggestion? Recommend changes ->

Was this helpful?

1234