
## Templates API

Apart from the dashboard, a programmatic way to interact with templates is via [API](/server-side/v2/foundation/templates-and-roles#api-reference).


Server Side API reference


## Protocols

-   [HMSDataSourceDelegate](../protocols/HMSDataSourceDelegate)
-   [HMSLogger](../protocols/HMSLogger)
-   [HMSPreviewListener](../protocols/HMSPreviewListener)
-   [HMSUpdateListener](../protocols/HMSUpdateListener)

## Classes

-   [HMSAudioSettings](../classes/HMSAudioSettings)
-   [HMSAudioTrack](../classes/HMSAudioTrack)
-   [HMSAudioTrackSettings](../classes/HMSAudioTrackSettings)
-   [HMSBrowserRecordingState](../classes/HMSBrowserRecordingState)
-   [HMSChangeTrackStateRequest](../classes/HMSChangeTrackStateRequest)
-   [HMSCommonTrackSource](../classes/HMSCommonTrackSource)
-   [HMSConfig](../classes/HMSConfig)
-   [HMSDataSource](../classes/HMSDataSource)
-   [HMSDevice](../classes/HMSDevice)
-   [HMSError](../classes/HMSError)
-   [HMSLocalAudioTrack](../classes/HMSLocalAudioTrack)
-   [HMSLocalPeer](../classes/HMSLocalPeer)
-   [HMSLocalVideoTrack](../classes/HMSLocalVideoTrack)
-   [HMSMessage](../classes/HMSMessage)
-   [HMSMessageRecipient](../classes/HMSMessageRecipient)
-   [HMSNetworkQuality](../classes/HMSNetworkQuality)
-   [HMSPeer](../classes/HMSPeer)
-   [HMSPermissions](../classes/HMSPermissions)
-   [HMSPublishSettings](../classes/HMSPublishSettings)
-   [HMSRemoteAudioTrack](../classes/HMSRemoteAudioTrack)
-   [HMSRemotePeer](../classes/HMSRemotePeer)
-   [HMSRemoteVideoTrack](../classes/HMSRemoteVideoTrack)
-   [HMSRemovedFromRoomNotification](../classes/HMSRemovedFromRoomNotification)
-   [HMSRole](../classes/HMSRole)
-   [HMSRoleChangeRequest](../classes/HMSRoleChangeRequest)
-   [HMSRoom](../classes/HMSRoom)
-   [HMSRTMPConfig](../classes/HMSRTMPConfig)
-   [HMSRTMPStreamingState](../classes/HMSRTMPStreamingState)
-   [HMSSDK](../classes/HMSSDK)
-   [HMSSection](../classes/HMSSection)
-   [HMSServerRecordingState](../classes/HMSServerRecordingState)
-   [HMSSimulcastLayerSettingsPolicy](../classes/HMSSimulcastLayerSettingsPolicy)
-   [HMSSimulcastSettingsPolicy](../classes/HMSSimulcastSettingsPolicy)
-   [HMSSpeaker](../classes/HMSSpeaker)
-   [HMSSubscribeDegradationPolicy](../classes/HMSSubscribeDegradationPolicy)
-   [HMSSubscribeSettings](../classes/HMSSubscribeSettings)
-   [HMSTrack](../classes/HMSTrack)
-   [HMSTrackSettings](../classes/HMSTrackSettings)
-   [HMSUtilities](../classes/HMSUtilities)
-   [HMSUtility](../classes/HMSUtility)
-   [HMSVideoSettings](../classes/HMSVideoSettings)
-   [HMSVideoTrack](../classes/HMSVideoTrack)
-   [HMSVideoTrackSettings](../classes/HMSVideoTrackSettings)
-   [HMSVideoView](../classes/HMSVideoView)
-   [HMSViewModel](../classes/HMSViewModel)

## Enums

-   [HMSAnalyticsEventLevel](../enums/HMSAnalyticsEventLevel)
-   [HMSCameraFacing](../enums/HMSCameraFacing)
-   [HMSCodec](../enums/HMSCodec)
-   [HMSConnectionRole](../enums/HMSConnectionRole)
-   [HMSErrorCode](../enums/HMSErrorCode)
-   [HMSLogLevel](../enums/HMSLogLevel)
-   [HMSMessageRecipientType](../enums/HMSMessageRecipientType)
-   [HMSPeerUpdate](../enums/HMSPeerUpdate)
-   [HMSRoomUpdate](../enums/HMSRoomUpdate)
-   [HMSSimulcastLayer](../enums/HMSSimulcastLayer)
-   [HMSTrackKind](../enums/HMSTrackKind)
-   [HMSTrackSource](../enums/HMSTrackSource)
-   [HMSTrackUpdate](../enums/HMSTrackUpdate)
-   [HMSVideoConnectionState](../enums/HMSVideoConnectionState)

## Etensions

-   [HMSDataSource](/ios/etensions/HMSDataSource)
-   [HMSPeer](/ios/etensions/HMSPeer)
-   [HMSSection](/ios/etensions/HMSSection)
-   [HMSViewModel](/ios/etensions/HMSViewModel)

## Structs

-   [HMSPerformanceStats](../structs/HMSPerformanceStats)

## Typealiases

-   [HMSSection.SectionIdentifier](../typealiases/HMSSection.SectionIdentifier)
-   [HMSVideoResolution](../typealiases/HMSVideoResolution)


iOS API reference


**CLASS**

```swift
@objcMembers public class HMSAudioSettings: Codable
```

## Properties

### bitRate

```swift
public let bitRate: Int
```

### codec

```swift
public let codec: String
```


HMSAudioSettings


<Content alias="basics" />

### Quickstart

If you just want to see 100ms' SDKs in action in under 5 minutes, run one our quickstart [app](../guides/quickstart)


Basic Concepts


<Content alias="basics" />

### Quickstart

If you just want to see 100ms' SDKs in action in under 5 minutes, run one our quickstart [app](/javascript/v2/guides/javascript-quickstart)



<Content alias="basics" />

### Quickstart

If you just want to see 100ms' SDKs in action in under 5 minutes, run one our quickstart [app](/ios/v2/guides/Quickstart)


Basics


<Content alias="basics" />

### Quickstart

If you just want to see 100ms' SDKs in action in under 5 minutes, run one our quickstart [app](/android/v2/guides/Quickstart)



<Content alias="templatesAndRoles" />

## API reference

Apart from the dashboard, a programmatic way to interact with templates is via [API](/server-side/v2/foundation/templates-and-roles#api-reference).


Templates and Roles


<Content alias="securityAndTokens" />

## Management Token

Any service calling 100ms' REST APIs need to authenticate using a management token. The service required to generate this token should be hosted on your server

### Sample management token generation code

<Tabs id="test-code" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='test-code-0'>

```js
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

jwt.sign(
    {
        access_key: app_access_key,
        type: 'management',
        version: 2,
        iat: Math.floor(Date.now() / 1000),
        nbf: Math.floor(Date.now() / 1000)
    },
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='test-code-1'>

```py
#!/usr/bin/env python3
import jwt
import uuid
import datetime

app_access_key = '<app_access_key>'
app_secret = '<app_secret>'


def generateManagementToken():
    expires = 24 * 3600
    now = datetime.datetime.utcnow()
    exp = now + datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
        'access_key': app_access_key,
        'type': 'management',
        'version': 2,
        'jti': str(uuid.uuid4()),
        'iat': now,
        'exp': exp,
        'nbf': now
        }, key=app_secret)


if __name__ == '__main__':
    print(generateManagementToken())
```

</Tab>

<Tab id="test-code-2">

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateManagementToken() {
    Map<String, Object> payload = new HashMap<>();
    payload.put("access_key", "<app_access_key>");
    payload.put("type", "management");
    payload.put("version", 2);
    String token = Jwts.builder().setClaims(payload).setId(UUID.randomUUID().toString())
        .setExpiration(new Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(new Date(System.currentTimeMillis()))
        .signWith(SignatureAlgorithm.HS256, "<app_secret>".getBytes()).compact();
  }
```

</Tab>

<Tab id="test-code-3">

```ruby
require 'jwt'
require 'securerandom'

$app_access_key = "<app_access_key>"
$app_secret = "<app_secret>"

def generateManagementToken()
    now = Time.now
    exp = now + 86400
    payload = {
    access_key: $app_access_key,
    type: "management",
    version: 2,
    jti: SecureRandom.uuid,
    iat: now.to_i,
    nbf: now.to_i,
    exp: exp.to_i
}
token = JWT.encode(payload, $app_secret, 'HS256')
return token
end

puts generateManagementToken
```

</Tab>

<Tab id="test-code-4">

```php
<?php

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$app_access_key = "<app_access_key>";
$app_secret = "<app_secret>"

$issuedAt   = new DateTimeImmutable();
$expire     = $issuedAt->modify('+24 hours')->getTimestamp();

$payload = [
    'access_key' => $app_access_key,
    'type' => 'management',
    'version' => 2,
    'jti' =>  Uuid::uuid4()->toString(),
    'iat'  => $issuedAt->getTimestamp(),
    'nbf'  => $issuedAt->getTimestamp(),
    'exp'  => $expire,
];

$token = JWT::encode($payload, $app_secret, 'HS256');
?>
```

</Tab>
<Note>

**Warning**

Don't expose management token to client apps.

</Note>

## App Token

App Token will be used by _Client-side_ apps while instantiating 100ms' SDKs. It is used for joining the conference. This token generating service should be hosted on your server

### Sample app token generation code

<Tabs id="client-code-token" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='client-code-token-0'>

```javascript
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

var payload = {
    access_key: app_access_key,
    room_id: '<room_id>',
    user_id: '<user_id>',
    role: '<role>',
    type: 'app',
    version: 2,
    iat: Math.floor(Date.now() / 1000),
    nbf: Math.floor(Date.now() / 1000)
};

jwt.sign(
    payload,
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='client-code-token-1'>

```python
#!/usr/bin/env python3
import jwt
import uuid
import datetime
import sys

app_access_key = "<app_access_key>"
app_secret = "<app_secret>"

def generate(room_id, user_id, role):
    expires = expires or 24 * 3600
    now = datetime.datetime.utcnow()
    exp  = now+ datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
                "access_key": app_access_key,
                "type":"app",
                "version":2,
                "room_id": room_id,
                "user_id": user_id,
                "role":role,
                "jti": str(uuid.uuid4()),
                "exp": exp,
                "iat": now,
                "nbf": now,
                }, key=app_secret)
if __name__ == "__main__":
    if len(sys.argv) == 3:
        room_id = sys.argv[0]
        user_id = sys.argv[1]
        role = sys.argv[2]
    print(generate(room_id=room_id, user_id=user_id, role=role))
```

</Tab>

<Tab id='client-code-token-2'  >

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateHmsClientToken() {
    Map<String, Object> payload = new HashMap<>();
    payload.put("access_key", "<app_access_key>");
    payload.put("room_id", "<room_id>");
    payload.put("user_id", "<user_id>");
    payload.put("role", "<role>");
    payload.put("type", "app");
    payload.put("version", 2);
    String token = Jwts.builder().setClaims(payload).setId(UUID.randomUUID().toString())
        .setExpiration(new Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(new Date(System.currentTimeMillis()))
        .signWith(SignatureAlgorithm.HS256, "<app_secret>".getBytes()).compact();
  }
```

</Tab>

<Tab id='client-code-token-3'  >

```ruby
require 'jwt'
require 'securerandom'



$app_access_key = "<app_access_key>"
$app_secret = "app_secret"

def generateAppToken(room_id, user_id, role)
    now = Time.now
    exp = now + 86400
    payload = {
        access_key: $app_access_key,
        room_id: room_id,
        user_id: user_id,
        role: role,
        type: "app",
        jti: SecureRandom.uuid,
        version: 2,
        iat: now.to_i,
        nbf: now.to_i,
        exp: exp.to_i
    }

    token = JWT.encode(payload, $app_secret, 'HS256')
end

puts generateAppToken "<room_id>", "<user_id>", "<role>"

```

</Tab>

<Tab id='client-code-token-4'>

```php
<?php

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$issuedAt  = new DateTimeImmutable();
$expire    = $issuedAt->modify('+24 hours')->getTimestamp();
$accessKey = "<app_access_key>";
$secret = "<app_secret>";
$version   = 2;
$type      = "app";
$role      = "<role>";
$roomId    = "<room_id>";
$userId    = "<user_id>";

$payload = [
    'iat'  => $issuedAt->getTimestamp(),
    'nbf'  => $issuedAt->getTimestamp(),
    'exp'  => $expire,
    'access_key' => $accessKey,
    'type' => "app",
    'jti' =>  Uuid::uuid4()->toString()
    'version' => 2,
    'role' => $role,
    'room_id' => $roomId,
    'user_id' => $userId
];

$token = JWT::encode(
    $payload,
    $secret,
    'HS256'
);
```

</Tab>


Authentication and Tokens

Handling audio-video edge cases


The exact amount the SDK adds to your app can vary based on a few parameters but to find out the most it will add, add up the SDK size and Webrtc Size in the Size Table below.

Note that when a single apk is built it will add all the webrtc binaries together but on-device, it will only take one of the webrtc architectures not all.

For example, the all-arch apk will be increasd by:

SDK (1.1 Mb) + Webrtc (11Mb + 10.8Mb + 8.8Mb + 5.7Mb) = **37.4 Mb**

However on an actual arm64 device, when the play store downloads it, it will be:

SDK (1.1 Mb) + Webrtc arm64 ( 8.8Mb ) = **9.9 Mb**

## Size Table

#### SDK Size:

1.1Mb - for each architecture.

#### Webrtc Size:

| Architecture | Size Increase (Uncompressed) | **APK Size Increase (Compressed)** |
|---|---|---|
|x86_64| 11mb | **6mb** |
|x86| 10.8mb | **6.1mb**|
|arm64-v8a|8.8mb|**5.3mb**|
|armeabi-v7|5.7mb|**4.7mb**|

> 💡 The webrtc binaries contribute most to the size increase. When inside your apk they are compressed by default so the apk size will only be what you see under **compressed* since the APKs themselves are compressed files. If the apk was unzipped then you'd see the uncompressed file sizes. In practise this only happens to ram when the app is in use and does not contribute to disk space.

You could observe the architectures within your app's play store / analytics dashboard to see what the most common architectures are for your customers.

SDK Size Impact


**CLASS**

```swift
open class HMSAudioTrack : HMSTrack
```


HMSAudioTrack


## Overview

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

[A sample app demonstrating this is available here](https://github.com/100mslive/100ms-flutter/tree/main/example).

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

-   [Getting the video call joining link](#getting-the-video-call-joining-link)
-   [Add the sdk dependencies](#add-sdk-dependencies)
-   [Create a login token to authenticate the user](#login)
-   [Add permissions](#add-permissions)
-   [Create an instance of the `HMSSDK`](#instantiate-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](#join-a-video-call)
-   [Know when people join or leave](#how-you-know-when-people-join-or-leave)
-   [How to render audio/video](#how-to-render-audio-and-video)
-   [Listening to updates effectively](#listening-to-updates-effectively)
    <hr />

## Prerequisites

Familiarity with the [fundamentals](https://flutter.dev/docs/reference/tutorials) of Flutter apps.

### Getting the video call joining link

To join a video call you need an authentication token and a room id. Or a server that will translate the link into them. The [100ms Dashboard](https://dashboard.100ms.live/register) is one way to generate these auth tokens. In production your own server will generate these and manage user authentication.

Links created by the dashboard will stop working after 10k minutes of video calls. You'll need to setup your own server after.

For the purposes of this quickstart you can rely on just the 100ms dashboard. Sign up for the 100ms Dashboard [here](https://dashboard.100ms.live/register).

From either the dashboard, or your own server once implemented, you need to generate a video call link. Video call links generated by the 100ms Dashboard look like `https://myname.app.100ms.live/meeting/correct-horse-battery`.

> ⚙️ For Production
>
> With your own server for authentication and link generation, the format of the link is up to you.

### Add SDK dependencies

Add the `hmssdk_flutter` plugin in dependencies of pubspec.yaml

```dart
#pubspec.yaml

dependencies:
flutter:
  sdk: flutter

hmssdk_flutter:
```

If you are running Flutter 3.0 or higher, use this branch to add the package: `flutter3.0` 
<https://github.com/100mslive/100ms-flutter/tree/flutter3.0>

### Login

#### Request

Here's how to get an auth token with 100ms's demo authentication

1. Sign up to the dashboard.
2. Get your video call link. It should look like `https://myname.app.100ms.live/meeting/correct-horse-battery`
3. Send an http post request to `https://prod-in.100ms.live/hmsapi/get-token`
4. With the header "subdomain" set to `myname.app.100ms.live` if your link was `https://myname.app.100ms.live/meeting/correct-horse-battery`
5. For a link of the type `https://myname.app.100ms.live/meeting/correct-horse-battery` The body is json with the format `{"code": "correct-horse-battery", "user_id":"your-customer-id" }` the user_id can be any random string as well and you can create it with `UUID.randomUUID().toString(),`.

> ⚙️ For Production
>
> Maybe you won't use links at all. You will need to generate tokens on the backend, and rooms for users. Look up the [Token Setup Guide](token) here.

#### Response

The 100ms server will respond with an auth token like this `{"token":"some-token-string"}`.

### Add Permissions

#### Android Permissions

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

```xml
<uses-feature android:name="android.hardware.camera"/>
<uses-feature android:name="android.hardware.camera.autofocus"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>
<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.BLUETOOTH"/>
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
```

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](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

#### iOS Permissions

Add following permissions in iOS Info.plist file

```xml
<key>NSMicrophoneUsageDescription</key>
<string>{YourAppName} wants to use your microphone</string>

<key>NSCameraUsageDescription</key>
<string>{YourAppName} wants to use your camera</string>

<key>NSLocalNetworkUsageDescription</key>
<string>{YourAppName} App wants to use your local network</string>
```

### Join a Video Call

To join a video call, call join method on HMSSDK with the config settings. To listen the updates, call addUpdateListener on HMSSDK.

These are some listener's callback functions:

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

```dart
HMSConfig config = HMSConfig(userName: this.userName, authToken: this.authToken);
hmsSDK = HMSSDK();
hmsSDK.build()
hmsSDK.join(config: this.config);
hmsSDK.addUpdateListener(listener);
```

```dart
/// 100ms SDK provides callbacks to the client app about any change or update happening in the room after a user has joined by implementing HMSUpdateListener.
/// These updates can be used to render the video on screen or to display other info regarding the room.
abstract class HMSUpdateListener {

  /// This will be called on a successful JOIN of the room by the user
  ///
  /// This is the point where applications can stop showing its loading state
  /// [room]: the room which was joined
  void onJoin({required HMSRoom room});

  /// This is called when there is a change in any property of the Room
  ///
  ///  [room]: the room which was joined
  ///  [update]: the triggered update type. Should be used to perform different UI Actions
  void onRoomUpdate({required HMSRoom room, required HMSRoomUpdate update});

  /// This will be called whenever there is an update on an existing peer
  /// or a new peer got added/existing peer is removed.
  ///
  /// This callback can be used to keep a track of all the peers in the room
  /// [peer]: the peer who joined/left or was updated
  /// [update]: the triggered update type. Should be used to perform different UI Actions
  void onPeerUpdate({required HMSPeer peer, required HMSPeerUpdate update});

  /// This is called when there are updates on an existing track
  /// or a new track got added/existing track is removed
  ///
  /// This callback can be used to render the video on screen whenever a track gets added
  ///  [track]: the track which was added, removed or updated
  ///  [trackUpdate]: the triggered update type
  ///  [peer]: the peer for which track was added, removed or updated
  void onTrackUpdate({required HMSTrack track, required HMSTrackUpdate trackUpdate, required HMSPeer peer});

  /// This will be called when there is an error in the system
  /// and SDK has already retried to fix the error
  /// [error]: the error that occurred
  void onError({required HMSException error});

  /// This is called when there is a new broadcast message from any other peer in the room
  ///
  /// This can be used to implement chat is the room
  /// [message]: the received broadcast message
  void onMessage({required HMSMessage message});

  /// This is called when someone asks for change or role
  ///
  /// for eg. admin can ask a peer to become host from guest.
  /// this triggers this call on peer's app
  void onRoleChangeRequest({required HMSRoleChangeRequest roleChangeRequest});

  /// This is called every 1 second with list of active speakers
  ///
  /// ## A HMSSpeaker object contains -
  ///    - peerId: the peer identifier of HMSPeer who is speaking
  ///    - trackId: the track identifier of HMSTrack which is emitting audio
  ///    - audioLevel: a number within range 1-100 indicating the audio volume
  ///
  /// A peer who is not present in the list indicates that the peer is not speaking
  ///
  /// This can be used to highlight currently speaking peers in the room
  /// [speakers] the list of speakers
  void onUpdateSpeakers({required List<HMSSpeaker> updateSpeakers});

  ///when network or some other error happens it will be called
  void onReconnecting();

  ///when you are back in the room after reconnection
  void onReconnected();

  ///when someone requests for track change of yours be it video or audio this will be triggered
  /// [hmsTrackChangeRequest] request instance consisting of all the required info about track change
  void onChangeTrackStateRequest({required HMSTrackChangeRequest hmsTrackChangeRequest});

  ///when someone kicks you out or when someone ends the room at that time it is triggered
  /// [hmsPeerRemovedFromPeer] it consists info about who removed you and why.
  void onRemovedFromRoom({required HMSPeerRemovedFromPeer hmsPeerRemovedFromPeer});
}

```

### 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

The SDK plays the audio for every person who joins the call. Audio will begin playing when join succeeds.
To render the person's video you need to create an instance of HMSVideoView.

### Showing Videos

A peer represents one person in the video call.

A peer's video track is in hmsPeer.videoTrack. ScreenShares can be found in auxilary tracks of peer i.e the auxiliary tracks is a list of tracks, one of which can be a ScreenShare if they have chosen to share their screen.

```dart
peer.auxiliaryTracks
          ?.where((each) => each.kind == HMSTrackKind.kHMSTrackKindVideo);
```

### Mute/UnMute Audio

You can mute/unmute audio by calling switchAudio on HMSSDK. `isOn` is state variable. If `isOn` is true then audio will unmute and if its false then audio will mute.

```dart

/// audio unmute
hmsSDK.switchAudio(isOn: true);

/// audio mute
hmsSDK.switchAudio(isOn: false);
```

### Mute/UnMute Video

You can mute/unmute video by calling switchVideo on HMSSDK. `isOn` is state variable. If `isOn` is true then video will turn on and if its false then video will turn off.

```dart

/// video on
hmsSDK.switchVideo(isOn: true);

/// video off
hmsSDK.switchVideo(isOn: false);
```

### Leave a video call

To leave a video call, just call leave on HMSSDK.

```dart
hmsSDK.leave();
```

## Where to go from here

Checkout the [simple version](https://github.com/100mslive/100ms-flutter/tree/main/example) of the project.

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


100ms SDK Flutter Quickstart Guide


<Content alias="basics" />

### Quickstart

If you just want to see 100ms' SDKs in action in under 5 minutes, run one our quickstart [app](/server-side/v2/guides/quickstart)



<Content alias="basics" />

# React Native QuickStart Guide

## Getting started

Hello there! In this guide, we'll build a video conferencing application using our React Native SDK. We'll be using functional components with the powerful hooks provided by our SDK and build an app where you can have video call with your friends.

## Prerequisites

To get started you should be familiar with basics of [React Native](https://reactnative.dev/).

## Installing the dependencies

```bash
npm install --save @100mslive/react-native-hms
```

## Permissions

### For Android Permissions

Add following permissions in `AndroidManifest.xml`

```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](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

### For iOS Permissions

Add following lines in `Info.plist` file

```xml
<key>NSCameraUsageDescription</key>
<string>Please allow access to Camera to enable video conferencing</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Please allow access to network usage to enable video conferencing</string>
<key>NSMicrophoneUsageDescription</key>
<string>Please allow access to Microphone to enable video conferencing</string>
```

## Concepts

- Room: When we join a conference call, the participants are said to be in a video call room.
- Peer: A participant in the video call. You are the local peer while others are remote peers.
- Track: Media. There are two types of track a peer can have - audio and video.

## Initializing the SDK

Call the function given below to initialise the SDK

```js
import HmsManager from '@100mslive/react-native-hms';

const hmsInstance = await HmsManager.build();
```

This function will return the instance of HMSSDK that will be used for calling various functions and accessing data.

## Add event listeners

Add event listeners for all the events you want updates from such as onPreview, onJoin, onError etc. The actions can be found in HMSUpdateListenerActions class.

The event handlers are the way of handling any update happening in hms. It is advised to attach all the event listeners so you don't miss any update.

```js
import HmsManager, { HMSUpdateListenerActions } from 'react-native-hms';

// instance acquired from build() method
hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PREVIEW,
  onPreview // function that will be called on Preview success
);

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoin);
```

## Joining a room

To join a room 3 fields are required:

- `username`: The name of the user. This is the value that will be set on the peer object and be visible to everyone connected to the room.
- `authToken`: A client-side token that is used to authenticate the user. You can read about how to generate this token [here](https://docs.100ms.live/react-native/v2/guides/token).
- `userID`: A unique ID that will be used to identify user.
- `roomID` (optional): The ID of the room that you wanna join

```js
import HmsManager, {
  HMSUpdateListenerActions,
  HMSConfig,
} from 'react-native-hms';

// instance acquired from build() method
const HmsConfig = new HMSConfig({ authToken, userID, roomID, userName });

hmsInstance.preview(HmsConfig); // to start preview
// or
hmsInstance.join(HmsConfig); // to join a room
```

## Leaving the room

Before we go ahead with adding video, let us add a way to leave the room as well. We can call the leave method on hmsActions to leave the room.

Once you're done with a call and want to exit, call leave on the HMSSDK instance you created to join it. Also you can always acquire instance of HMS using build() method.

```js
hmsInstance.leave();
```

## Render video

Let us next add a way to show a tile for every participant in the room. We use HmsView component to render video on screen. This component takes trackId and scaleType of HMSVideoTrack and renders the corresponding track. The prop scaleType can be selected from HMSVideoViewMode as required. We can also add mirror a boolean prop as true to flip videos horizontally. Here is a code snippet explaining the way to link a videoTrack to HmsView.

```js
import { HmsView, HMSVideoViewMode } from 'react-native-hms';

const styles = StyleSheet.create({
  hmsView: {
    height: '100%',
    width: '100%',
  },
});

<HmsView
  style={styles.hmsView}
  trackId={trackId}
  mirror={true}
  scaleType={HMSVideoViewMode.ASPECT_FILL}
/>;
```

There are 2 types of Peers - a localPeer & remotePeers. To extract trackId from peers we can use following code snippet.

```js
const localTrackId = hmsInstance.localPeer.videoTrack.trackId;

const remoteTrackId = hmsInstance.remotePeers[index].videoTrack.trackId;
```

These track IDs can directly be passed to HmsView component

> A Pro tip: for fastest updates we can use ON_PEER_UPDATE and ON_TRACK_UPDATE listeners, these listeners get updated localPeer and remotePeers whenever there is any event related to these values.

```js
HmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PEER_UPDATE,
  onPeerListener
);

HmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_TRACK_UPDATE,
  onTrackListener
);

const onPeerListener = ({
  remotePeers,
  localPeer,
}: {
  peer: HMSPeer;
  room?: HMSRoom;
  type?: HMSPeerUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  updateVideoIds(remotePeers, localPeer); // this function can be used to update local and remotePeers on React-Native side
};

const onTrackListener = ({
  remotePeers,
  localPeer,
}: {
  peer: HMSPeer;
  track: HMSTrack;
  room?: HMSRoom;
  type?: HMSTrackUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  updateVideoIds(remotePeers, localPeer);
};
```

## Mute/Unmute local Audio/Video tracks

Mute is something that applies to both audio and video. When you mute audio, you can't be heard by other people. When you mute video, you will not be broadcasting your video to other people.

It can be invoked only on local (you) peers' audio or video tracks.

You get a reference to your own local peer from localPeer on HMSSDK instance.

```js
// instance acquired from build() method

hmsInstance.localPeer.localAudioTrack().setMute(true); // audio track

hmsInstance.localPeer.localVideoTrack().setMute(true); // video track
```


React Native Quickstart Guide


## Getting started

Hello there! In this guide, we'll build a video conferencing application using the 100ms JavaScript SDK. This guide doesn't make any assumptions related to
the framework or library choices. In case you plan to use React, do check our React quickstart as well.

TL;DR - You can find the link to the complete example over [here](https://codesandbox.io/s/hms-js-quickstart-5rmes).

### Prerequisites

To get started you must be familiar with rudimentary JavaScript and have [nodejs](https://nodejs.org/) installed on your machine.

### Installing the dependencies

```bash
npm install --save @100mslive/hms-video-store@latest
```

### Initializing the SDK

Let us start with initializing the libraries. We need an instance of `HMSStore` and `HMSActions` to get started. Copy the code snippet below and paste it into your project.

```jsx:script.js
import { HMSReactiveStore } from '@100mslive/hms-video-store';

const hms = new HMSReactiveStore();
const hmsStore = hms.getStore();
const hmsActions = hms.getHMSActions();
```

`hmsStore` will hold the complete state of the application such as details of all the participants. We can also visualize this state at any time using the
[devtools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en) extension.

`hmsActions` will help us perform actions such as joining the room, mute our audio and send messages.

### Concepts

-   `Room`: When we join a conference call, the participants are said to be in a video call `room`.
-   `Peer`: A participant in the video call. You are the `local peer` while others are `remote peers`.
-   `Track`: Media. There are two types of track a peer can have - audio and video.

## Joining a room

To join a room (a video call), we need to call the `join` method on `hmsActions` and it requires us to pass a `config` object.
The config object must be passed the following fields:

-   `userName`: The name of the user. This is the value that will be set on the `peer` object and be visible to everyone connected to the room.
-   `authToken`: A client-side token that is used to authenticate the user. You can read about how to generate this token [here](./token).

For our application, let us collect both of these fields from the user using a form.

<Tabs id="join-form" items={['HTML', 'JS']} />

<Tab id="join-form-0">

```html:index.html
<form id="join">
    <h2>Join Room</h2>
    <div class="input-container">
        <input id="name" type="text" name="username" placeholder="Your name" />
    </div>
    <div class="input-container">
        <input id="token" type="text" name="token" placeholder="Auth token" />
    </div>
    <button type="button" class="btn-primary" id="join-btn">Join</button>
</form>
```

</Tab>

<Tab id="join-form-1">

```jsx:script.js
const joinBtn = document.getElementById("join-btn");
joinBtn.addEventListener('click', () => {
    hmsActions.join({
        userName: document.getElementById('name').value,
        authToken: document.getElementById('token').value
    });
});
```

</Tab>

![Join form](/guides/join-room.png)

Congratulations! **you now have an audio-only conference ready to use**. If you have a friend join from another device, you can have a nice friendly chat with them.

### Leaving the room

Before we go ahead with adding video, let us add a way to leave the room as well. We can call the `leave` method on `hmsActions` to leave the room.

We'll set up the `leave` method to be called whenever the user closes the window or refreshes the tab.

```jsx:script.js
function leaveRoom() {
    hmsActions.leave();
}

window.onunload = leaveRoom;
```

## Adding video tiles

Let us next add a way to show a tile for every participant in the room. We'll need a list of peers connected to the room.

### Fetching information from state

At any point in time we can get a list of peers with:

```jsx
import { selectPeers } from '@100mslive/hms-video-store';

const peers = hmsStore.getState(selectPeers);
```

Let's take a moment to discuss how `hmsStore` works. The store maintains the state of the video call which includes
the list of peers, the connection state of the room, the tracks, track states etc.
We can use "selectors" that return a slice of the state to get the data piece we're interested in.

### Subscribing to the state

The `hmsStore` is also reactive, and we can subscribe to the state.
What this means is that we can register a function which will get called whenever the selected state changes.
This allows us to write [declarative](https://en.wikipedia.org/wiki/Declarative_programming) code.

We'll subscribe to the `peers` state and render the tiles whenever something related to the peers changes.

<Tabs id="render-peers" items={['JS', 'HTML']} />

<Tab id="render-peers-0">

```jsx:script.js
import {
    HMSReactiveStore,
    selectPeers
} from '@100mslive/hms-video-store';

// ...

const peersContainer = document.getElementById('peers-container');

function renderPeers(peers) {
    // 1. clear the peersContainer
    // 2. loop through the peers and render a tile for each peer
}

hmsStore.subscribe(renderPeers, selectPeers);
```

</Tab>

<Tab id="render-peers-1">

```html:index.html
<div id="conference" class="conference-section">
    <h2>Conference</h2>

    <div id="peers-container"></div>
</div>
```

</Tab>

For each peer, we'll render a `<video>` element and a `<div>` element with their name.
We'll also make a helper function to create these DOM elements and add it to the `peersContainer`

```jsx{3-16,20-20,23-47}:script.js
const peersContainer = document.getElementById('peers-container');

// helper function to create html elements
function h(tag, attrs = {}, ...children) {
  const newElement = document.createElement(tag);

  Object.keys(attrs).forEach((key) => {
    newElement.setAttribute(key, attrs[key]);
  });

  children.forEach((child) => {
    newElement.append(child);
  });

  return newElement;
}

function renderPeers(peers) {
  // 1. clear the peersContainer
  peersContainer.innerHTML = "";

  // 2. loop through the peers and render a tile for each peer
  peers.forEach((peer) => {
    const video = h("video", {
      class: "peer-video",
      autoplay: true,
      muted: true,
      playsinline: true,
    });

    hmsActions.attachVideo(peer.videoTrack, video);

    const peerContainer = h(
      "div",
      {
        class: "peer-container"
      },
      video,
      h(
        "div",
        {
          class: "peer-name"
        },
        peer.name
      )
    );

    peersContainer.append(peerContainer);
  });
}

hmsStore.subscribe(renderPeers, selectPeers);
```

Now after you click join you should be able to see yourself!

![Web Conference](/guides/web-conference.png)

Since we are subscribed to the `peers` state, our tiles will be re-rendered any time a new peer joins or leaves the room.
**We have a fully functional video conferencing application now** 🎉🚀

## Changing UI based on connection state

Right now, our join form shows even after we have joined the room. We need a way to know the connection state of the room and hide the form after we've connected.

We can do this by subscribing to the store with the `selectIsConnectedToRoom` selector.

```jsx:script.js
import {
  selectIsConnectedToRoom,
} from "@100mslive/hms-video-store";

function onConnection(isConnected) {
  if (isConnected) {
    form.classList.add("hide");
    conference.classList.remove("hide");
    leaveBtn.classList.remove("hide");
  } else {
    form.classList.remove("hide");
    conference.classList.add("hide");
    leaveBtn.classList.add("hide");
  }
}


hmsStore.subscribe(onConnection, selectIsConnectedToRoom);
```

## Muting/unmuting local tracks

Right now we are publishing both audio and video feed of the user whenever they join the room.
We may want to allow the user to mute/unmute their own tracks - both audio and video.

Let's add 2 buttons on the bottom of the page and call the methods on `hmsActions` to mute/unmute the local tracks.

<Tabs id="mute-unmute" items={['JS', 'HTML']} />

<Tab id="mute-unmute-0">

```jsx:script.js
import {
  selectIsLocalAudioEnabled,
  selectIsLocalVideoEnabled,
} from "@100mslive/hms-video-store";

const muteAud = document.getElementById("mute-aud");
const muteVid = document.getElementById("mute-vid");

muteAud.addEventListener("click", () => {
  const audioEnabled = !hmsStore.getState(selectIsLocalAudioEnabled);

  hmsActions.setLocalAudioEnabled(audioEnabled);

  muteAud.textContent = audioEnabled ? "Mute" : "Unmute";
});

muteVid.addEventListener("click", () => {
  const videoEnabled = !hmsStore.getState(selectIsLocalVideoEnabled);

  hmsActions.setLocalVideoEnabled(videoEnabled);

  muteVid.textContent = videoEnabled ? "Hide" : "Unhide";
});
```

</Tab>

<Tab id="mute-unmute-1">

```html
<div id="controls" class="control-bar">
    <button id="mute-aud" class="btn-control">Mute</button>
    <button id="mute-vid" class="btn-control">Hide</button>
</div>
```

</Tab>

We fetch the current state of the local audio and video and toggle them whenever the buttons are clicked.

If you try it out now, you may notice that turning off the video makes the tile go blank but turning it on again doesn't bring it back.
This is due to a change in video track requiring a call to attach again. To fix it let's
call our `renderPeers` function whenever we change the state of the local video.

```jsx{8}:script.js
muteVid.addEventListener("click", () => {
  const videoEnabled = hmsStore.getState(selectIsLocalVideoEnabled);

  hmsActions.setLocalVideoEnabled(!videoEnabled);

  muteVid.textContent = !videoEnabled ? "Hide" : "Unhide";

  renderPeers(hmsStore.getState(selectPeers));
});
```

![Mute/Unmute](/guides/mute-unmute.gif)

## Mirroring local video

Each `peer` object has an `isLocal` property that indicates whether the peer is local or remote.
When looping over the peer list we can use this property to decide whether to mirror the video or not.

<Tabs id="mirror" items={['JS', 'CSS']} />

<Tab id="mirror-0" >

```jsx{10,28}:script.js
function renderPeers(peers) {
  peersContainer.innerHTML = "";

  if (!peers) {
    peers = hmsStore.getState(selectPeers);
  }

  peers.forEach((peer) => {
    const video = h("video", {
      class: "peer-video" + (peer.isLocal ? " local" : ""),
      autoPlay: true,
      muted: true
    });

    hmsActions.attachVideo(peer.videoTrack, video);

    const peerContainer = h(
      "div",
      {
        class: "peer-container"
      },
      video,
      h(
        "div",
        {
          class: "peer-name"
        },
        peer.name + (peer.isLocal ? " (You)" : "")
      )
    );

    peersContainer.append(peerContainer);
  });
}
```

</Tab>

<Tab id="mirror-1">

```css:styles.css
.local.peer-video {
    transform: scaleX(-1);
}
```

</Tab>

That wraps it up for this guide. We hope you had fun.
There are plenty of cool stuff which can be done with our SDK, be sure to check the [features section](/javascript/v2/features/integration) for more information.

Here's the complete example.

<Codesandbox id="5rmes" />


JavaScript Quickstart Guide



## Prerequisites

Familiarity with Xcode and iOS SDK, Cocoapods installed

## Xcode Project Setup

Create an Xcode project and select "iOS" for platform and "App" for application


![Xcode](/guides/xcode1.png)

Select "Storyboard" for interface and "Swift" for language


Assuming your project name is "basicvideocall", create "Podfile" in the project folder with the following contents
then run `pod install`

```jsx
platform :ios, '13.0'

target 'basicvideocall' do
  use_frameworks!
  pod 'HMSSDK'

end
```

Open .xcworkspace

Add the entitlements for video, audio and network access to your `Info.plist`

```xml
<key>NSCameraUsageDescription</key>
<string>Please allow access to Camera to enable video conferencing.</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Please allow access to network usage to enable video conferencing.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Please allow access to Microphone to enable video conferencing.</string>
```


### Initialising The SDK

Open `ViewController.swift`

Add `HMSSDK` import


```swift
import HMSSDK
```


Conform to HMSUpdateListener and add stubs when Xcode offers to


```swift
extension ViewController: HMSUpdateListener {
}
```


Create an instance of HMSSDK


```swift
class ViewController: UIViewController {
var hmsSDK = HMSSDK.build()
...
}
```


### Get Auth Token

Before we proceed we need to obtain a room id and a token. In case you are not sure how to do this here is a quick guide:

[Token Setup Guide](Token)

### Join Room

Alright with the token and room id we are ready to proceed.

Add `joinRoom()` function with room id and token you obtained in previous steps. Then call `joinRoom()` from `viewDidLoad()`


```swift
func joinRoom() {
    let config = HMSConfig(userID: UUID().uuidString, 
            roomID: "replace with room id", authToken: "replace with token")
        hmsSDK.join(config: config, delegate: self)
}

override func viewDidLoad() {
    super.viewDidLoad()
    joinRoom()
}
```

    
Congratulations! You have an audio conference app.

Build and launch on device, then join same room on web app to try a call between web and iOS. (To join from the web, use one of the role url links from your room [Room in Dashboard](https://dashboard.100ms.live/rooms))


## Adding Video

Lets create add a lazily initialized UIStackView that will hold our video views


```swift{4-24}
class ViewController: UIViewController {
    var hmsSDK = HMSSDK.build()

    lazy var stackView: UIStackView = {
        let result = UIStackView()
        result.axis = .vertical
        
        view.addSubview(result)
        result.translatesAutoresizingMaskIntoConstraints = false
        result.leadingAnchor.constraint(equalTo: view.leadingAnchor).isActive = true
        result.trailingAnchor.constraint(equalTo: view.trailingAnchor).isActive = true
        result.topAnchor.constraint(equalTo: view.topAnchor).isActive = true
        let heightConstraint =  result.heightAnchor.constraint(equalToConstant: 0)
        heightConstraint.isActive = true
        heightConstraint.priority = .defaultLow
        
        return result
    }()
```


Next step is to listen for `trackAdded` update so that we get notified when someone has published a video track.

In the handler we will create an instance of `HMSVideoView` that allows us to render the `HMSVideoTrack`


```swift
extension ViewController: HMSUpdateListener {
    ...
    
    func on(track: HMSTrack, update: HMSTrackUpdate, for peer: HMSPeer) {
        switch update {
        case .trackAdded:
            if let videoTrack = track as? HMSVideoTrack {
                addVideoView(for: videoTrack)
            }
        default:
            break
        }
    }

    func addVideoView(for track: HMSVideoTrack) {
        let videoView = HMSVideoView()
        videoView.translatesAutoresizingMaskIntoConstraints = false
        videoView.setVideoTrack(track)
        videoView.heightAnchor.constraint(equalTo: videoView.widthAnchor, multiplier: 9.0/16.0).isActive = true
        stackView.addArrangedSubview(videoView)
    }
```


Build and run the app. Congratulations you have an a/v call running! 

    
### Cleanup

A peer can decide to stop publishing any of his tracks at any time (most frequent case is start/stop screen share), also peer may choose to leave a room. In any of these events we want to remove the corresponding video view to release resources.

To start we will introduce a map of track to video view so that we can figure out which video view to remove



```swift{4}
class ViewController: UIViewController {
    var hmsSDK = HMSSDK.build()

    var trackViewMap = [HMSTrack: HMSVideoView]()

...
```

    
Next we want to add a map entry as a last step in our `addVideoView` function


```jsx
func addVideoView(for track: HMSVideoTrack) {
    let videoView = HMSVideoView()
    videoView.translatesAutoresizingMaskIntoConstraints = false
    videoView.setVideoTrack(track)
    videoView.heightAnchor.constraint(equalTo: videoView.widthAnchor, multiplier: 9.0/16.0).isActive = true
    stackView.addArrangedSubview(videoView)
    trackViewMap[track] = videoView
}
```

    
Now we will create a helper function that will remove the view for given track


```swift
func removeVideoView(for track: HMSVideoTrack) {
    trackViewMap[track]?.removeFromSuperview()
}
```


With this we are ready to add handlers for `trackRemoved` and `peerLeft` events as follows:


```swift
func on(peer: HMSPeer, update: HMSPeerUpdate) {
    switch update {
    case .peerLeft:
        if let videoTrack = peer.videoTrack {
            removeVideoView(for: videoTrack)
        }
    default:
        break
    }
}

func on(track: HMSTrack, update: HMSTrackUpdate, for peer: HMSPeer) {
    switch update {
    case .trackAdded:
        if let videoTrack = track as? HMSVideoTrack {
            addVideoView(for: videoTrack)
        }
    case .trackRemoved:
        if let videoTrack = track as? HMSVideoTrack {
            removeVideoView(for: videoTrack)
        }
    default:
        break
    }
}
```


And that's how you handle most common use case with the 100ms SDK!


### Final Points

To control mute/unmute state of local video and audio tracks use 

```swift
hmsSDK.localPeer?.localAudioTrack()?.setMute(true)
hmsSDK.localPeer?.localVideoTrack()?.setMute(true)
```


After you are done with the call it is a good idea to call 


```swift
hmsSDK.leave()
```

    
### Ways to go from here

Checkout complete project code on github:  [https://github.com/100mslive/100ms-ios-sdk/tree/main/BasicExample](https://github.com/100mslive/100ms-ios-sdk/tree/main/BasicExample)

Checkout a sample code for a full featured conferencing app: 

[https://github.com/100mslive/100ms-ios-sdk/tree/main/Example](https://github.com/100mslive/100ms-ios-sdk/tree/main/Example)



100ms SDK iOS 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 implementaion.](https://github.com/100mslive/hello-world-android/)

[Most full-featured implementation.](https://github.com/100mslive/100ms-android/)

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

-   [Getting the video call joining link](#getting-the-video-call-joining-link)
-   [Add the sdk dependencies](#add-sdk-dependencies).
-   [Create a login token to authenticate the user](#login).
-   [Add permissions](#permissions)
-   [Create an instance of the `HMSSDK`](#instantiate-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](#join-a-video-call).
-   [Know when people join or leave](#how-you-know-when-people-join-or-leave)
-   [How to render audio/video](#how-to-render-audio-and-video)
-   [Listening to updates effectively](#listening-to-updates-effectively)
    <hr />

## Prerequisites

Familiarity with Android Studio and the [fundamentals](https://developer.android.com/training/basics/firstapp) 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.

### Getting the video call joining link

To join a video call you need an authentication token and a room id. Or a server that will translate the link into them. The [100ms Dashboard](https://dashboard.100ms.live/register) is one way to generate these auth tokens. In production your own server will generate these and manage user authentication.

We encourage you to setup your own server to authenticate users rather than using the 100ms dashboard to do so in production.

For the purposes of this quickstart you can rely on just the 100ms dashboard. Sign up for the 100ms Dashboard [here](https://dashboard.100ms.live/register).

From either the dashboard, or your own server once implemented, you need to generate a video call link. Video call links generated by the 100ms Dashboard look like `https://myname.app.100ms.live/meeting/correct-horse-battery`.

> ⚙️ For Production
>
> With your own server for authentication and link generation, the format of the link is up to you.

### Add SDK dependencies

-   Add the JitPack repository to your root `settings.gradle` at the end of the `respositories` closure:

You can open it in Android Studio by double tapping shift and typing `settings.gradle`.

```json{7}:settings.gradle
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'

```

-   Add the 100ms sdk dependency to your app-level `build.gradle` [![](https://jitpack.io/v/100mslive/android-sdk.svg)](https://jitpack.io/#100mslive/android-sdk).

```json{3,4}:build.gradle
dependencies {
 // See the version in the jitpack badge above.
 implementation 'com.github.100mslive.android-sdk:lib:x.x.x'
    }
```

### Login

#### Request

Here's how to get an auth token with 100ms's demo authentication

1. Sign up to the dashboard.
2. Get your video call link. It should look like `https://myname.app.100ms.live/meeting/correct-horse-battery`
3. Send an http post request to `https://prod-in.100ms.live/hmsapi/get-token`
4. With the header "subdomain" set to `myname.app.100ms.live` if your link was `https://myname.app.100ms.live/meeting/correct-horse-battery`
5. For a link of the type `https://myname.app.100ms.live/meeting/correct-horse-battery` The body is json with the format `{"code": "correct-horse-battery", "user_id":"your-customer-id" }` the user_id can be any random string as well and you can create it with `UUID.randomUUID().toString(),`.

> ⚙️ For Production
>
> Maybe you won't use links at all. You will need to generate tokens on the backend, and rooms for users. Look up the [Token Setup Guide](Token) here.

#### Response

The 100ms server will respond with an auth token like this `{"token":"some-token-string"}`.

### Permissions

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

```xml: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](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

### Instantiate HMSSDK

Instantiate the HMSSDK like this:

<Tabs id="instanstiate-hmssdk" items={['Kotlin', 'Java']} />

<Tab id='instanstiate-hmssdk-0'>

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

</Tab>

<Tab id='instanstiate-hmssdk-1'>

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

</Tab>

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

<Tabs id="join-call" items={['Kotlin', 'Java']} />

<Tab id='join-call-0'>

```kotlin

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

</Tab>

<Tab id='join-call-1'>

```java

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

```

</Tab>

### 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

The SDK plays the audio for every person who joins the call. Audio will begin playing when join succeeds.
To see the person's video you need to create an instance of `org.webrtc.SurfaceViewRenderer`. The correct version for webrtc is exported via the 100ms android sdk already, so if you have version `2.0.9` and above no additional imports are required to use it.

### Showing Videos

A peer represents one person in the video call.

A peer's video track is in `hmsPeer.videoTrack`. ScreenShares can be found in `val screenShareVideoTrack = hmsPeer.auxiliaryTracks.find { it is HMSVideoTrack }`. i.e the auxiliary tracks is a list of tracks, one of which can be a ScreenShare if they have chosen to share their screen.

You would want a RecyclerView of participants in the video call.
The adapter data should be a list of class that has both the peer and the track to display. Call it a TrackPeerPair.

Your layout xml for a peer video would need to have an `org.webrtc.SurfaceViewRenderer`

```xml

<org.webrtc.SurfaceViewRenderer
 android:id="@+id/videoSurfaceView"
 android:layout_width="wrap_content"
 android:layout_height="wrap_content"
 app:layout_constraintStart_toStartOf="parent"
 app:layout_constraintTop_toTopOf="parent" />
```

Initialize this when it's added to the window. Release it when it's removed. Call `hmsPeer.videoTrack?.addSink(surfaceViewRenderer)` to start showing videos.

### 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. You'd need to map them into TrackPeerPair's.

## Where to go from here

Checkout the [simple version](https://github.com/100mslive/hello-world-android/) of the project.

Also a full featured [advanced version](https://github.com/100mslive/100ms-android/).

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


100ms SDK Android Quickstart Guide

Auth Token Quickstart Guide


## Attaching Preview and Error Listeners
It is important to attach preview listener and error listener before calling the preview 
function in order to get updates if preview got executed successfully or if it failed.

```js
import HmsManager, {
  HMSUpdateListenerActions,
} from '@100mslive/react-native-hms';

const build = () => {
  const hmsInstance = HmsManager.build() // save this hms instance

  hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_PREVIEW,
    onPreviewListener, // function that will be called on Preview success
  );
  
  hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_JOIN,
    onJoinListener, // function that will be called on Join success
  );

  hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_ERROR, 
    onErrorListener, // function that will be called on Preview or Join failure
  );
}
```

## Calling Preview and Join functions
Preview screen is a frequently used UX element which allows users to check if their input devices are working properly and set the initial state 
(mute/unmute) of their audio and video tracks before joining. Once the listeners are attached we can call the preview function. After the preview 
function is called we have to wait for the preview or error callback before calling the join function.

```js
import {
  HMSException,
} from '@100mslive/react-native-hms';

const preview = () => {
  hmsInstance.preview(config);
}

const onErrorListener = (data: HMSException) => {
  // this callback will be triggered if preview or join functions fails
}

const onPreviewListener = () => {
  // this callback will be triggered if preview is successful and then only we should call join
  hmsInstance.join(config);  
}

const onJoinListener = () => {
  // this callback will be triggered if join is successful
};
```


Joining with Preview


## Getting started

Hello there! In this guide, we'll build a video conferencing application using our React SDK. We'll be using functional
components with the powerful hooks provided by our SDK and build an app where you can have a video call with your friends.

TL;DR - You can find the link to the complete example over [here](https://codesandbox.io/s/100ms-react-quickstart-kh0hy?file=/src/App.jsx).

### Prerequisites

To get started you should be familiar with the basics of [React](https://reactjs.org/).

### Installing the dependencies

```bash
## npm
npm install --save @100mslive/react-sdk@latest
## yarn
yarn add @100mslive/react-sdk@latest
```

### Initializing the SDK

Let us start with initializing the libraries. We need to wrap the entire application with `<HMSRoomProvider />` component.

This will let us use the hooks for state and actions.

```jsx:src/index.js
import { StrictMode } from "react";
import ReactDOM from "react-dom";
import { HMSRoomProvider } from "@100mslive/react-sdk";

import App from "./App";

const rootElement = document.getElementById("root");
ReactDOM.render(
  <StrictMode>
    <HMSRoomProvider>
      <App />
    </HMSRoomProvider>
  </StrictMode>,
  rootElement
);

```

`hmsStore` will hold the complete state of the application such as details of all the participants. We can also visualize this state at any time using the
[devtools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en) extension.

`hmsActions` will help us perform actions such as joining the room, muting our audio/video, and sending messages.

### Concepts

-   `Room`: When we join a conference call, the participants are said to be in a video call `room`.
-   `Peer`: A participant in the video call. You are the `local peer` while others are `remote peers`.
-   `Track`: Media. There are two types of tracks a peer can have - audio and video.

## Joining a room

To join a room (a video call), we need to call the `join` method on `hmsActions` and it requires us to pass a `config` object.
The config object must be passed the following fields:

-   `userName`: The name of the user. This is the value that will be set on the `peer` object and be visible to everyone connected to the room.
-   `authToken`: A client-side token that is used to authenticate the user. You can read about how to generate this token [here](./token).

For our application, let us collect both of these fields from the user using a form. Let's create a `JoinForm` component and add it to the application.

```jsx:src/JoinForm.jsx
import { useState } from "react";
import { useHMSActions } from "@100mslive/react-sdk";

function JoinForm() {
  const hmsActions = useHMSActions();
  const [inputValues, setInputValues] = useState({
    name: "",
    token: ""
  });

  const handleInputChange = (e) => {
    setInputValues((prevValues) => ({
      ...prevValues,
      [e.target.name]: e.target.value
    }));
  };

  const handleSubmit = (e) => {
    e.preventDefault();
    hmsActions.join({
      userName: inputValues.name,
      authToken: inputValues.token
    });
  };

  return (
    <form onSubmit={handleSubmit}>
      <h2>Join Room</h2>
      <div className="input-container">
        <input
          required
          value={inputValues.name}
          onChange={handleInputChange}
          id="name"
          type="text"
          name="name"
          placeholder="Your name"
        />
      </div>
      <div className="input-container">
        <input
          required
          value={inputValues.token}
          onChange={handleInputChange}
          id="token"
          type="text"
          name="token"
          placeholder="Auth token"
        />
      </div>
      <button className="btn-primary">Join</button>
    </form>
  );
}

export default JoinForm;
```

Let's add this form to our `<App>` component.

```jsx:src/App.jsx
export default function App() {
    return (
        <div className="App">
            <JoinForm />
        </div>
    );
}
```

![Join form](/guides/join-room.png)

Congratulations! **you now have an audio-only conference ready to use**. If you have a friend join from another device, you can have a nice friendly chat with them.

## Leaving the room

Before we go ahead with adding video, let us add a way to leave the room as well. We can call the `leave` method on `hmsActions` to leave the room.

We'll set up the `leave` method to be called whenever the user closes the window or refreshes the tab.

```jsx{2-8}:src/App.jsx
export default function App() {
  const hmsActions = useHMSActions();

  useEffect(() => {
    window.onunload = () => {
      hmsActions.leave();
    };
  }, [hmsActions]);

  return (
    <div className="App">
      <JoinForm />
    </div>
  );
}
```

## Adding video tiles

Let us next add a way to show a tile for every participant in the room. We'll need a list of peers connected to the room.

### Fetching information from state

At any point in time we can get a list of peers with:

```jsx
import { useHMSStore, selectPeers } from '@100mslive/react-sdk';

function Component() {
    const peers = useHMSStore(selectPeers);
    return <Peers peers={peers} />;
}
```

Let's take a moment to discuss how `hmsStore` works. The store maintains the state of the video call which includes
the list of peers, the connection state of the room, the tracks, track states, etc.
We can use "selectors" that return a slice of the state to get the data piece we're interested in.

The `hmsStore` is also reactive, which means any component using the HMSStore hook will re-render when the slice of the state, it listens to, changes.
This allows us to write [declarative](https://en.wikipedia.org/wiki/Declarative_programming) code.

Let us now create a `Conference` component that will render a list of peers. We'll get the peers from the store and render them.
Our component will get rerendered if this list of peers changes.

```jsx:src/Conference.jsx
import { selectPeers, useHMSStore } from "@100mslive/react-sdk";
import React from "react";
import Peer from "./Peer";

function Conference() {
  const peers = useHMSStore(selectPeers);
  return (
    <div className="conference-section">
      <h2>Conference</h2>

      <div className="peers-container">
        {peers.map((peer) => (
          <Peer key={peer.id} peer={peer} />
        ))}
      </div>
    </div>
  );
}

export default Conference;
```

For each peer, we'll render a `<video>` element and a `<div>` element with their name.

To render the video, we need to call `attachVideo` method of `hmsActions`, which accepts a `trackId` and a DOM element.

But we have abstracted this implementation inside `useVideo` hook for ease. This hook will return an object videoRef given a video `trackId`. The returned `videoRef` can be used to set on a video element meant to display the video. The hook will take care of attaching and detaching video, and will automatically detach when the video goes out of view to save on bandwidth.

```jsx:src/Peer.jsx
import { useVideo } from "@100mslive/react-sdk";

function Peer({ peer }) {
  const { videoRef } = useVideo({
    trackId: peer.videoTrack
  });
  return (
    <div className="peer-container">
      <video
        ref={videoRef}
        className={`peer-video ${peer.isLocal ? "local" : ""}`}
        autoPlay
        muted
        playsInline
      />
      <div className="peer-name">
        {peer.name} {peer.isLocal ? "(You)" : ""}
      </div>
    </div>
  );
}

export default Peer;
```

> Note that `height` and `width` CSS properties need to be set on the `<video>` element to render the peer's video.

## Changing UI based on connection state

Right now, our join form shows even after we have joined the room. We need a way to know the connection state of the room and hide the form after we've connected.

We can do this with `selectIsConnectedToRoom` selector.

```jsx{5,8,13,17,22-26}:src/App.jsx
import "./styles.css";
import JoinForm from "./JoinForm";
import Conference from "./Conference";
import { useEffect } from "react";
import {
  selectIsConnectedToRoom,
  useHMSActions,
  useHMSStore
} from "@100mslive/react-sdk";

export default function App() {
  const isConnected = useHMSStore(selectIsConnectedToRoom);
  const hmsActions = useHMSActions();

  useEffect(() => {
    window.onunload = () => {
      if (isConnected) {
        hmsActions.leave();
      }
    };
  }, [hmsActions, isConnected]);

  return (
    <div className="App">
      <Header />
      {isConnected ? (
        <Conference />
      ) : (
        <JoinForm />
      )}
    </div>
  );
}

```

## Muting/unmuting local tracks

Right now we are publishing both audio and video feed of the user whenever they join the room.
We may want to allow the user to mute/unmute their own tracks - both audio and video.

If you specifically need granular data like knowing the current video status you can use `selectIsLocalVideoEnabled` and for audio `selectIsLocalAudioEnabled` instead.

In this case, we can use `useAVToggle` hook which will give us the current audio/video status of the user and also give us functions to toggle them.

```jsx:src/Footer.jsx
import { useAVToggle } from "@100mslive/react-sdk";

function Footer() {
  const {
    isLocalAudioEnabled,
    isLocalVideoEnabled,
    toggleAudio,
    toggleVideo
  } = useAVToggle();
  return (
    <div className="control-bar">
      <button className="btn-control" onClick={toggleAudio}>
        {isLocalAudioEnabled ? "Mute" : "Unmute"}
      </button>
      <button className="btn-control" onClick={toggleVideo}>
        {isLocalVideoEnabled ? "Hide" : "Unhide"}
      </button>
    </div>
  );
}

export default Footer;
```

We fetch the current state of the local audio and video and toggle them whenever the buttons are clicked.

![Mute/Unmute](/guides/mute-unmute.gif)

And finally, let's add this component to the `<App>` component to render the buttons only when we are connected to the room.

```jsx{1,19-22}:src/App.js
import Footer from './Footer';

export default function App() {
  const isConnected = useHMSStore(selectIsConnectedToRoom);
  const hmsActions = useHMSActions();

  useEffect(() => {
    window.onunload = () => {
      if (isConnected) {
        hmsActions.leave();
      }
    };
  }, [hmsActions, isConnected]);

  return (
    <div className="App">
      <Header />
      {isConnected ? (
        <>
          <Conference />
          <Footer />
        </>
      ) : (
        <JoinForm />
      )}
    </div>
  );
}
```

That wraps it up for this guide. We hope you had fun.
There is plenty of cool stuff which can be done with our SDK, be sure to check the [features section](/javascript/v2/features/integration) for more information. -->

Here's the complete example.

<Codesandbox id="100ms-react-quickstart-kh0hy" />


React Quickstart Guide


## Attaching Preview and Error Listeners
It is important to attach preview listener and error listener before calling the preview 
function in order to get updates if preview got executed successfully or if it failed.

```dart
import 'package:hmssdk_flutter/hmssdk_flutter.dart';

class HMSSDKInteractor {
  late HMSSDK hmsSDK;

  HMSSDKInteractor() {
    hmsSDK = HMSSDK();    // save this hms instance
    hmsSDK.build();       
  } 

  void addPreviewListener(HMSPreviewListener listener) {
    hmsSDK.addPreviewListener(listener: listener);
  }
  
  void addUpdateListener(HMSUpdateListener listener) {
    hmsSDK.addUpdateListener(listener: listener);
  }

}
```

## Calling Preview and Join functions
Preview screen is a frequently used UX element which allows users to check if their input devices are working properly and set the initial state 
(mute/unmute) of their audio and video tracks before joining. Once the listeners are attached we can call the preview function. After the preview 
function is called we have to wait for the preview or error callback before calling the join function.

```dart
import 'package:hmssdk_flutter/hmssdk_flutter.dart';

Class preview implements HMSUpdateListener, HMSActionResultListener{
  void preview(HMSConfig config){
    hmsInstance.preview(config);
  }
}

  @override
  void onError({required HMSException error}) {
    // this callback will be triggered if preview or join functions fails
  }

void onPreviewListener(HMSPreviewListener listener) {
// this callback will be triggered if preview is successful and then only we should call join
    hmsSDK.join(config: this.config);
  }

void onUpdateListener(HMSUpdateListener listener) {
    hmsSDK.addUpdateListener(listener: listener);
  }
```



## 100ms Android SDK 2.1.2 or higher
If using 100ms Android SDK version 2.1.2 and higher proguard configuration is bundled inside it. No additional code is required.


## Prior to Android SDK version 2.1.2
Prior to Android SDK version 2.1.2, the following configuration was needed in release builds.

Add it to your `proguard-rules.pro`

```:proguard-rules.pro
# 100ms proguard rules
-keep class org.webrtc.** { *; }
-keep class live.hms.video.** { *; }
```



Proguard configuration

Webhook


Here's a list of useful Selector hooks that you might want to use while building your application. Before using these make sure you have initialized the SDK, you can refer to this [guide](/javascript/v2/guides/javascript-quickstart#initializing-the-sdk).

Selector functions would fetch you information from the state at any point in time, it can be anything ranging from "how many people are in the room?" to "is my audio on or not?". The answer to all these questions is the store.

## Am I connected to the Room?

Knowing if you're in the room or not is the barest model information you need. `selectIsConnectedToRoom` returns a boolean flag denoting whether you've joined a room. NOTE: Returns true only after join, returns false during the preview.

<Tabs id="connect" items={['Javascript', 'React']} />

<Tab id='connect-0'>

```js
const isConnected = hmsStore.getState(selectIsConnectedToRoom);
```

</Tab>

<Tab id='connect-1'>

```jsx
const isConnected = useHMSStore(selectIsConnectedToRoom);
```

</Tab>

## Am I in the Preview?

`selectIsInPreview` returns a boolean denoting whether the room is in Preview state.

<Tabs id="preview" items={['Javascript', 'React']} />

<Tab id='preview-0'>

```js
const isInPreview = hmsStore.getState(selectIsInPreview);
```

</Tab>

<Tab id='preview-1'>

```jsx
const isInPreview = useHMSStore(selectIsInPreview);
```

</Tab>

## How many people have joined the room?

`selectPeerCount` returns the number of peers inside the room. If you have turned on
peer list in preview, this count won't include the local peer if they're still in preview.

<Tabs id="peerCount" items={['Javascript', 'React']} />

<Tab id='peerCount-0'>

```js
const count = hmsStore.getState(selectPeerCount);
```

</Tab>

<Tab id='peerCount-1'>

```jsx
const count = useHMSStore(selectPeerCount);
```

 </Tab>

## Who all are in my room?

`selectPeers` returns you an array of peers(remote peers and your local peer) present in the room. It will
include the local peer in preview phase.

<Tabs id="peers" items={['Javascript', 'React']} />

<Tab id='peers-0'>

```js
const peers = hmsStore.getState(selectPeers);
```

</Tab>

<Tab id='peers-1'>

```jsx
const peers = useHMSStore(selectPeers);
```

</Tab>

## What is my current state of room?

What if you fail to join the room? How do you know if the user is reconnecting? This is where `selectRoomState` comes in handy, it returns you the current state of your room. You can refer to the [ENUMS](/api-reference/javascript/v2/enums/HMSRoomState) types for reference.

<Tabs id="roomState" items={['Javascript', 'React']} />

<Tab id='roomState-0'>

```js
const roomState = hmsStore.getState(selectRoomState);
```

</Tab>

<Tab id='roomState-1'>

```jsx
const roomState = useHMSStore(selectRoomState);
```

</Tab>

## How do I know if my mic/video is on?

Mic/Video being turned on can lead to a lot of blunders, therefore it's critical to show it to the end-user. `selectIsLocalAudioEnabled` & `selectIsLocalVideoEnabled` helps you know if the local audio/video is enabled or not.

<Tabs id="av" items={['Javascript', 'React']} />

<Tab id='av-0'>

```js
const audioOn = hmsStore.getState(selectIsLocalAudioEnabled);
const videoOn = hmsStore.getState(selectIsLocalVideoEnabled);
```

</Tab>

<Tab id='av-1'>

```jsx
const audioOn = useHMSStore(selectIsLocalAudioEnabled);
const videoOn = useHMSStore(selectIsLocalVideoEnabled);
```

</Tab>

## How do I know the status of remote mic/video status?

`selectIsPeerAudioEnabled` & `selectIsPeerVideoEnabled` returns a boolean denoting the peer's Audio/Video status.

<Tabs id="rm" items={['Javascript', 'React']} />

<Tab id='rm-0'>

```js
const audioOn = hmsStore.getState(selectIsPeerAudioEnabled(peerId));
const videoOn = hmsStore.getState(selectIsPeerVideoEnabled(peerId));
```

</Tab>

<Tab id='rm-1'>

```jsx
const audioOn = useHMSStore(selectIsPeerAudioEnabled(peerId));
const videoOn = useHMSStore(selectIsPeerVideoEnabled(peerId));
```

</Tab>

## How do I get the video stream of a user?

You can get video stream of a user using `selectCameraStreamByPeer` it returns [HMSTrack](/api-reference/javascript/v2/interfaces/HMSTrack) which you can use to call [attach/detach](/javascript/v2/features/render-video) actions.

<Tabs id="cam" items={['Javascript', 'React']} />

<Tab id='cam-0'>

```js
const videoTrack = hmsStore.getState(selectCameraStreamByPeer(peerId));
```

</Tab>

<Tab id='cam-1'>

```jsx
const videoTrack = useHMSStore(selectCameraStreamByPeer(peerId));
```

</Tab>


Useful Selectors


<Content alias="securityAndTokens" />

## Management Token

Any service calling 100ms' REST APIs need to authenticate using a management token. The service required to generate this token should be hosted on your server

### Sample management token generation code

<Tabs id="test-code" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='test-code-0'>

```js
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

jwt.sign(
    {
        access_key: app_access_key,
        type: 'management',
        version: 2,
        iat: Math.floor(Date.now() / 1000),
        nbf: Math.floor(Date.now() / 1000)
    },
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='test-code-1'>

```py
#!/usr/bin/env python3
import jwt
import uuid
import datetime

app_access_key = '<app_access_key>'
app_secret = '<app_secret>'


def generateManagementToken():
    expires = 24 * 3600
    now = datetime.datetime.utcnow()
    exp = now + datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
        'access_key': app_access_key,
        'type': 'management',
        'version': 2,
        'jti': str(uuid.uuid4()),
        'iat': now,
        'exp': exp,
        'nbf': now
        }, key=app_secret)

if __name__ == '__main__':
    print(generateManagementToken())
```

</Tab>

<Tab id="test-code-2">

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateManagementToken() {
    Map<String, Object> payload = new HashMap<>();
    payload.put("access_key", "<app_access_key>");
    payload.put("type", "management");
    payload.put("version", 2);
    String token = Jwts.builder().setClaims(payload).setId(UUID.randomUUID().toString())
        .setExpiration(new Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(new Date(System.currentTimeMillis()))
        .signWith(SignatureAlgorithm.HS256, "<app_secret>".getBytes()).compact();
  }
```

</Tab>

<Tab id="test-code-3">

```ruby
require 'jwt'
require 'securerandom'

$app_access_key = "<app_access_key>"
$app_secret = "<app_secret>"

def generateManagementToken()
    now = Time.now
    exp = now + 86400
    payload = {
    access_key: $app_access_key,
    type: "management",
    version: 2,
    jti: SecureRandom.uuid,
    iat: now.to_i,
    nbf: now.to_i,
    exp: exp.to_i
}
token = JWT.encode(payload, $app_secret, 'HS256')
return token
end

puts generateManagementToken
```

</Tab>

<Tab id="test-code-4">

```php
<?php

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$app_access_key = "<app_access_key>";
$app_secret = "<app_secret>"

$issuedAt   = new DateTimeImmutable();
$expire     = $issuedAt->modify('+24 hours')->getTimestamp();

$payload = [
    'access_key' => $app_access_key,
    'type' => 'management',
    'version' => 2,
    'jti' =>  Uuid::uuid4()->toString(),
    'iat'  => $issuedAt->getTimestamp(),
    'nbf'  => $issuedAt->getTimestamp(),
    'exp'  => $expire,
];

$token = JWT::encode($payload, $app_secret, 'HS256');
?>
```

</Tab>
<Note>

**Warning**

Don't expose management token to client apps.

</Note>

## App Token

App Token will be used by _Client-side_ apps while instantiating 100ms' SDKs. It is used for joining the conference. This token generating service should be hosted on your server

### Sample app token generation code

<Tabs id="client-code-token" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='client-code-token-0'>

```javascript
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

var payload = {
    access_key: app_access_key,
    room_id: '<room_id>',
    user_id: '<user_id>',
    role: '<role>',
    type: 'app',
    version: 2,
    iat: Math.floor(Date.now() / 1000),
    nbf: Math.floor(Date.now() / 1000)
};

jwt.sign(
    payload,
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='client-code-token-1'>

```python
#!/usr/bin/env python3
import jwt
import uuid
import datetime
import sys

app_access_key = "<app_access_key>"
app_secret = "<app_secret>"

def generate(room_id, user_id, role):
    expires = expires or 24 * 3600
    now = datetime.datetime.utcnow()
    exp  = now+ datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
                "access_key": app_access_key,
                "type":"app",
                "version":2,
                "room_id": room_id,
                "user_id": user_id,
                "role":role,
                "jti": str(uuid.uuid4()),
                "exp": exp,
                "iat": now,
                "nbf": now,
                }, key=app_secret)
    if len(sys.argv) == 3:
        room_id = sys.argv[0]
        user_id = sys.argv[1]
        role = sys.argv[2]
    print(generate(room_id=room_id, user_id=user_id, role=role))
```

</Tab>

<Tab id='client-code-token-2'  >

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateHmsClientToken() {
    Map<String, Object> payload = new HashMap<>();
    payload.put("access_key", "<app_access_key>");
    payload.put("room_id", "<room_id>");
    payload.put("user_id", "<user_id>");
    payload.put("role", "<role>");
    payload.put("type", "app");
    payload.put("version", 2);
    String token = Jwts.builder().setClaims(payload).setId(UUID.randomUUID().toString())
        .setExpiration(new Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(new Date(System.currentTimeMillis()))
        .signWith(SignatureAlgorithm.HS256, "<app_secret>".getBytes()).compact();
  }
```

</Tab>

<Tab id='client-code-token-3'  >

```ruby
require 'jwt'
require 'securerandom'



$app_access_key = "<app_access_key>"
$app_secret = "app_secret"

def generateAppToken(room_id, user_id, role)
    now = Time.now
    exp = now + 86400
    payload = {
        access_key: $app_access_key,
        room_id: room_id,
        user_id: user_id,
        role: role,
        type: "app",
        jti: SecureRandom.uuid,
        version: 2,
        iat: now.to_i,
        nbf: now.to_i,
        exp: exp.to_i
    }

    token = JWT.encode(payload, $app_secret, 'HS256')
end

puts generateAppToken "<room_id>", "<user_id>", "<role>"

```

</Tab>

<Tab id='client-code-token-4'>

```php
<?php

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$issuedAt  = new DateTimeImmutable();
$expire    = $issuedAt->modify('+24 hours')->getTimestamp();
$accessKey = "<app_access_key>";
$secret = "<app_secret>";
$version   = 2;
$type      = "app";
$role      = "<role>";
$roomId    = "<room_id>";
$userId    = "<user_id>";

$payload = [
    'iat'  => $issuedAt->getTimestamp(),
    'nbf'  => $issuedAt->getTimestamp(),
    'exp'  => $expire,
    'access_key' => $accessKey,
    'type' => "app",
    'jti' =>  Uuid::uuid4()->toString()
    'version' => 2,
    'role' => $role,
    'room_id' => $roomId,
    'user_id' => $userId
];

$token = JWT::encode(
    $payload,
    $secret,
    'HS256'
);
```

</Tab>



<Content alias="domainsAndPorts" />

For smooth call experience add following domains and ports to your firewall whitelist

## Domains

`*.100ms.live`

## Ports

### Minimum requirement

| Ports                  | Protocol  | Description                   |
| :--------------------- | :-------- | :---------------------------- |
| 80, 443                | TCP       | API, WebSocket, TURN/TLS      |

### Requirements for best experience

| Ports                  | Protocol  | Description                   |
| :--------------------- | :-------- | :---------------------------- |
| 80, 443, 3478          | TCP       | API, WebSocket, TURN/TLS      |
| 443, 3478, 41000-65535 | UDP       | TURN/UDP, ICE, Media traffic  |


Domain and Port Whitelisting


**CLASS**

```swift
open class HMSAudioTrackSettings : NSObject, NSCopying
```

## Properties

### maxBitrate

```swift
open var maxBitrate: Int
```

### trackDescription

```swift
open var trackDescription: String?
```

## Methods

### init

```swift
public init()
```

### init

```swift
public init(maxBitrate: Int, trackDescription: String?)
```


HMSAudioTrackSettings


## Installing our libraries

Add the `hmssdk_flutter` plugin in dependencies of pubspec.yaml

```dart
#pubspec.yaml

dependencies:
  flutter:
    sdk: flutter

  hmssdk_flutter:
```

If you are running Flutter 3.0 or higher, use this branch to add the package: `flutter3.0` 
<https://github.com/100mslive/100ms-flutter/tree/flutter3.0>

## Setting up the library

Run following in command in terminal.

```bash
flutter pub get
flutter build apk
flutter build ios
flutter run
```
## Device Permissions

### Android 

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

```xml
<uses-feature android:name="android.hardware.camera"/>

<uses-feature android:name="android.hardware.camera.autofocus"/>

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

<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE"/>

<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS"/>

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

<uses-permission android:name="android.permission.BLUETOOTH"/>

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

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
```

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](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

### Update target Android version

Update the Android SDK version to 21 or later by navigating to the directory and updating the android/app/build.gradle file

```xml
defaultConfig{
  minSdkVersion 21
  …
}
```

### iOS

Add the entitlements for video, audio and network access to your Info.plist

```xml
<key>NSCameraUsageDescription</key>
<string>Allow access to Camera to enable video calling.</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Allow access to Camera to network to enable video calling.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Allow access to Camera to mic to enable video calling.</string>
```

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview.


## Debugging Tools
 
You can use [Android Studio](https://developer.android.com/studio), [VS Code](https://code.visualstudio.com/) & [Xcode](https://developer.apple.com/xcode/) to develop application with 100ms.

## Proguard configuration

Add this to your proguard-rules.pro

```kotlin
# 100ms proguard rules
-keep class org.webrtc.** { *; }
-keep class live.hms.video.** { *; }
```

100ms Flutter SDK Integration Guide


## Installing the dependencies

```bash
npm install --save @100mslive/react-native-hms
```

## Permissions

### For iOS

Add following lines in `Info.plist` file

```xml
<key>NSCameraUsageDescription</key>
<string>Please allow access to Camera to enable video conferencing</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Please allow access to network usage to enable video conferencing</string>
<key>NSMicrophoneUsageDescription</key>
<string>Please allow access to Microphone to enable video conferencing</string>
```

### For Android

Add following permissions in `AndroidManifest.xml`

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
<uses-feature android:name="android.hardware.camera" />
<uses-feature android:name="android.hardware.camera.autofocus" />
```

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](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

We suggest using [react-native-permission](https://www.npmjs.com/package/react-native-permissions) to acquire permissions from both platforms.

> Note: Compiling with Kotlin for compileSdkVersion 30 requires JDK 11 or above

### Proguard configuration

##### 100ms Android SDK 2.1.2 or higher
If using 100ms Android SDK version 2.1.2 and higher proguard configuration is bundled inside it. No additional code is required.

##### Prior to Android SDK version 2.1.2
Prior to Android SDK version 2.1.2, the following configuration was needed in release builds.

Add it to your proguard-rules.pro

```js
# 100ms proguard rules
-keep class org.webrtc.** { *; }
-keep class live.hms.video.** { *; }
```

### Expo Setup

100ms React Native SDK supports development with [Expo](https://expo.dev/). Following is a guide to set it up -

1. Install node modules
```bash
npm install
```

2. Install expo-cli globally to run the Expo commands
```bash
npm install --global expo-cli
```

3. Install Expo Dev Client
```bash
expo install expo-dev-client
```

4. Now we can run on iOS and Android
```bash
expo run: ios -d
```
```bash
expo run: android -d
```

Alternatively, you can run it from IDE of your choice (VS Code, Android Studio, Xcode, etc) and start the dev server from terminal (it will help running on devices). To start the server use the following command -
```bash
expo start --dev-client
```


Integrating the SDK


## Installing our libraries

You can use either npm or yarn to install the dependencies. Please install the respective libraries depending on whether
you're planning to use with react or other framework/plain JavaScript.

<Tabs id="packages-install" items={['JavaScript', 'React', 'JavaScript(CDN)']} />

<Tab id="packages-install-0">

```bash
npm install --save @100mslive/hms-video @100mslive/hms-video-store
```

</Tab>

<Tab id="packages-install-1">

```bash
## npm
npm install --save @100mslive/react-sdk@latest
## yarn
yarn add @100mslive/react-sdk@latest
```

</Tab>

<Tab id="packages-install-2">

```
https://cdn.skypack.dev/@100mslive/hms-video
https://cdn.skypack.dev/@100mslive/hms-video-store
```

</Tab>

## Setting up the sdk

Our core SDK can be used with plain JavaScript or any UI framework. We also provide a convenient hooks based interface
in case you're planning to integrate our SDK in a React app. Please follow the appropriate section below.

### JavaScript

There are three entities which we need to be familiar of -

-   `hmsStore` - this contains the complete state of the room at any given time. This includes for example, participant details,
    messages and track states.
-   `hmsActions` - this is used to perform any action such as joining, muting and sending a message.
-   `hmsNotifications` - this can be used to get notified on peer join/leave and new messages in order to show toast notifications to
    the user.

Let's create a `hms.js` file where we initialize and export the above entities, so they can be used as required. We'll assume that
this setup is in place in other sections of the documentation.

<Tabs id="store" items={['Setup and Export', 'Import and use']} />{' '}

<Tab id='store-0'>

```js:hms.js
import { HMSReactiveStore } from '@100mslive/hms-video-store';

const hms = new HMSReactiveStore();

// by default subscriber is notified about store changes post subscription only, this can be
// changed to call it right after subscribing too using this function.
hms.triggerOnSubscribe(); // optional, recommended

const hmsActions = hms.getHMSActions();
const hmsStore = hms.getStore();
const hmsNotifications = hms.getNotifications();

export { hmsActions, hmsStore, hmsNotifications };
```

</Tab>

<Tab  id='store-1'>

```js:some_other_file.js
import { hmsActions, hmsStore, hmsNotifications } from './hms';
```

</Tab>

### React Hooks

If you're planning to use our SDK with React, we provide three friendly hooks as a wrapper over our plain JavaScript interface.
You can wrap your UI in `HMSRoomProvider` and these hooks will become available to all the UI components. We'll learn more about these hooks,
and their use as we navigate through further sections.

<Tabs id="react" items={['Wrap In Provider', 'Use hooks']} />{' '}

<Tab id='react-0'>

```jsx:app.jsx
import { HMSRoomProvider } from '@100mslive/react-sdk';

export function App() {
  return (
    <HMSRoomProvider>
      <MyApp />
    </HMSRoomProvider>
  );
}

```

</Tab>

<Tab  id='react-1'>

```jsx:component.jsx
import {
  useHMSStore,
  useHMSActions,
  useHMSNotifications
} from '@100mslive/react-sdk';

export function MyComponent() {
  const hmsStore = useHMSStore();
  const hmsActions = useHMSActions();
  const hmsNotifications = useHMSNotifications();

  return </>;
}
```

</Tab>

## Debugging

Do checkout our debugging page [here](../debugging/debugging) for an easy debugging experience while integrating our sdk.


Integrating The SDK


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

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

1. User Name - the name which should be displayed to other peers in the room.
2. [Authentication Token](../guides/token) - the client side authentication token generated by the Token Service.

You can also optionally pass these fields -

1. settings: {isAudioMuted, isVideoMuted} - you can use this to set the initial audio/video state at time of join.
2. User metadata - this can be used to pass any additional metadata associated with the user.

We'll call the `join` method on `hmsActions` object with a config containing above fields to join the room.

<Tabs id="join" items={['JavaScript', 'React']} />{' '}

<Tab id='join-0'>

```js:join.js
import { hmsActions } from './hms';

const config = {
    userName: 'Jon Snow',
    authToken: '<Auth token>', // client-side token generated from your token service
    settings: {
        isAudioMuted: true,
        isVideoMuted: false
    },
    metaData: JSON.stringify({city: 'Winterfell', knowledge: 'nothing'}),
    rememberDeviceSelection: true,  // remember manual device change
};

hmsActions.join(config);

```

</Tab>

<Tab  id='join-1'>

```jsx:join.jsx
import { useHMSActions } from '@100mslive/react-sdk';

function Join() {
  const hmsActions = useHMSActions();

  const config = {
    userName: 'Jon Snow',
    authToken: '<Auth token>', // client-side token generated from your token service
    settings: {
        isAudioMuted: true,
        isVideoMuted: false,
    },
    metaData: JSON.stringify({city: 'Winterfell', knowledge: 'nothing'}),
    rememberDeviceSelection: true,  // remember manual device change
  };

  function onJoinClick() {
    hmsActions.join(config)
  }

  return <
        // form with input and join button
  />;
}
```

</Tab>

That's it. You have joined a room successfully 🥳. You should now be able to have an audio only call with this.

## Getting Current Room State

You might want to hide your join form from the UI or navigate to another page when the join has completed.
We provide [some selectors](/api-reference/javascript/v2/home/content#functions) which operate upon the room state to give the relevant information. One such
selector is [`selectIsConnectedToRoom`](/api-reference/javascript/v2/home/content#select-is-connected-to-room). Here's how to use it -

<Tabs id="connected" items={['JavaScript', 'React']} />{' '}

<Tab id='connected-0'>

```js
import { hmsStore } from './hms';
import { selectIsConnectedToRoom } from '@100mslive/hms-video-store';

// use getState to get the state at any time
console.log('isConnected - ', hmsStore.getState(selectIsConnectedToRoom));

function onRoomStateChange(connected) {
    console.log('isConnected - ', connected);
}

// you can also subscribe to the state and get your function called whenever the state changes
hmsStore.subscribe(onRoomStateChange, selectIsConnectedToRoom);
```

</Tab>

<Tab  id='connected-1'>

```jsx
import { useHMSStore, selectIsConnectedToRoom } from '@100mslive/react-sdk';

// if the connection state changes, the store hook will take care of rerendering the component
function ConnectionState() {
    const isConnected = useHMSStore(selectIsConnectedToRoom);

    return <div>{isConnected ? 'connected' : 'not connected, please join.'}</div>;
}
```

</Tab>

> For more granular
> room states, use [`selectRoomState`](/api-reference/javascript/v2/home/content#select-room-state).


Join Room


Leaving a room should be quick. Once a user wishes to end their interaction in the room, they can choose to leave the meeting. 👋

We provide a simple, no fuss API to do exactly that. Invoke the leave method using `hmsActions`. You can use the current
[room state](./join#getting-current-room-state) to render the UI accordingly post leave.

```jsx
hmsActions.leave()
```

## Leave on Navigating Away

If the user closes the tab without calling leave you might seem them as stuck for a few seconds for remote peers. This is
because our server assumes that there might be a network issue and keeps a buffer waiting for the peer to rejoin. For this
reason, it is important to call the leave api if we detect the user navigating away from the page. This includes, refreshing
or closing the tab. We can set up leave to be called on window unload event.

```js
window.addEventListener('beforeunload', () => hmsActions.leave());
window.addEventListener('onunload', () => hmsActions.leave());
```


Leave Room


It all comes down to this. All the setup so far has been done so that we can show live streaming video in our beautiful apps.

1. First, you need to get all the peers in the room. You can use the `selectPeers` selector for this.

2. Next, you'll need to have a reference to a video element. You must add the attributes as present below.

```html
<video autoplay muted playsinline />
```

3. You can then iterate over all the peers, and call the `attachVideo` function in hmsActions to render the video.

<Tabs id="render" items={['JavaScript', 'React']} />{' '}

<Tab id='render-0'>

```js
import { hmsActions } from './hms';

const peersContainer = document.getElementById('peers-container');

function renderVideo(peer) {
    // you can either get an existing video element or create a new onw.
    // const videoElement = document.getElementByID(peer.id)
    const videoElement = document.createElement('video');
    videoElement.autoplay = true;
    videoElement.muted = true;
    videoElement.playsinline = true;

    hmsActions.attachVideo(peer.videoTrack, videoElement);
}

function renderPeers(peers) {
    peersContainer = document.getElementById('peers-container');
    peersContainer.innerHTML = '';

    peers.forEach((peer) => {
        console.log(
            `rendering video for peer - ${peer.name}, roleName - ${peer.roleName}, isLocal- ${peer.isLocal}`
        );
        peersContainer.append(renderVideo(peer));
    });
}

// subscribe to the peers, so render is called whenever there is a change like peer join and leave
hmsStore.subscribe(renderPeers, selectPeers);
```

</Tab>

<Tab  id='render-1'>

```jsx
import { useRef, useEffect } from 'react';
import {
    useHMSStore,
    useHMSActions,
    selectPeers,
    selectCameraStreamByPeerID
} from '@100mslive/react-sdk';

function VideoTile({ peer }) {
    const videoRef = useRef(null);
    const hmsActions = useHMSActions();
    // get the camera track to render
    const videoTrack = useHMSStore(selectCameraStreamByPeerID(peer.id));
    useEffect(() => {
        if (videoRef.current && videoTrack) {
            if (videoTrack.enabled) {
                hmsActions.attachVideo(videoTrack.id, videoRef.current);
            } else {
                hmsActions.detachVideo(videoTrack.id, videoRef.current);
            }
        }
    }, [videoTrack, hmsActions]);

    return <video ref={videoRef} autoPlay muted playsInline></video>;
}

function Conference() {
    const peers = useHMSStore(selectPeers);

    return (
        <>
            {peers.map((peer) => (
                <VideoTile key={peer.id} peer={peer} />
            ))}
        </>
    );
}
```

</Tab>

The videos will now be rendered & start playing on your screen. 🥳

> In case you want to render local peer and remote peers separately, you can use the selectors - `selectLocalPeer` and `selectRemotePeers`.

## Detach video to conserve bandwidth and cleanup elements

You can call `detachVideo` on the `hmsActions` to unsubscribe a track and not fetch it's data. This can be done
for example when a video goes out of view. This should also be called when the component is going to be unmounted
for proper cleanups of the video elements.

```js
hmsActions.detachVideo(videoTrack.id, videoElement);
```


Render Video


Mute is something that applies to both audio and video. When you mute audio, you can't be heard by other people. When you mute video, you will not be broadcasting your video to other people.

```js
await hmsActions.setLocalVideoEnabled(false);
await hmsActions.setLocalAudioEnabled(true);
```

## Toggling current mute state

1. Get current state
2. Invert the state and set as new value

<Tabs id="mute" items={['JavaScript', 'React']} />

<Tab id='mute-0'>

```js
async function toggleAudio() {
    const enabled = hmsStore.getState(selectIsLocalAudioEnabled);
    await hmsActions.setLocalAudioEnabled(!enabled);
}

async function toggleVideo() {
    const enabled = hmsStore.getState(selectIsLocalVideoEnabled);
    await hmsActions.setLocalVideoEnabled(!enabled);
}
```

</Tab>

<Tab id='mute-1'>

```jsx
function MyComponent() {
  const audioEnabled = useHMSStore(selectIsLocalAudioEnabled);
  const videoEnabled = useHMSStore(selectIsLocalVideoEnabled);
  const hmsActions = useHMSActions();

  async function toggleAudio() {
    await hmsActions.setLocalAudioEnabled(!audioEnabled);
  }

  async function toggleVideo() {
    await hmsActions.setLocalVideoEnabled(!videoEnabled);
  }

  return <
        // toggle buttons for user
  />;
}
```

</Tab>


Mute / Unmute


What's a video call without being able to send messages to each other too? 100ms supports chat for every video/audio room you create.

![Chat](/guides/chat.png)

## Sending Chat Messages

### Broadcast Message:

This will be received by everyone in the room.

```js
hmsActions.sendBroadcastMessage('hello everyone!'); // yes it's that simple 😉
```

### Group Message:

This will be received by every peer who is part of the passed-in roles.

```js
hmsActions.sendGroupMessage('hi folks!', ['moderator', 'host']);
```

### Direct Message:

This will only be received by the peer to whom the message was sent to.

```js
hmsActions.sendDirectMessage('keep this message a secret!', peer.id);
```

## Showing the messages

The selector `selectHMSMessages` can be used to get all the messages. There are few other selectors to help with selecting
more specific messages.

<Tabs id="chat" items={['JavaScript', 'React']} />

<Tab id='chat-0'>

```js
import {
    selectHMSMessages,
    selectBroadcastMessages,
    selectMessagesByRole,
    selectMessagesByPeerID
} from '@100mslive/hms-video-store';

function renderMessages(messages) {
    console.log('messages - ', messages);
}

hmsStore.subscribe(renderMessages, selectHMSMessages); // get all messages
hmsStore.subscribe(renderMessages, selectBroadcastMessages); // get all broadcasted messages
hmsStore.subscribe(renderMessages, selectMessagesByRole('host')); // get conversation with the host role
hmsStore.subscribe(renderMessages, selectMessagesByPeerID(peer.id)); // get private conversation with peer
```

</Tab>

<Tab id='chat-1'>

```jsx
import { Message } from './components';
import {
    selectHMSMessages,
    selectBroadcastMessages,
    selectMessagesByRole,
    selectMessagesByPeerID
} from '@100mslive/react-sdk';

function Chat() {
    // use only the selectors that are required for the corresponding UI
    const allMessages = useHMSStore(selectMessages); // get all messages
    const brodacastMessages = useHMSStore(selectBroadcastMessages); // get all broadcasted messages
    const groupMessagesByRole = useHMSStore(selectMessagesByRole('host')); // get conversation with the host role
    const directMessages = useHMSStore(selectMessagesByPeerID(peer.id)); // get private conversation with peer

    return (
        <>
            {messages.map((msg) => (
                <Message key={msg.id} message={msg} />
            ))}
        </>
    );
}
```

</Tab>

Refer [API Reference for **HMSMessage Interface**](/api-reference/javascript/v2/interfaces/HMSMessage).

## Marking a message as read

We also have a boolean `read` field with every message which can be optionally used to track whether the user
has seen the message. You can set the read status for a message with the following interface.

```js
const readStatus = true; // true/false
hmsActions.setMessageRead(readStatus); // set status for all messages
hmsActions.setMessageRead(readStatus, msg.id); // set status for a specific message
```

## Message Notification

When a peer receives a message they'll get a [notification](./notifications) with type `HMSNotificationTypes.NEW_MESSAGE`.
The `HMSMessage` object will be present in `notification.data`.

## Custom Events

It's also possible to utilise the above system for sending custom messages across the room. All the above methods
take `type` as an optional last param. The `type` is `chat` by default but can be changed to any valid string. This can
be used to differentiate between different types of messages. For e.g.

```js
// broadcast a message to the whole room
hmsActions.sendBroadcastMessage('START', 'GAME_EVENT');
hmsActions.sendBroadcastMessage('🚀', 'EMOJI_REACTION');

// Send a message to role groups
hmsActions.sendGroupMessage('🔥', ['stage', 'backstage'], 'EMOJI_REACTION');

// Send a message to a specific peer
hmsActions.sendDirectMessage('❤️', peer.id, 'EMOJI_REACTION');
hmsActions.sendDirectMessage('STOP_SCREENSHARE', peer.id, 'MODERATOR_EVENT');
```

Suppose you have a custom event for sending "EMOJI_REACTION" and you don't want these messages to be stored in the store. In such cases `ignoreMessageTypes` action methods comes in handy. Notifications for the ignored messages will still be sent, it'll only not be put in the store.

```js
hmsActions.ignoreMessageTypes(['EMOJI_REACTION']);
```

Do note that the messages are not persistent and won't be available to a person joining the room after the event
was sent. So even though the above is good for emoji reactions,
if you're looking for implementing something like raise hand do check out our documentation for [peer metadata](../advanced-features/peer-metadata).

> In case you want to send information in a more structured way than a simple string, you can send a stringified JSON object.

## useCustomEvent

This is a react hook that eases firing & listening to custom events. It takes in a config of `type` which is the type of your event and `onEvent` a handler function that is fired when an event comes.

It returns an object containing `sendEvent` which helps to send the event data to others in the room who will receive it in the `onEvent` handler.

Let's understand the hook with an example where we're showing a button on UI to send emoji reactions.

```jsx
import { useCustomEvent, useHMSActions } from '@100mslive/react-sdk';
import { useCallback } from 'react';

const Confetti = () => {
    const actions = useHMSActions();

    // onEvent should use useCallback
    const onEvent = useCallback((msg) => {
        console.log(msg); // {emoji: "🚀"}
        // show emoji reactions on UI
    }, []);

    const { sendEvent } = useCustomEvent({
        type: 'EMOJI_REACTION',
        onEvent,
    });

    return <button onClick={() => sendEvent({emoji: "🚀"})}>Rockets</button>;
};

export default Confetti;
```


Chat


Any peer can change their own name before or after joining a room.
Before joining, the name would have to be specified in `HMSConfig` that is passed to the join method.
After joining, name can be changed with this call to hmsActions -

```
await hmsActions.changeName(newName);
```

The store will update on the remote side, and as a result corresponding UI will also be updated automatically.
A notification of type `HMSNotificationTypes.NAME_UPDATED` will also be sent in case a toast needs to be presented.


Change User Name


Device changes include changes in audio/video input and audio output devices. Plugging a headset, or disconnecting your airpods mid call are
some of the example of device changes. These are all taken care of by the SDK without requiring any code.

## Manual Device Change

![Device Change Settings](/guides/settings.png)

You may still want to allow users to see the currently selected devices and change them if required. We'll do this in three steps -

1. Fetching all attached devices list from `hmsStore`.
2. Fetching the currently selected devices from `hmsStore`.
3. Calling `hmsActions` to change the device if required.

> Note that changing audio output device is available only in chromium based browsers.

```js
// {audioInput, audioOutput, videoInput}
const devices = hmsStore.getState(selectDevices);

// {audioInputDeviceId, audioOutputDeviceId, videoInputDeviceId}
const selected = hmsStore.getState(selectLocalMediaSettings);

// show user a settings component to manually choose device
// The following selected devices can be obtained when changed from your UI.

// Update AudioInput device by calling
hmsActions.setAudioSettings({ deviceId: selectedAudioDeviceID });
// Update VideoInput device by calling
hmsActions.setVideoSettings({ deviceId: selecedVideoDeviceID });
// Update AudioOutput device by calling
hmsActions.setAudioOutputDevice(selectedAudioOutputDeviceID);
```

## Remember manually selected devices

We support an additional boolean in join config which can be passed in to let sdk use the localstorage to remember
manual device selections for future room [join](./join).

```js
hmsActions.join({ ...joinConfig, rememberDeviceSelection: true });
```


Device Changes


Preview screen is a frequently used UX element which allows users to check if their input devices are working properly and
set the initial state (mute/unmute) of their audio and video tracks before joining.
100ms SDKs provide an easy-to-use API to back this feature.
Additionally, the SDK will try to establish a connection to 100ms server to verify there are no network issues and that the
auth credentials are valid so that if everything is in order the subsequent room join is instant.

To invoke this API call

```js
const config = {
    userName: 'Jon Snow',
    authToken: '<Auth token>', // client-side token generated from your token service
    settings: { // initial states
        isAudioMuted: true,
        isVideoMuted: false
    },
    metaData: JSON.stringify({city: 'Winterfell', knowledge: 'nothing'}),
    rememberDeviceSelection: true,  // remember manual device change
    captureNetworkQualityInPreview: false, // whether to measure network score in preview
};
await hmsActions.preview(config);
```

You would need the same config object that you would pass to [join API](./join). The interface to render video, mute/unmute etc. remains the same.

> Note that if you use preview, there is no need of maintaining any state on your side for settings(device id, audio, video on). Selections
> during preview will be moved across to the join call.

## Post Preview call

Once you have made the preview call, these things will happen -

-   SDK will connect with the 100ms backend to ensure that the token is correct and fetch the permissions for the role.
-   Network speed will be measured and a connection score will be notified to the UI if [turned on](../advanced-features/connection-quality).
-   One peer for the local peer will be added to the store, accessible via `selectLocalPeer` selector.
-   Permission prompt will be given to the user for camera/mic if permissions are not there
-   Audio, Video tracks will be created as per the role permissions.
-   The video can be rendered [similarly as post join](./render-video).
-   [Audio Level](../advanced-features/audio-level) will start reflecting for the microphone, this can be used to verify that
    the microphone is working properly.
-   User will be able to see and modify input/output [devices](./device-change).

## When you do join

When join is done after the preview call, changes done by the user during preview such as changing device or muting their
tracks will be carry forwarded when user enters the room.

## Limitations

-   You can't preview and join with two different roles, in case you do need to do this, you can call leave and wait on the promise
    to resolve before calling join.

## Know Others in the room

It's also possible to know about the room state and other peers in the room, if the permission to receive room state is given for the 
role in dashboard. The peers present in the room can be known by using the `selectPeers` selector as given [here](../guides/useful-selectors#who-all-are-in-my-room).

## Network Quality in preview

Follow [this section](../advanced-features/connection-quality#connection-quality-score-in-preview) to get a sense of user's network quality in preview.


Preview


![Join Notification](/guides/notification-join.png)

![Poor Connection Notification](/guides/notification-internet.png)

Notifications can be used to display toast to user about activities happening in the room, such as peer join/leave or new messages.
It can also be used to know about any mid call sdk level error.

In order to subscribe for notifications we can use the hmsNotifications object created in the integration step.

<Tabs id="notification-initialize" items={['JavaScript', 'React']} />

<Tab id="notification-initialize-0">

```jsx
import { hmsNotifications } from './hms';

hmsNotifications.onNotification((notification) => {
    // This function will be called when a notification is received
    console.log('notification type', notification.type);

    // The data in notification depends on the notification type
    console.log('data', notification.data);
});
```

</Tab>

<Tab id="notification-initialize-1">

```jsx
import { useHMSNotifications } from '@100mslive/react-sdk';

function Notification() {
    const notification = useHMSNotifications();

    useEffect(() => {
        if (!notification) {
            return;
        }

        // notification is a reactive object
        // this function will run everytime there is a new notification
        console.log('notification type', notification.type);

        // The data in notification depends on the notification type
        console.log('data', notification.data);
    }, [notification]);

    return <div>Notification: {notification?.type}</div>;
}
```

</Tab>

## Notification types

The notification `type` is a string and can only take values from the [list here](/api-reference/javascript/v2/enums/HMSNotificationTypes).
You can use it to check the type of the notification.

The data in notification depends on the notification type. You can use the `switch` construct to the handle the notification type.

<Tabs id="notification-types" items={['JavaScript', 'React']} />

<Tab id="notification-types-0">

```jsx{14-44}
import { hmsNotifications } from './hms';

const unsubscribe = hmsNotifications.onNotification((notification) => {
    console.log('notification type', notification.type);
    console.log('data', notification.data);

    // you can use the following to show appropriate toast notifications for eg.
    switch (notification.type) {
        case HMSNotificationTypes.PEER_LIST:
            console.log(`${notification.data} are the peers in the room`); // received right after join
            break;
        case HMSNotificationTypes.PEER_JOINED:
            console.log(`${notification.data.name} joined`);
            break;
        case HMSNotificationTypes.PEER_LEFT:
            console.log(`${notification.data.name} left`);
            break;
        case HMSNotificationTypes.NEW_MESSAGE:
            console.log(
                `${notification.data.message} received from ${notification.data.senderName}`
            );
            break;
        case HMSNotificationTypes.ERROR:
            console.log('[Error]', notification.data);
            console.log('[Error Code]', notfication.data.code);
            break;
        case HMSNotificationTypes.RECONNECTING:
            console.log('[Reconnecting]', notification.data);
            break;
        case HMSNotificationTypes.RECONNECTED:
            console.log('[Reconnected]');
            break;
        case HMSNotificationTypes.NAME_UPDATED:
        case HMSNotificationTypes.METADATA_UPDATED:
        case HMSNotificationTypes.ROLE_UPDATED:
            console.log(`peer updated(${notification.type}), new peer=`, notification.data);
            break;
        case HMSNotificationTypes.TRACK_DEGRADED:
            console.log(`track - ${notification.data} degraded due to poor network`);
            break;
        case HMSNotificationTypes.TRACK_RESTORED:
            console.log(`track - ${notification.data} recovered`);
            break;
        case HMSNotificationTypes.ROOM_ENDED:
            console.log(`room ended, reason - ${notification.data.reason}`);
            break;
        case HMSNotificationTypes.REMOVED_FROM_ROOM:
            console.log(`removed from room, reason - ${notification.data.reason}`);
            break;
        case HMSNotificationTypes.DEVICE_CHANGE_UPDATE:
            console.log(`device changed - ${notification.data}`);
            break;
        default:
            break;
    }
});
```

</Tab>

<Tab id="notification-types-1">

```jsx{14-44}
import { useHMSNotifications } from '@100mslive/react-sdk';

function Notification() {
    const notification = useHMSNotifications();

    React.useEffect(() => {
        if (!notification) {
            return;
        }

        console.log('notification type', notification.type);
        console.log('data', notification.data);

        // you can use the following to show appropriate toast notifications for eg.
        switch (notification.type) {
            case HMSNotificationTypes.PEER_JOINED:
                console.log(`${notification.data.name} joined`);
                break;
            case HMSNotificationTypes.PEER_LEFT:
                console.log(`${notification.data.name} left`);
                break;
            case HMSNotificationTypes.NEW_MESSAGE:
                console.log(
                    `${notification.data.message} received from ${notification.data.senderName}`
                );
                break;
            case HMSNotificationTypes.ERROR:
                console.log('[Error]', notification.data);
                console.log('[Error Code]', notfication.data.code);
                break;
            case HMSNotificationTypes.RECONNECTING:
                console.log('[Reconnecting]', notification.data);
                break;
            case HMSNotificationTypes.RECONNECTED:
                console.log('[Reconnected]');
                break;
            case HMSNotificationTypes.NAME_UPDATED:
            case HMSNotificationTypes.METADATA_UPDATED:
            case HMSNotificationTypes.ROLE_UPDATED:
                console.log(`peer updated(${notification.type}), new peer=`, notification.data);
                break;
            case HMSNotificationTypes.TRACK_DEGRADED:
                console.log(`track - ${notification.data} degraded due to poor network`);
                break;
            case HMSNotificationTypes.TRACK_RESTORED:
                console.log(`track - ${notification.data} recovered`);
                break;
            case HMSNotificationTypes.ROOM_ENDED:
                console.log(`room ended, reason - ${notification.data.reason}`);
                break;
            case HMSNotificationTypes.REMOVED_FROM_ROOM:
                console.log(`removed from room, reason - ${notification.data.reason}`);
                break;
            case HMSNotificationTypes.DEVICE_CHANGE_UPDATE:
                console.log(`device changed - ${notification.data}`);
                break;
            default:
                break;
        }
    }, [notification]);

    return <div>Notification: {notification?.type}</div>;
}
```

</Tab>

## Listening to specific notifications

You can pass a single notification or array of notifications from one of `HMSNotificationTypes`.

<Tabs id="notification-types" items={['JavaScript', 'React']} />

<Tab id="notification-types-0">

```jsx{14-44}
import { hmsNotifications } from './hms';

const unsubscribe = hmsNotifications.onNotification((notification) => {
    console.log('notification type', notification.type);
    console.log('data', notification.data);
}, HMSNotificationTypes.PEER_JOINED);

const unsubscribePeerNotifications = hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }
    // this will be called when one of HMSNotificationTypes.PEER_JOINED, HMSNotificationTypes.PEER_LEFT is arrived
    console.log('notification type', notification.type);
    console.log('data', notification.data);
}, [HMSNotificationTypes.PEER_JOINED, HMSNotificationTypes.PEER_LEFT]);
```

</Tab>

<Tab id="notification-types-1">

```jsx{14-44}
import { useHMSNotifications } from '@100mslive/react-sdk';

function Notification() {
    const notification = useHMSNotifications(HMSNotificationTypes.PEER_JOINED);
    const peerNotification = useHMSNotifications([HMSNotificationTypes.PEER_JOINED, HMSNotificationTypes.PEER_LEFT]);

    React.useEffect(() => {
        if (!notification) {
            return;
        }

        console.log('notification type', notification.type);
        console.log('data', notification.data);

    }, [notification]);

    React.useEffect(() => {
        if (!peerNotification) {
            return;
        }
        console.log('notification type', notification.type);
        console.log('data', notification.data);
    }, [peerNotification]);

    return <div>Notification: {notification?.type}</div>;
}
```

</Tab>

## Unsubscribing from notifications

You can unsubscribe to the notifications by calling the method returned by the `hmsNotifications.onNotification` function.

<Tabs id="notification-unsubscribe" items={['JavaScript', 'React']} />

<Tab id="notification-unsubscribe-0">

```jsx
const unsubscribe = hmsNotifications.onNotification((notification) => {
    //...
});

unsubscribe();
```

</Tab>

<Tab id="notification-unsubscribe-1">

```jsx
// No code is required to unsubscribe from notifications
// Unmount the component that calls the `useHMSNotifications` hook
```

</Tab>

## Ideas

You can create notifications with buttons in them, to make it easier for the end user to respond to those notifications.
For e.g. -

![Screenshare Notification](/guides/notification-screen.png)


Notifications


## Create Account

Create an account at [Dashboard of 100ms](https://dashboard.100ms.live/)

<Image src="/guides/token/create-account.png" width={2880} height={1584} />

After you have created your account you have to Confirm your Email , check the promotions tab in your Mail Box if you can't find it.

Then login again and you would see this Section. Fill it out

## Build your app

### Choose a subdomain
<Image src="/guides/token/build-app.png" width={2872} height={1580} />

### Choose a template
Choose a template for your app

<Image src="/guides/token/template.png" width={2880} height={1580} />

Once you have chosen the template, click on `Set up App`

## Join the room
After your app is ready a default room will be created. You can join the room with one of the role present in the template

<Image src="/guides/token/go-to-dashboard.png" width={1920} height={1055} />


Quickstart


Joining a room is one of the most basic functionalities so we at 100ms have built an easy, developer friendly API to get you started.

A user can interact with participants of a room only after joining the room.

## Setting up the HMS Instance

First, create an instance of HMSManager class. Store this instance as a property. We'll have to call build method, that method returns an instance of HMSManager class and the same is used to perform all the operations. Ensure that the SDK object is alive in memory so that you can receive event callbacks from SDK. Simplest way to do this is as follows -

```js
import HmsManager from '@100mslive/react-native-hms';

const hmsInstance = await HmsManager.build();
```

## Check Permissions

Now you can proceed to request Camera and Audio permissions if already not given.

```js
// android
import { PERMISSIONS, RESULTS, requestMultiple } from 'react-native-permissions';

requestMultiple([PERMISSIONS.ANDROID.CAMERA, PERMISSIONS.ANDROID.RECORD_AUDIO]).then((results) => {
    if (
        results['android.permission.CAMERA'] === RESULTS.GRANTED &&
        results['android.permission.RECORD_AUDIO'] === RESULTS.GRANTED
    ) {
        joinRoom();
    }
});

// ios
joinRoom();
```

## Add event listeners

Add event listeners for all the events such as onPreview, onJoin, onError etc. The actions can be found in HMSUpdateListenerActions class. The event handlers are the way of handling any update happening in hms.

```js
import HmsManager, { HMSUpdateListenerActions } from 'react-native-hms';

// instance acquired from build() method
hmsInstance.addEventListener(
    HMSUpdateListenerActions.ON_PREVIEW,
    onPreview // function that will be called on Preview success
);

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoin);
```

## Join the room

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

1. User Name, the name which should be displayed to other peers in the room
2. User ID, a unique identifier for the user. Usually a UUID string.
3. Room ID, the unique room identifier which would have been generated & passed to your app from the backend.
4. Role, defines the set of permissions for a particular user (optional parameter).
5. Authentication Token, the client side authentication token generated by your Token Service. You can read about how to generate this token [here](https://docs.100ms.live/react-native/v2/guides/token).

Joining the room connects you to the remote peer and broadcasts your stream to other peers, we need instance of HMSConfig in order to pass the details of room and user to join function

```js
import HmsManager, { HMSUpdateListenerActions, HMSConfig } from '@100mslive/react-native-hms';

// instance acquired from build() method
const HmsConfig = new HMSConfig({ authToken, userName });

hmsInstance.preview(HmsConfig); // to start preview
// or
hmsInstance.join(HmsConfig); // to join a room
```

Don't forget to add listeners before calling join or preview to receive an event callback which indicates if a call was a success or a failure.

That's it. You have joined a room successfully. 🥳

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

✅ If successful, the `HMSUpdateListenerActions.ON_JOIN` callback of HMSUpdateListener will be invoked with information about the room encapsulated in the HMSRoom object.

❌ If failure, the `HMSUpdateListenerActions.ON_ERROR` callback will be invoked with exact failure reason.

## Joining room audio/video muted

If you want to join the room with preview, call setMute on localPeer's audio and video tracks in the onPreview event listener
which is called after the preview is successful. 

```js
const onPreview = () => {
    // instance acquired from build() method
    hmsInstance?.localPeer?.localVideoTrack()?.setMute(true);
    hmsInstance?.localPeer?.localAudioTrack()?.setMute(true);
}
``` 

If you want to join the room directly without preview, call setMute on localPeer's audio and video tracks in the onJoin event listener
which is called after the join is successful.

```js
const onJoin = () => {
    // instance acquired from build() method
    hmsInstance?.localPeer?.localVideoTrack()?.setMute(true);
    hmsInstance?.localPeer?.localAudioTrack()?.setMute(true);
}
``` 

## Get Room

`getRoom` is an async function on HMSSDK which returns the currently joined room. Returns null if the peer is not in a room.

```js
// instance acquired from build() method
await hmsInstance.getRoom(); 
```



When you make an API call to access an HMS SDK, the SDK may return error codes.
ErrorCodes are usually returned when a problem that cannot be recovered without app intervention has occurred.

These are returned as `type='error'` through the [notifications interface](/javascript/v2/features/notifications). The type of `notification.data` is `HMSException`. Find the [HMSException interface here](/api-reference/javascript/v2/interfaces/HMSException).

## Handling Autoplay Error

![Device Change Settings](/guides/autoplay-error.png)

Most browsers have a restriction on audio autoplay where audio is allowed only if the user has interacted with the page. You can read
more about the restrictions here for [chrome](https://developer.chrome.com/blog/autoplay/) and [safari](https://webkit.org/blog/7734/auto-play-policy-changes-for-macos/).

If an autoplay error is received(code=3008), UI can show a popup or a notification with button. Once a user click has happened confirming an interaction point,
unblockAudio can be called.

```js
await hmsActions.unblockAudio();
```

## Error Codes

Following are the different error codes that are returned by the SDK. Before returning any error code, SDK retries the errors wherever possible.

| **Error Code** | **Cause of the error**                                                             | **Action to be taken**                                                                                      |
| :------------- | :--------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| **1000**       | Failed to connect to Websocket - Happens to due network issues or firewall blocking Websocket connections                             | Mention user to check their network connection and firewall/anti-virus/VPN or try again after some time.                                |
| **1003**       | Websocket disconnected - Happens due to network issues                             | Mention user to check their network connection or try again after some time.                                |
| **2002**       | Invalid Endpoint URL                                                               | Check the endpoint provided while calling `join` on `HMSSDK`.                                               |
| **2003**       | Endpoint is not reachable                                                          | Mention user to check their network connection or try again after some time.                                |
| **2004**       | Token is not in proper JWT format                                                  | The token passed while calling `join` is not in correct format. Retry getting a new token.                  |
| **3001**       | User denied permission to access capture device at browser level                                                         | Ask user to check permission granted to audio/video capture devices in browser(in address bar).                                        |
| **3002**       | Capture Device is not Available                                                    | Ask user to check if the audio/video capture device is connected or not.                                    |
| **3003**       | Capture device is in use by some other application                                 | Show notification to user mentioning that the capturing device is used by some other application currently. |
| **3008**       | Browser has throw an autoplay exception                                            | Show notification to user mentioning that the browser blocked autoplay                                      |
| **3009**       | Device unable to satisfy requested media constraints                               | Reduce media constraints for the role in dashboard or upgrade device hardware.                              |
| **3011**       | System denied permission to access capture device                               | Ask user to check permission granted to audio/video/screen capture devices in system settings.                              |
| **4001**       | WebRTC error                                                                       | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4002**       | WebRTC error                                                                       | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4003**       | WebRTC error                                                                       | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4004**       | WebRTC error                                                                       | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4005**       | ICE Connection Failed due to network issue                                         | Mention user to check their network connection or try again after some time.                                |
| **5001**       | Trying to join a room which is already joined                                      | Trying to join an already joined room.                                                                      |
| **6000**       | Calling actions when not connected/joined to a room                                | Call the required action after joining a room.                                                              |
| **6002**       | webRTC Error: Error while renegotiating                                            | Please try again.                                                                                           |
| **6003**       | Trying to join a room when preview is in progress                                  | Call join action only when room state is "Preview" and not "Connecting".                                    |
| **6008**       | Invalid arguments(peer ID, track ID, or others) passed to actions                  | Check if the corresponding arguments are valid by checking the store when calling the action                |
| **6009**       | Trying to join a room when preview is in progress                                  | Call join action only when room state is "Preview" and not "Connecting".                                    |
| **6010**       | navigator.mediaDevices is undefined in insecure contexts served over HTTP protocol | Deploy the app in a secure context with HTTPS protocol.                                                     |
| **6011**       | RTCPeerConnection is undefined in browser                                          | Switch/Upgrade browser to WebRTC compatible version/check for browser extenstion blocking WebRTC.           |
| **40101**      | Token Error: Invalid Access Key                                                    | Access Key provided in the token is wrong.                                                                  |
| **40102**      | Token Error: Invalid Room Id                                                       | RoomID provided in the token is wrong.                                                                      |
| **40103**      | Token Error: Invalid Auth Id                                                       | AuthID provided in the token is wrong.                                                                      |
| **40104**      | Token Error: Invalid App Id                                                        | App ID provided in the token is wrong.                                                                      |
| **40105**      | Token Error: Invalid Customer Id                                                   | Customer Id provided in the token is wrong.                                                                 |
| **40107**      | Token Error: Invalid User Id                                                       | User ID provided in the token is wrong.                                                                     |
| **40108**      | Token Error: Invalid Role                                                          | The role provided in the token is wrong.                                                                    |
| **40109**      | Token Error: Bad JWT Token                                                         | Bad JWT Token.                                                                                              |
| **40100**      | Generic Error                                                                      | Need to debug further with logs.                                                                            |
| **40001**      | Invalid Room                                                                       | Room ID provided while fetching the token is an invalid room.                                               |
| **40002**      | Room Mismatched with Token                                                         | Room ID provided while fetching the token does not match.                                                   |
| **40004**      | Peer already joined                                                                | Peer who is trying to join has already joined the room.                                                     |
| **41001**      | Peer is gone                                                                       | The peer is no more present in the room.                                                                    |
| **7001**       | Platform Not Supported                                                             | The platform is not supported for plugin                                                                    |
| **7002**       | Plugin Init Failed                                                                 | Plugin initialization has failed                                                                            |
| **7003**       | Plugin Processing Failed                                                           | Plugin processing failed                                                                                    |
| **7004**       | Plugin Add Already Going on                                                        | Plugin add is already in progress                                                                           |
| **8001**       | Playlist: Invalid action call                                                      | Check current playing entry, next entry, previous entry when calling seek/seekTo, playNext, playPrevious.   |


Error Handling



HMSSDK is distributed via [Cocoapods](https://cocoapods.org/) and Swift Package Manager. 

## Swift Package Manager
Use https://github.com/100mslive/100ms-ios-sdk.git as the package source.

## Cocoapods
Add the `pod 'HMSSDK'` to your Podfile as follows:
  
  ```
  // Podfile
  
  platform :ios, '12.0'

  target 'MyAwesomeApp' do
    pod 'HMSSDK'
  end
  ```

then run `pod install --repo-update`

Add the entitlements for video, audio and network access to your `Info.plist`

```xml
<key>NSCameraUsageDescription</key>
<string>Allow access to camera to enable video calling.</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Allow access to local network to enable video calling.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Allow access to mic to enable video calling.</string>
```



Joining a room is one of the most basic functionalities so we at 100ms have built an easy, developer friendly API to get you started.

A user can interact with participants of a room only after joining the room.

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

1. User Name: the name which should be displayed to other peers in the room
2. User ID: a unique identifier for the user (Usually a UUID string).
3. Room ID: the unique room identifier which would have been generated & passed to your app from the backend.
4. Authentication Token: the client side authentication token generated by your Token Service.


Now that you have aforementioned data, you can proceed to join a room.

1. First, generate an auth token using any http request package 
   available on [pub.dev](https://pub.dev/) we are using [http](https://pub.dev/packages/http) package.

   ```dart
   Future<String> getToken({required String user, required String room}) async {
        http.Response response = await http.post(Uri.parse  (Constant.getTokenURL),
            body: {'room_id': room, 'user_id': user, 'role': Constant.defaultRole});

        var body = json.decode(response.body);
        return body['token'];
    }
   ```
    you need to do POST request at the endpoint generated which is present in your dashboard.
    You need three parameters to make POST request.

    `room_id`: room id. `user_id`: name you want. 
    `role`: role you want.


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

   ```dart
   HMSConfig config = HMSConfig(authToken: token,
                                userName: user);
   ```

3. You'll want to handle the callbacks from joining the room by making your ViewModel, Presenter or whatever you're using to handle business logic implement the HMSUpdateListener interface and overriding the methods.

4. Now, we are primed to join the room. All you have to do is pass the config object to `join` present in `HMSSDK` class.

   Create instance of HMSSDK -
   ```dart 
   HMSSDK hmsSDK = new HMSSDK();
   ```
   
   Build HMSSDK -
   ```dart
   hmsSDK.build();
   ```

   Now join by passing config object created in previous step.
   ```dart 
   hmsSDK.join(config);
   ```

That's it. You have joined a room successfully. 🥳

Now, let's take a look at the listener class you have to implement.
 
```dart

/// 100ms SDK provides callbacks to the client app about any change or update happening in the room after a user has joined by implementing HMSUpdateListener.
/// These updates can be used to render the video on screen or to display other info regarding the room.
abstract class HMSUpdateListener {

  /// This will be called on a successful JOIN of the room by the user
  ///
  /// This is the point where applications can stop showing its loading state
  /// [room]: the room which was joined
  void onJoin({required HMSRoom room});

  /// This is called when there is a change in any property of the Room
  ///
  ///  [room]: the room which was joined
  ///  [update]: the triggered update type. Should be used to perform different UI Actions
  void onRoomUpdate({required HMSRoom room, required HMSRoomUpdate update});

  /// This will be called whenever there is an update on an existing peer
  /// or a new peer got added/existing peer is removed.
  ///
  /// This callback can be used to keep a track of all the peers in the room
  /// [peer]: the peer who joined/left or was updated
  /// [update]: the triggered update type. Should be used to perform different UI Actions
  void onPeerUpdate({required HMSPeer peer, required HMSPeerUpdate update});

  /// This is called when there are updates on an existing track
  /// or a new track got added/existing track is removed
  ///
  /// This callback can be used to render the video on screen whenever a track gets added
  ///  [track]: the track which was added, removed or updated
  ///  [trackUpdate]: the triggered update type
  ///  [peer]: the peer for which track was added, removed or updated
  void onTrackUpdate({required HMSTrack track, required HMSTrackUpdate trackUpdate, required HMSPeer peer});

  /// This will be called when there is an error in the system
  /// and SDK has already retried to fix the error
  /// [error]: the error that occurred
  void onError({required HMSException error});

  /// This is called when there is a new broadcast message from any other peer in the room
  ///
  /// This can be used to implement chat is the room
  /// [message]: the received broadcast message
  void onMessage({required HMSMessage message});

  /// This is called when someone asks for change or role
  ///
  /// for eg. admin can ask a peer to become host from guest.
  /// this triggers this call on peer's app
  void onRoleChangeRequest({required HMSRoleChangeRequest roleChangeRequest});

  /// This is called every 1 second with list of active speakers
  ///
  /// ## A HMSSpeaker object contains -
  ///    - peerId: the peer identifier of HMSPeer who is speaking
  ///    - trackId: the track identifier of HMSTrack which is emitting audio
  ///    - audioLevel: a number within range 1-100 indicating the audio volume
  ///
  /// A peer who is not present in the list indicates that the peer is not speaking
  ///
  /// This can be used to highlight currently speaking peers in the room
  /// [speakers] the list of speakers
  void onUpdateSpeakers({required List<HMSSpeaker> updateSpeakers});

  ///when network or some other error happens it will be called
  void onReconnecting();

  ///when you are back in the room after reconnection
  void onReconnected();

  ///when someone requests for track change of yours be it video or audio this will be triggered
  /// [hmsTrackChangeRequest] request instance consisting of all the required info about track change
  void onChangeTrackStateRequest({required HMSTrackChangeRequest hmsTrackChangeRequest});

  ///when someone kicks you out or when someone ends the room at that time it is triggered
  /// [hmsPeerRemovedFromPeer] it consists info about who removed you and why.
  void onRemovedFromRoom({required HMSPeerRemovedFromPeer hmsPeerRemovedFromPeer});
}

```

HMSUpdateListener: a class conforming to HMSUpdateListener interface.
The methods of HMSUpdateListener are invoked to notify updates happening in the room like a peer joins/leaves, a track got muted/unmutes, etc.

Add this `updateListener` instance to 
```dart
HMSSDK hmsSDK = new HMSSDK();
hmsSDK.build();
hmsSDK.addUpdateListener(updateListener);
```

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

✅ If successful, the `fun onJoin(room: HMSRoom)` method of HMSUpdateListener will be invoked with information about the room encapsulated in the HMSRoom object.

❌ If failure, the `fun onError(error: HMSException)` method will be invoked with exact failure reason.



Screenshare involves sharing either the complete screen, a specific window or, a browser tab.
For a peer to share their screen, their role must have screenshare enabled in the dashboard.

![ScreenshareDashboard](/docs/v2/screenshare-dashboard.png)

To start a screenshare:

```js
try {
    await hmsActions.setScreenShareEnabled(true);
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

## AudioOnly Screenshare

To start audio only screenshare, you can pass a config as second argument.

```js
try {
    await hmsActions.setScreenShareEnabled(true, {
        audioOnly: true
    });
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

## VideoOnly Screenshare

To start video only screenshare, you can pass a config as second argument.

```js
try {
    await hmsActions.setScreenShareEnabled(true, {
        videoOnly: true
    });
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

To stop the screenshare:

```js
hmsActions.setScreenShareEnabled(false);
```

## Useful Selectors

```js
// to know if someone is screensharing
const screenshareOn = hmsStore.getState(selectIsSomeoneScreenSharing);

// to get the HMSPeer object of the peer screensharing, will select  first if multiple screenshares
const presenter = hmsStore.getState(selectPeerScreenSharing);

// to get the HMSPeer object of all the peers screensharing
const presenters = hmsStore.getState(selectPeersScreenSharing);

// a boolean to know if the local peer is the one who is screensharing
const amIScreenSharing = hmsStore.getState(selectIsLocalScreenShared);

// to get the screenshare video track, this can be used to call attachVideo for rendering
const screenshareVideoTrack = hmsStore.getState(selectScreenShareByPeerID(presenter.id));

// Get the peer who is sharing audio only screenshare
const peer = hmsStore.getState(selectPeerSharingAudio);
// Get the audio track of audio Only screenshare
const audioTrack = hmsStore.getState(selectScreenShareAudioByPeerID(peer?.id));
```

Find more [here](/api-reference/javascript/v2/home/content#functions).

## Screenshare with audio:

We also give support of adding screenshare with audio in chromium based browsers. This only applies if checkbox at bottom left
shown below is checked while sharing a browser tab.

![ScreenshareAudio](/docs/v2/screenshare-audio.png)


Screen Share


![Role Change](/guides/role-change.png)

## Introduction

Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. [Learn more about roles here.](../foundation/templates-and-roles)

Every peer is associated with a role. The [`HMSRole`](/api-reference/javascript/v2/interfaces/HMSRole) object can be used to know the following:

1. Check what this role is allowed to publish. i.e can it send video (and at what resolution)? can it send audio? can it share screen? This can be discovered by using `selectIsAllowedToPublish` to display the UI appropriately.
2. Check which other roles can this role subscribe to. This is internally taken care of by the 100ms infra and sdk, and your UI will only get tracks as per allowed subscriptions. `role.subscribeParams` can be used to get details.
3. Check what actions this role can perform. i.e can it change someone else's current role, mute others, end meeting, remove someone from the room. This can be discovered by using the `selectPermissions` selector.

### Example

Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe.
Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the `changeRole` API comes in.

## Know Thy Permissions

The below selectors can be used to know what the local peer is allowed to publish, and the permissions they have. To know about all the
permissions please check [`selectPermissions'`](../../../api-reference/javascript/v2/home/content#select-permissions) api reference.

```js
const role = hmsStore.getState(selectLocalPeerRole);
const permissions = hsmStore.getState(selectPermissions);
console.log("can I end room - ", permissions.endRoom);
console.log("can I end change role - ", permissions.changeRole);
const { video, audio, screen } = hmsStore.getState(selectIsAllowedToPublish);
```

## Change Role API

If the local peer has permissions to change role(`permissions.changeRole`), they can change either their or someone else's role using
the below interface.

```js
hmsActions.changeRole(forPeerId, toRoleName, force);
```

-   `forPeerId`: The peer ID whose role needs to be changed, the peer can be either of local or remote.
-   `toRoleName`: The target role name.
-   `force`(optional): The other peer gets a request by default to accept a role change, by setting force to true, the role can be changed
                        without requesting for approval.

> 💡 A list of all available role names in the current room can be accessed via the `selectAvailableRoleNames` selector. Further the `selectRoleByRoleName`
selector can be used to get the full [HMSRole](/api-reference/javascript/v2/interfaces/HMSRole) object for a role name.

### Handling a Role Change Request

The `force` parameter in `changeRole`, when false, is a polite request: "Would you like to change your role from listener to speaker?" which can be ignored by the other party.
The way it works is the other party will first receive a [request](/api-reference/javascript/v2/interfaces/HMSRoleChangeRequest) which they can accept or reject.


<Tabs id="roleChange" items={['Javascript', 'React']} />{' '}

<Tab id='roleChange-0'>

```js
function handleRoleChangeRequest(request) {
    if (!request) {
        return;
    }
    console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
    // shouldAccept can for example present a pop up to the user for deciding how to act on the request
    const accept = shouldAccept(request);
    if (accept) {
        hmsActions.acceptChangeRole(request);
    } else {
        hmsActions.rejectChangeRole(request);
    }
}

hmsStore.subscribe(handleRoleChangeRequest, selectRoleChangeRequest);
```

</Tab>

<Tab  id='roleChange-1'>

```jsx
function handleRoleChangeRequest(request) {
    const request = useHMSStore(selectRoleChangeRequest);
    const hmsActions = useHMSActions();

    useEffect(() => {
        console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
        // shouldAccept can for example present a pop up to the user for deciding how to act on the request
        const accept = shouldAccept(request);
        if (accept) {
            hmsActions.acceptChangeRole(request);
        } else {
            hmsActions.rejectChangeRole(request);
        }
    }, [request, hmsActions])

    return null;
}
```

</Tab>

If the request is accepted, the `peer.roleName` field in the store will update re rendering a declarative UI as required.

### Forced Role Change

Imagine that the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt.
This is where the `force` parameter comes in. When it is set to `true` the other party will not receive a confirmation `roleChangeRequest`
but instead will straight away receive a new set of updated permissions and stop publishing.

![Listener Role](/guides/role-listener.png)


### Notifications

You'll get a notification of type `ROLE_UPDATED` when role change happens for the local peer. When a peer's role change
happens in a way where the updated role has new publish permissions, the track will be muted by default. So for e.g., if a viewer(no audio/video)
is changed to a host, their tracks will be muted right after the role change. They'll be able to manually unmute post role change though.
If you want this unmuting to happen automatically, you can listen to the notification to call the action.

## Ideas

### Breakout Rooms/Groups

You can have multiple roles which act as breakout rooms subscribing only to peers within the role. A peer can join another breakout room
or group easily using the change role API.

### Waiting Room

You can create a specific role for a waiting room which doesn't subscribe to anyone else. When someone joins waiting room,
hosts get a notification, and they can let the person join by changing their role to attendees.

### Audio Rooms

An audio room can be designed with moderators, speakers and listeners where a moderator can promote a listener to speaker
and vice versa.

### Classroom

Roles can be created for muted-student(not allowed to unmute), student-spotlight(publishes higher quality video),
student-screen(allowed to screenshare), prefect(can mute others) etc. to create an enriching feature rich classroom experience.


Change Role


You're running a room and decide that someone who's currently talking shouldn't be talking, or perhaps you want their video turned off. You're looking for a remote mute/unmute in this case.

## Muting/Unmuting

Use the [selectPermissions](./change-role#know-thy-permissions) selector to check whether the local peer has the
permission to `mute` or `unmute` others and then call one of the APIs below.

1. Muting Single Track

To mute a single track, call [`hmsActions.setRemoteTrackEnabled`](../../../api-reference/javascript/v2/interfaces/HMSActions#set-remote-track-enabled)
with the `trackID` of the track you want to mute/unmute and `enable`(`true` for unmuting, `false` for muting).

```js
try {
    await hmsActions.setRemoteTrackEnabled(peer.audioTrack, true);
} catch (error) {
    // Permission denied or invalid track ID or not connected to room
    console.error(error);
}
```

2. Muting Multiple Tracks

You can use this API to mute mute/unmute multiple peers at the same time either by their roles, track source, track type
or any combination of the above. Note that this API always excludes
the local peer from the operation and applies only to remote peers.

```js
try {
    const options = {
        enabled: false, // false to mute, true to unmute
        roles: ['student', 'parents'], // optional, array of roles to mute, mutes everyone if not passed
        type: 'audio', // optional, audio/video, mutes both if not passed
        source: 'regular' // optional, mutes all sources(regular, screen etc.) if not passed
    };
    await hmsActions.setRemoteTracksEnabled(options);
} catch (error) {
    // Permission denied or invalid track ID or not connected to room
    console.error(error);
}
```

> 🚧 If the local peer doesn't have the required `mute`/`unmute` permission, the actions will throw an [HMSException error](error-handling).

## Handling a mute/unmute request

![Remote Unmute Request](/guides/remote-unmute.png)

Once the peer with adequate permissions calls `setRemoteTrackEnabled`, the local peer will receive a [notification](notifications).
In case of single track mute it will be of type `CHANGE_TRACK_STATE_REQUEST` with a
[HMSChangeTrackStateRequest](../../../api-reference/javascript/v2/interfaces/HMSChangeTrackStateRequest) object as the data.

-   Mute requests are automatically applied to the receiver by the SDK. No action is required.

-   For unmute request, use the information in `notification.data` to show a dialog to the user to ask if they want to accept
    the change and then apply the settings locally. The same as in a regular user [Mute/Unmute](mute).

<Tabs id="remotemutehandle" items={['JavaScript', 'React']} />

<Tab id='remotemutehandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // For Single Track Remote Mute
        case HMSNotificationTypes.CHANGE_TRACK_STATE_REQUEST:
            const { requestedBy, track, enabled } = notification.data;
            // Unmute Request
            if (enabled) {
                // Ask for consent using dialog or any other appropriate UI
                await hmsActions.setEnabledTrack(track.id, enabled);
            } else {
                // Mute Request
                // Show toast to user
            }
            break;
        // For bulk remote mute, notification will contain all the tracks which will be impacted by this request
        case HMSNotificationTypes.CHANGE_MULTI_TRACK_STATE_REQUEST:
            const { requestedBy, tracks, type, source, enabled } = notification.data;
            // Unmute Request
            if (enabled) {
                // Ask for consent using dialog or any other appropriate UI
                tracks.forEach(
                    async (track) => await hmsActions.setEnabledTrack(track.id, enabled)
                );
            } else {
                // Mute Request
                // Show toast to user
            }
            break;
    }
});
```

</Tab>

<Tab id='remotemutehandle-1'>

```jsx
import { useHMSNotifications } from '@100mslive/react-sdk';

function Notification() {
    const notification = useHMSNotifications();

    useEffect(() => {
        if (!notification) {
            return;
        }

        switch (notification.type) {
            // For Single Track Remote Mute
            case HMSNotificationTypes.CHANGE_TRACK_STATE_REQUEST:
                const { requestedBy, track, enabled } = notification.data;
                // Unmute Request
                if (enabled) {
                    // Ask for consent using dialog or any other appropriate UI
                    await hmsActions.setEnabledTrack(track.id, enabled);
                } else {
                    // Mute Request
                    // Show toast to user
                }
                break;
            // For bulk remote mute, notification will contain all the tracks which will be impacted by this request
            case HMSNotificationTypes.CHANGE_MULTI_TRACK_STATE_REQUEST:
                const { requestedBy, tracks, type, source, enabled } = notification.data;
                // Unmute Request
                if (enabled) {
                    // Ask for consent using dialog or any other appropriate UI
                    tracks.forEach(
                        async (track) => await hmsActions.setEnabledTrack(track.id, enabled)
                    );
                } else {
                    // Mute Request
                    // Show toast to user
                }
                break;
        }
    }, [notification]);

    return <div>Notification: {notification?.type}</div>;
}
```

</Tab>


Remote Mute/Unmute


If the local peer has [`removeOthers`](./change-role#know-thy-permissions) permission they can remove a peer using the below api.

```js
try {
    const reason = 'Good Bye';
    await hmsActions.removePeer(peer.id, reason);
} catch (error) {
    // Permission denied or invalid peer ID or not connected to room
    console.error(error);
}
```

> 🚧 If the local peer doesn't have the required `removeOthers` permission, a [HMSException](error-handling) will be thrown.

## Remove Peer Notification

Once the peer with adequate permissions calls `removePeer` for the local peer, the local peer will receive a [notification](notifications) with type `REMOVED_FROM_ROOM` with a [HMSLeaveRoomRequest](../../../api-reference/javascript/v2/interfaces/HMSLeaveRoomRequest) object as the data.

The SDK automatically calls leave and performs necessary clean ups immediately after this notification is sent, clients should show the appropriate UI(show a dialog, redirect to a 'good-bye' page) on receiving this notification.

<Tabs id="removepeerhandle" items={['JavaScript', 'React']} />

<Tab id='removepeerhandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // ...Other notification type cases
        case 'REMOVED_FROM_ROOM':
            // Redirect or Show toast to user
            toast('Reason: ', notification.data.reason);
            break;
    }
});
```

</Tab>

<Tab id='removepeerhandle-1'>

```jsx
import { useHMSNotifications } from '@100mslive/react-sdk';

function Notification() {
    const notification = useHMSNotifications();

    useEffect(() => {
        if (!notification) {
            return;
        }

        switch (notification.type) {
            // ...Other notification type cases
            case 'REMOVED_FROM_ROOM':
                // Redirect or Show toast to user
                toast('Reason: ', notification.data.reason);
                break;
        }
    }, [notification]);

    return <div>Notification: {notification?.type}</div>;
}
```

</Tab>


Remove Peer


![End Room](/guides/end-room.png)

If the local peer has [`endRoom`](./change-role#know-thy-permissions) permission they can end a room using the below api. It's also possible to lock
the room to prevent any future rejoins.

<Tabs id="endroomcall" items={['JavaScript', 'React']} />

<Tab id='endroomcall-0'>

```js
function renderEndRoomButton(permissions) {
    const endRoomButton = document.getElementById('end-room-button');

    if (permissions.endRoom) {
        endRoomButton.addEventListener('click', function () {
            try {
                const lock = false; // set to true to disallow rejoins
                const reason = 'party is over';
                await hmsActions.endRoom(lock, reason);
            } catch (error) {
                // Permission denied or not connected to room
                console.error(error);
            }
        });
        endRoomButton.style.display = 'inline-block';
    } else {
        endRoomButton.style.display = 'none';
    }
}

// subscribe to the permissions, so render is called whenever there is a change due to role change
hmsStore.subscribe(renderEndRoomButton, selectPermissions);
```

</Tab>

<Tab id='endroomcall-1'>

```jsx
function EndRoomButton() {
    const permissions = useHMSStore(selectPermissions);
    const hmsActions = useHMSActions();

    const endRoom = () => {
        try {
            const lock = false; // set to true to disallow rejoins
            const reason = 'party is over';
            await hmsActions.endRoom(lock, reason);
        } catch (error) {
            // Permission denied or not connected to room
            console.error(error);
        }
    };

    return permissions.endRoom ? <button onClick={endRoom}>End Room</button> : null;
}
```

</Tab>

> 🚧 If the local peer doesn't have the required `endRoom` permission, the `hmsActions.endRoom` call will throw an [HMSException error](error-handling).

## End Room Notification

Once the peer with adequate permissions calls `endRoom`, all other peers in the room will receive a [notification](../features/notifications) with type `ROOM_ENDED` with a [HMSLeaveRoomRequest](../../../api-reference/javascript/v2/interfaces/HMSLeaveRoomRequest) object as the data.

The SDK automatically calls leave and performs necessary clean ups immediately after this notification is sent, clients should show the appropriate UI(show a toast, redirect to a 'good-bye' page) within this period.

<Tabs id="endroomhandle" items={['JavaScript', 'React']} />

<Tab id='endroomhandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // ...Other notification type cases
        case 'ROOM_ENDED':
            // Redirect or Show toast to user
            toast(notification.data.reason);
            break;
    }
});
```

</Tab>

<Tab id='endroomhandle-1'>

```jsx
import { useHMSNotifications } from '@100mslive/react-sdk';

function Notification() {
    const notification = useHMSNotifications();

    useEffect(() => {
        if (!notification) {
            return;
        }

        switch (notification.type) {
            // ...Other notification type cases
            case 'ROOM_ENDED':
                // Redirect or Show toast to user
                toast(notification.data.reason);
                break;
        }
    }, [notification]);

    return <div>Notification: {notification?.type}</div>;
}
```

</Tab>


End Room


Once you're done with a call and want to exit, call leave on the HMSSDK instance you created to join it. This function will return a promise that will resolve upon completion of leave process.

```js
await hmsInstance.leave();
```



Joining a room is one of the most basic functionalities so we at 100ms have built an easy, developer friendly API to get you started.


A user can interact with participants of a room only after _joining_ the room.

When user indicates that they want to _join_ the room, your app should have -
1. `userName`, the name which should be displayed to other peers in the room
2. `userID`, a unique identifier for the user. It can be your reference identifier or a [UUID string](https://developer.apple.com/documentation/foundation/uuid/1779712-uuidstring).
3. `roomID`, the unique room identifier which would have been generated & passed to your app from backend
4. `authToken`, the client side authentication token generated by your Token Service
 
Now that you have aforementioned data, you can proceed to join a room.

1. First, create an instance of `HMSSDK` class. Store this instance as a property. Ensure that the SDK object is alive in memory so that you can receive event callbacks from SDK. Simplest way to do this is as follows -
```swift
import HMSSDK

class MyMeetingClass {
    
    let hmsSDK: HMSSDK // store instance of HMSSDK as a property in your class

    init() {
        hmsSDK = HMSSDK.build() // initialize the SDK using the `build()` class function
    }
}
```
Note: If you are using Preview then you must already have an instance of HMSSDK before invoking Preview APIs.

2. Next, create an object of `HMSConfig` class using the available joining configurations
```swift
let config = HMSConfig(userName: "My good name",
                         userID: UUID().uuidString,
                         roomID: "abc123",
                      authToken: "eyJH5c")
```

3. Now, we are primed to join the room. All you have to do is pass the `config` object to `hmsSDK`
```swift
hmsSDK.join(config: config, delegate: self)
```

That's it. You have joined a room successfully. 🥳

Now, let's take a look at the signature of the Join API
```swift
func join(config: HMSConfig, delegate: HMSUpdateListener)
```
As evident, `join` accepts 2 arguments - 
- `config`: an object of type `HMSConfig` class, the room configuration object which encapsulates user & token data
- `delegate`: a class conforming to `HMSUpdateListener` protocol. 

The methods of `HMSUpdateListener` are invoked to notify updates happening in the room like a peer joins/leaves, a track got muted/unmutes, etc.

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

✅ If successful, the `func on(join room: HMSRoom)` method of `HMSUpdateListener` will be invoked with information about the room encapsulated in the `HMSRoom` object. 

❌ If failure, the `func on(error: HMSError)` method will be invoked with exact failure reason. 



Mute is something that applies to both audio and video.

When you mute audio, you can't be heard by other people.

When you mute video, you will not be broadcasting your video to other people.

It can be called on local (you) peers' audio or video tracks.

You get a reference to your own local peer from localPeer on HMSSDK instance.

```js
// instance acquired from build() method

hmsInstance.localPeer.localAudioTrack().setMute(true); // audio track

hmsInstance.localPeer.localVideoTrack().setMute(true); // video track
```


### Mute/Unmute Status

Mute/Unmute can be done for local peer as well as remote peer according to their mute status.


In most of the cases you would need to render the components on basis of current mute status of peers like their mic and camera icons.


```js
isAudioMute: boolean = peer?.audioTrack?.isMute(),
isVideoMute: boolean = peer?.videoTrack?.isMute(),
```


For muting remote peer refer to [Change Track State](./change-track-state) docs and for muting remote peers locally refer to [Playback Allowed](./playback-allowed) docs.



Mute/Umute


Console logging from sdk can be controlled by using the [`setLogLevel`](https://docs.100ms.live/api-reference/javascript/v2/interfaces/HMSActions#set-log-level) api.

```js
hmsActions.setLogLevel(HMSLogLevel.WARN); // log warnings and errors
hmsActions.setLogLevel(HMSLogLevel.ERROR); // only errors will be logged
hmsActions.setLogLevel(HMSLogLevel.NONE); // nothing will be logged by our sdk
```


Log Level


Leaving a room should be quick. Once a user wishes to end their interaction in the room, they can choose to leave the meeting. 👋

100ms SDK provides a simple, no fuss API to do exactly that. Invoke the `leave` method on instance of `HMSSDK`.

```swift
hmsSDK.leave()
```

You should expect that the `leave` function always succeeds, even in scenarios like "No Internet Connection", "Low Battery", etc



Sometimes people have bad internet connections but everyone deserves a good meeting.

When the network is too slow to support audio and video conversations together, the 100ms SDK can automatically turn off downloading other peer's videos, which may improve the audio quality and avoid disconnections.

If the network quality improves, the videos will be restored automatically as well.

To turn on subscribe degradation in your room, open the [templates](https://dashboard.100ms.live/templates) in the dashboard and enable it for roles there.

![Dashboard Degradation Option](/docs/v2/degradation.png)


## Responding in the app

The [HMSTrack](/api-reference/javascript/v2/interfaces/HMSTrack#degraded) object has a boolean `degraded` field which will
become true if the track gets degraded.

If `degraded` is true, treat it as if the video is turned off. If the UI is not changed, the video tile will appear black or frozen.
So for eg. if your UI shows an avatar when the track is not enabled, it should also do so on degradation.


Subscribe Degradation


What's a video without being able to send messages to each other too? 100ms supports chat for every video/audio room you create.

## Sending Chat Messages

With the HMSSDK instance call different send message functions.

### Broadcast Messages

This will be received by everyone in the room.

```js
// instance acquired from build() method
hmsInstance.sendBroadcastMessage('hello everyone!'); // yes it's that simple 😉
```

### Group Messages

This will be received by every peer who is part of the passed in roles.

```js
// instance acquired from build() method

// all available Roles can be obtained from hmsInstance using hmsInstance.knownRoles. 
// it will return an array of HMSRole from which required roles can be selected for this API.

hmsInstance.sendGroupMessage('hi folks!', [role1, role2]);
```

### Direct Messages

This will only be received by the peer whom the message was sent to.

```js
// instance acquired from build() method
hmsInstance.sendDirectMessage('keep this message a secret!', peer);
```

## Receiving Chat Messages

When you called hmsInstance.join(config) to join a room, add a ON_MESSAGE event listener with callback function onMessageReceived.

```js
// import HMSUpdateListenerActions,HMSMessage classes
import { HMSUpdateListenerActions, HMSMessage } from '@100mslive/react-native-hms';

// instance acquired from build() method
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_MESSAGE, onMessageReceived);

const onMessageReceived = (message: HMSMessage) => {
    // perform action
};
```

## Putting together a list of chat messages.

The UI is completely up to you to decide! You'll also need to hold onto all the received messages if you want to display history.



Want to preserve your video call for posterity in a recording?
Or live stream it out to millions of viewers on YouTube, Twitch, Facebook, MUX or whatever gives you an RTMP ingest URL?

Turn on RTMP streaming or recording!

In 100ms, recording and streaming is usually achieved by having a bot join your room
and stream what it sees and hears to a file (recording) or to an rtmp ingest url (streaming).
It's also possible to start streaming and recording from [server side APIs](/server-side/v2/features/rtmp-streaming-and-browser-recording).

> There is another type
> of SFU based recording as well which allows for all the tracks to be recorded individually, you can find more details about it
> [here](/server-side/v2/features/recording).

## Starting and Stopping streaming / recording

These are the options which need to be passed to start rtmp or recording -

1. **meetingURL**: _string_. The url the 100ms bot user will open to join your room. It must allow access without any user level interaction.
2. **rtmpURLs**: _string[]_. Optional, if streaming is required, this has to be one or more RTMP Ingest Urls with max limit of 3 urls where the stream should go.
3. **record**: _bool_. Optional, If recording is required this can be set as true. This value has no effect on streaming.
4. **resolution**: _{ width: number, height: number }_. Optional, if passed the recording or rtmp will be done in the passed in resolution.

-   If both rtmpURLs and record = true are provided, both streaming and recording will begin.
-   If only rtmpURLs are provided, only streaming will begin.
-   If only record true is provided, only recording will begin.

If either one is started, the other can't be started without first stopping whatever is running.
Eg: Only streaming is started. Recording can't be started unless streaming is stopped first.

If both are required, they have to be started together by providing both RTMP Ingest Urls and recording = true.

```js
async start() {
    const params = {
        meetingURL: "",
        rtmpURLs: [""],
        record: true
    };
    try {
        await hmsActions.startRTMPOrRecording(params);
    } catch(err) {
        console.error("failed to start rtmp/recording", err);
    }
}

async stop() {
    try {
        await hmsActions.stopRTMPAndRecording();
    } catch (err) {
        console.error("failed to stop rtmp/recording", err);
    }
}

```

## Current Recording/RTMP State

As it is with everything else in the 100ms web world, we've selectors to tell us about the current state of the room,
whether recording or streaming is already going on and if recording is happening, which type of recording is currently running.

```js
const recordingState = hmsStore.getState(selectRecordingState);
const rtmpState = hmsStore.getState(selectRTMPState);

console.log('is sfu recording going on - ', recordingState.server.running);

if (recordingState.browser.running) {
    console.log('time when browser recording was started - ', recordingState.browser.startedAt);
} else if (recordingState.browser.error) {
    console.error('error in browser recording - ', recordingState.browser.error);
}

if (rtmpState.running) {
    console.log('time when rtmp was started - ', rtmpState.startedAt);
} else if (rtmpState.error) {
    console.error('error in rtmp streaming - ', rtmpState.error);
}
```

## Tips

-   If you're using the dashboard webapp from 100ms, please make sure to use a role which doesn't have publish permissions for beam tile to not show up.
    The meeting url can be edited in the streaming/recording popup to join with a recording specific role configured as such.
-   If using your own webapp, do put in place retries for API calls like tokens etc. just in case any call fails. As human users we're
    used to reloading the page in these scenarios which is difficult to achieve in the automated case.
-   Make sure to not disable the logs for the passed in meeting URL. This will allow for us to have more visibility into the room, refreshing the page
    if join doesn't happen within a time interval.


RTMP Streaming / Recording


HLS Streaming allows for scaling to millions of viewers in near real time. You can give a link of your
webapp which will be converted to a HLS feed by our server and can be played across devices for consumption.
Behind the scenes, this will be achieved by having a bot join your room and stream what it sees and hears. Once the feed
is ready, the server will give a url which can be played using any HLS Player.

> Note that the media server serving the content in this case is owned by 100ms. If you're looking for a way to stream
on YouTube, Twitch etc., please have a look at our RTMP streaming docs [here](./rtmp-recording).

## Starting HLS

To start HLS, you'll need to pass in a meeting URL. The 100ms bot will open this URL to join your room, so
it must allow access without any user level interaction. In the future, it'll be possible to start HLS for multiple such URLs for the same room.
For this purpose, the API supports taking in an array, although currently only the first element of the array will be respected. To distinguish between
multiple urls, an additional field `metadata` can be optionally passed. The `meetingURL` and `metadata` are clubbed together to form what we'll call
a `variant`.

You can call `hmsActions.startHLSStreaming` with a `hlsConfig` having an array of such variants.

Additionally you can also start recording by passing in a recording config with below fields - 
1. `singleFilePerLayer`: if the desired end result is a mp4 file per HLS layer, false by default
2. `hlsVod`: if the desired end result is a zip of m3u8 and all the chunks, false by default

```js
async startHLS() {
    const params = {
        variants: [{meetingURL: "", metadata: "landscape"}]
    };
    params.recording = {singleFilePerLayer: true, hlsVod: false}; // to enable recording
    try {
        await hmsActions.startHLSStreaming(params);
    } catch (err) {
        console.error("failed to start hls", err);
    }
}
````

## Stopping HLS

You can call `hmsActions.stopHLSStreaming` to stop HLS Streaming which will stop all the variants.

```js
async stopHLS() {
    try {
        await hmsActions.stopHLSStreaming();
    } catch (err) {
        console.error("failed to stop hls", err);
    }
}
```

## Current HLS State

The `selectHLSState` selector can be used to know if HLS is currently running, and the url where it can be viewed.

<Tabs id="hls" items={['JavaScript', 'React']} />{' '}

<Tab id='hls-0'>

```js
function updateHLSState(hlsState) {
    console.log("is hls streaming going on - ", hlsState.running);
    if (hlsState.running) {
        console.log("hls url - ", hlsState.variants[0]?.url);
    } else if (hlsState.error) {
        console.error("error in hls streaming - ", hlsState.error); 
    }
}

hmsStore.subscribe(updateHLSState, selectHLSState);
```

</Tab>

<Tab  id='hls-1'>

```jsx
function HLSState() {
    const hlsState = useHMSStore(selectHLSState);
    console.log("is hls streaming going on - ", hlsState.running);
    if (hlsState.running) {
        console.log("hls url - ", hlsState.variants[0]?.url)
    } else if (hlsState.error) {
        console.error("error in hls streaming - ", hlsState.error); 
    }
    return null;
}
```

</Tab>

## Displaying HLS Stream

Not all browsers support HLS [natively](https://caniuse.com/?search=hls), however you can use players like [hls.js](https://github.com/video-dev/hls.js/) or
[Shaka Player](https://github.com/google/shaka-player). In case you need more UI side customisations you can go with something like
[videojs](https://videojs.com/) which internally uses `hls.js` for the hls piece.

Here is a simple example of using `hls.js` to play the hls url given by the SDK. Make sure you've installed the library(`npm i hls.js`) before using this code.

<Tabs id="hlsview" items={['JavaScript', 'React']} />{' '}

<Tab id='hlsview-0'>

```js
import Hls from "hls.js";

function renderHLS({hlsUrl}) {
    const video = document.getElementById('video');
    const browserHasNativeHLSSupport = videoRef.current.canPlayType("application/vnd.apple.mpegurl");
    if (Hls.isSupported()) {
        let hls = new Hls();
        hls.loadSource(hlsUrl);
        hls.attachMedia(video);
    }
    // hls.js is not supported on iOS Safari, but as the browser has native support for playing HLS,
    // we can use the video element directly.
    else if (browserHasNativeHLSSupport) {
        video.src = hlsUrl;
    }
}
```

</Tab>

<Tab  id='hlsview-1'>

```jsx
import Hls from "hls.js";

function HLSView({hlsUrl}) {
    const videoRef = useRef(null);
    useEffect(() => {
        if (videoRef.current && hlsUrl) {
            const browserHasNativeHLSSupport = videoRef.current.canPlayType("application/vnd.apple.mpegurl");
            if (Hls.isSupported()) {
                let hls = new Hls();
                hls.loadSource(hlsUrl);
                hls.attachMedia(videoRef.current);
            }
            // hls.js is not supported on iOS Safari, but as the browser has native support for playing HLS,
            // we can use the video element directly.
            else if (browserHasNativeHLSSupport) {
                videoRef.current.src = hlsUrl;
            }
        }
    }, [hlsUrl]);

    return <video ref={videoRef} autoPlay controls></video>
}
```

</Tab>

## Testing with the Dashboard WebApp

You may want to try out the end to end flow on our dashboard webapp before moving ahead with building in your app. To do
this, you can create an additional role named `hls-viewer` which will be presented with the hls stream when they join the room.

![Streaming](/docs/v2/web-hamburger.png)

To start the hls stream, you can select Streaming from the hamburger menu on bottom center of the page. There will be a HLS checkbox in
the popup that opens which can be checked to start HLS. Once HLS has started, you can join from the `hls-viewer` role to
see the hls stream.

## Tips

* If you're using the dashboard webapp from 100ms, please make sure to use a role which doesn't have publish permissions for beam tile to not show up.
  The meeting url can be edited in the streaming/recording popup to join with a recording specific role configured as such.
* If using your own webapp, do put in place retries for API calls like tokens etc. just in case any call fails. As human users we're
used to reloading the page in these scenarios which is difficult to achieve in the automated case.
* Make sure to not disable the logs for the passed in meeting URL. This will allow for us to have more visibility into the room, refreshing the page
if join doesn't happen within a time interval.



HLS Streaming


## Introduction

If your app doesn't already use a global store, you can use a part of hmsStore to store simple states that needs sharing between your components. You might want to do this for improved performance and cleaner code on the app layer(avoiding prop drilling). Note that this is not a replacement for external global store. It's limited by design and only suitable for straightforward use cases.

> Note that this is not suitable for -
>  - storing large amount of data
>  - data changing at a high frequency
>  - complex interlinked state

## Usage

### Setting up initial appData

[`initAppData`](/api-reference/javascript/v2/interfaces/HMSActions#init-app-data) takes an object of key value pairs to set the intial app data in store.

```ts
const data: Record<string,any> = {uiMode: "activeSpeaker", toasts: {message: false, errors: true}};
hmsActions.initAppData(data);
```

### Updating State

[`setAppData`](/api-reference/javascript/v2/interfaces/HMSActions#set-app-data) takes in key and value and update the state in store. If key doesn't already exist, it is added.

```ts
hmsActions.setAppData("uiMode", "gallery");
// new value => {uiMode: "gallery", toasts: {message: false, errors: true}}
```

If your value is also an object, there is an additional boolean option which can be used to merge(instead of replace) the new value with existing value.

#### With Merge as true

```ts
hmsActions.setAppData("toasts", {message: true}, true);
// new value => {uiMode: "gallery", toasts: {message: true, errors: true}}
```

#### Without merge as true

```ts
hmsActions.setAppData("toasts", {message: true});
// new value => {uiMode: "gallery", toasts: {message: true}}
```

### Reading App Data
The selector [`selectAppData`](/api-reference/javascript/v2/home/content#select-app-data) can be used for this. You can pass it the key
you want to get, and it'll give the value. The component using it will only be rendered if the value actually changes.

```ts
console.log(hmsStore.getState("uiMode")); // "gallery"
console.log(hmsStore.getState("toasts")); // {message: false, errors: true}
```

### Example

<Tabs id="appData" items={['JavaScript', 'React']} />{' '}

<Tab id='appData-0'>

```js:app.js
function initAppData() {
    const initialAppData = {
      uiMode: "activeSpeaker",
      toasts: {
          message: false,
          errors: true,
      }
    };

    hmsActions.initAppData(initialAppData);
    console.log("inital toasts to show", hmsStore.getState(selectAppData("toasts"))); // { message: false, errors: true }
    hmsActions.setAppData("toasts", {message: true}, true); // merge this value in current value
    console.log("merged new toasts", hmsStore.getState(selectAppData("toasts"))); // { message: true, errors: true }
    hmsActions.setAppData("toasts", {message: true}, true); // replace current value
    console.log("replaced new toasts, hmsStore.getState(selectAppData("toasts"))); // { message: true }
    
    console.log("uiMode", hmsStore.getState(selectAppData("uiMode")); // activeSpeaker
    hmsActions.setAppData("uiMode", "gallery");
    console.log("uiMode", hmsStore.getState(selectAppData("uiMode")); // gallery
}

```

</Tab>

<Tab  id='appData-1'>

```jsx:app.jsx
export function myComponent() {
  const toasts = useHMSStore(selectAppData("toasts"));
  const uiMode = useHMSStore(selectAppData("uiMode"));
    
  const hmsActions = useHMSActions();
  useEffect(() => {
    const initialAppData = {
      uiMode: "activeSpeaker",
      toasts: {
          message: false,
          errors: true,
      }
    };

    hmsActions.initAppData(initialAppData);
  }, [hmsActions]); // runs only once

  // toasts becomes { message: true, errors: true } after first call to toggle
  toggleMessageToast = useCallback(()=> {
    hmsActions.setAppData("toasts", { message: !toasts.message }, true);
  }, [hmsActions]);

  // toasts becomes { message: false, errors: true } after call to this method
  resetToasts = useCallback((newValue)=> {
    hmsActions.setAppData("toasts",{
          message: false,
          errors: true,
      });
  }, [hmsActions]);

  return <> {/* components */} </>;
}
```

</Tab>


Store AppData


Preview screen is a frequently used UX element which allows users to check if their input devices are working properly and set the initial state (mute/unmute) of their audio and video tracks before joining. 100ms SDKs provide an easy-to-use API to back this feature.

## Calling Preview function

We can call preview method in HMSSDK Instance. it is advised to attach error listener and preview listener before calling that function in order to get updates if preview got executed successfully or if it failed.

```js
import HmsManager, {
  HMSUpdateListenerActions,
} from '@100mslive/react-native-hms';

const hmsInstance = HmsManager.build()

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PREVIEW,
  onPreview, // function that will be called on Preview success
);
// attach room and peer update listeners for current status
hmsInstance?.addEventListener(
  MSUpdateListenerActions.ON_ROOM_UPDATE,
  onRoomListener,
);
hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_PEER_UPDATE,
  onPeerListener,
);

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);
```

once listeners are attached we can call preview method as shown in following snippet.

```js
import HmsManager, { HMSUpdateListenerActions, HMSConfig } from '@100mslive/react-native-hms';

// instance acquired from build() method
const HmsConfig = new HMSConfig({ authToken, username });
hmsInstance.preview(HmsConfig); // to start preview
```



An user should be able to mute or unmute both audio & video as per their choice. 100ms SDK makes it simple to do just that in nifty way.

1. First, get the reference to local peer using the convenience method `localPeer` on `HMSSDK` class
2. Next, get the audio or video track of the local peer
3. Now, set it's mute status to true or false.
- When mute is true, local peer won't transmit any audio or video. 🤫🤐
- When mute is false, local peer can speak & show the world whatever they want to. 🕺💃

### Mute Audio 🙊
```swift
hmsSDK.localPeer?.localAudioTrack()?.setMute(true)
```

### Ummute Audio 🐵
```swift
hmsSDK.localPeer?.localAudioTrack()?.setMute(false)
```

### Mute Video 🙈
```swift
hmsSDK.localPeer?.localVideoTrack()?.setMute(true)
```

### Unmute Video 🐒
```swift
hmsSDK.localPeer?.localVideoTrack()?.setMute(false)
```

Note: Ensure that you call these functions from the main queue. 


What's a video without being able to send messages to each other too? 100ms supports chat for every video/audio room you create.

You can see an example of every way of sending messages and interpreting messages in the advanced [sample app](https://github.com/100mslive/100ms-ios-sdk).

### Addressing messages

* [Broadcast messages](#sending-broadcast-messages) can be sent to Everyone in the chat `hmssdk.sendBroadcastMessage`.

* [Direct messages](#sending-direct-messages) let you send message to a specific person `hmssdk.sendDirectMessage`.

* [Group messages](#sending-group-messages) let you send a message to everyone with a particular `HMSRole`. Such as all `hosts` or all `teachers` or all `students` `hmsSdk.sendGroupMessage`

### Sending Chat Messages

#### Sending Broadcast Messages

You want to let everyone in the chat know something? Call `sendBroadcastMessage` on the instance of `HMSSDK` to a send a broadcast.

The text of the message, its type and a listener for whther the message reached the server or not are the parameters.

> 💡 Note that the callback only lets you know if the server has received your request for the message or if there was some error. It does not convey whether the message was delivered to or read by the recipient.
> also it's important to make a new callback per message because it will only contain the results of that particular call for sending a message.


```swift
hmssdk.sendBroadcastMessage(type: "chat", message: "") { message, error in

}
```

#### Sending Direct Messages

Got secrets to share? Send a message directly to a single person in the chat with a direct message. Call `sendDirectMessage` on an instance of `HMSSDK`.

The text of the message, its type and a listener for whther the message reached the server or not are the parameters.

> 💡 Note that the callback only lets you know if the server has received your request for the message or if there was some error. It does not convey whether the message was delivered to or read by the recipient.
> also it's important to make a new callback per message because it will only contain the results of that particular call for sending a message.

```swift
hmssdk.sendDirectMessage(type: "chat", message: "", peer: recipientPeer) { message, error in

}
```

#### Sending Group Messages

Want to share with a group? Send a message directly to a group in the chat with a group message. Call `sendGroupMessage` on an instance of `HMSSDK`.

The text of the message, its type and a listener for whether the message reached the server or not are the parameters.

> 💡 Note that the callback only lets you know if the server has received your request for the message or if there was some error. It does not convey whether the message was delivered to or read by the recipient.
> also it's important to make a new callback per message because it will only contain the results of that particular call for sending a message.

```swift
hmssdk.sendGroupMessage(type: "chat", message: "", roles: recipientRoles) { message, error in

}
```

### Receiving Chat Messages

When you called `hmsSdk.join(config, delegate)` to join a room, the `HMSUpdateListener` implementation that was passed in had the callback `on(message:)`.

This where you'll receive new messages as `HMSMessage` during the call. It contains:

```swift
public class HMSMessage {
    public let message: String
    public let type: String
    public var sender: HMSPeer?
    public var recipient: HMSMessageRecipient
    public let time: Date
}    
```
`message`: Content of the text message or the text description of the raw message.

`type`: Type of message sent. Default value is `chat`.

`recipient`: The intended recipient(s) of this message as a `HMSMessageRecipient`.

`time`: Timestamp of when the messaging server receives this message. Update the time in your own messages when this comes back from the server in `on(message:)` for accurate ordering of your own messages.

`sender`: The `HMSPeer` who is sending this message.

Identifying Senders: The sender of a message is always contained in the `sender` field of HMSMessage. This lets you get the name and peer id for any message sender.

Message Body: The body of the message is in `message` as a String.

Time: The time the message was sent is contained in `time`.

#### Identifying who the message was for

The HMSMessageRecipient contained in the `recipient` field of `HMSMessage` lets you know who the message was for.

The `HMSMessageRecipient` contains:
```swift
public class HMSMessageRecipient {
    public let type: HMSMessageRecipientType
    public let peerRecipient: HMSPeer?
    public let rolesRecipient: [HMSRole]?
}
```

`peerRecipient`: Only contains a peer when a specific single peer is being direct messaged.

`rolesRecipient`: Only contains values when a group message is being sent to one or many roles.

`type`: Will be `broadcast` for a message being sent to everyone. If this is true, the other two field will be null, empty respectively.

`peer` will be set when it's a direct message.

`roles` will be set when it's a message to one or many roles. 


It all comes down to this. All the setup so far has been done so that we can show live streaming video in our beautiful apps.

The React Native SDK provides a Component `HmsView` that renders the video on screen.

We can pass video trackId, scaleType and mirror to this component.

```js
import { HMSVideoViewMode } from '@100mslive/react-native-hms';
...
// hms instance acquired from build method
const HmsView = hmsInstance.HmsView;
const styles = StyleSheet.create({
  hmsView: {
    height: '100%',
    width: '100%',
  },
});
<HmsView trackId={trackId} scaleType={HMSVideoViewMode.ASPECT_FILL} style={styles.hmsView} mirror={true} />
...
```


## Track Id
It is a required prop in the `HmsView` component. There are 2 types of Peers remotePeers and a localPeer to extract trackId from peers we can use following code snippet. These track IDs can directly be passed to HmsView component
```js
const localTrackId = hmsInstance.localPeer.videoTrack.trackId;
const remoteTrackId = hmsInstance.remotePeers[index].videoTrack.trackId;
```


## Scale Type
It is a optional prop in the `HmsView` component. By default value of scale type is set to `HMSVideoViewMode.ASPECT_FILL`. There are 3 scale types you can pass to render a video. 
```js
import { HMSVideoViewMode } from '@100mslive/react-native-hms';

const ASPECT_FILL = HMSVideoViewMode.ASPECT_FILL
const ASPECT_FIT = HMSVideoViewMode.ASPECT_FIT
const ASPECT_BALANCED = HMSVideoViewMode.ASPECT_BALANCED
```

## Mirror
It is a optional prop in the `HmsView` component. You can mirror the videos as well. By default the mirror prop is set to false. For an attractive rendering you can set mirror true for the videos rendered to the left of the camera.

> A Pro tip: Try to render only 2 to 4 videos on a screen and set sink false for other videos. This will stop downloading video data of tiles which are not visible on screen.

## Is Degraded
Sometimes people have bad internet connections but everyone deserves a good meeting.When the network is too slow to support audio and video conversations together, the 100ms SDK can automatically turn off downloading other peer's videos, which may improve the audio quality and avoid disconnections.If the network quality improves, the videos will be restored automatically as well.
Show a black tile with avatar or initials when isDegraded is true.
```js
const isDegraded: boolean = peer.videoTrack.isDegraded
```

> A Pro tip: For fastest updates we can use ON_PEER_UPDATE and ON_TRACK_UPDATE listeners, these listeners get updated localPeer and remotePeers whenever there is any event related to these values.

```js
HmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PEER_UPDATE,
  onPeerListener
);
HmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_TRACK_UPDATE,
  onTrackListener
);

const onPeerListener = ({
  remotePeers,
  localPeer,
}: {
  peer: HMSPeer;
  room?: HMSRoom;
  type?: HMSPeerUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  updateVideoIds(remotePeers, localPeer); // this function can be used to update local and remotePeers on React-Native side
};

const onTrackListener = ({
  remotePeers,
  localPeer,
}: {
  peer: HMSPeer;
  track: HMSTrack;
  room?: HMSRoom;
  type?: HMSTrackUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  updateVideoIds(remotePeers, localPeer);
};
```

## Troubleshooting in HmsView

If a video renders for the first time and then it doesn't appear at all this can be due to the usage of multiple instances.

However we will recommend you to use a single instance approach if possible, which means once you call a build method and get a hms instance from that save that instance in a global state. Do not call the build method again and again as it will return a new hms instance every time.

If you need to use a multiple instance approach according to your usage then we recommend you to use the HmsView from the instance as shown above. HmsView export from the package is deprecated after version `0.9.4`.



When you make various function calls through HmsInstance, it may return errors with different error codes. ErrorCodes are returned when a problem that cannot be recovered without app intervention has occurred.

These are returned as HMSException in the onError callback of the HMSUpdateListner.

```js
// import HMSUpdateListenerActions class
import { HMSUpdateListenerActions } from '@100mslive/react-native-hms';

// instance acquired from build() method
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

const onError = (error) => {
    // console.log(error);
};
```

Following are the different error codes that are returned in the callback . Before returning any error code, it retries the errors (whichever is possible).

| Error Code  | Cause of the error                                     | Action to be taken                                                                                          |
| ----------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **`1003`**  | Websocket disconnected - Happens due to network issues | Mention user to check their network connection or try again after some time.                                |
| **`2002`**  | Invalid Endpoint URL                                   | Check the endpoint provided while calling join on HMSSDK.                                                   |
| **`2003`**  | Endpoint is not reachable                              | Mention user to check their network connection or try again after some time.                                |
| **`2004`**  | Token is not in proper JWT format                      | The token passed while calling join is not in correct format. Retry getting a new token.                    |
| **`3001`**  | Cant Access Capture Device                             | Ask user to check permission granted to audio/video capture devices.                                        |
| **`3002`**  | Capture Device is not Available                        | Ask user to check if the audio/video capture device is connected or not.                                    |
| **`3003`**  | Capture device is in use by some other application     | Show notification to user mentioning that the capturing device is used by some other application currently. |
| **`3008`**  | Browser has thrown an autoplay exception.              | Show notification to user mentioning that the browser blocked autoplay                                      |
| **`4001`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4002`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4003`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4004`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4005`**  | ICE Connection Failed due to network issue             | Mention user to check their network connection or try again after some time.                                |
| **`5001`**  | Trying to join a room which is already joined          | Trying to join an already joined room.                                                                      |
| **`6002`**  | webRTC Error: Error while renegotiating                | Please try again.                                                                                           |
| **`40101`** | Token Error: Invalid Access Key                        | Please try again.                                                                                           |
| **`40102`** | Token Error: Invalid Room Id                           | RoomID provided in the token is wrong.                                                                      |
| **`40103`** | Token Error: Invalid Auth Id                           | AuthID provided in the token is wrong.                                                                      |
| **`40104`** | Token Error: Invalid App Id                            | App ID provided in the token is wrong.                                                                      |
| **`40105`** | Token Error: Invalid Customer Id                       | Customer Id provided in the token is wrong.                                                                 |
| **`40107`** | Token Error: Invalid User Id                           | User ID provided in the token is wrong.                                                                     |
| **`40108`** | Token Error: Invalid Role                              | The role provided in the token is wrong.                                                                    |
| **`40109`** | Token Error: Bad JWT Token                             | Bad JWT Token.                                                                                              |
| **`40100`** | Generic Error                                          | Need to debug further with logs.                                                                            |
| **`40001`** | Invalid Room                                           | Room ID provided while fetching the token is an invalid room.                                               |
| **`40002`** | Room Mismatched with Token                             | Room ID provided while fetching the token does not match.                                                   |
| **`40004`** | Peer already joined                                    | Peer who is trying to join has already joined the room.                                                     |
| **`41001`** | Peer is gone                                           | The peer is no more present in the room.                                                                    |



It all comes down to this. All the setup so far has been done so that we can show live streaming video in our beautiful apps. 

How to do it? What should I be careful about? Is it easy? 😨😰😱

It's simpler than you think. That's what we are here for. 🙌✌️🤝

1. First, you need to create a `HMSVideoView` object in your View hierarchy.
`HMSVideoView` is a subclass of `UIView` so add it to your UI just as a regular view using Storyboard, XIB or in-code.

2. Next, you'll have a reference to a video track object. Specifically, a object of type `HMSVideoTrack` (or any of it's subclasses). For example, the local peer's video track can be accessed like so -
```swift
hmsSDK.localPeer?.localVideoTrack() // it's a HMSLocalVideoTrack, a subclass of HMSVideoTrack
```

3. Now, pass the video **track** object to video **view** using `setVideoTrack` method of `HMSVideoView`
```swift
videoView.setVideoTrack(track) // videoView is HMSVideoView, track is HMSVideoTrack
```
Video Track to Video View. Remember this. You'll be doing this often.

That's it. 

The video which the peer will be transmitting will now be rendered & start playing in your video view. 🥳 


You can easily add or remove an event listener by using the addEventListener() or removeEventListener() method. HMSUpdateListenerActions is an enum class which has all the types of event listeners.

```js
import HmsManager, {
  HMSUpdateListenerActions,
  HMSException,
  HMSMessage,
  HMSLeaveRoomRequest,
  HMSSpeaker,
  HMSPeer,
  HMSTrack
} from '@100mslive/react-native-hms';

const hmsInstance = await HmsManager.build();

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PREVIEW,
  onPreviewListener
);

const onPreviewListener = ({ previewTracks }) => {
  const videoTrack = previewTracks.videoTrack;
  const videoTrackId = videoTrack.trackId;
  // gets triggered when we call preview function. You can set your camera and mic on/off while joining.
  // perform action
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_JOIN, onJoinListener);

const onJoinListener = ({ localPeer, remotePeers }) => {
  // gets triggered when join is successful. You can navigate to other screens.
  // use these objects to update your local and remote peers.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_ROOM_UPDATE,
  onRoomListener
);

const onRoomListener = ({
  room,
  type,
  localPeer,
  remotePeers,
}:{
  room?: HMSRoom;
  type?: HMSRoomUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  // gets triggered when room is muted or unmuted.
  // use these objects to update your local and remote peers.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_PEER_UPDATE,
  onPeerListener
);

const onPeerListener = ({
  room,
  type,
  remotePeers,
  localPeer,
  peer,
}: {
  room?: HMSRoom;
  type?: HMSPeerUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
  peer: HMSPeer;
}) => {
  // gets triggered when peer leaves, joins, peer's audio or video is muted, starts or stops speaking, role is changed or becomes dominant speaker.
  // use these objects to update your local and remote peers.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_TRACK_UPDATE,
  onTrackListener
);

const onTrackListener = ({
  track,
  peer,
  room,
  type,
  remotePeers,
  localPeer,
}: {
  track: HMSTrack;
  peer: HMSPeer;
  room?: HMSRoom;
  type?: HMSTrackUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  // gets triggered when track is added, removed, muted, unmuted, degraded and restored back.
  // use these objects to update your local and remote peers.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_ERROR,
  onErrorListener
);

const onErrorListener = (data: HMSException) => {
  // gets triggered whenever some error occours with a error description. You can either log it or navigate to some error screen.
  // data contains a error code and message due to which error occoured.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_MESSAGE,
  onMessageListener
);

const onMessageListener = (data: HMSMessage) => {
  // gets triggered whenever you receive a direct message, broadcasted message or role-based message.
  // whenever local peer receives a message this is triggered. Add the message to reducer.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_SPEAKER,
  onSpeakerListener
);

const onSpeakerListener = (data: HMSSpeaker[]) => {
  // gets triggered whenever someone speaks
  // an array of speakers is received. Use it to highlight the speakers.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.RECONNECTING,
  onReconnectingListener
);

const onReconnectingListener = (data) => {
  // triggered whenever local peer is trying to reconnect to room i.e. bad network.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.RECONNECTED,
  onReconnectedListener
);

const onReconnectedListener = (data) => {
  // triggered when local peer is reconnected to the room.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST,
  onRoleChangeRequestListener
);

const onRoleChangeRequestListener = (data: HMSRoleChangeRequest) => {
  // triggered when someone requests a role change for local peer. We can get data.requestedBy.name, data.suggestedRole.name
  // You can show a modal allowing user to accept or decline the role change request whenever this is triggered.
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_REMOVED_FROM_ROOM,
  onRemovedFromRoomListener
);

const onRemovedFromRoomListener = (data: HMSLeaveRoomRequest) => {
  // triggered whenever someone removes local peer from the room or the room is ended.
  // You can navigate to home screen, clear all reducers and reset all the states whenever this is triggered
};

hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_CHANGE_TRACK_STATE_REQUEST,
  onChangeTrackStateRequest
);

const onChangeTrackStateRequest = (data: HMSChangeTrackStateRequest) => {
  // triggered when someone requests a unmute for local peer. We can get data.requestedBy.name, data.trackType
  // You can show a modal allowing user to accept or decline the role change request whenever this is triggered.
};

hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_LOCAL_AUDIO_STATS,
  onChangeLocalAudioStats,
);

const onChangeLocalAudioStats = (data: {
  localAudioStats: HMSLocalAudioStats;
  track: HMSLocalAudioTrack;
  peer: HMSPeer;
}) => {
  // This contains stats related to local audio track.
};

hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_LOCAL_VIDEO_STATS,
  onChangeLocalVideoStats,
);

const onChangeLocalVideoStats = (data: {
  localVideoStats: HMSLocalVideoStats;
  track: HMSLocalVideoTrack;
  peer: HMSPeer;
}) => {
  // This contains stats related to local video track.
};

hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_RTC_STATS,
  onChangeRtcStats,
);

const onChangeRtcStats = (data: {rtcStats: HMSRTCStatsReport}) => {
  // This will contain the combined stats for the room.
};


hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_REMOTE_AUDIO_STATS,
  onChangeRemoteAudioStats,
);

const onChangeRemoteAudioStats = (data: {
  remoteAudioStats: HMSRemoteAudioStats;
  track: HMSRemoteAudioTrack;
  peer: HMSPeer;
}) => {
  // This contains stats related to remote audio track.
};

hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_REMOTE_VIDEO_STATS,
  onChangeRemoteVideoStats,
);

const onChangeRemoteVideoStats = (data: {
  remoteVideoStats: HMSRemoteVideoStats;
  track: HMSRemoteVideoTrack;
  peer: HMSPeer;
}) => {
  // This contains stats related to remote video track.
};
```


Event Listeners


Preview screen is a frequently used UX element which allows users to check if their input devices are working properly and set the initial state (mute/unmute) of their audio and video tracks before joining. 100ms SDKs provide an easy-to-use API to back this feature. Additionally, the SDK will try to establish a connection to 100ms server to verify there are no network issues and that the auth credentials are valid so that if everything is in order the subsequent room join is instant.

To invoke this API call

```swift
hmsSDK.preview(config: config, delegate: previewDelegate)
```

You would need the same config object that you would pass to [join API](Join). The `previewDelegate` is an object conforming to `HMSPreviewListener` protocol that has four callbacks:

```swift
func onPreview(room: HMSRoom, localTracks: [HMSTrack])
```

Which is called when SDK has passed all its preflight checks and established the connection to 100ms server. This will pass an array of local tracks that you can display to the user (see [Render Video](Render-Video) and [Mute](Mute) sections for more details).

If however there was some error related to getting the input sources or some preflight check has failed 

```swift
func on(error: HMSError)
```

delegate callback will be fired with the HMSError instance you can use to find what went wrong (see [Error Handling](Error-Handling)).

```swift
func on(room: HMSRoom, update: HMSRoomUpdate)
```

Can be used to get the room updates such as state of recording, peer count etc.


```swift
func on(peer: HMSPeer, update: HMSPeerUpdate)
```

Can be used to get peer updates i.e peer join and leave. 


## HMSPeerUpdate

```js
import { HMSPeerUpdate, HMSUpdateListenerActions, HMSRoom, HMSLocalPeer, HMSRemotePeer } from '@100mslive/react-native-hms';

// hms instance acquired from build method
hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_PEER_UPDATE,
  onPeerListener,
);

const onPeerListener = ({ type } : {
  peer: HMSPeer;
  room?: HMSRoom;
  type?: HMSPeerUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  if(type === HMSPeerUpdate.PEER_JOINED){
    // when a peer joins
  }
  if(type === HMSPeerUpdate.PEER_LEFT){
    // when a peer leaves
  }
  if(type === HMSPeerUpdate.ROLE_CHANGED){
    // when a peer's role is changed
  }
  if(type === HMSPeerUpdate.METADATA_CHANGED){
    // when a peer's metadata is changed
  }
  if(type === HMSPeerUpdate.NAME_CHANGED){
    // when a peer's name is changed
  }
  if(type === HMSPeerUpdate.NETWORK_QUALITY_UPDATED){
    // when a peer's network quality is changed
  }
};
```

## HMSTrackUpdate

```js
import { HMSTrackUpdate, HMSUpdateListenerActions, HMSRoom, HMSLocalPeer, HMSRemotePeer } from '@100mslive/react-native-hms';

// hms instance acquired from build method
hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_TRACK_UPDATE,
  onTrackListener,
);

const onTrackListener = ({ type } : {
  peer: HMSPeer;
  track: HMSTrack;
  room?: HMSRoom;
  type?: HMSTrackUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  if(type === HMSTrackUpdate.TRACK_ADDED){
    // when track is added
  }
  if(type === HMSTrackUpdate.TRACK_REMOVED){
    // when track is removed
  }
  if(type === HMSTrackUpdate.TRACK_MUTED){
    // when track is muted
  }
  if(type === HMSTrackUpdate.TRACK_UNMUTED){
    // when track is unmuted
  }
  if(type === HMSTrackUpdate.TRACK_DESCRIPTION_CHANGED){
    // when track's description is changed
  }
  if(type === HMSTrackUpdate.TRACK_DEGRADED){
    // when track is degraded
  }
  if(type === HMSTrackUpdate.TRACK_RESTORED){
    // when track is restored
  }
};
```

## HMSRoomUpdate

```js
import { HMSRoomUpdate, HMSUpdateListenerActions, HMSRoom, HMSLocalPeer, HMSRemotePeer } from '@100mslive/react-native-hms';

// hms instance acquired from build method
hmsInstance?.addEventListener(
  HMSUpdateListenerActions.ON_ROOM_UPDATE,
  onRoomListener,
);

const onRoomListener = ({ type } : {
  room?: HMSRoom;
  type?: HMSRoomUpdate;
  localPeer: HMSLocalPeer;
  remotePeers: HMSRemotePeer[];
}) => {
  if(type === HMSRoomUpdate.ROOM_MUTED){
    // when room is muted
  }
  if(type === HMSRoomUpdate.ROOM_UNMUTED){
    // when room is unmuted
  }
  if(type === HMSRoomUpdate.SERVER_RECORDING_STATE_UPDATED){
    // when server recording state is updated
  }
  if(type === HMSRoomUpdate.RTMP_STREAMING_STATE_UPDATED){
    // when rtmp streaming state is updated
  }
  if(type === HMSRoomUpdate.BROWSER_RECORDING_STATE_UPDATED){
    // when browser recording state is updated
  }
  if(type === HMSRoomUpdate.HLS_RECORDING_STATE_UPDATED){
    // when hls recording state is updated
  }
  if(type === HMSRoomUpdate.HLS_STREAMING_STATE_UPDATED){
    // when hls streaming state is updated
  }
};
```


Event Listeners Enums


If the local peer has endRoom permission they can end a room. It's also possible to lock the room to prevent any future rejoins.

## Check if user has permissions

```js
const endRoom: boolean = peer.role.permissions.endRoom;
```

## End Room for all

```js
const reason = 'Host ended the room';
const lock = false; // optional parameter

// instance acquired from build() method
hmsInstance.endRoom(reason, lock);
```

## End Room Notification

Once the peer with adequate permissions calls endRoom, all other peers in the room will receive a notification with type ON_REMOVED_FROM_ROOM with a HMSLeaveRoomRequest object as the data.

```js
// import classes
import { HMSUpdateListenerActions, HMSLeaveRoomRequest } from '@100mslive/react-native-hms';

const onRemovedFromRoom = (data: HMSLeaveRoomRequest) => {
    // redirect to home screen
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_REMOVED_FROM_ROOM, onRemovedFromRoom);
```



You're chatting away on your video call and, uh-oh, a phone call comes in! No worries, the 100ms SDK abstracts away handling this situation for you.

When a telephonic voice call comes in and the user accepts the following happens.
- You and all the other parties are muted.
- If the app goes to background your video will be muted

When the call ends the SDK will restore the audio, taking care not to unmute you if you had muted yourself before the call came in. Neither will it unmute all the peers if you had muted them from the app.

No code required, this happens automatically for all calls!

Interruption Handling


Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. Check what actions this role can perform. i.e can it change someone else's current role, end meeting, remove someone from the room.

## Check if user has permissions

```js
const changeRole: boolean = peer.role.permissions.changeRole;
```

## Example

Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the changeRole comes in.

## Request Role Change

You can either request a user to accept a role change request or forcefully change user's current role. If the request is accepted, the role and permissions will get updated. If the request is denied and you still want to change user's role then use force flag.

Imagine that the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the force parameter comes in. When it is set to true the other party will not receive a confirmation roleChangeRequest but instead will straight away receive a new set of updated permissions and stop publishing.

```js
import { HMSRole, HMSRemotePeer } from '@100mslive/react-native-hms';
const roles: HMSRole[] = hmsInstance?.knownRoles
const newRole: HMSRole = roles[0];

// can any remote peer
const peer: HMSRemotePeer = hmsInstance?.remotePeers[0] 

const force = false

// instance acquired from build() method
hmsInstance.changeRole(peer, newRole, force); // request role change
hmsInstance.changeRole(peer, newRole, !force); // force role change
```

## Request Role Change Listener

Once the peer with adequate permissions calls change role, following peer in the room will receive a notification with type ON_ROLE_CHANGE_REQUEST containing requestedBy and suggestedRole in the data object.

```js
// import classes
import { HMSUpdateListenerActions, HMSLeaveRoomRequest } from '@100mslive/react-native-hms';

const onRoleChangeRequest = ({ requestedBy, suggestedRole }) => {
    // open a promt to accept or reject the request
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ROLE_CHANGE_REQUEST, onRoleChangeRequest);
```

## Accept Request Role Change

Once the peer with adequate permissions calls change role, you can either accept or reject the request.

```js
// call this if you accept role change else close the prompt
hmsInstance.acceptRoleChange();
```



If the local peer has removeOthers permission they can remove a peer.

## Check if user has permissions

```js
const removeOthers: boolean = peer.role.permissions.removeOthers;
```

## Remove Peer

```js
import { HMSPeer } from '@100mslive/react-native-hms';

const reason = 'removed from room';

// instance acquired from build() method
const peer: HMSPeer = hmsInstance?.remotePeers[0]

hmsInstance.removePeer(peer, reason);
```

## Remove Peer Notification

Once the peer with adequate permissions calls removePeer for the local peer, the local peer will receive a notification with type REMOVED_FROM_ROOM with a HMSLeaveRoomRequest object as the data.

```js
// import classes
import { HMSUpdateListenerActions, HMSLeaveRoomRequest } from '@100mslive/react-native-hms';

const onRemovedFromRoom = (data: HMSLeaveRoomRequest) => {
    // redirect to home screen
};

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_REMOVED_FROM_ROOM, onRemovedFromRoom);
```



Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. [Learn more about roles here.](../foundation/templates-and-roles)

Each `HMSPeer` instance has a `role` property which returns an `HMSRole` instance. You can use this property to do following:

1. Check what this role is allowed to publish. I.e can it send video (and at what resolution)? can it send audio? can it  share screen? Who can this role subscribe to? (I.e student can only see the teacher's video) This is can be discovered by checking `publishSettings` and `subscribeSettings` properties
2. Check what actions this role can perform. i.e can it change someone else's current role, end meeting, remove someone from the room. This is can be discovered by checking `permissions` property

In certain scenarios you may want to change someone's role. Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the `changeRole` API comes in.

To invoke the api you will need 2 things. An instance of `HMSPeer` of the peer who's role you want to change and the `HMSRole` instance for the target role.  All the peers that are in the current room are accessible via `peers` property of `HMSRoom` instance that you can get via `room` property of `HMSSDK` instance after successful room join. A list of all available roles in the current room can be accessed via `roles` property of `HMSSDK` 

Once you have both you can invoke

```swift
 hmsSDK.changeRole(for: targetPeer, role: targetRole)
```

If the change role succeeds you will get a 

```swift
func on(peer: HMSPeer, update: HMSPeerUpdate)
```

delegate callback with the the same peer you passed as targetPeer and a `roleUpdated` update type.

`changeRole` has an optional `force` parameter which is `false` by default meaning that `changeRole` is basically a polite request: "Would you like to change you role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a 

```swift
func on(roleChangeRequest: HMSRoleChangeRequest)
```

delegate callback. At which point app can choose to show a prompt to the user asking for permission. If the user accepts, app should call 

```swift
hmsSDK.accept(changeRole: roleChangeRequest)
```

which completes the `changeRole` loop. Both parties will receive a `roleUpdated` callback so that they both can do necessary UI updates. Now the user actually becomes a speaker and the audio publishing will start automatically. 

Now lets imagine the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the `force` parameter comes in. When it is set to `true` the other party will not receive a confirmation `roleChangeRequest` but instead will straight away receive a new set of updated permissions and stop publishing. `roleUpdated` callback will still be fired so that the app can update the user's UI state.


Any peer can change their own name before or after joining a room. Before joining, the name would have to be specified in `HMSConfig` that is passed to the join method. This document shows how the name can be changed after joining.

## Responding to name changes

Whenever a remote peer's name is changed a callback will be received in `on(peer: HMSPeer, update: HMSPeerUpdate)` of `HMSUpdateListener` where the `update` will be of type `HMSPeerUpdate.nameUpdated`.

When this callback is received the UI for that peer should be updated as well.

## Changing the name

The peer who wants to change their name should call the following method on an `HMSSDK` instance.

```swift
let newName = "Ashwini Shetty"
hmsSdk.change(name: newName) { success, error in
   ...
}
```



Changing track state is a concept that allows users to mute other peers's audio / video and request unmute other peer's audio / video if they have required permissions or not according to their role.

## Check if user has permissions

```js
const mute: boolean = peer.role.permissions.mute;
const unmute: boolean = peer.role.permissions.unmute;
```

## Example

Imagine a room with 10 people having 3 speakers and they have to speak one by one. The first speaker can mute other 2 speakers and start. After some point when the first speaker is finished they can mute himself and request other speakers to unmute.

## Mute other tracks

If you have the required permissions you can mute remote tracks audio / video. The track of the remote peer would be muted without any requests.

```js
const mute: boolean = true;

// instance acquired from build() method
hmsInstance?.changeTrackState(audioTrack as HMSTrack, mute);
hmsInstance?.changeTrackState(videoTrack as HMSTrack, mute);
```

## Unmute other tracks

If you have the required permissions you can request to unmute remote tracks audio / video. If the request is accepted by the remote peer ON_TRACK_UPDATE listener will get triggered.

```js
const unmute: boolean = false;

// instance acquired from build() method
hmsInstance?.changeTrackState(audioTrack as HMSTrack, unmute);
hmsInstance?.changeTrackState(videoTrack as HMSTrack, unmute);
```

## Accept Track change request

Once the peer with adequate permissions calls change track state or unmute, you can either accept or reject the request.

```js
import { HMSUpdateListenerActions, HMSChangeTrackStateRequest } from '@100mslive/react-native-hms';

// add change track state listener
hmsInstance.addEventListener(
  HMSUpdateListenerActions.ON_CHANGE_TRACK_STATE_REQUEST,
  onChangeTrackStateRequest,
);

// reject or accept the request
const onChangeTrackStateRequest = (data: HMSChangeTrackStateRequest) => {
  const requestedBy = data?.requestedBy?.name
  const trackType = data?.trackType            
  if( trackType === 'audio' ) {
    hmsInstance?.localPeer?.localAudioTrack()?.setMute(false);
  } else if ( trackType === 'video' ) {
      hmsInstance?.localPeer?.localVideoTrack()?.setMute(false);
  }
};
```

## Mute all remote audio tracks 

If you have the required permissions you can mute all remote audio tracks at once.

```js
// instance acquired from build method
hmsInstance.remoteMuteAllAudio()
```

Change Track State


You're running a video call room and decide that someone who's currently talking shouldn't be talking.

You'd prefer they'd stay mute. Or perhaps you want their video turned off as well as their audio. You're looking for a remote mute.

Muting can apply to both audio and video.

## Unmuting
You may also decide that you want to let someone else speak who was currently muted. Or may want to ask someone to turn on their video.

You can request people to unmute themselves as well.

## Check if user has permissions
Can't let just anyone mute others. First you need to create a role with the permissions to mute others and also to ask them to unmute.

The permission to mute others is within PermissionsParams mute and you should check for that within the HMSRole of the peer to see if they have it.

Similarly the permission to unmute other peers is within PermissionsParams unmute.

Here's how to check whether the local peer has the permission to mute or unmute others:

```js
const mute: boolean = peer.role.permissions.mute;
const unmute: boolean = peer.role.permissions.unmute;
```

## Example

Imagine a room with 10 people having 7 listeners & 3 speakers. You want to unmute audio/video of all the speakers and mute audio/video of all the listeners.

## Muting/Unmuting
There are two APIs for muting/unmuting.

* One which only works on a single track (audio/video) for a single peer at a time. [Learn more about API here.](./change-track-state)

* One which can mute multiple tracks for multiple peers. Either by their role, or track source or track type or any combination of the above.

## Multiple Peers or Tracks

Once you have checked that the caller has permissions to mute another peer's audio or video, call `hmsInstance.changeTrackStateForRoles`.

To mute audio for a multiple peers or tracks:

`hmsInstance.changeTrackStateForRoles` takes four parameters

* `Mute` Boolean true if the track needs to be muted, false otherwise
* `Type` Optional, the HMSTrackType which should be affected. If this and source are specified, it is considered an `AND operation`. If null, all track sources are affected.
* `Source` Optional, the HMSTrackSource which should be affected. If this and type are specified, it is considered an `AND operation`. If null, all track sources are affected.
* `Roles` Array of HMSRole optional, may have a single item in a array, whose tracks should be affected. If null, all roles are affected.

Here's an example of how you would check if the caller was allowed to mute peers and then call for a mute/unmute on all peers in the chat.

```js
// instance acquired from build() method
hmsInstance?.changeTrackStateForRoles(true, undefined, undefined, [
  hmsInstance?.knownRoles,
]);
```
This can be further narrowed by specifying only those tracks of type Audio.

Note that `HMSTrackSource.REGULAR` is the peer's own audio and video as opposed to one provided by screenshare or a plugin.
```js
import { HMSTrackType, HMSTrackSource } from '@100mslive/react-native-hms';

// instance acquired from build() method
hmsInstance?.changeTrackStateForRoles(true, HMSTrackType.AUDIO, HMSTrackSource.REGULAR, [
  hmsInstance?.knownRoles,
]);
```


Change Track State For Roles


Done with talking and it's time to end the call for everyone not just yourself? You may be looking to end the room.

### Permissions

Can't let just anyone end a call. First you need to create a [role](../foundation/templates-and-roles) with the permissions to end a room.

The permission to end a room is called `endRoom` and you should check for that within the `permissions` property of `HMSRole` of the peer to see if they have it.

 
### Ending the Room

Once you're sure the peer has the permissions to end the room they can call for the room to end when they're ready with `hmsSdk.endRoom`.

`endRoom` takes three parameters.

reason: Optional message you want to pass along the end room notification to other peers

lock: Whether you want to prevent anyone from rejoining the room. If false, they will be allowed to enter the room again if the client called `join`. If this is false, they will not able to join this room again.

completion handler: Lets you know whether the end room operation executed. was ended successfully or not. 

> 💡 After calling endRoom the local peer needs to dispose of the video calling UI as well.

```swift
hmssdk.endRoom(lock: false, reason: "Meeting is over") { success, error in
if (success) {
    // pop to previous screen
}
}
```

### How to handle an end room callback

Once the peer with adequate permissions calls `endRoom`, all other peers in the room will receive a callback in `HMSUpdateListener.onRemovedFromRoom`.

The `on(removedFromRoom:)` callback has a single parameter called `HMSRemovedFromRoomNotification` with the following structure.

```swift
class HMSRemovedFromRoomNotification {
    public let requestedBy: HMSPeer
    public let reason: String
    public let roomEnded: Bool
}
```

> 💡 This is the same callback that will be triggered if a peer was [removed from a room](Remove-Peer) as well. Except that `roomEnded` will be true when the entire room was ended.

reason: The string message detailing why the room was ended.

requestedBy: The details of the peer who called `endRoom`.

roomEnded: True if the entire room was ended. False if only the receiving peer was removed.

Clients should read this callback and show the appropriate UI.


Mute is something that applies to both audio and video and its possible to mute remote peers only for yourself. When you will mute audio or video, you won't be able to hear or see the remote person but it will be audible and visible to others.

## Fetch isPlaybackAllowed

You can check if playback is allowed or not for a certain remote peer's audio or video.

```js
const remotePeer: HMSRemotePeer;
const isAudioPlaybackAllowed = remotePeer.remoteAudioTrack().isPlaybackAllowed(); 
const isVideoPlaybackAllowed = remotePeer.remoteVideoTrack().isPlaybackAllowed();
```

## Set isPlaybackAllowed

You can set playback for a certain remote peer's audio or video. If you set it to false it will turn off the audio or video only for you. You can revert it back by setting it true.

```js
const remotePeer: HMSRemotePeer;
const isAudioPlaybackAllowed = remotePeer.remoteAudioTrack().setPlaybackAllowed(false);
const isVideoPlaybackAllowed = remotePeer.remoteVideoTrack().setPlaybackAllowed(true);
```

## Local mute all remote peers audio

```js
// instance acquired from build method

hmsInstance.setPlaybackForAllAudio(true)  // mute
hmsInstance.setPlaybackForAllAudio(false) // unmute
```


Playback Allowed


You're running a room and decide that someone who's currently talking shouldn't be talking.

You'd prefer they'd stay mute. Or perhaps you want their video turned off as well as their audio. You're looking for a remote mute.

Muting can apply to both audio and video.

##### Unmuting

You may also decide that you want to let someone else speak who was currently muted. Or may want to ask someone to turn on their video.

You can request people to unmute themselves as well.

### Permissions

Can't let just anyone mute others. First you need to create a [role](../foundation/templates-and-roles) with the permissions to end a room.

The permission to end a room is called `mute` and you should check for that within the `permissions` property of `HMSRole` of the peer to see if they have it.

### Muting/Unmuting

Once you have checked that the caller has permissions to mute another peer's audio or video, call for it with `hmsSdk.changeTrackState`.

To mute a track:

Get the audio or video track of the peer whom you want to mute and pass it as the first parameter to `hmsSdk.changeTrackState`.

The second parameter is a boolean for muting. If true, the track will be muted. If false the track will be requested to unmute.

Finally you can pass a completion handler to check whether changeTrackState suceeded or failed as the third parameter.

### Handling a mute callback

Muting is automatically applied to the receiver tracks. No action is required.

### Handling an unmute callback
Unmute callbacks are received in the target peer's `on(changeTrackStateRequest:)` callback of `HMSUpdateListener`.

The target peer will receive an object of `HMSChangeTrackStateRequest`.

Here's its structure.

```swift
class HMSChangeTrackStateRequest {
    public let track: HMSTrack
    public let mute: Bool
    public let requestedBy: HMSPeer
}
```

With the information here, show a dialog to the user to ask if they want to accept the change and then apply the settings locally. The same as in a regular user [Mute/Unmute](Mute).


Remote Mute


Sometimes people have bad internet connections but everyone deserves a good meeting.

When the network is too slow to support audio and video conversations together, the 100ms SDK can automatically turn off downloading other peer's videos, which may improve the audio quality and avoid disconnections.

If the network quality improves, the videos will be restored automatically as well.

To turn on subscribe degradation in your room, open the templates in the dashboard and enable it for roles there.

## Responding in the app

All HMSVideoTracks, within the HMSPeer's have a variable called `isDegraded`.

If `isDegraded` is true, treat it as if the video is turned off. If the UI is not changed, the video tile will appear black.

```js
const isDegraded: boolean = peer.videoTrack.isDegraded
```


HMSMessageRecipientType

Cases

broadcast

peer

roles