100ms Logo

100ms

Docs

Search docs
/

HMSActions

The below interface defines our SDK API Surface for taking room related actions. It talks to our 100ms backend and handles error reconnections, state managements and lots of other things so you don't have to. You can use this gateway with any sort of UI to make connecting to our backend easier. In case you use react, we also provide a HMSProvider class with very powerful hooks and out of box components which you can use to setup your website in minutes. Our components have in built integration with this interface and you won't have to worry about passing props if you use them.

Remarks

There is a one to one mapping between an instance of this class and a 100ms room, in case you're creating multiple rooms please create new instance per room.

Properties

audioPlaylist

audioPlaylist: IHMSPlaylistActions

audio Playlist contains all actions that can be performed on the audio playlist This will be available after joining the room


endRoom

endRoom: (lock: boolean, reason: string) => Promise<void>

Type declaration

▸ (lock, reason): Promise<void>

If you have the endRoom permission, you can end the room. That means everyone will be kicked out. If lock is passed as true, the room cannot be used further.

Parameters
NameType
lockboolean
reasonstring
Returns

Promise<void>


unblockAudio

unblockAudio: () => Promise<void>

Type declaration

▸ (): Promise<void>

Method to be called with some UI interaction after autoplay error is received Most browsers have limitations where an audio can not be played if there was no user interaction. SDK throws an autoplay error in this case, this method can be called after an UI interaction to resolve the autoplay error

Returns

Promise<void>


videoPlaylist

videoPlaylist: IHMSPlaylistActions

video Playlist contains all actions that can be performed on the video playlist This will be available after joining the room

Methods

acceptChangeRole

acceptChangeRole(request): Promise<void>

Accept the role change request received

Parameters

NameTypeDescription
requestHMSRoleChangeRequestThe original request that was received

Returns

Promise<void>


addPluginToAudioTrack

addPluginToAudioTrack(plugin): Promise<void>

Add or remove a audio plugin from/to the local peer audio track. Eg. gain filter, noise suppression etc. Audio plugins can be added/removed at any time after the audio track is available

See

HMSAudioPlugin

Parameters

NameTypeDescription
pluginHMSAudioPluginHMSAudioPlugin

Returns

Promise<void>


addPluginToVideoTrack

addPluginToVideoTrack(plugin, pluginFrameRate?): Promise<void>

Add or remove a video plugin from/to the local peer video track. Eg. Virtual Background, Face Filters etc. Video plugins can be added/removed at any time after the video track is available. pluginFrameRate is the rate at which the output plugin will do processing

See

HMSVideoPlugin

Parameters

NameTypeDescription
pluginHMSVideoPluginHMSVideoPlugin
pluginFrameRate?numbernumber

Returns

Promise<void>


addTrack

addTrack(track, type): Promise<void>

You can use the addTrack method to add an auxiliary track(canvas capture, electron screen-share, etc...) This method adds the track to the local peer's list of auxiliary tracks and publishes it to make it available to remote peers.

Parameters

NameTypeDescription
trackMediaStreamTrackMediaStreamTrack - Track to be added
typestringHMSTrackSource - 'regular' | 'screen' | 'plugin' - Source of track - default: 'regular'

Returns

Promise<void>


attachVideo

attachVideo(localTrackID, videoElement): Promise<void>

You can use the attach and detach video function to add/remove video from an element for a track ID. The benefit of using this instead of removing the video yourself is that it'll also auto unsubscribe to the stream coming from server saving significant bandwidth for the user.

Parameters

NameTypeDescription
localTrackIDstringtrackID as stored in the store for the peer
videoElementHTMLVideoElementHTML native element where the video has to be shown

Returns

Promise<void>


changeMetadata

changeMetadata(metadata): Promise<void>

If you want to update the metadata of local peer. If an object is passed, it should be serializable using JSON.stringify.

Parameters

NameType
metadataany

Returns

Promise<void>


changeName

changeName(name): Promise<void>

If you want to update the name of peer.

Parameters

NameType
namestring

Returns

Promise<void>


changeRole

changeRole(forPeerId, toRole, force?): Promise<void>

Request for a role change of a remote peer. Can be forced.

Parameters

NameTypeDescription
forPeerIdstringThe remote peer id whose role needs to be changed
toRolestringThe name of the new role.
force?booleanthis being true would mean that user won't get a request to accept role change

Returns

Promise<void>


detachVideo

detachVideo(localTrackID, videoElement): Promise<void>

See

attachVideo

Parameters

NameType
localTrackIDstring
videoElementHTMLVideoElement

Returns

Promise<void>


ignoreMessageTypes

ignoreMessageTypes(msgTypes, replace?): void

ignore messages with this type for storing in store. You can use this to have a clear segregation between chat messages(you would want to persist for the duration of the call) and one off custom events(emoji reactions, stop screenshare, moderator messages, etc.). You can also use this to store messages on your own side if some additional processing is required(the default type is "chat"). Notifications for the ignored messages will still be sent, it'll only not be put in the store.

Parameters

NameTypeDescription
msgTypesstring[]list of messages types to ignore for storing
replace?boolean(default is false) whether to replace the list of ignored messages. Types are appended to the existing list by default so you can call this method from different places and all will hold.

Returns

void


initAppData

initAppData(data): void

Parameters

NameTypeDescription
dataRecord<string, any>full app data object. use this to initialise app data in store. App Data is a small space in the store for UI to keep a few non updating global state fields for easy reference across UI. Note that if the fields are updating at high frequency or there are too many of them, it's recommended to have another UI side store to avoid performance issues.

Returns

void


join

join(config): Promise<void>

join function can be used to join the room, if the room join is successful, current details of participants and track details are populated in the store.

Remarks

If join is called while an earlier join is in progress for the room id, it is ignored

Parameters

NameTypeDescription
configHMSConfigjoin config with room id, required for joining the room

Returns

Promise<void>


leave

leave(): Promise<void>

This function can be used to leave the room, if the call is repeated it's ignored.

Returns

Promise<void>


populateSessionMetadata

populateSessionMetadata(): Promise<void>

Fetch the current room metadata from the server and populate it in store

  • the API is not stable and might have breaking changes later

Returns

Promise<void>


preview

preview(config): Promise<void>

Parameters

NameType
configHMSConfig

Returns

Promise<void>


refreshDevices

refreshDevices(): Promise<void>

Returns

Promise<void>


rejectChangeRole

rejectChangeRole(request): void

Reject pending role change request

Parameters

NameTypeDescription
requestHMSRoleChangeRequestThe original request that was received

Returns

void


removePeer

removePeer(peerID, reason): Promise<void>

If you have removeOthers permission, you can remove a peer from the room.

Parameters

NameTypeDescription
peerIDstringpeerID of the peer to be removed from the room
reasonstringa string explaining why the peer is removed from the room. This string could be used to notify the user before they're removed from the room using the REMOVED_FROM_ROOM type of notification

Returns

Promise<void>


removePluginFromAudioTrack

removePluginFromAudioTrack(plugin): Promise<void>

See

addPluginToAudioTrack

Parameters

NameType
pluginHMSAudioPlugin

Returns

Promise<void>


removePluginFromVideoTrack

removePluginFromVideoTrack(plugin): Promise<void>

See

addPluginToVideoTrack

Parameters

NameType
pluginHMSVideoPlugin

Returns

Promise<void>


removeTrack

removeTrack(trackId): Promise<void>

You can use the removeTrack method to remove an auxiliary track. This method removes the track from the local peer's list of auxiliary tracks and unpublishes it.

Parameters

NameTypeDescription
trackIdstringstring - ID of the track to be removed

Returns

Promise<void>


sendBroadcastMessage

sendBroadcastMessage(message, type?): Promise<void>

Send a plain text message to all the other participants in the room.

Parameters

NameTypeDescription
messagestringstring message to broadcast
type?stringtype of message eg: image, video etc. - optional defaults to chat

Returns

Promise<void>


sendDirectMessage

sendDirectMessage(message, peerID, type?): Promise<void>

Parameters

NameTypeDescription
messagestring
peerIDstringid of the peer to which message has to be sent
type?stringtype of message eg: image, video etc. - optional defaults to chat

Returns

Promise<void>


sendGroupMessage

sendGroupMessage(message, roles, type?): Promise<void>

Parameters

NameTypeDescription
messagestringstring message to send
rolesstring[]roles to which to send the message
type?stringtype of message eg: image, video etc. - optional defaults to chat

Returns

Promise<void>


sendHLSTimedMetadata

sendHLSTimedMetadata(metadataList): Promise<void>

Used to define date range metadata in a media playlist. This api adds EXT-X-DATERANGE tags to the media playlist. It is useful for defining timed metadata for interstitial regions such as advertisements, but can be used to define any timed metadata needed by your stream. usage (e.g) const metadataList = [{ payload: "some string 1", duration: 2 }, { payload: "some string 2", duration: 3 }] sendHLSTimedMetadata(metadataList);

Parameters

NameType
metadataListHLSTimedMetadata[]

Returns

Promise<void>


sendMessage

sendMessage(message): void

Deprecated

The method should not be used

See

sendBroadcastMessage Send a plain text message to all the other participants in the room.

Parameters

NameTypeDescription
messagestringstring message to broadcast

Returns

void


setAppData

setAppData(key, value, merge?): void

use it for updating a particular property in the appdata

Example

assume appdata is initially { mySettings: { setting1: 'val1', setting2: 'val2', }, mySettings2: 43, mySettings3: false, }; after calling, setAppData("mySettings", {setting1:'val1-edit', setting3:'val3'}, true); it becomes { mySettings: { setting1: 'val1-edit', setting2: 'val2', setting3: 'val3', }, mySettings2: 43, mySettings3: false, }; Note: This is not suitable for keeping large data or data which updates at a high frequency, it is recommended to use app side store for those cases.

Parameters

NameTypeDescription
keystringa string. Does not check for existence. If the key is already not a property of the appData, it is added.
valueRecord<string | number, any>value to set for the key.
merge?booleanset it to true if you want to merge the appdata. - Always replaces the value for a given key if this parameter is not explicitly set to true. - Always replaces if the value is anything other than a plain object (i.e) JSON.parse()able. - If set to true on non-plain objects, this is ignored.

Returns

void

setAppData(key, value): void

Parameters

NameType
keystring
valueany

Returns

void


setAudioOutputDevice

setAudioOutputDevice(deviceId): Promise<void>

Set the audio output(speaker) device

Parameters

NameTypeDescription
deviceIdstringstring deviceId of the audio output device

Returns

Promise<void>


setAudioSettings

setAudioSettings(settings): Promise<void>

Change settings of the local peer's audio track

Parameters

NameTypeDescription
settingsPartial<HMSAudioTrackSettings>HMSAudioTrackSettings ({ volume, codec, maxBitrate, deviceId, advanced })

Returns

Promise<void>


setEnabledTrack

setEnabledTrack(trackId, enabled): Promise<void>

Parameters

NameTypeDescription
trackIdstringstring - ID of the track whose mute status needs to be set
enabledbooleanboolean - true when we want to unmute the track and false when we want to unmute it

Returns

Promise<void>


setLocalAudioEnabled

setLocalAudioEnabled(enabled): Promise<void>

This function can be used to enable/disable(unmute/mute) local audio track

Parameters

NameTypeDescription
enabledbooleanboolean - true to unmute, false to mute

Returns

Promise<void>


setLocalVideoEnabled

setLocalVideoEnabled(enabled): Promise<void>

This function can be used to enable/disable(unmute/mute) local video track

Parameters

NameTypeDescription
enabledbooleanboolean - true to unmute, false to mute

Returns

Promise<void>


setLogLevel

setLogLevel(level): void

Set the type of logs from the SDK you want to be logged in the browser console.

Note that HMSLogLevel is decremental meaning,

  • HMSLogLevel.VERBOSE(0) - will log every message from SDK.
  • HMSLogLevel.DEBUG(1) - will log messages that are helpful in debugging, important info, warnings and errors.
  • HMSLogLevel.INFO(2) - will log important info, warnings and errors.
  • HMSLogLevel.WARN(3) - will log warnings and errors.
  • HMSLogLevel.ERROR(4) - will log only errors.
  • HMSLogLevel.NONE(5) - won't log anything(Not recommended).

Usage: hmsActions.setLogLevel(4) or hmsActions.setLogLevel(HMSlogLevel.ERROR).

Parameters

NameType
levelHMSLogLevel

Returns

void


setMessageRead

setMessageRead(readStatus, messageId?): void

If just readStatus argument is passed, the function will set read flag of every message as the readStatus argument passed. If both readStatus and messageId argument is passed, then just read flag of message with passed messageId will be set as readStatus argument. if message with passed messageId is not found in store, no change in store will take place.

Parameters

NameTypeDescription
readStatusbooleanboolean value which you want to set as read flag for message/messages.
messageId?stringmessage id whose read falg you want to set.

Returns

void


setPreferredLayer

setPreferredLayer(trackId, layer): Promise<void>

set the quality of the selected videoTrack for simulcast.

Parameters

NameType
trackIdstring
layerHMSPreferredSimulcastLayer

Returns

Promise<void>


setRemoteTrackEnabled

setRemoteTrackEnabled(forRemoteTrackID, enabled): Promise<void>

Change track state a remote peer's track This can be used to mute/unmute a remote peer's track

Parameters

NameTypeDescription
forRemoteTrackIDstring | string[]The track ID or array of track IDs for which you want to change the state
enabledbooleantrue if you wish to enable(unmute permission is required) the track, false if you wish to disable(mute permission is required) the track

Returns

Promise<void>


setRemoteTracksEnabled

setRemoteTracksEnabled(params): Promise<void>

Use this to mute/unmute multipe tracks by source, role or type

Parameters

Returns

Promise<void>


setScreenShareEnabled

setScreenShareEnabled(enabled, config?): Promise<void>

If you want to enable screenshare for the local peer this class can be called. The store will be populated with the incoming track, and the subscriber(or react component if our hook is used) will be notified/rerendered

Parameters

NameTypeDescription
enabledbooleanboolean
config?HMSScreenShareConfigcheck the config object for details about the fields

Returns

Promise<void>


setSessionMetadata

setSessionMetadata(metadata): Promise<void>

If you want to update the metadata of the session. If an object is passed, it should be serializable using JSON.stringify.

Session metadata is available to every peer in the room and is persisted throughout a session till the last peer leaves a room

  • the API is not stable and might have breaking changes later

Parameters

NameType
metadataany

Returns

Promise<void>


setVideoSettings

setVideoSettings(settings): Promise<void>

Change settings of the local peer's video track

Parameters

NameTypeDescription
settingsPartial<HMSVideoTrackSettings>HMSVideoTrackSettings ({ width, height, codec, maxFramerate, maxBitrate, deviceId, advanced })

Returns

Promise<void>


setVolume

setVolume(value, trackId?): Promise<void>

Set the output volume of audio tracks(overall/particular audio track)

Parameters

NameTypeDescription
valuenumbernumber between 0-100
trackId?stringstring If undefined sets the overall volume(of every audio track in the room); If valid - set the volume of particular audio track

Returns

Promise<void>


startHLSStreaming

startHLSStreaming(params?): Promise<void>

If you have configured HLS streaming from dashboard, no params are required. otherwise

Parameters

NameType
params?HLSConfig

Returns

Promise<void>


startRTMPOrRecording

startRTMPOrRecording(params): Promise<void>

If you want to start RTMP streaming or recording.

Parameters

NameType
paramsRTMPRecordingConfig

Returns

Promise<void>


stopHLSStreaming

stopHLSStreaming(params?): Promise<void>

If you want to stop HLS streaming. The passed in arguments is not considered at the moment, and everything related to HLS is stopped.

Parameters

NameType
params?HLSConfig

Returns

Promise<void>


stopRTMPAndRecording

stopRTMPAndRecording(): Promise<void>

If you want to stop both RTMP streaming and recording.

Returns

Promise<void>


validateAudioPluginSupport

validateAudioPluginSupport(plugin): HMSPluginSupportResult

To check the support of the plugin, based on browser, os and audio devices

See

HMSPluginSupportResult

Parameters

NameTypeDescription
pluginHMSAudioPluginHMSAudioPlugin

Returns

HMSPluginSupportResult


validateVideoPluginSupport

validateVideoPluginSupport(plugin): HMSPluginSupportResult

To check the support of the plugin, based on browser, os and audio devices

See

HMSPluginSupportResult

Parameters

NameTypeDescription
pluginHMSVideoPluginHMSVideoPlugin

Returns

HMSPluginSupportResult