Client

The documentation for Huddle01 Android SDK to connect your Android App to Huddle01 servers.

Getting Started

1. Add Jitpack

Add Jitpack in the repositories block inside allprojects block in your project-level build.gradle file.

allprojects {
		repositories {
			...
			maven { url 'https://jitpack.io' }
		}
	}

2. Add Huddle01 Android SDK Dependency

Add the dependency in your app-level build.gradle file inside the dependency block. Also, replace the version number with the latest one.

dependencies {
    ...
    implementation 'com.github.Huddle-01:huddle01-android-sdk:v1.0.1'
}

3. Initialize HuddleClient

To initialize the HuddleClient, call the initApp function inside the onCreate of your Application class.

public class Application extends android.app.Application {
    @Override
    public void onCreate() {
        super.onCreate();
        HuddleClient.initApp(this);
    }
}

You will need to create your own class extending the Android Application class and make necessary changes in your AndroidManifest.xml file.

Creating and Joining Room

To create a new Room, you will need to create a new object of HuddleClient type.

HuddleClient huddleClient = new HuddleClient.Builder(getApplicationContext(), apiKey)
                .setPeerId(mPeerId)
                .setRoomId(mRoomId)
                .setDisplayName(mDisplayName)
                .setCanConsume(true)
                .setCanProduce(true)
                .setCanUseDataChannel(true)
                .setRoomEventListener(roomEventListener)
                .setMeListener(meListener)
                .setFrontCamEnabledOnInit(true)
                .build();

Here, some mandatory things to do are are:

• Passing context in Builder()

• Passing an API key inside the Builder()

• Setting event listener of type RoomEventListener in setRoomEventListener()

• Setting event listener of type MeListener in setMeListener()

The defaults for rest of the fields are:

• peerId - A random string of size 8

• roomId - A random string of size 8

• displayName - A random string of size 6

• canConsume - true

• canProduce - true

• canUseDataChannel - true

• frontCamEnabledOnInit - true (false means that the session will start with a rear camera)

build() function will terminate the object creation process and create a room with the provided parameters.

You may use this sample API Key: i4pzqbpxza8vpijQMwZsP1H7nZZEH0TN3vR4NdNS

To join room, once the room is created, call the joinRoom() function. Do check for RECORD_AUDIO, INTERNET, CAMERA permissions before joining the room.

if(permissionGranted){
    huddleClient.joinRoom();
}

Event Listeners

When you create a room, you need to supply two Event Listeners:

• RoomEventListener

• MeListener

RoomEventListener

onRoomUrlGenerated

Trigger: on Room URL generation complete in the SDK.

Returns: A string roomUrl corresponding to the roomId

public void onRoomUrlGenerated(String roomId, String roomUrl) {
    //set the room URL in your viewmodel/store
}

onRoomStateChanged

Trigger: when Room state changes due to some event in the SDK.

Returns: state of type ConnectionState.

public void onRoomStateChanged(ConnectionState state) {
    //perform action
}

ConnectionState can contain 4 possible values:

• ConnectionState.NEW: when a new room is created.

• ConnectionState.CONNECTING: when a join request is sent to the huddle servers and you're not connected to the room.

• ConnectionState.CONNECTED: when huddle servers grant you the connection to the room. Now, you're inside the room.

• ConnectionState.CLOSED: when you terminate the session by calling close() or the maximum number of retries to join the room have been reached.

onError

Trigger: when SDK encounters an error.

Returns: an error message in the String format.

public void onError(String message) {
    //perform action
}

onPeerChanged

Trigger: any change in Peers like new peer joined, peer left, and peer changed display name.

Returns: a String named actionType denoting which action has occurred, a String named peerId denoting the peerId on which the action has occurred, a Nullable JSONObject named info, which is NonNull when new peer is added.

public void onPeerChanged(String actionType, String peerId, @Nullable JSONObject info, @Nullable String displayName) {
    //ideally switch between actionType and perform actions
}

There are 3 possible actionTypes:

• Constants.ACTION_ADDED: when a new peer arrives

• Constants.ACTION_DISPLAY_NAME_CHANGED: when a peer changes its display name.

• Constants.ACTION_REMOVED: when a peer terminates its session or is removed somehow.

onProducersChanged

Trigger: when a new producer is added, a producer is paused/resumed, or a producer is removed.

Returns: a String named actionType denoting the action that has taken place, a producer of type HuddleProducer on which the action has taken place.

public void onProducersChanged(String actionType, HuddleProducer producer) {
    //ideally switch between actionTypes and perform actions
}

There are 4 possible actionTypes:

• Constants.ACTION_ADDED: when a new producer is added

• Constants.ACTION_PAUSED: when a producer (mic/camera) pauses its stream.

• Constants.ACTION_RESUMED: when a producer (mic/camera) pauses its stream.

• Constants.ACTION_REMOVED: when a producer is removed like a camera is disabled or peer leaves the session.

onConsumerAdded

Trigger: when a new consumer is added.

Returns: String peerId denoting the peerId on which the consumer is added, String consumerType denoting mic/camera type consumers, a consumer of type HuddleConsumer, a boolean remotelyPaused denoting if the consumer is already paused from the peer side when joining.

public void onConsumerAdded(String peerId, String consumerType, HuddleConsumer consumer, boolean remotelyPaused) {
    //perform action
}

onConsumerRemoved

Trigger: when a consumer is removed due to some reason.

Returns: peerId denoting which peer the consumer is associated with, consumerId denoting the consumer which is removed.

public void onConsumerRemoved(String peerId, String consumerId) {
    //perform action
}

onConsumerStateChanged

Trigger: when a consumer is paused/resumed.

Returns: A string actionType denoting type of action taken place, string consumerId, and string originator ("local"/"remote").

public void onConsumerStateChanged(String actionType, String consumerId, String originator) {
    //ideally switch between actionTypes and perform actions.
}

There are 2 supported actionTypes:

• Constants.ACTION_PAUSED

• Constants.ACTION_RESUMED

onDataProducerChanged

Trigger: when a DataProducer is added/removed.

Returns: String actionType denoting type of action, a dataProducer of type HuddleDataProducer.

public void onDataProducerChanged(String actionType, HuddleDataProducer dataProducer) {
    //do something
}

There are 2 supported actionTypes:

• Constants.ACTION_ADDED

• Constants.ACTION_REMOVED

onDataConsumerChanged

Trigger: when a DataConsumer is added/removed.

Returns: String actionType denoting type of action, string peerId denoting which peer the data consumer is associated with, and a dataConsumer of type HuddleDataConsumer.

public void onDataConsumerChanged(String actionType, String peerId, HuddleDataConsumer dataConsumer) {
    // do something
}

There are 2 supported actionTypes:

• Constants.ACTION_ADDED

• Constants.ACTION_REMOVED

onReactionRecieved

Trigger: when a reaction arrives from some peer.

Returns: a peer of type Peer and a string reaction denoting reaction in the string unicode format.

public void onReactionReceived(Peer peer, String reaction) {
    //do something
}

onChatReceived

Trigger: when a chat message is recieved from some peer.

Returns: a peer of type Peer and a string message denoting the text message.

public void onChatReceived(Peer peer, String message) {
    //do something
}

onNotification

Trigger: when SDK broadcasts a notification message related to some event.

Returns: notification of type Notify.

public void onNotification(Notify notify) {
    //do something
}

MeListener

onMeReceived

Trigger: when SDK registers your information while creating the room.

Returns: String peerId denoting your peerId, string displayName denoting your display name, deviceInfo of type DeviceInfo denoting your device information.

public void onMeReceived(String peerId, String displayName, DeviceInfo deviceInfo) {
    //do something
}

onMediaCapabilitiesReceived

Triggers: reports the capabilities of your device, if can send/receive audio and video.

Returns: boolean canSendMic denoting audio capability, boolean canSendCam denoting video capability.

public void onMediaCapabilitiesReceived(boolean canSendMic, boolean canSendCam) {
    //do something
}

onNewDisplayName

Trigger: when SDK registers a new display name for you.

Returns: String displayName denoting changed display name.

public void onNewDisplayName(String displayName) {
    //do something
}

Available Methods

The following methods solve complex video conferencing tasks in a single line:

Function	Purpose	Remarks
joinRoom()	joins the room when the room is created	Use only when permissions are granted and room is created.
closeRoom()	leaves the room, if there are no remaining participants then disposes the room	To be called after the joinRoom() function.
sendChatMessage(String message)	sends chat message to all other peers via data channels	make sure useDataChannel is set to true while creating the room.
sendReaction(String reaction)	sends a reaction via data channels. The reaction should be a unicode of the emoji in the String format.	make sure useDataChannel is set to true while creating the room.
changeCam()	toggles between front and back cameras if available.	--
enableCam()	enables camera and related producers.	Preferably used when the camera is already disabled.
disableCam()	disables camera and related producers.	Preferably used when the camera is already enabled.
muteMic()	mutes the audio and pauses the related producers.	Preferably used when the mic is already unmuted.
unmuteMic()	unmutes the audio and resumes the related producers.	Preferably used when the mic is already muted.
changeDisplayName()	changes the device's display name.	--

Introduced Data Types

The Huddle01 Android SDK offers you flexibility to perform state management according to the design pattern that is being used in your app (MVVM, MVI, etc.). However, we also expose certain data types that may definitely come handy while performing state management as these data types are capable of internal state management.

State Data Types

Peers

Maintains info related to all the peers.

Function	Parameters	Return Type
addPeer	String peerId JSONObject peerInfo	void
removePeer	String peerId	void
setPeerDisplayName	String peerId String displayName	void
addConsumer	String peerId HuddleConsumer consumer	void
removeConsumer	String peerId String consumerId	void
addDataConsumer	String peerId HuddleDataConsumer consumer	void
removeDataConsumer	String peerId String consumerId	void
getPeer	String peerId	Peer
getAllPeers	--	List<Peer>
clear	--	void

Consumers

Maintains info related to all the consumers in the session.

Function	Parameters	Return Type
addConsumer	String type HuddleConsumer consumer boolean remotelyPaused	void
removeConsumer	String consumerId	void
setConsumerPaused	String consumerId String originator	void
setConsumerResumed	String consumerId String originator	void
clear	--	void

Producers

Maintains info related to all the producers in the session.

Function	Parameters	Return Type
addProducer	HuddleProducer producer	void
removeProducer	String producerId	void
setProducerPaused	String producerId	void
setProducerResumed	String producerId	void
filter	String kind("audio"/"video")	ProducersWrapper
clear	--	void

DataProducers

Maintains info related to all data producers in the session.

Function	Parameters	Return Type
addDataProducer	HuddleDataProducer producer	void
removeDataProducer	String producerId	void
clear	--	void

DataConsumers

Maintains info related to all data consumers in the session.

Function	Parameters	Return Type
addDataConsumer	HuddleDataConsumer consumer	void
removeDataConsumer	String consumerId	void
clear	--	void

Other Data Types

Huddle01 Android SDK also exposes some other data types which are used internally as well as exposed to the app.

Peer

Field	Getter	Setter	DataType
id	✔️	✖️	String
displayName	✔️	✔️	String
deviceInfo	✔️	✔️	DeviceInfo
consumers	✔️	✖️	Set<String>
dataConsumers	✔️	✖️	Set<String>

DeviceInfo

Field	Getter	Setter	DataType
flag	✔️	✔️	String
name	✔️	✔️	String
version	✔️	✔️	String

HuddleConsumer

Function	Return Type
getId()	String
getRtpParameters()	String
getKind()	String
resume()	void
close()	void
dispose()	void
pause()	void
getTrack()	org.webrtc.MediaStreamTrack
getPaused()	boolean
getClosed()	boolean

HuddleProducer

Function	Return Type
getId()	String
getRtpParameters	String
getKind()	String
resume()	void
close()	void
dispose()	void
pause()	void
getTrack()	org.webrtc.MediaStreamTrack
getPaused()	boolean
getClosed()	boolean

HuddleDataConsumer

Function	Return Type
getId()	String
getLabel()	String
getSctpStreamParameters()	String
getProtocol()	String
getDataProducerId()	String
getClosed()	boolean
close()	void
dispose()	void

HuddleDataProducer

Function	Return Type
getId()	String
getLabel()	String
getSctpStreamParameters()	String
getProtocol()	String
getClosed()	boolean

Notify

Function	Return Type
getId()	String
getType()	String
getText()	String
getTimeout	int

For any help, reach out to us on Slack. We are available 24*7 at: Huddle01 Community.