
/[lib](/)

## Packages

| Name                                                                            |
| ------------------------------------------------------------------------------- |
| [live.hms.video.audio](../lib/live.hms.video.audio/index)                       |
| [live.hms.video.error](../lib/live.hms.video.error/index)                       |
| [live.hms.video.media.codec](../lib/live.hms.video.media.codec/index)           |
| [live.hms.video.media.settings](../lib/live.hms.video.media.settings/index)     |
| [live.hms.video.media.streams](../lib/live.hms.video.media.streams/index)       |
| [live.hms.video.media.tracks](../lib/live.hms.video.media.tracks/index)         |
| [live.hms.video.sdk](../lib/live.hms.video.sdk/index)                           |
| [live.hms.video.sdk.models](../lib/live.hms.video.sdk.models/index)             |
| [live.hms.video.sdk.models.enums](../lib/live.hms.video.sdk.models.enums/index) |
| [live.hms.video.sdk.models.role](../lib/live.hms.video.sdk.models.role/index)   |
| [live.hms.video.utils](../lib/live.hms.video.utils/index)                       |


Android API reference

Server Side API reference

React API reference


## Protocols

-   [HMSDataSourceDelegate](/api-reference/ios/v2/protocols/HMSDataSourceDelegate)
-   [HMSLogger](/api-reference/ios/v2/protocols/HMSLogger)
-   [HMSPreviewListener](/api-reference/ios/v2/protocols/HMSPreviewListener)
-   [HMSUpdateListener](/api-reference/ios/v2/protocols/HMSUpdateListener)

## Classes

-   [HMSAudioSettings](/api-reference/ios/v2/classes/HMSAudioSettings)
-   [HMSAudioTrack](/api-reference/ios/v2/classes/HMSAudioTrack)
-   [HMSAudioTrackSettings](/api-reference/ios/v2/classes/HMSAudioTrackSettings)
-   [HMSConfig](/api-reference/ios/v2/classes/HMSConfig)
-   [HMSDataSource](/api-reference/ios/v2/classes/HMSDataSource)
-   [HMSDevice](/api-reference/ios/v2/classes/HMSDevice)
-   [HMSError](/api-reference/ios/v2/classes/HMSError)
-   [HMSLocalAudioTrack](/api-reference/ios/v2/classes/HMSLocalAudioTrack)
-   [HMSLocalPeer](/api-reference/ios/v2/classes/HMSLocalPeer)
-   [HMSLocalVideoTrack](/api-reference/ios/v2/classes/HMSLocalVideoTrack)
-   [HMSMessage](/api-reference/ios/v2/classes/HMSMessage)
-   [HMSNetworkQuality](/api-reference/ios/v2/classes/HMSNetworkQuality)
-   [HMSPeer](/api-reference/ios/v2/classes/HMSPeer)
-   [HMSPermissions](/api-reference/ios/v2/classes/HMSPermissions)
-   [HMSPublishSettings](/api-reference/ios/v2/classes/HMSPublishSettings)
-   [HMSRemoteAudioTrack](/api-reference/ios/v2/classes/HMSRemoteAudioTrack)
-   [HMSRemotePeer](/api-reference/ios/v2/classes/HMSRemotePeer)
-   [HMSRemoteVideoTrack](/api-reference/ios/v2/classes/HMSRemoteVideoTrack)
-   [HMSRole](/api-reference/ios/v2/classes/HMSRole)
-   [HMSRoleChangeRequest](/api-reference/ios/v2/classes/HMSRoleChangeRequest)
-   [HMSRoom](/api-reference/ios/v2/classes/HMSRoom)
-   [HMSSDK](/api-reference/ios/v2/classes/HMSSDK)
-   [HMSSection](/api-reference/ios/v2/classes/HMSSection)
-   [HMSSimulcastLayerSettingsPolicy](/api-reference/ios/v2/classes/HMSSimulcastLayerSettingsPolicy)
-   [HMSSimulcastSettingsPolicy](/api-reference/ios/v2/classes/HMSSimulcastSettingsPolicy)
-   [HMSSpeaker](/api-reference/ios/v2/classes/HMSSpeaker)
-   [HMSSubscribeSettings](/api-reference/ios/v2/classes/HMSSubscribeSettings)
-   [HMSTrack](/api-reference/ios/v2/classes/HMSTrack)
-   [HMSTrackSettings](/api-reference/ios/v2/classes/HMSTrackSettings)
-   [HMSUtilities](/api-reference/ios/v2/classes/HMSUtilities)
-   [HMSUtility](/api-reference/ios/v2/classes/HMSUtility)
-   [HMSVideoSettings](/api-reference/ios/v2/classes/HMSVideoSettings)
-   [HMSVideoTrack](/api-reference/ios/v2/classes/HMSVideoTrack)
-   [HMSVideoTrackSettings](/api-reference/ios/v2/classes/HMSVideoTrackSettings)
-   [HMSVideoView](/api-reference/ios/v2/classes/HMSVideoView)
-   [HMSViewModel](/api-reference/ios/v2/classes/HMSViewModel)

## Enums

-   [HMSAnalyticsEventLevel](/api-reference/ios/v2/enums/HMSAnalyticsEventLevel)
-   [HMSCameraFacing](/api-reference/ios/v2/enums/HMSCameraFacing)
-   [HMSCodec](/api-reference/ios/v2/enums/HMSCodec)
-   [HMSConnectionRole](/api-reference/ios/v2/enums/HMSConnectionRole)
-   [HMSErrorCode](/api-reference/ios/v2/enums/HMSErrorCode)
-   [HMSLogLevel](/api-reference/ios/v2/enums/HMSLogLevel)
-   [HMSPeerUpdate](/api-reference/ios/v2/enums/HMSPeerUpdate)
-   [HMSRoomUpdate](/api-reference/ios/v2/enums/HMSRoomUpdate)
-   [HMSSimulcastLayer](/api-reference/ios/v2/enums/HMSSimulcastLayer)
-   [HMSTrackKind](/api-reference/ios/v2/enums/HMSTrackKind)
-   [HMSTrackSource](/api-reference/ios/v2/enums/HMSTrackSource)
-   [HMSTrackUpdate](/api-reference/ios/v2/enums/HMSTrackUpdate)
-   [HMSVideoConnectionState](/api-reference/ios/v2/enums/HMSVideoConnectionState)

## Extensions

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

## Structs

-   [HMSPerformanceStats](/api-reference/ios/v2/structs/HMSPerformanceStats)

## Typealiases

-   [HMSSection.SectionIdentifier](/api-reference/ios/v2/typealiases/HMSSectionSectionIdentifier)
-   [HMSVideoResolution](/api-reference/ios/v2/typealiases/HMSVideoResolution)


iOS API reference


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


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](/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)


Templates and Roles


<Content alias="securityAndTokens" />

<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).decode('utf-8')


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).decode("utf-8")
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


| OS         | Browsers:       | Features       | Minimum Browser Version | Maximum Browser Version | Minimum OS Version  | Maximum OS version |
| ---------- | --------------- | -------------- | ----------------------- | ----------------------- | ------------------- | ------------------ |
| Windows    | Google Chrome   | Screen Sharing | 78                      | 91                      | 7                   | 10                 |
|            |                 | Audio          | 78                      | 91                      | 7                   | 10                 |
|            |                 | Video          | 78                      | 91                      | 7                   | 10                 |
|            | Mozilla Firefox | Screen Sharing | NA                      | NA                      | 7                   | 10                 |
|            |                 | Audio          | 78                      | 89                      | 7                   | 10                 |
|            |                 | Video          | 78                      | 89                      | 7                   | 10                 |
|            | Edge            | Screen Sharing | 83                      | 91                      | 7                   | 10                 |
|            |                 | Audio          | 83                      | 91                      | 7                   | 10                 |
|            |                 | Video          | 83                      | 91                      | 7                   | 10                 |
| Mac OS     | Google Chrome   | Screen Sharing | 78                      | 91                      | OS X Mojave         | OS X Big Sur       |
|            |                 | Audio          | 78                      | 91                      | OS X Mojave         | OS X Big Sur       |
|            |                 | Video          | 78                      | 91                      | OS X Mojave         | OS X Big Sur       |
|            | Mozilla Firefox | Screen Sharing | NA                      | NA                      | OS X Mojave         | OS X Big Sur       |
|            |                 | Audio          | 78                      | 89                      | OS X Mojave         | OS X Big Sur       |
|            |                 | Video          | 78                      | 89                      | OS X Mojave         | OS X Big Sur       |
|            | Safari          | Screen Sharing | 13.1                    | 14.1.1                  | OS X Mojave         | OS X Big Sur       |
|            |                 | Audio          | 13.1                    | 14.1.1                  | OS X Mojave         | OS X Big Sur       |
|            |                 | Video          | 13.1                    | 14.1.1                  | OS X Mojave         | OS X Big Sur       |
|            | Edge            | Screen Sharing | 83                      | 91                      | OS X Mojave         | OS X Big Sur       |
|            |                 | Audio          | 83                      | 91                      | OS X Mojave         | OS X Big Sur       |
|            |                 | Video          | 83                      | 91                      | OS X Mojave         | OS X Big Sur       |
| Android OS | Google Chrome   | Screen Sharing | 78                      | 91                      | Android 5.0, API 21 |                    |
|            |                 | Audio          | 78                      | 91                      | Android 5.0, API 21 |                    |
|            |                 | Video          | 78                      | 91                      | Android 5.0, API 21 |                    |
|            | Mozilla Firefox | Screen Sharing | 78                      | 89                      | Android 5.0, API 21 |                    |
|            |                 | Audio          | 78                      | 89                      | Android 5.0, API 21 |                    |
|            |                 | Video          | 78                      | 89                      | Android 5.0, API 21 |                    |
|            | Edge            | Screen Sharing | 83                      | 46                      | Android 5.0, API 21 |                    |
|            |                 | Audio          | 83                      | 46                      | Android 5.0, API 21 |                    |
|            |                 | Video          | 83                      | 46                      | Android 5.0, API 21 |                    |
|            | SDK             | Screen Sharing | API 21                  |                         | Android 5.0, API 21 |                    |
|            |                 | Audio          | API 21                  |                         | Android 5.0, API 21 |                    |
|            |                 | Video          | API 21                  |                         | Android 5.0, API 21 |                    |
| iOS Mobile | Google Chrome   | Screen Sharing | 78                      | 91                      | iOS 14              |                    |
|            |                 | Audio          | 78                      | 91                      | iOS 14              |                    |
|            |                 | Video          | 78                      | 91                      | iOS 14              |                    |
|            | Mozilla Firefox | Screen Sharing | 34                      | 34                      | iOS 14              |                    |
|            |                 | Audio          | 34                      | 34                      | iOS 14              |                    |
|            |                 | Video          | 34                      | 34                      | iOS 14              |                    |
|            | Safari          | Screen Sharing | 13.1                    | 14.1.1                  | iOS 14              |                    |
|            |                 | Audio          | 13.1                    | 14.1.1                  | iOS 14              |                    |
|            |                 | Video          | 13.1                    | 14.1.1                  | iOS 14              |                    |
|            | Edge            | Screen Sharing | 46                      | 46                      | iOS 14              |                    |
|            |                 | Audio          | 46                      | 46                      | iOS 14              |                    |
|            |                 | Video          | 46                      | 46                      | iOS 14              |                    |
|            | SDK             | Screen Sharing | 10                      |                         | iOS 10              |                    |
|            |                 | Audio          | 10                      |                         | iOS 10              |                    |
|            |                 | Video          | 10                      |                         | iOS 10              |                    |


Supported Devices


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



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


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

Currently the SDK does not support bitcode so we need to disable it in build settings.


![Bitcode](/guides/bitcode.png)

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


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


## 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/Example)

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.

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

You'll also need the webrtc dependency for the `org.webrtc.SurfaceViewRenderer` that's required to display people's videos.

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

### 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`. Take it from webrtc library `implementation 'org.webrtc:google-webrtc:1.0.32006'`.

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


<Content alias="securityAndTokens" />

### 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).decode('utf-8')


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).decode("utf-8")
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>



## 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 video call with your friends.

TL;DR - You can find the link to the complete example over [here](https://codesandbox.io/s/happy-meddling-syndrome-q4ukf).

### Prerequisites

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

### Installing the dependencies

```bash
npm install --save @100mslive/hms-video@latest @100mslive/hms-video-react@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.jsx
import { StrictMode } from "react";
import ReactDOM from "react-dom";
import { HMSRoomProvider } from "@100mslive/hms-video-react";

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, 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. Let's create a `JoinForm` component and add it to the application.

```jsx:src/JoinForm.jsx
import { useState } from "react";

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
          value={inputValues.name}
          onChange={handleInputChange}
          id="name"
          type="text"
          name="name"
          placeholder="Your name"
        />
      </div>
      <div className="input-container">
        <input
          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/hms-video-react';

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 store and render them.
Our component will get rerendered if this list of peers changes.

```jsx:src/Conference.jsx
import { selectPeers, useHMSStore } from "@100mslive/hms-video-react";
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.
In order to render the video, we need to call `attachVideo` method of `hmsActions`, which accepts a trackId and a DOM element.

```jsx:src/Peer.jsx
import {
  selectVideoTrackByPeerID,
  useHMSActions,
  useHMSStore
} from "@100mslive/hms-video-react";
import { useRef, useEffect } from "react";

function Peer({ peer }) {
  const videoRef = useRef(null);
  const hmsActions = useHMSActions();
  const videoTrack = useHMSStore(selectVideoTrackByPeerID(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 (
    <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/hms-video-react";

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.

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

```jsx:src/Footer.jsx
import {
  selectIsLocalAudioEnabled,
  selectIsLocalVideoEnabled,
  useHMSActions,
  useHMSStore
} from "@100mslive/hms-video-react";

function Footer() {
  const videoEnabled = useHMSStore(selectIsLocalVideoEnabled);
  const audioEnabled = useHMSStore(selectIsLocalAudioEnabled);
  const hmsActions = useHMSActions();

  const toggleAudio = () => {
    hmsActions.setLocalAudioEnabled(!audioEnabled);
  };

  const toggleVideo = () => {
    hmsActions.setLocalVideoEnabled(!videoEnabled);
  };

  return (
    <div className="control-bar">
      <button className="btn-control" onClick={toggleAudio}>
        {audioEnabled ? "Mute" : "Unmute"}
      </button>
      <button className="btn-control" onClick={toggleVideo}>
        {videoEnabled ? "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 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="q4ukf" />


React Quickstart Guide

Clubhouse clone in React


## 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']} />

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

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

</Tab>

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

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

</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.
hmsManager.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/hms-video-react';

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

```
</Tab>

<Tab  id='react-1'>


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

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

  return </>;
}
```

</Tab>

## Debugging Tools

We believe that debugging is an important aspect of a developer first SDK.
We have designed our APIs and error messages with developer experience and ease of debugging in mind. We hope that
you'll have a delightful experience walking through the features and integrating our sdk in your app. Our core sdk
is written in Typescript, so all the typings are included with the SDK and are guaranteed to be true. This means that,
even if you use JavaScript, editors will be able to give a significantly improved experience in terms of intellisense.

We take the debugging experience one step further by connecting our store to redux devtools extension out of box. This gives you transparency and
visibility into the whole room state while building your UI.
We highly recommend installing the [devtools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en)
extension to visualize this state along with all the activities taking place in a single view. This makes it easier
to understand when and how the UI should change. You can use the time travel feature of the redux devtools
to recreate state changes for debugging specific issues as well.

![Redux Devtools](/guides/redux-devtools.png)

We also give a ready to use UI without writing any code which can be accessed
from the [dashboard account](https://dashboard.100ms.live). The code for this sample is open sourced [here](https://github.com/100mslive/100ms-web).
You can either start with this codebase or write your own, and use it for testing your webapp
in the initial phase of development.


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'})
};

hmsActions.join(config);

```

</Tab>

<Tab  id='join-1'>

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

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'})
  };

  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`. 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/hms-video-react';

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


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

```jsx
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/hms-video-react';

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
hmsActions.setLocalVideoEnabled(false);
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
function toggleAudio() {
  const enabled = hmsStore.getState(selectIsLocalAudioEnabled);
  hmsActions.setLocalAudioEnabled(!enabled);
}

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

</Tab>

<Tab id='mute-1'>

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

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

  function toggleVideo() {
    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

There are multiple types of messages that can be sent - Broadcast, Group, Direct Messages

### Broadcast Message:
This will be received by everyone in the room  

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

### Group Message:
At the moment, we support sending messages across roles.

```js
hmsActions.sendGroupMessage("hello everyone!", ['role1', 'role2']); // yes it's that simple 😉
```

### Direct Message:
This will be received by selected peer in the room 

```js
hmsActions.sendDirectMessage("hello everyone!", selectPeer.id); // yes it's that simple 😉
```

## Showing all the messages

You can access all messages using the selector `selectHMSMessages`. 

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

<Tab id='chat-0'>

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

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

hmsStore.subscribe(renderMessages, selectHMSMessages); // get all messages
hmsStore.subscribe(renderMessages, selectMessagesByRole('role1')); //get messages by role
hmsStore.subscribe(renderMessages, selectMessagesByPeerID(selectPeer.id)); // get messages by peer
hmsStore.subscribe(renderMessages, selectBroadcastMessages); // get only broadcast messages

// You can get unread counts by the following selectors
function unreadCount(count) {
  console.log('unreadcount - ', count);
}
hmsStore.subscribe(unreadCount, selectUnreadHMSMessagesCount); // all messages unread count
hmsStore.subscribe(unreadCount, selectBroadcastMessagesUnreadCount); // broadcast unread count
hmsStore.subscribe(unreadCount, selectMessagesUnreadCountByRole('role1')); // role unread count 
hmsStore.subscribe(unreadCount, selectMessagesUnreadCountByPeerID(selectPeer.id)); // peer unread count

```

</Tab>

<Tab id='chat-1'>

```jsx
import { Message } from './components';
import {
  selectHMSMessages,
  selectMessagesByRole,
  selectMessagesByPeerID,
  selectBroadcastMessages,
  selectBroadcastMessagesUnreadCount,
  selectMessagesUnreadCountByRole,
  selectMessagesUnreadCountByPeerID,
  selectUnreadHMSMessagesCount,
} from '@100mslive/hms-video-react';

function Chat() {
  // use only the selectors that are required for the corresponding UI
  const allMessages = useHMSStore(selectMessages);
  const brodacastMessages = useHMSStore(selectBroadcastMessages);
  const groupMessagesByRole = useHMSStore(selectMessagesByRole('role1'));
  const directMessages = useHMSStore(selectMessagesByPeerID('selectPeer.id'));
  const allMessagesUnreadCount = useHMSStore(selectUnreadHMSMessagesCount);
  const broadcastUnreadCount = useHMSStore(selectBroadcastMessagesUnreadCount);
  const groupMessagesByRoleUnreadCount = useHMSStore(selectMessagesUnreadCountByRole('role1'));
  const directMessagesUnreadCount = useHMSStore(selectMessagesUnreadCountByPeerID(selectPeer.id));

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

</Tab>

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


Chat


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

const deviceId = 'default';
// show user a settings component to manually choose device

// call the corresponding method to change the device id
hmsActions.setAudioSettings({deviceId});
hmsActions.setVideoSettings({deviceId});
hmsActions.setAudioOutputDevice(deviceId);
```

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
hmsActions.preview(config)
```

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


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) => {
    if (!notification) {
        return;
    }

    // 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/hms-video-react';

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 { HMSReactiveStore } from '@100mslive/hms-video-store';

const manager = new HMSReactiveStore();
const hmsNotifications = manager.getNotifications();

const unsubscribe = hmsNotifications.onNotification((notification) => {
    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;
        default:
            break;
    }
});
```

</Tab>

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

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

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;
            default:
                break;
        }
    }, [notification]);

    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

Error Handling



HMSSDK is distributed via [Cocoapods](https://cocoapods.org/). Add the `pod 'HMSSDK'` to your Podfile as follows:
  
  ```
  // Podfile
  
  platform :ios, '10.0'

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

Currently the SDK does not support bitcode so we need to disable it in build settings.

![Bitcode](/guides/bitcode.png)

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



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

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(selectPeerScreenSharing);

// to get the HMSPeer object of all the peers screensharing
const presenter = hmsStore(selectPeersScreenSharing);

// a boolean to know if the local peer is the one who is screensharing
const amIScreenSharing = hmsStore(selectIsLocalScreenShared);

// to get the screenshare video track, this can be used to call attachVideo for rendering
const screenshareVideoTrack = hmsStore(selectScreenShareByPeerID(presenter.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)

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` 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, end meeting, remove someone from the room. This can be discovered by using the `selectPermissions` selector.

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 3 things.

-   `remotePeerId`: The remote peer ID whose role you want to change.
-   `toRoleName`: The target role name.
-   `force`: Whether you want to change their role without asking them or give them a chance to accept/reject.

All the peers that are in the current room are accessible via `selectPeers` selector.

A list of all available role names in the current room can be accessed via the `selectAvailableRoleNames` selector. You can further use the `selectRoleByRoleName`
selector to get the full role object for a role name which will have the role's permissions and what they're allowed to do.

Once you have all you can invoke:

```ts
function changeRole(forPeerId: string, toRoleName: string, force: boolean) {
    hmsActions.changeRole(forPeerId, toRoleName, force);
}
```

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.

```js
function handleRoleChangeRequest(request) {
    if (!request) {
        return;
    }
    console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
    // decide what to do with the request
    const accept = shouldAccept(request);
    if (accept) {
        hmsActions.acceptChangeRole(request);
    } else {
        hmsActions.rejectChangeRole(request);
    }
}

hmsStore.subscribe(handleRoleChangeRequest, selectRoleChangeRequest);
```

If the request is accepted, the `peer.roleName` field in the store will update for all peers which should update their UI as well.

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)


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 as well. You're looking for a remote mute/unmute in this case.

### Muting/Unmuting

Use the [selectPermissions](../../../api-reference/javascript/v2/home/content#select-permissions) selector to check whether the local peer has the permission to `mute` or `unmute` others and then 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);
}
```

> 🚧 If the local peer doesn't have the required `mute`/`unmute` permission, the `hmsActions.setRemoteTrackEnabled` call will throw an [HMSException error](error-handling).

### Handling a mute/unmute request

Once the peer with adequate permissions calls `setRemoteTrackEnabled`, the local peer will receive a [notification](notifications) with 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, hold onto the information from the `HMSChangeTrackStateRequest` object, 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) {
        // ...Other notification type cases
        case 'CHANGE_TRACK_STATE_REQUEST':
            // Unmute Request
            if (notification.data.enabled) {
                // Ask for consent using dialog or any other appropriate UI
                await hmsActions.setEnabledTrack(notification.data.track.id, enabled);
            } else {
                // Mute Request
                // Show toast to user
            }
            break;
    }
});
```

</Tab>

<Tab id='remotemutehandle-1'>

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

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

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

        switch (notification.type) {
            // ...Other notification type cases
            case 'CHANGE_TRACK_STATE_REQUEST':
                // Unmute Request
                if (notification.data.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;
        }
    }, [notification]);

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

</Tab>

![Remote Unmute Request](/guides/remote-unmute.png)


Remote Mute/Unmute


Someone's overstayed their welcome and now you need to remove a peer from the chat. Just call `hmsActions.removePeer`.

![Remove Peer](/guides/remove-peer.png)

### Removing a peer

Use the [`selectPermissions`](../../../api-reference/javascript/v2/home/content#select-permissions) selector to check whether the local peer has the `removeOthers` permission and then call [`hmsActions.removePeer`](../../../api-reference/javascript/v2/interfaces/HMSActions#remove-peer) to end the room with `peerID` of the `HMSRemotePeer` that you'd like to be removed from the call and the `reason`.

```js
try {
    await hmsActions.removePeer(peer.id, 'Good bye');
} 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, the `hmsActions.removePeer` call will throw an [HMSException error](error-handling).

### Handling the 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/hms-video-react';

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


Done with talking and it's time to end the call for everyone not just yourself? You may be looking to end the room.

![End Room](/guides/end-room.png)

### Ending the Room

Use the [`selectPermissions`](../../../api-reference/javascript/v2/home/content#select-permissions) selector to check whether the local peer has the `endRoom` permission to end the room and then call [`hmsActions.endRoom`](../../../api-reference/javascript/v2/interfaces/HMSActions#end-room) to end the room with `lock`(`true` to prevent rejoining) and `reason`.

<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 {
                await hmsActions.endRoom(lock, 'Reason goes here');
            } 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 {
            await hmsActions.endRoom(lock, 'Reason goes here');
        } catch (error) {
            // Permission denied or not connected to room
            console.error(error);
        }
    };

    return permissions.endRoom ? <button onClick={endRoom}>End Room</button> : null;
}
```

</Tab>

> 💡 After calling endRoom the local peer needs to dispose of the video calling UI as well.

> 🚧 If the local peer doesn't have the required `endRoom` permission, the `hmsActions.endRoom` call will throw an [HMSException error](error-handling).

### Handling end room by a remote peer

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/hms-video-react';

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


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. 



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



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. 

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


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


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


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.


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


Someone's overstayed their welcome and now you need to remove a peer from the chat. Just call `hmsSdk.removePeerRequest`.


### Permissions

Can't let just anyone remove others from the room. 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 `removeOthers` and you should check for that within the `permissions` property of `HMSRole` of the peer to see if they have it.

### Removing a peer

Once the permissions are checked to ensure the caller has the permission to remove a peer, remove them by calling `hmsSdk.removePeer`.

The parameters are:

peer: The `HMSRemotePeer` that you'd like to be removed from the room.

reason: Optional message you want to pass along the peer being removed

completion handler: Let you know whether the remove operation executed successfully or not. 


```swift
hmssdk.removePeer(targetPeer, reason: "You are violating the community rules.") { success, error in
}
```

### Handling the remove peer callback

The target peer of the `removePeer` will receive a callback in `HMSUpdateListener` of `onRemovedFromRoom(notification : HMSRemovedFromRoom)`.

The `HMSRemovedFromRoom` object which is passed into the callback has the 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 room was [ended](End-Room) as well. Except that `roomEnded` will be false.

reason: The string message detailing why the peer is being removed.

requestedBy: The details of the peer who called `removePeer`.

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.


## 0.0.10 - 2021-08-17
### Added
- Sending private and group messages APIs
- Remove peer from a room API
- Remote mute peer API
- End room API
- videoContentMode property added to HMSVideoView to allow selecting if content should fit or fill the view
- videoTrack getter added HMSVideoView for convenience
### Changed
- send(message:) API renamed to sendBroadcastMessage

## 0.0.9 - 2021-08-05
- Fixed individual track publish settings not respected during change role
- Fixed wrong track source coming for trackRemoved update
- Fixed button states not updating properly during role change in sample app

## 0.0.8 - 2021-07-26
- HMSVideoView will auto pick the best fitting simulcast layer
- Sample app will not show role change options if user does not have necessary permissions

## 0.0.7 - 2021-07-16
- Added simulcast support
- Added support for forced change role
- HMSSpeaker now has a reference to HMSPeer instead of id

## 0.0.6 - 2021-07-09
- Added capability to change role mid-call
- Passing HMSRole object to peers
- SDK checks for appropriate permissions before trying to publish audio & video
- Corrected parsing of roles that do not subscribe to other roles

## 0.0.5 - 2021-07-02
- Automatic video track switch off in bad network conditions.
- Preview API added to the SDK, added preview screen to the sample app.

## 0.0.4 - 2021-06-25

-   Added Media Interruption Handling
-   Optimized network usage
-   Updated background to foreground transitions
-   Improved Error logging

## 0.0.3 - 2021-06-22

-   Removed private modules to fix installing failure

## 0.0.2 - 2021-06-16

-   Added Reconnection for reliability in bad network conditions
-   Handled network provider $WiFi to Mobile Data$ transitions mid-call
-   Upgraded Data Source which apps can use to easily create customized views
-   Added descriptive Error Codes
-   Added Analytics to track SDK performance
-   Added default handing to app background/foreground transitions
-   Handled joining meetings in different roles
-   Multiple Sample App enhancements

## 0.0.1 - 2021-06-04

-   Simplified SDK interfaces that can power a fully-featured video conferencing application
    -   `join`
    -   `leave`
    -   `listeners` for tracks/peers/other data
-   Features not covered in this release
    -   Handling network disconnections $disconnect from wi-fi to 4g ends the call$
    -   Handling subscription network degradations
    -   Handling second order publish network degradations
    -   Detailed analytics
    -   Recording


Release Notes


![Show Audio Level](/guides/audio-levels.png)

You can also show audio levels in your UI corresponding to every peer so it's easier to see who is speaking currently.
You can retrieve the speaker object for any peer which will contain peerID,
trackID and their audioLevel using `selectSpeakerByPeerID` selector.

You can also fetch the current active speaker using the `selectDominantSpeaker` selector.

```js
import {
  selectSpeakerByPeerID,
  selectDominantSpeaker,
} from '@100mslive/hms-video-store';

function updateAudioLevel(speaker) {
    console.log(`audio level for peer - ${speaker.peerID}, track - ${speaker.trackID} is ${speaker.audioLevel}`)
}

hmsStore.subscribe(updateAudioLevel, selectSpeakerByPeerID('<Peer ID>'));

function activeSpeaker(peer, prevPeer) {
    console.log(`previous active speaker - ${prevPeer.name} with role - ${prevPeer.roleName}`)
    console.log(`current active speaker - ${peer.name} with role - ${peer.roleName}`)
}

hmsStore.subscribe(activeSpeaker, selectDominantSpeaker);
```


Show Audio Level


![Change Volume](/guides/volume.png)

Audio volume refers to the volume of an audio track as perceived on the receiving end. This is a number between 0 to 100.
To modify audio volume - 

```js
const volume = 70;

// set the volume across whole room for each track
hmsActions.setVolume(volume);

// set the volume for a specific track
hmsActions.setVolume(volume, "<track_id>");
```


Manage Audio Volume


You can also add custom video or audio tracks to the sdk which will be published to others. Possible use cases -
* a synthetic track which doesn't use camera
* screenshare with custom-built annotations in an electron app.
* audio track from a source other than microphone


To add a custom/auxiliary track, you need to get hold of a MediaStreamTrack object and add it using the `addTrack` method on `hmsActions`.

```js
/**
 * track: MediaStreamTrack - Track to be added
 * source?: 'regular' | 'screen' | 'plugin' - Source of track - default: 'regular'
 */
await hmsActions.addTrack(track, source);

// to remove the track
await hmsActions.removeTrack(trackId);
```


## Accessing custom/auxiliary tracks

```js
// if you have hold of the peer object, it'll have ids of all the auxiliary tracks
console.log(peer.auxiliaryTracks);

// all auxiliary tracks
hmsStore.getState(selectAuxiliaryTracksByPeerID);

// audio auxiliary track
hmsStore.getState(selectAuxiliaryAudioByPeerID);

// track with source as screenshare
hmsStore.getState(selectScreenShareByPeerID);
hmsStore.getState(selectScreenShareAudioByPeerID);
```


Add custom tracks


## Introduction

Room is a virtual space which holds conferencing of the people. To allow users to join a 100ms video conferencing session inside your app, you first need to create a `room`.

## Create Room

You can create room using either dashboard or API.

## Create Room using Dashboard

You can create room on [100ms Dashboard](https://dashboard.100ms.live/create-room). While creating a room you can specify it's name, template, region and/or enable recording. 

Room creation via dashboard is helpful in doing quick POC or creating smaller number of rooms.


<Image width={2168} height={1212} alt="Create a room" src="/docs/v2/create-a-room.png" />

You can add or modify templates on [100ms Dashboard](https://dashboard.100ms.live/templates).

<Image
    width={2462}
    height={1638}
    alt="Room Details on Dashboard"
    src="/docs/v2/role-dashboard.png"
/>

## Create Room using API

You can also create room using API. This provides a more scalable way of creating room.

<PostRequest
    title="Create Room API"
    desp="This endpoint is used to create Room. "
    url="https://prod-in2.100ms.live/api/v2/rooms"
/>

<Tabs items={['Request', 'Response']} id="req" />

<Tab id="req-0">

```bash
curl https://prod-in2.100ms.live/api/v2/rooms -H 'Authorization: Bearer  <management_token>' -X POST -H 'Con
tent-Type: application/json' -d '{"name": "test-room", "description": "This is a test room", "recording_info": {"enabled": true, "upload_info": {"type": "s3", "location": "test-bucket", "prefix": "test-prefix",
"options": {"region": "ap-south-1"}, "credentials": {"key": "aws-access-key", "secret": "aws-secret-key"}}}}'
```
</Tab>
<Tab id="req-1">

```js
{
   "id":"61101349d0f56e684b608c08",
   "name":"test-room",
   "description":"This is a test room",
   "active":true,
   "recording_info":{
      "enabled":true,
      "upload_info":{
         "type":"s3",
         "location":"test-bucket",
         "prefix":"test-prefix",
         "credentials":{
            "key":"aws-access-key",
            "secret":"aws-secret-key"
         },
         "options":{
            "region":"ap-south-1"
         }
      }
   },
   "user":"60b8e13a6eb86d8101b57353",
   "customer":"60b8e13a6eb86d8101b57354",
   "created_at":"2021-08-08T17:24:25.682362823Z",
   "updated_at":"0001-01-01T00:00:00Z"
}
```
</Tab>

### Headers
| Name                           | Value                        | Required |
| :----------------------------- | :--------------------------- | :------- |
| Content-type <br/>             | application/json             | Yes      |
| Authorization <br/>            | Bearer `<management token>`  | Yes      |

### Body Paramters
| Name                 | Type     | Description                                                                                                                                                                                                                                                                                                  | Required |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| name <br/>           | `string` | A unique identifier you can assign to 100ms rooms. This is `case-insensitive`. Accepted characters are `a-z, A-Z, 0-9, and . - : _` If not provided, this is generated automatically. <br/><br/> **Note**: If `create Room` is called with an existing room name, then the corresponding room ID is returned | No       |
| description <br/>    | `string` | A string to describe your room's usage. E.g. "9PM English Class Batch 2"                                                                                                                                                                                                                                     | No       |
| template <br/>       | `string` | [Template](./templates-and-roles) of the room. You can get template name from room details section on dashboard                                                                                                                                                                                              | No       |
| recording_info <br/> | `object` | Object of type `recording_info`. This object contains information for enabling recording/setting storage location for recordings.                                                                                                                                                                            | No       |
| region <br/>         | `string` | Region in which you want to create room - `in` - India region, `us` - US region or `auto` which stands for automatic region selection which happens also in case this parameter is not provided                                                                                                              | No       |


<Tab id="req-1">

<Response res="200: OK" />

```json
{
    "id": "5fd0cdeb7b86052f14384482",
    "name": "class_9_english_batch_2",
    "description": "Class 9 English Batch 2",
    "active": false,
    "recording_info": {
        "enabled": true,
        "upload_info": {
            "type": "s3",
            "location": "client-name-recordings"
        }
    },
    "user": "5fd0cc767b86052f1438447d",
    "customer": "5fd0cc767b86052f1438447e",
    "created_at": "2020-12-09T13:15:23.875Z",
    "updated_at": "2021-01-01T08:03:09.495990338Z",
    "template": "sample-template"
}
```

</Tab>

---

### recording_info
| Name        | Type      | Description                                                                                                                                                                                     | Required |
| :---------- | :-------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| enabled     | `boolean` | Enable recording. Disabled by default                                                                                                                                                           | No       |
| upload_info | `object`  | Object of type `upload_info`. This object contains information on recordings storage location. If you want to store recording with 100ms, and not use your own s3, don't add this to the object | No       |

To know more about recording please visit [Recording](./recording)

### upload_info
| Name        | Type     | Description                                                                                                                                                                                      | Required |
| :---------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| type        | `string` | Upload Destination type. Currently, only `s3` is supported                                                                                                                                       | Yes      |
| location    | `string` | Name of the AWS s3 bucket in which you want to store all recordings                                                                                                                              | Yes      |
| prefix      | `string` | Upload prefix path                                                                                                                                                                               | No       |
| options     | `object` | Options to be used for uploading i.e. region, ACLs etc                                                                                                                                           | No       |
| credentials | `object` | Object of type `Credentials`. This is used to share AWS credentials to access the s3 bucket specified.                                                                                           | No       |

### Credentials
| Name   | Type     | Description                                                                  | Required |
| :----- | :------- | :--------------------------------------------------------------------------- | :------- |
| key    | `string` | Access Key for the AWS account hosting the s3 bucket for recordings' storage | Yes      |
| secret | `string` | Secret for the AWS account hosting the s3 bucket for recordings' storage     | Yes      |


Room


## Introduction

Recording can be used to save audio/video calls for offline viewing. 100ms supports both individual and composite recordings.

## Types of recording

### Individual recording
Media for each peer is provided as a seperate mp4 file. This file will have both audio and video of the peer. These files can be used for offline review or in implementating custom composition.

### Composite recording
Audio and video of all peers is composed as per their joining/leaving the meeting and provided as a single mp4. This file can be used for offline viewing of the meeting.

## How to enable recording

### Using Dashboard
Recording can be enabled when creating a room
<Image width={2168} height={1212} alt="Enable recording when creating a room" src="/docs/v2/create-a-room.png" />

### Using API
- [See detailed API](/server-side/v2/features/room)

### Uploading destination configuration
By default recordings will be uploaded to 100ms storage and a presigned URL for the same will be provided to customers via a webhook. The presigned url will expire in 12hours.
Customers can also configure the recordings to be stored in thier cloud storage. Following are the configurations for the same.

| Name        | Type     | Description                                                                                                                                                                                      | Required |
| :---------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| type        | `string` | Upload Destination type. Currently, only `s3` is supported                                                                                                                                       | Yes      |
| location    | `string` | Name of the AWS s3 bucket in which you want to store all recordings                                                                                                                              | Yes      |
| prefix      | `string` | Upload prefix path                                                                                                                                                                               | No       |
| options     | `object` | Options to be used for uploading i.e. region, ACLs etc                                                                                                                                           | No       |
| credentials | `object` | Object of type `Credentials`. This is used to share AWS credentials to access the s3 bucket specified. Leave this blank if you are using an `IAM role` to provide 100ms access to your s3 bucket | No       |

Where `credentials` is

| Name   | Type     | Description                                                                  | Required |
| :----- | :------- | :--------------------------------------------------------------------------- | :------- |
| key    | `string` | Access Key for the AWS account hosting the s3 bucket for recordings' storage | Yes      |
| secret | `string` | Secret for the AWS account hosting the s3 bucket for recordings' storage     | Yes      |

Recording mp4 will be placed at - `s3://location/prefix/<room_id>/<start_date>/<session_id>/`


Recording


## Introduction

RTMP Streaming can be used to live stream your video conferencing apps to platforms like Facebook, YouTube, Twitch, etc.
Browser Recording can be used to record your video conferencing apps to a file, for subsequent access.
You can start either RTMP Streaming or Browser Recording or both for any room

## Pre-requisites

1. Management token

- [Click here to see how to generate management token](/server-side/v2/foundation/authentication-and-tokens)

2. Single click meeting url to directly enter a room

## APIs

### Start Streaming/Recording
<PostRequest
    desp="This endpoint is used to start live streaming/recording"
    url="https://prod-in2.100ms.live/api/v2/beam"
/>

<Tabs items={['Request', 'Response']} id="start" />

<div id="start-0">

#### Headers

| Name                           | Value                        | Required |
| :----------------------------- | :--------------------------- | :------- |
| Content-type <br/>             | application/json             | Yes      |
| Authorization <br/>            | Bearer `<management token>`  | Yes      |

#### Body Parameters

| Name              | Type     | Description                                                                                                                                                                                                                                                                                                 | Required |
| :---------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| operation <br/>   | `string` | Must be "start"                                                                                                                                                                                                                                                                                             | Yes      |
| room_id <br/>     | `string` | The room id of the room which we need to start streaming/recording                                                                                                                                                                                                                                          | Yes      |
| meeting_url <br/> | `string` | Single click meeting url which we need to start streaming/recording                                                                                                                                                                                                                                         | Yes      |
| rtmp_url <br/>    | `string` | The RTMP output url to which the meeting will be streamed. <br/> Required when RTMP streaming needs to be started. <br/> Supports `rtmp://` & `rtmps://`                                                                                                                                                    | No       |
| record <br/>      | `bool`   | Flag to enable browser recording                                                                                                                                                                                                                                                                            | No       |

#### cURL

```bash
curl \
    --location \
    --request POST 'https://prod-in2.100ms.live/api/v2/beam' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <management_token>' \
    --data-raw '{
        "operation": "start",
        "room_id": <rooom_id>,
        "meeting_url": <meeting_url>,
        "rtmp_url": <rtmp_url>,
        "record": true
    }'
```

</div>

<Tab id="start-1">
    <Response res="200: OK" resText="Beam has started successfully" />
</Tab>

---

### Stop Streaming/Recording
<PostRequest
    desp="This endpoint is used to stop live streaming/recording"
    url="https://prod-in2.100ms.live/api/v2/beam"
/>

<Tabs items={['Request', 'Response']} id="stop" />

<div id="stop-0">

#### Headers

| Name                           | Value                        | Required |
| :----------------------------- | :--------------------------- | :------- |
| Content-type <br/>             | application/json             | Yes      |
| Authorization <br/>            | Bearer `<management token>`  | Yes      |

#### Body Paramters

| Name              | Type     | Description                                                           | Required |
| :---------------- | :------- | :-------------------------------------------------------------------- | :------- |
| operation <br/>   | `string` | Must be "stop"                                                        | Yes      |
| room_id <br/>     | `string` | The room id of the room for which we need to stop streaming/recording | Yes      |

#### cURL

```bash
curl \
    --location \
    --request POST 'https://prod-in2.100ms.live/api/v2/beam' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <management_token>' \
    --data-raw '{
        "operation": "stop",
        "room_id": <rooom_id>
    }'
```

</div>

<Tab id="stop-1">
    <Response res="200: OK" resText="Beam has stopped successfully" />
</Tab>

## Postman Collection

<DownloadCollection type='rtmp' />


RTMP Streaming & Browser Recording


## Introduction

Simulcast enables applications to automatically adapt meeting experience across network fluctuations, changes in number of participants, rendering layout changes, etc.


## Usage

When simulcast is enabled, clients will send multiple video streams (or layers) at different quality and bitrate. Receivers can choose the most appropriate stream/layer depending on its bandwidth, display tile size, etc.
This will enable best call experience while considering the network bandwidth and display layout.



Simulcast


## Introduction

Webhook is an HTTP(S) endpoint used for pushing the notifications to your application. It will be invoked by 100ms servers to notify events of your room.

## Requirements
Webhook MUST implement `POST` HTTP method for receiving notifications. 100ms notifications are in JSON format so it should be handled accordingly. 

Additionally, you can specify headers which will be passed transparently to your webhook endpoint. This can be used for securing or tracing the origin of the request.

## How to configure Webhook
Webhook can be configured using [Developer](https://dashboard.100ms.live/developer) section of [100ms Dashboard](https://dashboard.100ms.live/)

![Webhook](/docs/v2/dashboard-webhook-configuration.png)

## Events
Event is a JSON dictionary which has following keys.

### Event Attributes
| Name       | Type         | Description                                                                                   | Example                              |
| :--------- | :----------- | :-------------------------------------------------------------------------------------------- | :----------------------------------- |
| version    | `string`     | Version of the event                                                                          | 2.0                                  |
| id         | `string`     | Id of the event                                                                               | bd0c76fd-1ab1-4d7d-ab8d-bbfa74b620c4 |
| app_id     | `string`     | App ID from which this event is generated                                                     | 5ff5881b80b66969e1fb35f6             |
| account_id | `string`     | App ID(Customer ID) from which this event is generated                                        | 5ff5881b80b66969e1fb35f4             |
| timestamp  | `timestamp`  | Timestamp of the event                                                                        | 2020-11-11T16:32:17Z                 |
| type       | `string`     | Type of the event                                                                             | peer.join.success                    |
| data       | `dict`       | Event data. Its keys will be different for different type of event. See the description below |                                      |

### Sample Event Payload
```json
{
   "version":"2.0",
   "id":"6c75de35-b778-4fb0-88ae-114c28dc285f",
   "account_id":"60b8e13a6eb86d8101b57354",
   "timestamp":"2021-08-08T07:04:15Z",
   "type":"peer.join.success",
   "data":{
      "joined_at":"2021-08-08T07:04:15.001380432Z",
      "peer_id":"83b869e1-9a4b-4037-84b2-913cf76e4392",
      "room_id":"60b8e13a6eb86d8101b57354",
      "session_id":"610f81ee870dde099a249948",
      "user_id":"test-user"
   }
}
```

### peer.join.success
This event will be send when any peer joins the room successfully

#### Attributes
| Name       | Type         | Description                                                                  | Example                              |
| :--------- | :----------- | :--------------------------------------------------------------------------- | :----------------------------------- |
| room_id    | `string`     | 100ms assigned room id                                                       | 5f9edc6ac238215aec2312df             |
| peer_id    | `string`     | 100ms assigned id to identify the joining user                               | bd0c76fd-1ab1-4d7d-ab8d-bbfa74b620c4 |
| joined_at  | `timestamp`  | Timestamp when user joined                                                   | 2020-11-11T16:32:17Z                 |
| room_name  | `string`     | Room name assigned by you when creating room                                 | class-9-batch-2                      |
| user_id    | `string`     | User id assigned by the customer                                             | user.001                             |
| session_id | `string`     | 100ms assigned id to identofy the session. A room can have multiple sessions | 5f9edc6bd238215aec7700df             |

### peer.leave.success
This event will be send when peer leaves the room

#### Attributes
| Name       | Type     | Description                                                                  | Example                              |
| :--------- | :------- | :--------------------------------------------------------------------------- | :----------------------------------- |
| room_id    | `string` | 100ms assigned room id                                                       | 5f9edc6ac238215aec2312df             |
| peer_id    | `string` | 100ms assigned id to identify the joining user                               | bd0c76fd-1ab1-4d7d-ab8d-bbfa74b620c4 |
| left_at    | `string` | Timestamp when user left                                                     | 2020-11-11T17:32:17Z                 |
| room_name  | `string` | Room name assigned by you when creating room                                 | class-9-batch-2                      |
| user_id    | `string` | User id assigned by customer                                                 | user.001                             |
| duration   | `number` | Duration the user spent in the room in seconds                               | 36000                                |
| session_id | `string` | 100ms assigned id to identofy the session. A room can have multiple sessions | 5f9edc6bd238215aec7700df             |

### recording.success
This event will be send when final composed recording is generated and uploaded to the destination

#### Attributes
| Name       | Type     | Description                                                                                    | Example                           |
| :--------- | :------- | :--------------------------------------------------------------------------------------------- | :-------------------------------- |
| room_id    | `string` | 100ms assigned room id                                                                         | 5f9edc6ac238215aec2312df          |
| room_name  | `string` | Room name assigned by you when creating room                                                   | class-9-batch-2                   |
| location   | `string` | s3 URI of the recorded video                                                                   | s3://bucket/prefix/ac.mp4         |
| URL        | `string` | Presigned s3 URL for the recorded video, for download. Valid for 24 hours                      | https://s3-location/bucket/ac.mp4 |
| duration   | `number` | Duration the user spent in the room in seconds                                                 | 3600                              |
| size       | `number` | Size of the recorded video (in bytes)                                                          | 10024                             |
| session    | `string` | 100ms assigned id identifying the session for the recording. A room can have multiple sessions | 5f9edc6bd238215aec7700df          |


Webhook


Three main sections here are:
[Adding Jitpack](#adding-jitpack) - Since you need to retrieve the 100ms Android SDK.
[Adding the 100ms SDK](#adding-the-100ms-sdk) - To add the SDK to your project's dependencies.
[Adding Permissions](#permissions) - Since a video calling app needs camera/record-audio permissions you'll need this for the apps to work.

### Adding Jitpack

The 100ms SDK is distributed via Jitpack.

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 the Shift key and typing `settings.gradle`. It will be in your project root.

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

```

### Adding the 100ms SDK
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).

You'll also need the webrtc dependency for the `org.webrtc.SurfaceViewRenderer` that's required to display people's videos.

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

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



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](https://docs.oracle.com/javase/8/docs/api/java/util/UUID.html#randomUUID--).
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, 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 -

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

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

```kotlin
  private val hmsSDK = HMSSDK
    .Builder(application)
    .build()
```

</Tab>

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

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

```

</Tab>

> 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

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

<Tab id="createconfig-0">

```kotlin
val hmsConfig = HMSConfig("user display name", authToken)
```

</Tab>

<Tab id="createconfig-1">

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

</Tab>

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

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

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

```kotlin
fun joinRoom(config : HMSConfig, hmsUpdateListener : HMSUpdateListener){
    hmsSDK.join(config, hmsUpdateListener)
}
```

</Tab>

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

```java
private void joinRoom(HMSConfig config, HMSUpdateListener hmsUpdateListener ) {
    hmsSdk.join(config, hmsUpdateListener);
}
```

</Tab>

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

Now, let's take a look at the signature of the Join API

```kotlin
fun join(config: HMSConfig, hmsUpdateListener: HMSUpdateListener)
```

As evident, `join` accepts 2 arguments -

-   `config`: an object of type `HMSConfig` class, the room configuration object which encapsulates user & token data.
-   `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.

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.



Once you're done with a call and want to exit, call leave on the HMSSDK instance you created to join it.

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

<Tab id='leave-0'>

```kotlin
hmsSDK.leave()
```
</Tab>

<Tab id='leave-1'>

```java
hmsSDK.leave();
```
</Tab>



Done with talking and it's time to end the video call room for everyone not just yourself? You may be looking to end the room.

### Permissions

Can't let just anyone end the video call room. 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 `PermissionsParams.endRoom` and you should check for that within the `HMSRole` of the peer to see if they have it.

Here's how to check whether the local peer has the permission to end the room:

<Tabs id="endroom" items={['Kotlin', 'Java 8', 'Java 7']} />

<Tab id='endroom-0'>

```kotlin
fun isAllowedToEndMeeting(): Boolean {
    return hmsSDK.getLocalPeer()!!
                .hmsRole.permission?
                .endRoom == true
}

```

</Tab>

<Tab id='endroom-1'>


 ```java
 private boolean hasEndRoomPermissions() {
    return Optional.ofNullable(hmsSdk.getLocalPeer())
            .map(HMSPeer::getHmsRole)
            .map(HMSRole::getPermission)
            .map(PermissionsParams::getEndRoom)
            .orElse(false);
 }
 ```

 </Tab>
 
<Tab id='endroom-2'>

```java
private boolean hasEndRoomPermissions() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if(peer != null) {
        HMSRole role = peer.getHmsRole();
        if(role != null) {
            PermissionsParams permissions = role.getPermission();
            if(permissions != null) {
                return permissions.getEndRoom();
            }
        }
    }
    return false;
}
```

</Tab>

`hmsSdk.getLocalPeer()` will not return null as long as you're in a preview or in a meeting. Since you likely won't need to check for permissions if you're not in one it would be ok.

### Ending the Room

Once you're sure the peer has the permissions to end the room, they can end it by calling `hmsSdk.endRoom`.

`endRoom` takes three parameters.

1. *message*: The String message you want to show people when they are forced to leave. This is a good place to thank them for joining the room and informing them that it has ended.
2. *lock*: A Boolean for 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 true, they will NOT able to join this room again.
3. *hmsActionResultListener*: These are the callbacks that let you know whether the room was ended successfully or not. If the room could be closed, `onSuccess` will be called. For any errors `onError` will be called with the appropriate `HMSException`.

> 💡 After calling endRoom the video calling UI should be disposed of as well since only the other peers will get the `onPeerRemoved` callback. The caller has to rely on the `onSuccess` callback for `endRoom` to decide when to terminate the meeting room UI locally.

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

<Tab id='endroomcall-0'>

```kotlin
val message = "Closing time. Thanks for coming!"
val lock = false

hmsSDK.endRoom(message, lock, object : HMSActionResultListener{
    override fun onError(error: HMSException) {
    }

    override fun onSuccess() {
    }
})
```
</Tab>

<Tab id='endroomcall-1'>


```java
String message = "Closing time. Thanks for coming!";
boolean lock = false;

hmsSDK.endRoom(message, lock, new HMSActionResultListener() {
    @Override
    public void onSuccess() {
        
    }

    @Override
    public void onError(@NonNull HMSException e) {

    }
});
```
</Tab>

### How to handle an end room callback for receivers

Once the peer with adequate permissions calls `endRoom`, all other peers in the room will receive a callback in `HMSUpdateListener.onRemovedFromRoom`.

The `onRemovedFromRoom` callback has a single parameter called `HMSRemovedFromRoom` with the following structure.

```kotlin
data class HMSRemovedFromRoom(
    val reason : String,
    val peerWhoRemoved : HMSRemotePeer?,
    val roomWasEnded : Boolean
)
```

> 💡 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.
* *peerWhoRemoved*: The details of the peer who called `endRoom`.
* *roomWasEnded*: 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.


## Latest Versions

| Package                    | Version                                                                                                                                |
| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| @100mslive/hms-video       | [![npm version](https://badge.fury.io/js/%40100mslive%2Fhms-video.svg)](https://badge.fury.io/js/%40100mslive%2Fhms-video)             |
| @100mslive/hms-video-react | [![npm version](https://badge.fury.io/js/%40100mslive%2Fhms-video-react.svg)](https://badge.fury.io/js/%40100mslive%2Fhms-video-react) |
| @100mslive/hms-video-store | [![npm version](https://badge.fury.io/js/%40100mslive%2Fhms-video-store.svg)](https://badge.fury.io/js/%40100mslive%2Fhms-video-store) |


## 2021-08-16
Released: `@100mslive/hms-video@0.0.148`, `@100mslive/hms-video-store@0.2.22`, `@100mslive/hms-video-react@0.3.32`.

#### Added
- Mute/unmute remote peers. [Refer Usage](/api-reference/javascript/v2/interfaces/HMSActions#set-remote-track-enabled)
- Remove peer from room. [Refer Usage](/api-reference/javascript/v2/interfaces/HMSActions#remove-peer)
- End room. [Refer Usage](/api-reference/javascript/v2/interfaces/HMSActions#remove-peer)
- Private Messages to peers/roles. 
    - [Direct Message to Peer](/api-reference/javascript/v2/interfaces/HMSActions#send-direct-message)
    - [Group Message to Role](/api-reference/javascript/v2/interfaces/HMSActions#send-group-message)
    - [Broadcast Message to everyone in the room](/api-reference/javascript/v2/interfaces/HMSActions#send-broadcast-message)

#### Breaking Change
- **sendMessage is now deprecated**, please use sendBroadcastMessage, sendGroupMessage and sendDirectMessage for messaging. [Refer Usage](/api-reference/javascript/v2/interfaces/HMSActions#send-broadcast-message)


## 0.0.128 - 2021-08-07
- Fix tracks not getting removed properly in Firefox in between role changes

## 0.0.127 - 2021-08-06
- Fix black tile issue

## 0.0.124 - 2021-08-06
- Export `HMSLogLevel` to set the HMSdk's log level.

## 0.0.123 - 2021-08-05

#### Added

-   Autoplay handling added.
    -   on autoplay error, the onError callback is called
    -   unblockAutoplay method is provided to resolve the autoplay error
    -   [Refer Usage](/javascript/v2/features/error-handling#handling-autoplay-error)
-   Audio/video state is preserved when setSettings is called.
-   Device change handling improvements
    -   Output device selection logic improved
    -   Handled headphones with no microphone
    -   Stereo headphones are handled correctly for input/output
-   Handle virtual background on role change
-   Cleanup video/audio elements to limit chrome 92 bug for mediaplayers

#### Fixed

-   Fix Settings component to show correct selected devices
-   Fix video elements not detached when not in view

## 2021-07-28

#### Added

-   Changing roles mid-call. [Refer Usage](/javascript/v2/features/change-tole)
-   BREAKING CHANGE: The interface of `HMSPeer` has been modified for users using the JavaScript SDK without the [Reactive Store](#).

```jsx
// Before
peer.role; // returns a string

// After
peer.role; // returns HMSRole

interface HMSRole {
    name: string;
    publishParams: PublishParams;
    subscribeParams: {
        subscribeToRoles: string[],
        maxSubsBitRate: number
    };
    permissions: {
        endRoom: boolean,
        removeOthers: boolean,
        stopPresentation: boolean,
        muteAll: boolean,
        askToUnmute: boolean,
        muteSelective: boolean,
        changeRole: boolean
    };
    priority: number;
}

export interface PublishParams {
    audio: {
        bitRate: number,
        codec: string
    };
    video: {
        bitRate: number,
        codec: string,
        frameRate: number,
        width: number,
        height: number
    };
    screen: {
        bitRate: number,
        codec: string,
        frameRate: number,
        width: number,
        height: number
    };
    allowed: string[];
}
```

-   BREAKING CHANGE: For users of the [Reactive Store](#) and [React SDK](#), the `HMSPeer` interface has been modified. Use `peer.roleName` instead of `peer.role` to obtain the name of a peer's role.

#### Fixed

-   Improved automatic detection of input/output devices.
-   Audio level update in Firefox due to wrong track ID.

#### Known Issues

-   Safari on Mac gives echo with some wired headphones
-   With some bluetooth headphones(eg: OnePlus Bullets) with stereo output option, the default audioOutput doesn't work on windows.
    (Quick Fix: Change device to another option of same device)

## 2021-07-17

#### Added

-   Added custom audio output management. [Refer Usage](/javascript/v2/advanced-features/volume-control)
-   Added audio output device and volume control using `hmsActions.setAudioOutputDevice("a-valid-MediaDeviceInfo-object-id")` and `hmsActions.setVolume(30)`. [Refer Usage](#)
-   Audio Level at preview could be fetched by `selectPeerAudioByID(localPeer.id)`.

#### Fixed

-   Audio level update callback in preview. [Refer Usage](/javascript/v2/advanced-features/audio-level)
-   **Experimental** Automatic device change on plug/unplug. Use `track.setSettings` to override input devices. [Refer Usage](/javascript/v2/features/device-change). Use audio output manager(`hms.getAudioOutput().setDevice()`) to override output devices. [Refer Usage](/javascript/v2/features/device-change)

## 2021-07-14

#### Versions

| Package                    | Version |
| -------------------------- | ------- |
| @100mslive/hms-video       | 0.0.79  |
| @100mslive/hms-video-react | 0.2.57  |

#### Added

-   Adjust remote peer volume locally
-   Add HMSPeer, HMSTrack objects to HMSSpeaker for use in `onAudioLevelUpdate` callback.

```ts
interface HMSSpeaker {
    peer: HMSPeer;
    track: HMSTrack;
    audioLevel: number;
}
```

-   Add HMSPolicy to HMSPeer.

#### Fixed

-   Analytics

## 2021-07-09

#### Added

-   New preview API.
-   Screenshare with Audio

#### Fixed

-   Analytics

## 2021-07-08

#### Added

-   Preview method to enable showing preview UI. [Refer Usage](/javascript/v2/features/preview)
-   Audio in screen-share

#### Fixed

-   Analytics

## 2021-07-02

#### Added

-   Enable OpusDtx
-   Replace HMSPeer with HMSLocalPeer and HMSRemotePeer
-   Made @100mslive/hms-video as peer dependency. Install `@100mslive/hms-video` alongside `@100mslive/hms-video-react` to use 100ms web SDK in your app.

For yarn,

```
yarn add @100mslive/hms-video @100mslive/hms-video-react
```

For npm,

```
npm i @100mslive/hms-video @100mslive/hms-video-react
```

-   Added transitionType property to hmsToast.

#### Fixed

-   Black tiles in Safari - Correctly queue messages when data channel not open
-   Retry Join Init API fetch failure and throw terminal error on retry failure
-   Silent Audio
-   Import problem in Angular - Replace Bowser with ua-parser-js
-   UI fixes in components.

## 2021-06-24

#### Added

-   Connection Reestablishment Mechanism.
-   On network switch, disconnection, Websocket signal, Publish and Subscribe ICE connections will be retried for reconnection
-   onReconnecting - called when reconnection starts
-   onReconnected - called when reconnection has succeeded
-   onError - called when reconnection has failed
    -   [Refer usage](/javascript/v2/features/notifications#notification-types)
-   Internal Bug fixes

## 2021-06-21

#### Added

-   addTrack and removeTrack to add/remove auxiliary tracks to local peer. [See documentation](/javascript/v2/advanced-features/custom-tracks).

## 2021-06-17

#### Added

-   Notifications [See Documentation](/javascript/v2/features/notifications)

## 2021-06-13

#### Fixed

-   Join with camera/microphone device failures.
-   Join with camera/microphone failures.
-   Preview shows correct error message.
-   Start preview if either of camera/microphone is available.
-   Stop preview when page goes into background.
-   UI Fixes in modal, chat.

## 2021-06-11

#### Versions

| Package                    | Version |
| -------------------------- | ------- |
| @100mslive/hms-video       | 0.0.26  |
| @100mslive/hms-video-react | 0.2.14  |

#### Added

-   HMSPeer object will now have `customerUserId` property that stores the `userId` from [Client Token](/javascript/v2/foundation/security-and-tokens).

#### Fixed

-   Removed unsupported deviceId constraint in Safari.
-   Use EventEmitter instead of EventTarget to support older versions of some browsers.
-   `selectDominantSpeaker` replaces `selectDominantSpeakerName`. `selectDominantSpeaker` will return a `HMSPeer` object which contains customerUserId, name, role.
-   More responsive UI for smaller screens.

## 2021-06-10

#### Added

-   Handle device change on mid-call.

#### Fixed

-   Video tile going black when double/multiple clicked for unmute.
-   Block on preview on camera/mic failure.

## 2021-06-09

#### Added

-   Support for Firefox$&gt;=60$.
-   Shim and polyfills for cross browser compatibility.
-   Exported `isSupported` method to check if browser and device are supported. `import { isSupported } from "@100mslive/hms-video";`

#### Fixed

-   Show dismissible warning for unsupported browsers in preview.
-   Export MessageModal component.

## 0.0.19 - 2021-06-02

#### Added

-   Error Codes - every error thrown from the SDK now will be of type HMSException, a wrapper over the native Error.

```typescript
interface HMSException {
    code: number; // A code number denoting the type of error
    name: string; // Name of the error
    action: string; // What action caused the error
    message: string; // Message related to the error
    description: string; // Additional information and steps to recover from the error
}
```

## 0.0.18 - 2021-06-02

#### Fixed

-   Screenshare permitted only when user's role is allowed to share screen.
-   Improved screenshare quality by removing maxBitrate limit.

## Alpha

Our alpha release is here.

Thanks for your patience :\).

This release might still have bugs, some interfaces can change $we will keep them to a minimum$

This release has

-   Simplified SDK interfaces that can power a fully-featured video conferencing application
    -   `join`
    -   `leave`
    -   `getPeers, getLocalPeer` for tracks/peers/other data
-   Features not covered in this release
    -   Handling network disconnections $disconnect from wi-fi to 4g ends the call$
    -   Handling subscription network degradations
    -   Handling second order publish network degradations
    -   Detailed analytics
    -   Recording
-   Our sample app is currently a React edtech app to demonstrate how roles work, and also how our UI-components work. Documentation for these roles will be released soon
-   Browser coverage is limited to latest versions of Chrome on desktop. We will improve this over the next few releases
-   Please contact @akash goswami in your Slack channel if you have any questions



## Introduction

Virtual background plugin helps in customising one’s background. The customising options are blurring the background or replacing it with a static image.
This guide provides an overview of usage of the virtual background plugin of 100ms.

![VirtualBackground](/docs/v2/virtual.gif)

## Supported Devices

Virtual background is currently only supported on web in Chrome, Firefox, Brave and Edge browsers.<br/>
We have not extended support for Mobile browsers in this release.

## Basic Concepts

-   `blur background` - This is an action where the background of the video is blurred. No external image is used/required.
-   `image background` - This is where the plugin will replace the video background with the image provided by user.
-   `plugin load time` - The time taken by plugin to load model. This is in the range of 3-5 seconds for first time. Subsequent loads take less than 100 milliseconds.

## Pre-requisites

**Get the 100ms VirtualBackground Package**

```bash
npm install --save @100mslive/hms-virtual-background@latest
```

## Import plugin

```jsx
import HMSVirtualBackgroundPlugin from '@100mslive/hms-virtual-background';
```

## Instantiate Virtual Background

This accepts background as a parameter, It can be of 3 types:

-  `blur` - String - This will set the background to blur
-  `image` - HTMLImageElement - This will replace the background to the image provide
-  `none` - String - This will remove the background effect from the video

```jsx
// background : {'blur' | image | 'none'}
const virtualBackground = new HMSVirtualBackgroundPlugin(background : {'blur' | image | 'none'});
```

## Interfaces

### Check if plugin is supported

isSupported can be used to check if the browser is supported or not.
It will return True/False based on browser.

```jsx
if (virtualBackground.isSupported()) {
  console.log('Platform is supported');
} else {
  console.log('Platform not supported');
}
```

### Init(Optional)

Init is used to load model of virtual background for the first time.
It takes on an average 3-5 seconds.<br/>
Calling init is handled internally by SDK if not done by user, in this case addPlugin call will
take 3-5 seconds for the first time and then less than 100 milliseconds in the subsequent calls.
Check [this section](#start-and-stop-virtual-background) for addPlugin API usage

```jsx
virtualBackground.init();
```

Init can also be used by user to show a loader icon for background selector component during the plugin loading stage

```jsx
virtualBackground.init().then(() => console.log('background can be changed now'));
```

### Start and Stop Virtual Background

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

Check [this section](#tuning-plugin-frame-rate-optional) to use custom pluginFrameRate

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

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

async function toggleVB() {
  const showBackground = hmsStore.getState(selectIsLocalVideoPluginPresent(virtualBackground.getName()));
  try {
    if (!showBackground) {
      // Recommended value
      const pluginFrameRate = 15;
      // add virtual background
      await hmsActions.addPluginToVideoTrack(virtualBackground, pluginFrameRate);
    } else {
      // remove virtual background
      await hmsActions.removePluginFromVideoTrack(virtualBackground);
    }
  } catch (err) {
    console.log('virtual background failure - ', showBackground, err);
  }
}
```

</Tab>

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

```jsx
import {
  useHMSStore,
  useHMSActions,
  selectIsLocalVideoPluginPresent
} from '@100mslive/hms-video-react';

function VirtualBackground() {
  const showBackground = useHMSStore(selectIsLocalVideoPluginPresent(virtualBackground.getName()));
  const hmsActions = useHMSActions();

  const toggleVB = async() => {
    try {
      if (!showBackground) {
        // Recommended value
        const pluginFrameRate = 15;
        await hmsActions.addPluginToVideoTrack(virtualBackground, pluginFrameRate);
      } else {
        await hmsActions.removePluginFromVideoTrack(virtualBackground);
      }
    } catch (err) {
      console.log('virtual background failure - ', showBackground, err);
    }
  }

  return <Button onClick={toggleVB} />;
}
```

</Tab>

### Change Background

The function `setBackground` can be used to update the background again later.
It accepts string or HTMLImageElement as a parameter
Image will get fit to the video by maintaining the aspect ratio.
If the aspect ratio of the background image is not the same as the video, the image will be cropped to fit in the background.

```jsx
// background parameter is explained in Instantiate Virtual Background section
try{
  virtualBackground.setBackground(background : {'blur' | image | 'none'});
}catch(err){
  console.log("Failed to update background", err);
}
```

### Tuning pluginFrameRate(Optional)

`pluginFrameRate`- number - pluginFrameRate helps in controlling the performance and experience of Virtual background plugin.
pluginFrameRate translates to the number of frames for which background is detected. Higher value will use more resources
(cpu/memory/battery), while making the virtual background experience smooth. Lower value will be generous on resources,
 while lowering the virtual background smoothness. Recommended value is 15. Values higher than this will not significantly
 improve virtual background smoothness but will be heavy on resources. For lower end devices value can be in the range of 7-10.


## Recommendations For Better User Experience

For enhancing the performance of virtual background plugin we recommend enabling SIMD on the browser.
With SIMD enabled, browsers can process multiple data points with each instruction, resulting in a performance boost of more than 2x.

-   `Chrome` - Open `chrome://flags/` in browser, search for simd, enable WebAssembly SIMD support and restart.
-   `Firefox`- Open `about:config` in browser, search for simd, set javascript.options.wasm_simd=true and restart.
-   `Edge` - Open `about:flags` in browser, search for simd, enable WebAssembly SIMD support and restart.
-   `Brave` - Open `about:flags` in browser, search for simd, enable WebAssembly SIMD support and restart.


Virtual Background


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) or remote (other people) peers' audio or video tracks.

You get a reference to your own local peer from `getLocalPeer` on `HMSSDK`.

You can do the same for remote peers and `HMSRemoteVideoTrack` and `HMSRemoteAudioTrack`. Get other people's peers by calling `hmsSDK.getRemotePeers()`

> 💡 You may get null for any track if they were not allowed to publish that track according to their `HMSRole`.

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

<Tab id='peer-0'>

```kotlin
val myPeer = hmsSDK.getLocalPeer()
myPeer?.videoTrack?.setMute(true)
myPeer?.audioTrack?.setMute(true)
```
</Tab>

<Tab id='peer-1'>

```java
HMSLocalPeer myPeer = hmssdk.getLocalPeer();
HMSLocalAudioTrack myAudioTrack = myPeer.getAudioTrack();
if(myAudioTrack != null) {
    myAudioTrack.setMute(true);
}

HMSLocalVideoTrack myVideoTrack = myPeer.getVideoTrack();
if(myVideoTrack != null) {
    myVideoTrack.setMute(true);
}
```
</Tab>




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.

You can see an example of every type of message (of the types below) being sent and displayed in the advanced [sample app](https://github.com/100mslive/100ms-android/).

### Addressing messages

* [Broadcast messages](#sending-broadcast-messages) are sent to Everyone in the chat `hmssdk.sendBroadcastMessage`.

* [Direct messages](#sending-direct-messages) are sent to a specific person `hmssdk.sendDirectMessage`.

* [Group messages](#sending-group-messages) are sent to everyone with a particular `HMSRole`. Such as all `hosts` or all `teachers` or all `students` `hmsSdk.sendGroupMessage`.
    * Learn more about [roles](../foundation/templates-and-roles) and how to create them on the backend.

### Sending Chat Messages

#### Sending Broadcast Messages

Want to let everyone in the chat know something? Call `sendBroadcastMessage` on the instance of `HMSSDK` to a send a broadcast.

The parameters are:

1. *textMessage*: The text of the message.
2. *type*: The type of the message, default is `HMSMessageType.CHAT`.
3. *hmsMessageResultListener*: An instance of `HMSMessageResultListener`.
    - `onSuccess` will be called when the server receives the request. The `onSuccess` contains a `HMSMessage` which has the updated `serverReceiveTime` a date containing the server timestamp.
    - `onError` will be called with an instane of `HMSException` detailing what went wrong.

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

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

<Tab id='broadcastmsg-0'>

```kotlin
hmssdk.sendBroadcastMessage(textMessage, HMSMessageType.CHAT,
    object : HMSMessageResultListener {
      override fun onError(error: HMSException) {
      }

      override fun onSuccess(hmsMessage: HMSMessage) {
      }
})
```
</Tab>

<Tab id='broadcastmsg-1'>

```java
hmssdk.sendBroadcastMessage(textMessage, HMSMessageType.CHAT,
    new HMSMessageResultListener() {
        @Override
        public void onSuccess(@NonNull HMSMessage hmsMessage) {
            
        }

        @Override
        public void onError(@NonNull HMSException e) {

        }
    }
);
```
</Tab>

#### 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 parameters are:

1. *textMessage*: The text of the message.
2. *type*: The type of the message, default is `HMSMessageType.CHAT`.
3. *peerTo*: The `HMSPeer` instance who should receive message.
4. *hmsMessageResultListener*: An instance of `HMSMessageResultListener`.
    - `onSuccess` will be called when the server receives the request. The `onSuccess` contains a `HMSMessage` which has the updated `serverReceiveTime` a date containing the server timestamp.
    - `onError` will be called with an instane of `HMSException` detailing what went wrong.

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

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

<Tab id='directmsg-0'>

```kotlin
fun sendDirectMessage(textMessage : String, recipient : HMSPeer) {
    hmssdk.sendDirectMessage(textMessage, HMSMessageType.CHAT, recipient, 
        object : HMSMessageResultListener {
            override fun onError(error: HMSException) {
            }

            override fun onSuccess(hmsMessage: HMSMessage) {
            }
            })
}
```

</Tab>

<Tab id='directmsg-1'>

```java
    private void sendDirectMessage(String textMessage, HMSPeer recipient ) {
        hmsSdk.sendDirectMessage(textMessage, HMSMessageType.CHAT, recipient, 
            new HMSMessageResultListener() {
                    @Override
                    public void onSuccess(@NonNull HMSMessage hmsMessage) {
                        
                    }

                    @Override
                    public void onError(@NonNull HMSException e) {

                    }
        }); 
    }
```

</Tab>


#### Sending Group Messages

Need to call attention to all the hosts? All the teachers? All the developers? Call `sendGroupMessage` on an instance of `HMSSDK`.

The parameters are:

1. *textMessage*: The text of the message.
2. *type*: The type of the message, default is `HMSMessageType.CHAT`.
3. *hmsRolesTo*: The `List<HMSRoles>` of all [roles](../foundation/templates-and-roles) which should receive the message.
4. *hmsMessageResultListener*: An instance of `HMSMessageResultListener`.
    - `onSuccess` will be called when the server receives the request. The `onSuccess` contains a `HMSMessage` which has the updated `serverReceiveTime` a date containing the server timestamp.
    - `onError` will be called with an instane of `HMSException` detailing what went wrong.

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

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

<Tab id='groupmsg-0'>

```kotlin

private fun sendGroupMessage(textMessage: String, recipients : List<HMSRole> ) {
    hmssdk.sendGroupMessage(message.message, HMSMessageType.CHAT, recipients, object : HMSMessageResultListener {
      override fun onError(error: HMSException) {
      }

      override fun onSuccess(hmsMessage: HMSMessage) {
      }

    })
  }

```

</Tab>

<Tab id='groupmsg-1'>

```java

private void sendGroupMessage(String textMessage, List<HMSRole> recipients) {
    hmsSdk.sendGroupMessage(textMessage, HMSMessageType.CHAT, recipients, 
            new HMSMessageResultListener() {
                @Override
                public void onSuccess(@NonNull HMSMessage hmsMessage) {
                    
                }
    
                @Override
                public void onError(@NonNull HMSException e) {
    
                }
    });
}

```

</Tab>

### Receiving Chat Messages

When you called `hmsSdk.join(config, hmsUpdateListener)` to join a room, the `HMSUpdateListener` implementation that was passed in had the callback `fun onMessageReceived(message: HMSMessage)`.

This where you'll receive new messages as `HMSMessage` during the call. It contains:

```kotlin

data class HMSMessage internal constructor(
  val message: String,
  val type: String,
  val recipient: HMSMessageRecipient = HMSMessageRecipient(),
  var serverReceiveTime: Date,
  var sender: HMSPeer
)
```

* message: Content of the text message or the text description of the raw message.
* type: Type of message sent. Default value is `HMSMessageType.CHAT`.
* recipient: The intended recipient(s) of this message as a `HMSMessageRecipient`.
* serverReceiveTime: timestamp of when the messaging server receives this message. Update the time in your own messages when this comes back from the server in `HMSUpdateListener.onMessageReceived` 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` as a Java Date.

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

#### 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:
```kotlin
class HMSMessageRecipient internal constructor(
    var recipientPeer: HMSPeer? = null,
    var recipientRoles: List<HMSRole> = mutableListOf(),
    var recipientType: HMSMessageRecipientType : HMSMessageRecipientType
)
```

recipientPeer: Only contains a peer when a specific single peer is being direct messaged.

recipientRoles: Only contains values when a group message is being sent to many roles.

recipientType: Will be `HMSMessageRecipientType.BROADCAST` for a message being sent to everyone. If this is true, the other two fields will be null and empty respectively.

`HMSMessageRecipientType.PEER` will be set when it's a direct message.

`HMSMessageRecipientType.ROLES` will be set when it's a message to one or many roles.

A good way to map this to your own app is a class like `Recipient` below. You could choose to copy this file into your code for the mapping.


```kotlin{17-23}:RecipientMapping.kt

sealed class Recipient {
    
    object Everyone : Recipient() {
        override fun toString(): String = "Everyone"
    }
    
    data class Role(val role : HMSRole) : Recipient() {
        override fun toString(): String =
            role.name
    }
    
    data class Peer(val peer : HMSPeer) : Recipient() {
        override fun toString(): String = peer.name
    }

    companion object {
        fun toRecipient(message : HMSMessageRecipient) : Recipient =
            when(message.recipientType) {
                HMSMessageRecipientType.BROADCAST -> Everyone
                HMSMessageRecipientType.PEER -> Peer(message.recipientPeer!!)
                HMSMessageRecipientType.ROLES -> Role(message.recipientRoles.firstOrNull()!!)
        }
    }
}
```

So that if you need to convert the message to your own class you can set the recipient like:

```kotlin{7}
override fun onMessageReceived(message: HMSMessage) {
    ChatMessage(
        message.sender.name,
        message.serverReceiveTime,
        message.message,
        false,
        recipient = Recipient.toRecipient(message.recipient)
    )
}
```


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 `preview` with `HMSConfig` and `HMSPreviewListener` as params.

```kotlin
hmsSDK.preview(config, hmsPreviewListener)
```

You would need the same config object that you would pass to [join API](Join).

`HMSPreviewListener` has one callback:

```kotlin
fun onPreview(room: HMSRoom, localTracks: Array<HMSTrack>)
```

Which is called when SDK has passed all its pre-flight checks and established the connection to 100ms server. This will pass an array of local audio/video tracks that you can display to the user (see [Render Video](Render-Video) and [Mute](Mute) sections for more details).



At the very least for rendering video you'll need an instance of `org.webrtc.SurfaceViewRenderer` and a `HMSVideoTrack` instance from a peer.

For the `SurfaceViewRenderer`, add the dependency `implementation 'org.webrtc:google-webrtc:1.0.32006'`.

In xml layouts it would look like

```xml
    <org.webrtc.SurfaceViewRenderer
        android:id="@+id/peerVideo"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        />
```

The peer's video is in `hmsPeer.videoTrack` and their ScreenShare video will be an instance of `HMSVideoTrack` in the list `hmsPeer.auxiliaryTracks`.

You would get them like so:

```kotlin
val hmsVideoTrack : HMSVideoTrack? = hmsPeer.videoTrack
```

### Getting and Preparing a SurfaceView

Get an instance of the SurfaceView.

```kotlin
val surfaceView : SurfaceViewRenderer = findViewById(R.id.surface_view)
```

Set the scaling to whatever you prefer. Aspect Fit is recommended for common use cases. See more scale types [here](https://chromium.googlesource.com/external/webrtc/trunk/talk/+/cdd35e557b600d1f7dbe9c99531a42adf194f973/app/webrtc/java/android/org/webrtc/RendererCommon.java#37).

```kotlin
surfaceView.setEnableHardwareScaler(true)
surfaceView.setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FIT)
```

### Adding a video to the SurfaceView

Each time you want to add a video to the surfaceview, it needs to be initialized again.

```kotlin
surfaceView.init(SharedEglContext.context, null)

val hmsVideoTrack : HMSVideotrack = hmsPeer.videoTrack
hmsVideoTrack?.addSink(surfaceView)
```

It's also important to remove it when done.

> 💡 Only the SharedEglContext.context can be used. Creating a new context will result in a black screen.

### Removing a video from the SurfaceView

It's very important to remove the video when you're done showing it, or before you show a different video on the same SurfaceViewRenderer.

```kotlin
hmsVideoTrack.removeSink(this)
surfaceView.release()
```
There is a limit to the number of `SharedEglContext`'s that can be bound per mobile device. It's normally high enough to easily accomodate all the videos that will reasonably fit on a screen. If the video's aren't released however, it becomes very easy to exceed this limit and the app will crash.

Until you call `removeSink` the video is being streamed over the device's data so it's also important remove sinks.

### Special cases for videos in RecyclerViews

If you're going to be using a RecyclerView to display multiple videos in a grid there are specific places where you should do these operations.

Currently the best known way is in the ViewHolder to have a method for binding items, a method to start the surfaceview and a method to release the surfaceview along a boolean check.

The Adapter calls bind item as usual but also stops the surfaceview when it binds. Two additional Adapter methods are overloaded. `onViewAttachedToWindow` and `onViewDetachedFromWindow` which will call SurfaceView binding and releasing respectively but while checking the `sinkAdded` property.

`sinkAdded` keeps track of whether a track was rendered to a Peer's surface view or not. Since someone might have turned off their video but still be speaking and so a tile might be shown with no video.

Complete source code is available [here](https://github.com/100mslive/hello-world-android).

#### PeerViewHolder

`init` Scaler types can be set here and don't need to be reset per `bind` call.

`startSurfaceView` will init the `SurfaceViewRenderer` and binding the track if one exists, this also sets the `sinkAdded` to true.

`stopSurfaceView` will release the `SurfaceViewRenderer` if there was a video attached and also remove the video sink.

```kotlin:PeerViewHolder.kt
class PeerViewHolder(view: View, private val getItem: (Int) -> TrackPeerMap) :
    RecyclerView.ViewHolder(view) {
    private val TAG = PeerViewHolder::class.java.simpleName
    private var sinkAdded = false

    init {
        itemView.findViewById<SurfaceViewRenderer>(R.id.videoSurfaceView).apply {
            setEnableHardwareScaler(true)
            setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FIT)
        }
    }

    fun startSurfaceView() {
        if (!sinkAdded) {
            itemView.findViewById<SurfaceViewRenderer>(R.id.videoSurfaceView).apply {

                getItem(adapterPosition).videoTrack?.let { hmsVideoTrack ->
                    init(SharedEglContext.context, null)
                    hmsVideoTrack.addSink(this)
                    sinkAdded = true
                }
            }
        }
    }

    fun stopSurfaceView() {
        itemView.findViewById<SurfaceViewRenderer>(R.id.videoSurfaceView).apply {

            if (sinkAdded && adapterPosition != -1) {
                getItem(adapterPosition).videoTrack?.let {
                    it.removeSink(this)
                    release()
                    sinkAdded = false
                }
            }
        }
    }

    fun bind(peer: TrackPeerMap) {

        if (!sinkAdded) {
            itemView.findViewById<SurfaceViewRenderer>(R.id.videoSurfaceView).apply {
                setEnableHardwareScaler(true)
                setScalingType(RendererCommon.ScalingType.SCALE_ASPECT_FIT)
                sinkAdded = false
            }
        }
        itemView.findViewById<TextView>(R.id.peerName).text = peer.peer.name
    }

}
```

#### PeerAdapter

The adapter stops the surface every time it binds. Starts it when the view is attached to the window, and stops it when the view is detached from the window. Also it passes its own getItem method to the PeerViewHolder in `onCreateViewHolder`.

```kotlin:PeerAdapter.kt

    override fun onBindViewHolder(holder: PeerViewHolder, position: Int) {
        getItem(position)?.let {
            holder.stopSurfaceView()
            holder.bind(it)
        }
    }

    override fun onViewAttachedToWindow(holder: PeerViewHolder) {
        super.onViewAttachedToWindow(holder)
        holder.startSurfaceView()
    }

    override fun onViewDetachedFromWindow(holder: PeerViewHolder) {
        super.onViewDetachedFromWindow(holder)
        holder.stopSurfaceView()
    }

    override fun onCreateViewHolder(parent: ViewGroup, viewType: Int): PeerViewHolder {
        val view =
            LayoutInflater.from(parent.context).inflate(R.layout.layout_peer_item, parent, false)
        return PeerViewHolder(view, ::getItem)
    }

```




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.
- All videos including your own are turned off.
- You are muted.

When the call ends the SDK will restore all videos, 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!


Someone's overstayed their welcome and now you need to remove a peer from the video call room. Just call `hmsSdk.removePeerRequest`.

### Permissions

Can't let just anyone remove others from the video call room. First you need to create a [role](../foundation/templates-and-roles) with the permissions to remove others.

In the SDK, the permission to remove others from the room is within `PermissionsParams` `removeOthers` and you should check for that within the `HMSRole` of the peer to see if they have it.

Here's how to check whether the local peer has the permission to end the room:

<Tabs id="removepeerperm" items={['Kotlin', 'Java 8', 'Java 7']} />

<Tab id='removepeerperm-0'>

```kotlin
fun isAllowedToRemovePeer(): Boolean {
    return hmsSDK.getLocalPeer()!!
                .hmsRole.permission?
                .removeOthers == true
}
```

</Tab>

<Tab id='removepeerperm-1'>

```java
private boolean isAllowedToRemovePeer() {
    return Optional.ofNullable(hmsSdk.getLocalPeer())
            .map(HMSPeer::getHmsRole)
            .map(HMSRole::getPermission)
            .map(PermissionsParams::getRemoveOthers)
            .orElse(false);
}
```

</Tab>

<Tab id='removepeerperm-2'>

```java
private boolean isAllowedToRemovePeer() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if(peer != null) {
        HMSRole role = peer.getHmsRole();
        if(role != null) {
            PermissionsParams permissions = role.getPermission();
            if(permissions != null) {
                return permissions.getRemoveOthers();
            }
        }
    }
    return false;
}
```

</Tab>

`hmsSdk.getLocalPeer()` will not return null as long as you're in a preview or in a meeting. Since you likely won't need to check for permissions if you're not in one it would be ok.

### Removing a peer

Once the permissions are checked to ensure the caller has the permission to remove a peer, remove them by calling `hmsSdk.removePeerRequest`.

The parameters are:

peer: is the `HMSRemotePeer` that you'd like to be removed from the video call room.

reason: is the string that should be conveyed to them as the reason for being removed.

hmsActionResultListener: is the listener that will convey the success or error of the server accepting the request.

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

<Tab id='removepeer-0'>

```kotlin
fun requestPeerLeave(peer: HMSRemotePeer, reason: String) {
    hmsSDK.removePeerRequest(peer, reason,
         object : HMSActionResultListener{
            override fun onError(error: HMSException) {
            }

            override fun onSuccess() {
            }
    })
  }

```

</Tab>

<Tab id='removepeer-1'>

```java
public void requestPeerLeave(HMSRemotePeer peer, String reason) {
    hmsSdk.removePeerRequest(peer, reason, new HMSActionResultListener() {
        @Override
        public void onSuccess() {

        }

        @Override
        public void onError(@NonNull HMSException e) {

        }
    });
}
```

</Tab>

### Handling the remove peer callback

The target of the `removePeerRequest` will receive a call in `HMSUpdateListener` of `onRemovedFromRoom(notification : HMSRemovedFromRoom)`.

The `HMSRemovedFromRoom` object which is passed into the callback has the structure:

```kotlin
data class HMSRemovedFromRoom(
    val reason : String,
    val peerWhoRemoved : HMSRemotePeer?,
    val roomWasEnded : Boolean
)
```

reason: Is the string that the caller of `removePeerRequest` sent as the reason they were being removed from the room.

peerWhoRemoved: Is an `HMSRemotePeer` instance containing the details of the person who called `removePeerRequest`. This can be used to show the name of the person who removed them.

roomWasEnded: This will be false if the peer was removed. If true, it indicates that the peer was not removed, but the entire room was ended. See [End Room](End-Room) for details.

When this callback is received, the UI should be cleaned up from the client side. The video call room would be ended from the SDK once this callback is sent.



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.

### Permissions

Can't let just anyone mute others. First you need to create a [role](../foundation/templates-and-roles) 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:

<Tabs id="muteunmute" items={['Kotlin', 'Java 8', 'Java 7']} />

<Tab id='muteunmute-0'>

```kotlin

fun isAllowedToMuteOthers(): Boolean {
    return hmsSDK.getLocalPeer()!!
                .hmsRole.permission?
                .mute == true
}

fun isAllowedToUnMuteOthers(): Boolean {
    return hmsSDK.getLocalPeer()!!
                .hmsRole.permission?
                .unmute == true
}

```

</Tab>

<Tab id='muteunmute-1'>

```java

private boolean hasMutePermissions() {
    return Optional.ofNullable(hmsSdk.getLocalPeer())
            .map(HMSPeer::getHmsRole)
            .map(HMSRole::getPermission)
            .map(PermissionsParams::getMute)
            .orElse(false);
}

private boolean hasUnMutePermissions() {
    return Optional.ofNullable(hmsSdk.getLocalPeer())
            .map(HMSPeer::getHmsRole)
            .map(HMSRole::getPermission)
            .map(PermissionsParams::getUnmute)
            .orElse(false);
}

```

</Tab>

<Tab id='muteunmute-2'>

```java

private boolean hasMutePermissions() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if (peer != null) {
        HMSRole role = peer.getHmsRole();
        if (role != null) {
            PermissionsParams permissions = role.getPermission();
            if (permissions != null) {
                return permissions.getMute();
            }
        }
    }
    return false;
}

private boolean hasUnMutePermissions() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if (peer != null) {
        HMSRole role = peer.getHmsRole();
        if (role != null) {
            PermissionsParams permissions = role.getPermission();
            if (permissions != null) {
                return permissions.getUnmute();
            }
        }
    }
    return false;
}

```

</Tab>


`hmsSdk.getLocalPeer()` will not return null as long as you're in a preview or in a meeting. Since you likely won't need to check for permissions if you're not in one it would be ok.

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

`hmsSdk.changeTrackState` takes three parameters:

hmsTrack: The `HMSTrack` that should be muted or unmuted. Can be audio or video.

mute: A `Boolean` where true indicates that it should be muted. false indicates that it should be unmuted.

hmsActionResultListener: A `HMSActionResultListener` instance which will receive `onSuccess` if the server acknowledges the the request as valid. `onError` if there was an exception along with the `HMSException` for it.

<Tabs id="audiomuteunmutecall" items={['Kotlin', 'Java 8', 'Java 7']} />

<Tab id='audiomuteunmutecall-0'>

```kotlin

fun changeAudioState(hmsRemotePeer: HMSRemotePeer, mute : Boolean) {
    val track = hmsRemotePeer.audioTrack
    if(track != null) {
        hmsSdk.changeTrackState(track, mute, object : HMSActionResultListener {
            override fun onError(error: HMSException) {
            }

            override fun onSuccess() {
            }

        })
    }
}
```

</Tab>

<Tab id='audiomuteunmutecall-1'>

```java

public void changeAudioState(HMSRemotePeer hmsRemotePeer, Boolean mute) {
        HMSRemoteAudioTrack track = hmsRemotePeer.getAudioTrack();
        if(track != null) {
            hmsSdk.changeTrackState(track, mute, new HMSActionResultListener() {
                @Override
                public void onSuccess() {
                    
                }

                @Override
                public void onError(@NonNull HMSException e) {

                }
            });
        }
    }
```

</Tab>

<Tab id='audiomuteunmutecall-2'>

```java

private boolean hasMutePermissions() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if(peer != null) {
        HMSRole role = peer.getHmsRole();
        if(role != null) {
            PermissionsParams permissions = role.getPermission();
            if(permissions != null) {
                return permissions.getMute();
            }
        }
    }
    return false;
}

private boolean hasUnMutePermissions() {
    HMSLocalPeer peer = hmsSdk.getLocalPeer();
    if(peer != null) {
        HMSRole role = peer.getHmsRole();
        if(role != null) {
            PermissionsParams permissions = role.getPermission();
            if(permissions != null) {
                return permissions.getUnmute();
            }
        }
    }
    return false;
}
```

</Tab>

Similarly the video track can be muted or unmuted.


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

<Tab id='videomuteunmutecall-0'>

```kotlin

fun changeAudioState(hmsRemotePeer: HMSRemotePeer, mute : Boolean) {
    val track = hmsRemotePeer.videoTrack
    if(track != null) {
        hmsSdk.changeTrackState(track, mute, object : HMSActionResultListener {
            override fun onError(error: HMSException) {
            }

            override fun onSuccess() {
            }

        })
    }
}
```

</Tab>

<Tab id='videomuteunmutecall-1'>

```java

public void changeAudioState(HMSRemotePeer hmsRemotePeer, Boolean mute) {
        HMSRemoteVideoTrack track = hmsRemotePeer.getVideoTrack();
        if(track != null) {
            hmsSdk.changeTrackState(track, mute, new HMSActionResultListener() {
                @Override
                public void onSuccess() {
                    
                }

                @Override
                public void onError(@NonNull HMSException e) {

                }
            });
        }
    }
```

</Tab>

### Handling a mute callback

Mute callbacks are automatically applied to the receiver. No action is required.

### Handling an unmute callback
Unmute callbacks are received in the target peer's `HMSUpdateListener.onChangeTrackStateRequest`.

The target peer will receive an object of `HMSChangeTrackStateRequest`.

Here's its structure.

```kotlin
data class HMSChangeTrackStateRequest(
    val track : HMSTrack,
    val requestedBy : HMSPeer,
    val mute : Boolean)
```

This contains information on which track is requested for unmuting. Check the track type and inform the user as appropriate.

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

<Tab id='trackcheck-0'>

```kotlin
fun checkTrack(track : HMSTrack) {
    if(track.type == HMSTrackType.AUDIO) {
        
    } else if (track.type == HMSTrackType.VIDEO) {
        
    }
}
```

</Tab>

<Tab id='trackcheck-1'>

```java
public void checkTrack(HMSTrack track) {
    if( track.getType() == HMSTrackType.AUDIO) {

    } else if (track.getType() == HMSTrackType.VIDEO) {
        
    }
}
```

</Tab>

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



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? (eg: 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 the `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 3 things.
- `remotePeer`: An instance of `HMSPeer` of the peer who's role you want to change.
- `toRole`: The `HMSRole` instance for the target role. 
- `force`: Whether you want to change their role without asking them or give them a chance to accept/reject.

All the peers that are in the current room are accessible via `getPeers` method of `HMSSDK` instance after a successful room join.

A list of all available roles in the current room can be accessed via the `getRoles` method of `HMSSDK`.

Once you have all you can invoke:

```kotlin
fun changeRole(remotePeer : HMSPeer, toRole: HMSRole, force: Boolean) {
    hmsSDK.changeRole(remotePeer, toRole, force)
}
```

If the change role succeeds you will get an update in the `HMSUpdateListener`:

```kotlin
fun onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer)
```

with the the same peer you passed as targetPeer and a `ROLE_CHANGED` update type.

The `force` parameter in `changeRole`, when false, 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 

```kotlin
fun onRoleChangeRequest(request: HMSRoleChangeRequest)
```

callback in `HMSUpdateListener`. At which point the app can choose to show a prompt to the user asking for permission. If the user accepts, app should call 

```kotlin
hmsSDK.acceptChangeRole(hmsRoleChangeRequest)
```

with the same request which it received in `onRoleChangeRequest` 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.


Can't share your screen from Android yet. We're always working on adding new features.



## Introduction

Virtual background plugin helps in customising one’s background. The customising options are blurring the background or replacing it with a static image.
This guide provides an overview of usage of the virtual background plugin of 100ms.

![VirtualBackground](/docs/v2/vb.gif)

## Supported Devices

Virtual background is currently only supported on web in Chrome, Firefox, Brave and Edge browsers.<br/>
We have not extended support for Mobile browsers in this release.

## Basic Concepts

-   `blur background`  - This is an action where the background of the video is blurred. No external image is used/required.
-   `image background` - This is where the plugin will replace the video background with the image provided by user.
-   `plugin load time` - The time taken by plugin to load model. This is in the range of 3-5 secs for first time. Subsequent loads take less than 100ms.

## Pre-requisites

**Get the 100ms VirtualBackground Package**

```bash
npm install --save @100mslive/hms-virtual-background@latest
```

## Import plugin

```jsx
import HMSVirtualBackgroundPlugin from "@100mslive/hms-virtual-background";
```

## Instantiate Virtual Background

This accepts background as a parameter, It can be of 3 types:
- `blur` - String - This will set the background to blur
- `image` - HTMLImageElement - This will replace the background to the imgSource provide
- `none` - String - This will remove the background effect from the video

```jsx
// background : {'blur' | image | 'none'}
const virtualBackground = new HMSVirtualBackgroundPlugin(background : {'blur' | image | 'none'});
```

## Check if plugin is supported

isSupported can be used to check if the browser is supported or not.
It will return True/False based on browser.

```jsx
if(virtualBackground.isSupported()){
    console.log("Platform is supported");
}else{
    console.log("Platform not supported");
}
```

## Init(Optional)

Init is used to load model of virtual background for the first time.
It takes on an average 3-5 secs.<br/>
Calling init is handled internally by SDK if not done by user, in this case addPlugin call will
take 3-5 secs for the first time and then less than 100ms in the Subsequent calls.
Check [this section](#add-and-remove-plugin) for addPlugin API usage

```jsx
virtualBackground.init();
```

Init can also be used by user to show a loader icon for background selector component during the plugin loading stage

```jsx
virtualBackground.init().then(() => console.log("background can be changed now"))
```

## Add and Remove Plugin

<Tabs id="plugin-code" items={['Store', 'React', 'SDK']} />

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

```js
// Import modules
import {hmsActions, hmsStore, selectIsLocalVideoPluginPresent } from "./hms";
```

```js
// This will apply the virtual background effect to the local video
try{
    await hmsActions.addPluginToVideoTrack(virtualBackground);
}catch(err){
    console.log("failed to add Plugin", err);
}
```

```js
// This will remove the virtual background effect from the local video
try{
    await hmsActions.removePluginFromVideoTrack(virtualBackground);
}catch(err){
    console.log("failed to remove Plugin", err);
}
```

```js
// To know the current plugins and if Virtual Background is part of it
// getName api can be used to get the name of the plugin
const isVBPresent = hmsStore.getState(
    selectIsLocalVideoPluginPresent(virtualBackground.getName())
);
if(isVBPresent){
    console.log("virtual background effect is applied to the local video");
}else{
    console.log("virtual background effect is removed from the local video");
}
```
</Tab>

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

```js
// Import modules
import { selectIsLocalVideoPluginPresent, useHMSStore, useHMSActions } from '@100mslive/hms-video-react';
import React, { useRef, useEffect } from 'react';
```

```js
function VirtualBackground() {
     const hmsActions = useHMSActions();
     const [showBackground, setShowBackground] = useState(false);

     useEffect(() => {
       if(showBackground){
           try{
                await hmsActions.addPluginToVideoTrack(virtualBackground);
           }catch(err){
                console.log("failed to add Plugin", err);
           }
       }else{
           try{
                await hmsActions.removePluginFromVideoTrack(virtualBackground);
           }catch(err){
                console.log("failed to remove Plugin", err);
           }
       }
     },[showBackground, hmsActions]);

     return(<Button onClick={() => setShowBackground(!showBackground)}/>)
}

export default VirtualBackground;
```

```js
// To know the current plugins and if Virtual Background is part of it
function checkIfPluginPresent(){
// getName api can be used to get the name of the plugin
    const isVBPresent = useHMSStore(
        selectIsLocalVideoPluginPresent(virtualBackground.getName())
    );
    if(isVBPresent){
        console.log("virtual background effect is applied to the local video");
    }else{
        console.log("virtual background effect is removed from the local video");
    }
}

export default checkIfPluginPresent;
```
</Tab>

<Tab id='plugin-code-2'>

```js
// This will apply the virtual background effect to the local video
try{
    await hms.getLocalPeer().videoTrack?.addPlugin(virtualBackground);
}catch(err){
    console.log("failed to add Plugin", err);
}
```

```js
// This will remove the virtual background effect from the local video
try{
    await hms.getLocalPeer().videoTrack?.removePlugin(virtualBackground);
}catch(err){
    console.log("failed to remove Plugin", err);
}
```

```js
// To know the current plugins and if virtual background is part of it
const videoTrack = hms.getLocalPeer().videoTrack;
const plugins =  videoTrack?.getPlugins();
const isVBApplied = plugins.includes(virtualBackground.getName());

if(isVBApplied){
    console.log("virtual background effect is applied to the local video");
}else{
    console.log("virtual background effect is removed from the local video");
}
```
</Tab>

## Change Background

Call setBackground from the plugin to update the background again later if required
It accepts string or HTMLImageElement as a parameter

Image will get fit to the video by maintaining the aspect ratio.
Input aspect ratio of the background image is preferred else we are cropping the image to fit in background

```jsx
// background parameter is explained in Instantiate Virtual Background section
try{
    virtualBackground.setBackground(background : {'blur' | image | 'none'});
}catch(err){
    console.log("Failed to update background", err);
}
```

## Recommendations For Better User Experience

For an enhanced virtual background plugin performance enable simd in browser

-  `Chrome` - Open `chrome://flags/` in browser, search for simd, enable WebAssembly SIMD support and restart.
-  `Firefox`- Open `about:config` in browser, search for simd, set javascript.options.wasm_simd=true and restart.
-  `Edge`   - Open `about:flags` in browser, search for simd, enable WebAssembly SIMD support and restart.
-  `Brave`  - Open `about:flags` in browser, search for simd, enable WebAssembly SIMD support and restart.

Getting Started - Virtual Background


## Introduction

This guide provides an overview of the key objects you'll use with 100ms' JavaScript SDK to build a live audio/video application

> If you haven't already done so, try our sample [quickstartapp](https://github.com/100mslive/100ms-web-v2). Then you can come back later to see how to build your own live audio/video app in more detail

## Supported Devices

Our alpha release has been tested on modern Chrome browsers. We will expand browser support to all modern browsers soon.

## Basic Concepts

-   `Room` - A room represents a real-time audio, video session, the basic building block of the 100ms Video SDK
-   `Track` - A track represents either the audio or video that makes up a peer's stream
-   `Peer` - A peer represents all participants connected to a room. Peers can be "local" or "remote"
-   `Broadcast` - A local peer can send any message/data to all remote peers in the room

## Pre-requisites

1. **Get the 100ms JS SDK**

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

2. **Get Access Keys**: You can get your access keys in the [Developer](https://dashboard.100ms.live/developer) section of [100ms dashboard](https://dashboard.100ms.live)

3. **Create a room and setup a token generation service**: To create a room, follow the steps described [in this section](/server-side/v2/features/room). To setup a token generation service, follow the steps in [this section](/server-side/v2/foundation/authentication-and-tokens). Alternatively, you can use our [quickstart server](/server-side/v2/guides/quickstart) for this.

## Import modules & instantiate 100ms Client

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

const hms = new HMSSdk();
```

## Provide joining configuration, add listeners and join a room

<Tabs id="join-room" items={['Joining code', 'Room,Peer,Track Interfaces', 'Update Types']} />{' '}

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

```jsx
const joinConfig = {
    userName: 'Erlich Bachmann',
    authToken: '<Auth token>', //This is the client-side token generated from your token service
    metaData: 'Custom description', //This is a custom data. You can send stringified JSON
    settings: {
        isAudioMuted: false,
        isVideoMuted: false
    }
};

const listener = {
    onJoin(room) {
        // 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
        // Parameter room: the room which was joined
        // For now, no events are sent to this callback. Leave this empty
    },
    onRoomUpdate(type, room) {
        // This is called when there is a change in any property of the Room. This is an advanced use case
        // Parameters:
        // type: the triggered update type. Should be used to perform different UI Actions
        // room: the room which was joined
        // check the type tab to see all types
    },
    onPeerUpdate(type, peer) {
        // 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
        // Parameters:
        // type: the triggered update type. Should be used to perform different UI Actions
        // peer: the peer who joined/left or was updated
        // .Usually a call to getPeers(), getLocalPeer() is needed here
        // check the type tab to see all types
    },
    onTrackUpdate(type, track, peer) {
        // 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
        // Parameters:
        // type: the triggered update type
        // track: the track which was added, removed or updated
        // peer: the peer for which track was added, removed or updated
        // Usually a call to getPeers(), getLocalPeer() is needed here
        // check the type tab to see all types
    },
    onMessageReceived(message) {
        // 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
        // Parameter message: the received broadcast message
    },
    onError(error) {
        // This will be called when there is an error in the system
        // and SDK has already retried to fix the error
        // Parameter error: the error that occured
    },
    onReconnecting(error: HMSException) {
        // This is called when connection reestablishment starts
        // This can be used to show a loading notification in the UI
        // Parameter error: the error from the action that failed and caused the connection reestablishment
    },
    onReconnected() {
        // This is called when the connection reestablishment completed susccessfully
    },
    onDeviceChange(deviceMap: DeviceMap): void {
        // This is called once after join is called and everytime a device is either added or removed
        // The deviceMap contains a map of all the devices connected
    },
    onRoleChangeRequest(request: HMSRoleChangeRequest): void {
        // This is called when a role change request is received from another user
        // Refer to the section involving changing roles mid-call below for more details
    }
};

function onAudioLevelUpdate(speakers) {
    // This is a separate listener that will be updated for listening to audio levels
    // This is optional
}

hms.join(joinConfig, listener);
hms.addAudioListener({ onAudioLevelUpdate: onAudioLevelUpdate });
```

</Tab>

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

```jsx
interface HMSPeer {
    peerId: string;
    name: string;
    isLocal: boolean;
    customerUserId?: string;
    customerDescription: string;
    videoTrack?: HMSTrack | null;
    audioTrack?: HMSTrack | null;
    auxiliaryTracks: HMSTrack[];
    role?: string;
}

interface HMSTrack {
    trackId: string;
    enabled: boolean;
    source?: HMSTrackSource;
    type: HMSTrackType;
    setEnabled(value: boolean): Promise<void>;
}

interface HMSSpeaker {
    peer: HMSPeer;
    track: HMSTrack;
    audioLevel: number;
}

interface HMSMessage {
    sender: string;
    receiver?: string;
    time: Date;
    type: HMSMessageType;
    message: string;
}

interface DeviceMap {
    audioInput: InputDeviceInfo[];
    audioOutput: MediaDeviceInfo[];
    videoInput: InputDeviceInfo[];
}

/**
 * This interface represents the role change request that is
 * sent to the users of the SDK.
 */
interface HMSRoleChangeRequest {
    requestedBy: HMSPeer;
    role: HMSRole;
    token: string;
}
```

</Tab>

<Tab id='join-room-2'>

```jsx

//this is the enum for type parameter in onPeerUpdate
enum HMSPeerUpdate {
    PEER_JOINED = 0,
    PEER_LEFT = 1,
    BECAME_DOMINANT_SPEAKER = 4,
    RESIGNED_DOMINANT_SPEAKER = 5,
    ROLE_UPDATED = 8
}

//this is the enum for type parameter in onTrackUpdate
enum HMSTrackUpdate {
    TRACK_ADDED = 0,
    TRACK_REMOVED = 1,
    TRACK_MUTED = 2,
    TRACK_UNMUTED = 3,
}

// There are other events yet to be implmeneted, which will fill in the enum gaps
```

</Tab>

## Get peers/tracks data

```jsx
const localPeer = hms.getLocalPeer();
const peers = hms.getPeers();
const localVideoTrack = localPeer.videoTrack;
```

## Render video

All audio tracks are rendered automatically by the SDK. As the developer, you just need to render the video track

```jsx
const localVideoTrack = localPeer.videoTrack;
const videoElement = document.getElementById('local-video-id');
localVideoTrack.addSink(videoElement);

//rendering code
<video id="local-video-id" autoplay muted></video>;
```

## Mute/unmute local tracks

```jsx
await localVideoTrack.setEnabled(false);
await localAudioTrack.setEnabled(false);

//On unmuting video, call addSink again to render the video
await localVideoTrack.setEnabled(true);
localVideoTrack.addSink(videoElement);
```

## Adjust remote peer volume

```jsx
const remotePeer = hms.getPeers().filter((peer) => !peer.isLocal)[0];
const remoteAudioTrack = remotePeer.audioTrack;
//mute
remoteAudioTrack.setVolume(0);
//unmute
remoteAudioTrack.setVolume(100);
// here we should probably use something between 0-100
remoteAudioTrack.setVolume(100);

// Get volume
remoteAudioTrack.getVolume();
```

## Sharing screen

```jsx
// Starting screenshare
hms.startScreenShare(onStop);
// onStop is the callback called if user stops the screenshare
// from the system prompt

// Stopping screenshare
hms.stopScreenShare();
```

## Sending and receiving messages

You can broadcase a message from local peer to all remote peers in the room.

When you(the local peer) receives a message from others(any remote peer), func `onMessageReceived(message: HMSMessage)` of
listener passed at the time of join is invoked.

```js
const message = "Hello World!"
sdk.sendMessage(HMSMessageType.CHAT, message)

function onMessageReceived(msg) {
    const sender = msg.sender; // peer id of sender
    const message = msg.message; // string message sent by remote
}
```

## Leave

```jsx
hms.leave();
```

## Managing roles

Roles define the permissions and the parameters for video, audio and screen of the users in the room.

The role of a user is attached to the `HMSPeer` object. Refer `HMSRole` interface in the next secion.

### Changing roles mid-call

In order to change the role of a remote peer during the call, you can use the `changeRole` method provided by the SDK.

#### Initiating a role-change request

<Tabs id="role-change" items={['Usage', 'Interface']} />

<Tab id="role-change-0">

```jsx
const roles: HMSRole[] = hms.getRoles(); // this returns a list of roles in the room
const peers = hms.getPeers();

// later in your code
/**
 * forPeer - HMSRemotePeer - The user whose role must be changed
 * newRole - String - The name of the new role
 * [force] - boolean - If true, the role change will be forced. false by default.
 */
hms.changeRole(forPeer, newRole, force);
```

</Tab>

<Tab id="role-change-1">

```jsx
interface HMSRole {
    name: string;
    publishParams: PublishParams;
    subscribeParams: {
        subscribeToRoles: string[],
        maxSubsBitRate: number
    };
    permissions: {
        endRoom: boolean,
        removeOthers: boolean,
        stopPresentation: boolean,
        muteAll: boolean,
        askToUnmute: boolean,
        muteSelective: boolean,
        changeRole: boolean
    };
    priority: number;
}

interface PublishParams {
    audio: {
        bitRate: number,
        codec: string
    };
    video: {
        bitRate: number,
        codec: string,
        frameRate: number,
        width: number,
        height: number
    };
    screen: {
        bitRate: number,
        codec: string,
        frameRate: number,
        width: number,
        height: number
    };
    allowed: string[];
}
```

</Tab>

> The SDK will throw an error if the user requesting the role change does not have permission to change roles. You can check if the user has permission to change role by checking `localPeer.permissions.changeRole`

#### Accepting a role-change request

A user will receive role-change requests via the [`listener`](#provide-joining-configuration-add-listeners-and-join-a-room) passed to `join` method.

In order to accept the request, call the `acceptRoleChange` method, passing the incoming request.

```jsx
/**
 * request: HMSRoleChangeRequest - The role change request to be accepted
 */
hms.acceptChangeRole(request);
```

On successful role change, the `onPeerUpdate` event will be fired for all the users connected to the room. The type of update would be `HMSPeerUpdate.ROLE_UPDATED` and the updated peer would also be passed to this callback.

> If the role change was forced, the user will not receive the request. Instead, `onPeerUpdate` will be fired for all the connected users and with modified role for the user concerned.

> In case of unforced change, the user can choose to reject the role change request by ignoring the `onRoleChangeRequest` event i.e. take no action when the event is fired.

## Advanced use cases

### Showing a preview screen before joining

To display a preview of your local stream before joining the call, you can use the `preview` method provided by the SDK.

This method does NOT publish this video to the room. Publishing is handled via the join method.

```jsx
const previewConfig = {
    userName: 'Erlich Bachmann', // If you choose to provide a name later, you can pass an empty string here
    authToken: '<Auth token>', //This is the client-side token generated from your token service
    settings: {
        isAudioMuted: false,
        isVideoMuted: false
    }
};

const previewListener = {
    onPreview(room, localTracks) {
        // localTracks contains the video and audio tracks of the user
        // Inside this callback you are safe to access local peer
        const localPeer = hms.getLocalPeer();

        const videoTrack = localPeer.videoTrack;

        videoTrack.addSink(document.getElementById('preview-video-id'));
    },
    onError(exception) {
        // this will be called if there were any errors accessing user's camera or mic
        // or if there is network disconnection
    },
    onDeviceChange(deviceMap: DeviceMap): void {
        // This is called once after preview is called and everytime a device is either added or removed
        // The deviceMap contains a map of all the devices connected
    }
};

hms.preview(previewConfig, previewListener);
hms.addAudioListener({ onAudioLevelUpdate: onAudioLevelUpdate });

<video id="preview-video-id" autoplay muted></video>;
```

You can use the [track methods](#mute-unmute-local-tracks) mentioned above to mute/unmute local tracks during preview.

### Changing mic/camera before/during the call

```jsx
//Changing before the call
const joinConfig = {
    userName: 'Erlich Bachmann',
    authToken: '<Auth token>', //This is the client-side token generated from your token service
    metaData: 'Custom description', //This is a custom data. You can send stringified JSON
    settings: {
        isAudioMuted: false,
        isVideoMuted: false,
        audioInputDeviceId: 'default';
        videoInputDeviceId: 'default';
    },
};
hms.join(joinConfig, listener);


//Changing midway during the call
localVideoTrack.setSettings({deviceId:'default'});
```

### Adding / removing auxiliary tracks

To add an auxiliary track$canvas capture, electron screen-share, etc...$, you can use the addTrack method provided by the SDK. This method adds the track to the local peer's list of auxiliary tracks and publishes it to make it available to remote peers.

```jsx
/**
 * track: MediaStreamTrack - Track to be added
 * source: 'regular' | 'screen' | 'plugin' - Source of track - default: 'regular'
 */
await hms.addTrack(track, source);
```

To remove an auxiliary track, you can use the removeTrack method provided by the SDK. This method removes the track from the local peer's list of auxiliary tracks and unpublishes it.

```jsx
// trackId: ID of the track to be removed
await hms.removeTrack(trackId);
```

> `removeTrack` removes the track only from the list of auxiliary tracks of the local peer. It doesn't remove/unpublish the `audioTrack`/ `videoTrack` of the local peer.

### Managing Audio Ouput

To customize the audio output device and volume, AudioOutputManager could be used.

<Tabs id="audio-output-manager" items={['Usage', 'Interface']} />

<Tab  id="audio-output-manager-0">

```jsx
const audioOutput = hms.getAudioOutput();
audioOutput.setDevice('a-device-id'); // deviceId of a valid MediaDeviceInfo
const device = audioOutput.getDevice();

audioOutput.setVolume(95);
const volume = audioOutput.getVolume();
```

</Tab>
<Tab  id="audio-output-manager-1">

```jsx
interface AudioOutputManager {
    /**
     * Get the currently used audio output device(speaker).
     */
    getDevice(): MediaDeviceInfo | undefined;
    /**
     * Set a particular speaker as audio output destination.
     * @param deviceId A valid MediaDeviceInfo object's deviceId
     */
    setDevice(deviceId: string): MediaDeviceInfo | undefined;
    /**
     * Get the overall output volume of the room. Returns number between 0-100.
     */
    getVolume(): number;
    /**
     * Set the overall output volume of the room.
     * @param value A number between 0-100.
     */
    setVolume(value: number): void;
    /**
     * This is to be called only after autoplay error is received
     * on some UI interaction
     */
    unblockAutoplay(): Promsie<void>;
}
```

</Tab>

> To set the output volume of a particular audio track[HMSAudioTrack], use `track.setVolume(95);` and use `track.getVolume();` to retrieve the current value.

### Handling Autoplay

Most modern browsers don't allow audio to be played without any interaction. on Autoplay error, we throw an error in `onError` handler passed to join/preview with an error code `3008`.

To unblock the autoplay error, use the following method on some UI interaction(eg: button click).

```jsx
await hms.getAudioOutput().unblockAutoplay();
```

### Setting Log Level

To set log level for logging only errors and warnings in production, use hms.setLogLevel.

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

hms.setLogLevel(HMSLogLevel.WARN); // Log warnings and errors
hms.setLogLevel(HMSLogLevel.ERROR); // Log only errors
```

```jsx
enum HMSLogLevel {
  VERBOSE,
  DEBUG,
  INFO,
  WARN,
  ERROR,
  NONE,
}
```


Getting Started - JavaScript

## 2.0.8 - 2021-08-17

### Added

-  Sending private and group messages APIs
-  Remove peer from a room API
-  Remote mute peer API
-  End room API

### Changed
-  send(message:) API renamed to sendBroadcastMessage

## 2.0.7 - 2021-08-06

### Fixed

-   Bug fixes in subscribe degradation
-   Bug fixes in role change
-   Bug fixes in onReconnection handling
-   Bug fix in incoming phone call handling

## 2.0.6 - 2021-07-27

### Fixed

-   Bugs in change role

### Added

-   Support for subscribe degradation

## 2.0.5 - 2021-07-20

### Added

-   HMSSpeaker contains HMSPeer instead of peerId
-   Support for changing of roles

## 2.0.4 - 2021-07-09

### Fixed

-   Crash fixes on leave and network change
-   Audio Routing to earpiece on interruption
-   No audio in BT headset on connecting disconnecting error
-   Check if role allows publishing in preview
-   Release camera on leave

### Added

-   SDK will handle all interruptions like incoming voice and VoIP calls
-   Pass HMSRole to client via HMSPeer

## 2.0.2 - 2021-06-30

### Fixed

-   Made `hmsSDK.getLocalpeer()` nullable
-   Fix logging bug
-   Fix bug where `ontrackUpdate` came before RTCTrack

## 2.0.1 - 2021-06-29

### Added

-   Retry when join call returns server error in 5xx or 429
-   `isTerminal` property to analytics

### Fixed

-   NPE Crash on SDKStore.getLocalPeer()
-   Unsupported notification message crash
-   Call onError callback in webrtc subscription failure

## 2.0.0-beta02 - 2021-06-24

### Added

-   Preview API
-   Enabled Opus dtx for audio
-   Added retry to INIT api call

## 2.0.0-beta01 - 2021-06-16

### Added

-   Proper error messages from client and server
-   Handling of bad network conditions by retrying inside SDK
-   Audio Manager is part of the SDK
-   Callbacks for `onReconnecting` and `onReconnected`
-   Added Analytics to track issues

## 2.0.0-alpha04 - 2021-06-04

### Added

-   Simplified SDK interfaces that can power a fully-featured video conferencing application
    -   `join`
    -   `leave`
    -   `listeners` for tracks/peers/other data
-   Features not covered in this release

    -   Handling network disconnections $disconnect from wi-fi to 4g ends the call$
    -   Handling subscription network degradations
    -   Handling second order publish network degradations
    -   Detailed analytics
    -   Recording

-   Please contact @akash goswami in your Slack channel if you have any questions


Android SDK

/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioDevice](../index)/[WIRED_HEADSET](index)

# WIRED_HEADSET

[androidJvm]\
[WIRED_HEADSET](index)


index

/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioDevice](../index)/[SPEAKER_PHONE](index)

# SPEAKER_PHONE

[androidJvm]\
[SPEAKER_PHONE](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioDevice](../index)/[NONE](index)

# NONE

[androidJvm]\
[NONE](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioDevice](../index)/[EARPIECE](index)

# EARPIECE

[androidJvm]\
[EARPIECE](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioDevice](../index)/[BLUETOOTH](index)

# BLUETOOTH

[androidJvm]\
[BLUETOOTH](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioDevice](index)/[values](values)

# values

[androidJvm]\
open fun [values](values)(): [Array](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-array/index.html)<[HMSAudioManager.AudioDevice](index)>


values

/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioDevice](index)/[valueOf](value-of)

# valueOf

[androidJvm]\
open fun [valueOf](value-of)(name: [String](https://developer.android.com/reference/kotlin/java/lang/String.html)): [HMSAudioManager.AudioDevice](index)


value of

/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioDevice](index)

# AudioDevice

[androidJvm]\
enum [AudioDevice](index)

AudioDevice is the names of possible audio devices that we currently support.

## Entries

|                                                  |                                                                    |
| ------------------------------------------------ | ------------------------------------------------------------------ |
| [SPEAKER_PHONE](-s-p-e-a-k-e-r_-p-h-o-n-e/index) | [androidJvm]<br />[SPEAKER_PHONE](-s-p-e-a-k-e-r_-p-h-o-n-e/index) |
| [WIRED_HEADSET](-w-i-r-e-d_-h-e-a-d-s-e-t/index) | [androidJvm]<br />[WIRED_HEADSET](-w-i-r-e-d_-h-e-a-d-s-e-t/index) |
| [EARPIECE](-e-a-r-p-i-e-c-e/index)               | [androidJvm]<br />[EARPIECE](-e-a-r-p-i-e-c-e/index)               |
| [BLUETOOTH](-b-l-u-e-t-o-o-t-h/index)            | [androidJvm]<br />[BLUETOOTH](-b-l-u-e-t-o-o-t-h/index)            |
| [NONE](-n-o-n-e/index)                           | [androidJvm]<br />[NONE](-n-o-n-e/index)                           |

## Functions

| Name                | Summary                                                                                                                                                                    |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [valueOf](value-of) | [androidJvm]<br />open fun [valueOf](value-of)(name: [String](https://developer.android.com/reference/kotlin/java/lang/String.html)): [HMSAudioManager.AudioDevice](index) |
| [values](values)    | [androidJvm]<br />open fun [values](values)(): [Array](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-array/index.html)<[HMSAudioManager.AudioDevice](index)>        |


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioManagerState](../index)/[UNINITIALIZED](index)

# UNINITIALIZED

[androidJvm]\
[UNINITIALIZED](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioManagerState](../index)/[RUNNING](index)

# RUNNING

[androidJvm]\
[RUNNING](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../../index)/[HMSAudioManager](../../index)/[AudioManagerState](../index)/[PREINITIALIZED](index)

# PREINITIALIZED

[androidJvm]\
[PREINITIALIZED](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioManagerState](index)/[values](values)

# values

[androidJvm]\
open fun [values](values)(): [Array](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-array/index.html)<[HMSAudioManager.AudioManagerState](index)>


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioManagerState](index)/[valueOf](value-of)

# valueOf

[androidJvm]\
open fun [valueOf](value-of)(name: [String](https://developer.android.com/reference/kotlin/java/lang/String.html)): [HMSAudioManager.AudioManagerState](index)


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioManagerState](index)

# AudioManagerState

[androidJvm]\
enum [AudioManagerState](index)

AudioManager state.

## Entries

|                                                      |                                                                        |
| ---------------------------------------------------- | ---------------------------------------------------------------------- |
| [UNINITIALIZED](-u-n-i-n-i-t-i-a-l-i-z-e-d/index)    | [androidJvm]<br />[UNINITIALIZED](-u-n-i-n-i-t-i-a-l-i-z-e-d/index)    |
| [PREINITIALIZED](-p-r-e-i-n-i-t-i-a-l-i-z-e-d/index) | [androidJvm]<br />[PREINITIALIZED](-p-r-e-i-n-i-t-i-a-l-i-z-e-d/index) |
| [RUNNING](-r-u-n-n-i-n-g/index)                      | [androidJvm]<br />[RUNNING](-r-u-n-n-i-n-g/index)                      |

## Functions

| Name                | Summary                                                                                                                                                                          |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [valueOf](value-of) | [androidJvm]<br />open fun [valueOf](value-of)(name: [String](https://developer.android.com/reference/kotlin/java/lang/String.html)): [HMSAudioManager.AudioManagerState](index) |
| [values](values)    | [androidJvm]<br />open fun [values](values)(): [Array](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-array/index.html)<[HMSAudioManager.AudioManagerState](index)>        |


/[lib](/api-reference/android/v2/home/content)/[live.hms.video.audio](../../index)/[HMSAudioManager](../index)/[AudioManagerEvents](index)/[onAudioDeviceChanged](on-audio-device-changed)

# onAudioDeviceChanged

[androidJvm]\
abstract fun [onAudioDeviceChanged](on-audio-device-changed)(selectedAudioDevice: [HMSAudioManager.AudioDevice](../-audio-device/index), availableAudioDevices: [Set](https://developer.android.com/reference/kotlin/java/util/Set.html)<[HMSAudioManager.AudioDevice](../-audio-device/index)>)
