
## Templates API

Apart from the dashboard, a programmatic way to interact with templates is via [API](/server-side/v2/policy/template-object).


Server Side API reference


## Protocols

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

## Classes

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

## Enums

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

## Extensions

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

## Structs

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

## Typealiases

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


iOS API reference


**CLASS**

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

## Properties

### bitRate

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

### codec

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


HMSAudioSettings


<Content alias="basics" />

### Quickstart

If you want to see 100ms' SDKs in action in under 5 minutes, run one of our quickstart [apps](/android/v2/guides/quickstart)


Basics


<Content alias="basics" />

### Quickstart

If you want to see 100ms' SDKs in action in under 5 minutes, run one of our quickstart [apps](../guides/quickstart)

### 100ms Flutter app

You can download & check out the 100ms Flutter app - 

🤖 The Flutter Android app from [Google Play Store here](https://play.google.com/store/apps/details?id=live.hms.flutter)

📱 Flutter iOS app from [Apple App Store here](https://apps.apple.com/app/100ms-live/id1576541989)


### Github Repo 
You can checkout the 100ms Flutter SDK Github repo which also contains a fully fledged [Example app implementation here](https://github.com/100mslive/100ms-flutter/) 


Basic Concepts


## 100ms API collection

TL;DR - You can directly use our Postman collection to start exploring 100ms APIs. 

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a?action=collection%2Ffork&collection-url=entityId%3D22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a%26entityType%3Dcollection%26workspaceId%3Dd9145dd6-337b-4761-81d6-21a30b4147a2)

Refer to the [Postman guide](/server-side/v2/introduction/postman-guide) to get started with 100ms API collection. 

### Authentication
100ms uses management tokens to authenticate REST APIs. The service required to generate this token should be hosted on your server. You must use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard to create the management token. Refer to the [authentication and tokens guide](/server-side/v2/introduction/authentication-and-tokens#code-sample-generate-management-token) for more information on generating the management token.

<Content alias="basics" />

### Quickstart

If you want to see 100ms' SDKs in action in under 5 minutes, run one of our quickstart [apps](/javascript/v2/guides/javascript-quickstart)

## API Overview

Create rooms, configure and maintain room policies and templates, start recording or RTMP streaming, and access events via 100ms' APIs. These APIs use standard HTTP verbs and HTTP status codes to make it simple to incorporate video into your code. We serve our API through HTTPS to secure your requests to our servers.

<BaseRequest
    title="https://api.100ms.live/{version}/"
/>

> **Note**: our current version is v2.

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a?action=collection%2Ffork&collection-url=entityId%3D22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a%26entityType%3Dcollection%26workspaceId%3Dd9145dd6-337b-4761-81d6-21a30b4147a2)

Refer to the [Postman guide](/server-side/v2/introduction/postman-guide) to get started with 100ms API collection. 


<Content alias="basics" />

### Quickstart

If you want to see 100ms' SDKs in action in under 5 minutes, run one of our quickstart [apps](../guides/quickstart)


### [Github Repo](https://github.com/100mslive/react-native-hms/)
You can checkout the 100ms React Native SDK Github repo which also contains a fully fledged [Example app implementation here](https://github.com/100mslive/react-native-hms/) 



### [Example App](https://github.com/100mslive/react-native-hms/tree/develop/example)

In the [100ms Example App](https://github.com/100mslive/react-native-hms/tree/main/example) we have shown how to setup the various listeners, what data to store in the redux and what all features you can implement.

We have also implemented multiple views which are commonly used. Checkout the [videos & relevant code in the Example app](https://github.com/100mslive/react-native-hms/tree/main/example#additional-features).



<Content alias="basics" />

### Quickstart

If you want to see 100ms' SDKs in action in under 5 minutes, run one of our quickstart [apps](/ios/v2/guides/quickstart)



<Content alias="basics" />

### Quickstart

If you want to see 100ms' SDKs in action in under 5 minutes, run one of our quickstart [apps](/javascript/v2/guides/javascript-quickstart)



<Content alias="templatesAndRoles" />

## API reference

Apart from the dashboard, a programmatic way to interact with templates is via [API](/server-side/v2/policy/template-object).


Templates and Roles


## Request

Our REST APIs enable you to access various capabilities to complete your integration based on the requirements for your use case.

<BaseRequest title="https://api.100ms.live/v2/" />

You can leverage these requests using the common HTTP methods:

1. **GET** - retrieves data from 100ms server. **Example**: Retrieve details of a specific room
2. **POST** - sends new data to 100ms server. **Example**: Create a room
3. **DELETE** - removes existing data from 100ms server. **Example**: Delete a role from a template.

### Content type

The input of the request should be of the type application/json. The payload for all POST requests should be passed as a JSON object with the Content-Type as `application/json`.

Most of the GET request arguments must be passed as a path param whereas some of the APIs accept it as a query param.

DELETE request arguments should be passed as a path param.

#### Headers

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

## Response

100ms API responds to all requests with a response in JSON format along with an HTTP status code to indicate whether the request was successful.

### HTTP status codes

All requests return one of these standard HTTP status codes

| Code               | Description                                                       |
| ------------------ | ----------------------------------------------------------------- |
| 200 - OK           | The request has succeeded.                                        |
| 204 - No Content   | Resource deleted.                                                 |
| 401 - Unauthorized | No valid API management token provided.                           |
| 403 - Forbidden    | The API management token provided doesn't have enough permission. |
| 404 - Not Found    | The request resource was not found.                               |
| 500 - Server Error | Something went wrong with 100ms servers. (These are rare).        |

### Errors

-   API responses with `4XX` and `5XX HTTP status codes` indicate that the request has failed.
-   `4XX`: This can be either 401 or 403 or 404. You can refer to the [status codes section](#http-status-codes) for more information. Also, the response body will contain the error message that will help to resolve the error and resend the request.

    #### Example:

    ```json
    {
        "code": 404,
        "message": "Error: Room not found",
        "data": {
            "description": "Error: Room not found"
        }
    }
    ```

-   `5XX`: Server errors. This happens when something is wrong with 100ms servers(these are rare).

## Pagination

All API resources support bulk fetches via “list” API methods (For example, list all rooms). These APIs use query parameters - limit, start, and last - to support pagination.

To fetch the first page of 10 objects, set `limit=10` as a query param. This API will respond with a list of objects in key `data`. The response also has key `last` with the unique identifier for the last object in `data`.

To fetch the second page of 10 objects (11 to 20), pass the previous `last` value as the `start` query param. Set `limit = 10` and `start = &lt;last value from previous response&gt;`.

### List API response variables

| Name        | Type       | Description                                                                                                            |
| :---------- | :--------- | :--------------------------------------------------------------------------------------------------------------------- |
| limit <br/> | `int`      | Number of objects the API tried to find. If returned array has lesser number of results, only those number were found. |
| data <br/>  | `array`    | Array of objects.                                                                                                      |
| last <br/>  | `ObjectID` | The last object in the list of objects in the response. Can be used as `start` for subsequent request.                 |

### Params used for pagination

| Name  | Type     | Description                                                                                            |
| :---- | :------- | :----------------------------------------------------------------------------------------------------- |
| limit | `int`    | A limit on the number of objects to be returned.<br/> `Default value`: 10<br/> `Allowed range`: 10-100 |
| start | `object` | Determines the starting point in the list of objects to be returned in the response.                   |


Request/Response


<Content alias="securityAndTokens" />

## App Token

100ms _client-side SDKs_ use App Tokens to authenticate a peer (participant) while [joining a room](/android/v2/features/join). Generate this token on the server-side and make it available for your client-side apps that use the 100ms SDKs.

-   To create the App Token, use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard.
-   **room_id**: This is the unique identifier for your room. You can get it from the [rooms page](https://dashboard.100ms.live/rooms) in your dashboard or in the response payload of the [create room server-side API](/server-side/v2/Rooms/create-via-api).
-   **user_id**: This identifier can be used to map a 100ms peer to your own internal user object for business logic. Specify your internal user identifier as the peer’s user_id. If not available, use any random string.

### Code sample: Generate app token

<Tabs id="client-code-token" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='client-code-token-0'>

```javascript
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

var payload = {
    access_key: app_access_key,
    room_id: '<room_id>',
    user_id: '<user_id>',
    role: '<role>',
    type: 'app',
    version: 2,
    iat: Math.floor(Date.now() / 1000),
    nbf: Math.floor(Date.now() / 1000)
};

jwt.sign(
    payload,
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='client-code-token-1'>

```python
#!/usr/bin/env python3
import jwt
import uuid
import datetime
import sys

app_access_key = "<app_access_key>"
app_secret = "<app_secret>"

def generate(room_id, user_id, role):
    expires = expires or 24 * 3600
    now = datetime.datetime.utcnow()
    exp  = now+ datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
                "access_key": app_access_key,
                "type":"app",
                "version":2,
                "room_id": room_id,
                "user_id": user_id,
                "role":role,
                "jti": str(uuid.uuid4()),
                "exp": exp,
                "iat": now,
                "nbf": now,
                }, key=app_secret)
if __name__ == "__main__":
    if len(sys.argv) == 3:
        room_id = sys.argv[0]
        user_id = sys.argv[1]
        role = sys.argv[2]
    print(generate(room_id=room_id, user_id=user_id, role=role))
```

</Tab>

<Tab id='client-code-token-2'  >

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateHmsClientToken() {
    Map<String, Object> payload = new HashMap<>();
    payload.put("access_key", "<app_access_key>");
    payload.put("room_id", "<room_id>");
    payload.put("user_id", "<user_id>");
    payload.put("role", "<role>");
    payload.put("type", "app");
    payload.put("version", 2);
    String token = Jwts.builder().setClaims(payload).setId(UUID.randomUUID().toString())
        .setExpiration(new Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(new Date(System.currentTimeMillis()))
        .signWith(SignatureAlgorithm.HS256, "<app_secret>".getBytes()).compact();
  }
```

</Tab>

<Tab id='client-code-token-3'  >

```ruby
require 'jwt'
require 'securerandom'



$app_access_key = "<app_access_key>"
$app_secret = "app_secret"

def generateAppToken(room_id, user_id, role)
    now = Time.now
    exp = now + 86400
    payload = {
        access_key: $app_access_key,
        room_id: room_id,
        user_id: user_id,
        role: role,
        type: "app",
        jti: SecureRandom.uuid,
        version: 2,
        iat: now.to_i,
        nbf: now.to_i,
        exp: exp.to_i
    }

    token = JWT.encode(payload, $app_secret, 'HS256')
end

puts generateAppToken "<room_id>", "<user_id>", "<role>"

```

</Tab>

<Tab id='client-code-token-4'>

```php
<?php

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$issuedAt  = new DateTimeImmutable();
$expire    = $issuedAt->modify('+24 hours')->getTimestamp();
$accessKey = "<app_access_key>";
$secret = "<app_secret>";
$version   = 2;
$type      = "app";
$role      = "<role>";
$roomId    = "<room_id>";
$userId    = "<user_id>";

$payload = [
    'iat'  => $issuedAt->getTimestamp(),
    'nbf'  => $issuedAt->getTimestamp(),
    'exp'  => $expire,
    'access_key' => $accessKey,
    'type' => "app",
    'jti' =>  Uuid::uuid4()->toString()
    'version' => 2,
    'role' => $role,
    'room_id' => $roomId,
    'user_id' => $userId
];

$token = JWT::encode(
    $payload,
    $secret,
    'HS256'
);
```

</Tab>

<Note>

**Warning**

Your app key and secret carry many privileges, please ensure to keep them secure.

</Note>

## Management Token

For setting up management tokens for server side API requests, please refer to the [authentication guide](/server-side/v2/introduction/authentication-and-tokens) in server-side API section.


Authentication and Tokens


<Content alias="securityAndTokens" />

## App Token

100ms _client-side SDKs_ use App Tokens to authenticate a peer (participant) while [joining a room](/flutter/v2/features/join). Generate this token on the server-side and make it available for your client-side apps that use the 100ms SDKs.

-   To create the App Token, use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard.
-   **room_id**: This is the unique identifier for your room. You can get it from the [rooms page](https://dashboard.100ms.live/rooms) in your dashboard or in the response payload of the [create room server-side API](/server-side/v2/Rooms/create-via-api).
-   **user_id**: This identifier can be used to map a 100ms peer to your own internal user object for business logic. Specify your internal user identifier as the peer’s user_id. If not available, use any random string.

### Code sample: Generate app token

<Tabs id="client-code-token" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='client-code-token-0'>

```javascript
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

var payload = {
    access_key: app_access_key,
    room_id: '<room_id>',
    user_id: '<user_id>',
    role: '<role>',
    type: 'app',
    version: 2,
    iat: Math.floor(Date.now() / 1000),
    nbf: Math.floor(Date.now() / 1000)
};

jwt.sign(
    payload,
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='client-code-token-1'>

```python
#!/usr/bin/env python3
import jwt
import uuid
import datetime
import sys

app_access_key = "<app_access_key>"
app_secret = "<app_secret>"

def generate(room_id, user_id, role):
    expires = expires or 24 * 3600
    now = datetime.datetime.utcnow()
    exp  = now+ datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
                "access_key": app_access_key,
                "type":"app",
                "version":2,
                "room_id": room_id,
                "user_id": user_id,
                "role":role,
                "jti": str(uuid.uuid4()),
                "exp": exp,
                "iat": now,
                "nbf": now,
                }, key=app_secret)
if __name__ == "__main__":
    if len(sys.argv) == 3:
        room_id = sys.argv[0]
        user_id = sys.argv[1]
        role = sys.argv[2]
    print(generate(room_id=room_id, user_id=user_id, role=role))
```

</Tab>

<Tab id='client-code-token-2'  >

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateHmsClientToken() {
    Map<String, Object> payload = 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(Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(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  = 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>

<Note>

**Warning**

Your app key and secret carry many privileges, please ensure to keep them secure.

</Note>

## Management Token

For setting up management tokens for server side API requests, please refer to the [authentication guide](/server-side/v2/introduction/authentication-and-tokens) in server-side API section.



## Management Token
100ms uses management tokens to authenticate REST APIs. The service required to generate this token should be hosted on your server. You must use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard to create the management token.

### Code sample: Generate management token

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

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

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

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

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

</Tab>

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

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

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


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

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

</Tab>

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

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

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

</Tab>

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

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

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

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

puts generateManagementToken
```

</Tab>

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

```php
<?php

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

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

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

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

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

</Tab>

<Note>

**Warning**

Your app key and secret carry many privileges, please ensure to keep them secure. All requests must be made over HTTPS. Requests made over plain HTTP and without a management token will fail.
</Note>

## App token

For setting up app tokens for client apps, please refer to the [authentication guide](/javascript/v2/foundation/security-and-tokens) in client SDK section.

Authentication and tokens


<Content alias="securityAndTokens" />

## App Token

100ms _client-side SDKs_ use App Tokens to authenticate a peer (participant) while [joining a room](/react-native/v2/features/join). Generate this token on the server-side and make it available for your client-side apps that use the 100ms SDKs.

- To create the App Token, use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard.
- **room_id**: This is the unique identifier for your room. You can get it from the [rooms page](https://dashboard.100ms.live/rooms) in your dashboard or in the response payload of the [create room server-side API](/server-side/v2/Rooms/create-via-api).
- **user_id**: This identifier can be used to map a 100ms peer to your own internal user object for business logic. Specify your internal user identifier as the peer’s user_id. If not available, use any random string.

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

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

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

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

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

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

</Tab>

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

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

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

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

</Tab>

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

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

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

</Tab>

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

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



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

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

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

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

```

</Tab>

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

```php
<?php

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

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

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

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

</Tab>

<Note>

**Warning**

Your app key and secret carry many privileges, please ensure to keep them secure.

</Note>

## Management Token

For setting up management tokens for server side API requests, please refer to the [authentication guide](/server-side/v2/introduction/authentication-and-tokens) in server-side API section.



<Content alias="securityAndTokens" />

## App Token

100ms _client-side SDKs_ use App Tokens to authenticate a peer (participant) while [joining a room](/ios/v2/features/join). Generate this token on the server-side and make it available for your client-side apps that use the 100ms SDKs.

-   To create the App Token, use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard.
-   **room_id**: This is the unique identifier for your room. You can get it from the [rooms page](https://dashboard.100ms.live/rooms) in your dashboard or in the response payload of the [create room server-side API](/server-side/v2/Rooms/create-via-api).
-   **user_id**: This identifier can be used to map a 100ms peer to your own internal user object for business logic. Specify your internal user identifier as the peer’s user_id. If not available, use any random string.

### Code sample: Generate app token

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

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

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

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

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

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

</Tab>

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

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

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

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

</Tab>

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

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

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

</Tab>

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

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



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

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

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

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

```

</Tab>

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

```php
<?php

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

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

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

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

</Tab>

<Note>

**Warning**

Your app key and secret carry many privileges, please ensure to keep them secure.

</Note>

## Management Token

For setting up management tokens for server side API requests, please refer to the [authentication guide](/server-side/v2/introduction/authentication-and-tokens) in server-side API section.



<Content alias="securityAndTokens" />

## App Token

100ms _client-side SDKs_ use App Tokens to authenticate a peer (participant) while [joining a room](/javascript/v2/features/join). Generate this token on the server-side and make it available for your client-side apps that use the 100ms SDKs.

-   To create the App Token, use the `app_access_key` and `app_secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard.
-   **room_id**: This is the unique identifier for your room. You can get it from the [rooms page](https://dashboard.100ms.live/rooms) in your dashboard or in the response payload of the [create room server-side API](/server-side/v2/Rooms/create-via-api).
-   **user_id**: This identifier can be used to map a 100ms peer to your own internal user object for business logic. Specify your internal user identifier as the peer’s user_id. If not available, use any random string.

### Code sample: Generate app token

<Tabs id="client-code-token" items={['Node.js', 'Python', 'Java', 'Ruby', 'PHP']} />

<Tab id='client-code-token-0'>

```javascript
var jwt = require('jsonwebtoken');
var uuid4 = require('uuid4');

var app_access_key = '<app_access_key>';
var app_secret = '<app_secret>';

var payload = {
    access_key: app_access_key,
    room_id: '<room_id>',
    user_id: '<user_id>',
    role: '<role>',
    type: 'app',
    version: 2,
    iat: Math.floor(Date.now() / 1000),
    nbf: Math.floor(Date.now() / 1000)
};

jwt.sign(
    payload,
    app_secret,
    {
        algorithm: 'HS256',
        expiresIn: '24h',
        jwtid: uuid4()
    },
    function (err, token) {
        console.log(token);
    }
);
```

</Tab>

<Tab id='client-code-token-1'>

```python
#!/usr/bin/env python3
import jwt
import uuid
import datetime
import sys

app_access_key = "<app_access_key>"
app_secret = "<app_secret>"

def generate(room_id, user_id, role):
    expires = expires or 24 * 3600
    now = datetime.datetime.utcnow()
    exp  = now+ datetime.timedelta(seconds=expires)
    return jwt.encode(payload={
                "access_key": app_access_key,
                "type":"app",
                "version":2,
                "room_id": room_id,
                "user_id": user_id,
                "role":role,
                "jti": str(uuid.uuid4()),
                "exp": exp,
                "iat": now,
                "nbf": now,
                }, key=app_secret)
if __name__ == "__main__":
    if len(sys.argv) == 3:
        room_id = sys.argv[0]
        user_id = sys.argv[1]
        role = sys.argv[2]
    print(generate(room_id=room_id, user_id=user_id, role=role))
```

</Tab>

<Tab id='client-code-token-2'  >

```java
import java.time.Instant;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;
import java.util.UUID;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;

private void generateHmsClientToken() {
    Map<String, Object> payload = new HashMap<>();
    payload.put("access_key", "<app_access_key>");
    payload.put("room_id", "<room_id>");
    payload.put("user_id", "<user_id>");
    payload.put("role", "<role>");
    payload.put("type", "app");
    payload.put("version", 2);
    String token = Jwts.builder().setClaims(payload).setId(UUID.randomUUID().toString())
        .setExpiration(new Date(System.currentTimeMillis() + 86400 * 1000))
        .setIssuedAt(Date.from(Instant.ofEpochMilli(System.currentTimeMillis() - 60000)))
        .setNotBefore(new Date(System.currentTimeMillis()))
        .signWith(SignatureAlgorithm.HS256, "<app_secret>".getBytes()).compact();
  }
```

</Tab>

<Tab id='client-code-token-3'  >

```ruby
require 'jwt'
require 'securerandom'



$app_access_key = "<app_access_key>"
$app_secret = "app_secret"

def generateAppToken(room_id, user_id, role)
    now = Time.now
    exp = now + 86400
    payload = {
        access_key: $app_access_key,
        room_id: room_id,
        user_id: user_id,
        role: role,
        type: "app",
        jti: SecureRandom.uuid,
        version: 2,
        iat: now.to_i,
        nbf: now.to_i,
        exp: exp.to_i
    }

    token = JWT.encode(payload, $app_secret, 'HS256')
end

puts generateAppToken "<room_id>", "<user_id>", "<role>"

```

</Tab>

<Tab id='client-code-token-4'>

```php
<?php

use Firebase\JWT\JWT;
use Ramsey\Uuid\Uuid;

$issuedAt  = new DateTimeImmutable();
$expire    = $issuedAt->modify('+24 hours')->getTimestamp();
$accessKey = "<app_access_key>";
$secret = "<app_secret>";
$version   = 2;
$type      = "app";
$role      = "<role>";
$roomId    = "<room_id>";
$userId    = "<user_id>";

$payload = [
    'iat'  => $issuedAt->getTimestamp(),
    'nbf'  => $issuedAt->getTimestamp(),
    'exp'  => $expire,
    'access_key' => $accessKey,
    'type' => "app",
    'jti' =>  Uuid::uuid4()->toString()
    'version' => 2,
    'role' => $role,
    'room_id' => $roomId,
    'user_id' => $userId
];

$token = JWT::encode(
    $payload,
    $secret,
    'HS256'
);
```

</Tab>

<Note>

**Warning**

Your app key and secret carry many privileges, please ensure to keep them secure.

</Note>

## Management Token

For setting up management tokens for server side API requests, please refer to the [authentication guide](/server-side/v2/introduction/authentication-and-tokens) in server-side API section.


Handling audio-video edge cases

Webhook


<Content alias="liveStreaming" />

Use the 100ms client-side SDKs to integrate streaming in your application. See code snippets for the Android SDK [here](/android/v2/features/hls).


Interactive Live Streaming


<Content alias="liveStreaming" />

Use the 100ms client-side SDKs to integrate streaming in your application. See code snippets for the Flutter SDK [here](/flutter/v2/features/hls).



<Content alias="domainsAndPorts" />

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

## Domains

`*.100ms.live`

## Ports

### Minimum requirement

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

### Requirements for best experience

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


Domain and Port Whitelisting


<Content alias="liveStreaming" />

Use the 100ms client-side SDKs to integrate streaming in your application. See code snippets for the Flutter SDK [here](/react-native/v2/features/hls-streaming).



<Content alias="liveStreaming" />

Use the 100ms client-side SDKs to integrate streaming in your application. See code snippets for the iOS SDK [here](/ios/v2/features/hls).



<Content alias="liveStreaming" />

Use the 100ms client-side SDKs to integrate streaming in your application. See code snippets for the web SDK [here](/javascript/v2/features/hls).




| Increase APK size |
|---|---|---|
|(armeabi-v7)| **5.8MB**|
|(arm64-v8a) **(most common one)**| **6.4MB**|
|(x86_64)| **7.1MB**|
|(x86)| **7.2MB**|



SDK Size Impact


100ms collection includes API for rooms, sessions, policies, etc., packaged and ready to use with Postman, along with documentation for each API to help you learn about them. You can import/fork these APIs and start using them instantly.

The API collection comes with predefined collection variables and a pre-request script that generates the management token to help you get started immediately.

## Fork the collection

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a?action=collection%2Ffork&collection-url=entityId%3D22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a%26entityType%3Dcollection%26workspaceId%3Dd9145dd6-337b-4761-81d6-21a30b4147a2)

You can click on this button to fork the 100ms API collection.

## Authentication

100ms uses management tokens to authenticate REST APIs. To create the management token, you must use the `App Access Key` and `App Secret` from the [developer section](https://dashboard.100ms.live/developer) in your 100ms dashboard.

![Copy app secret and key](/docs/v2/app-key-secret.png)

### Simplified token generation

We have simplified the process of management token generation for you within this collection:

-   All you have to do is update the **collection variables** `APP_ACCESS_KEY` and `APP_SECRET`;
-   We have added a pre-request script within the collection, which will generate the management token and set the same as a `collection variable` (TOKEN) in the forked Postman collection.
-   Automatically, this will be used as authentication for all the APIs in the 100ms collection.

![Add-token](/docs/v2/token.png)

> **Note:** Refer to the [authentication and tokens guide](https://100ms.live/docs/server-side/v2/introduction/authentication-and-tokens#code-sample-generate-management-token) for more generating the management token in your preferred programming language for your development/production environment.

## Example: Create a room

Let's try to create a room to see how the 100ms collection works. From the forked REST API collection, select the folder named **Room APIs **and select the request to `create room`. Replace the placeholders like name, description, template_id, etc with the desired values. Click the `Send` button once done.

## API Reference

You can refer to the detailed[ API reference](/server-side/v2/Rooms/object) to understand the request/response structure better, request arguments, response variables, webhooks, etc.

## Stay up to date

Similar to how the forked repository on GitHub works, you can stay up to date with the 100ms master collection by pulling the changes.

In the forked collection of your Postman instance, Click on the 'three-dots(...) menu' next to the 'Save' button in the top right section and select `Pull changes` from the drop-down menu.

![pulling the changes](/docs/v2/pull-changes.png)


Postman Guide


**CLASS**

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


HMSAudioTrack


## Overview

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

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

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

-   [Get an instant video call joining link](#getting-the-video-call-joining-link)
-   [Add the SDK dependencies](#add-sdk-dependencies)
-   [Create a login token to authenticate the user](#login)
-   [Add permissions](#add-permissions)
-   [Create an instance of the `HMSSDK`](#instantiate-hmssdk)

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

-   [Call `hmssdk.join` with the video call link to join the call](#join-a-video-call)
-   [Know when people join or leave](#how-you-know-when-people-join-or-leave)
-   [How to render audio/video](#how-to-render-audio-and-video)
-   [Listening to updates effectively](#listening-to-updates-effectively)
    <hr />

## Prerequisites

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

> HMSSDK requires flutter 2.10.x or above versions

### Get an instant video call joining link

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

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

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

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

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

### Add SDK dependencies

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

```dart section=AddSDKDependencies sectionIndex=1
#pubspec.yaml

dependencies:
flutter:
  sdk: flutter

hmssdk_flutter:
```

### Login

#### Request

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

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

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

#### Response

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

### Add Permissions

#### Android Permissions

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

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

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview. Please follow [Android Documentation](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

#### iOS Permissions

Add following permissions in iOS Info.plist file

```xml section=iOSPermissions sectionIndex=1
<key>NSMicrophoneUsageDescription</key>
<string>{YourAppName} wants to use your microphone</string>

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

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

### Join a Video Call

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

These are some listener's callback functions:

`onJoin` - called when the join was successful and you have entered the room.

> 💡 Audio will be automatically connected, video requires some work on your side.

`onPeerUpdate` - called when a person joins or leaves the call and when their audio/video mutes/unmutes.

`onTrackUpdate` - usually when a person joins the call, the listener will first call `onPeerUpdate` to notify about the join. Subsequently `onTrackUpdate` will be called with their actual video track.

> 💡 It's essential that this callback is listened to or you may have peers without video.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  ///whenever a new audio device is plugged in or audio output is changed we
  ///get the onAudioDeviceChanged update
  ///This callback is only fired on Android devices. On iOS, this callback will not be triggered.
  /// - Parameters:
  ///   - currentAudioDevice: Current audio output route
  ///   - availableAudioDevice: List of available audio output devices
  void onAudioDeviceChanged(
      {HMSAudioDevice? currentAudioDevice,
      List<HMSAudioDevice>? availableAudioDevice});
}

```

### How you know when people join or leave

The join method takes an interface called `HMSUpdateListener`. It lets you know when peers join and leave the call, mute/unmute their audio and video and lots more.

The `HMSUpdateListener` has a callback to notify about people joining or leaving. It is `onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer)`.

> 💡 HMSPeer is object that represents a person in the call.

---

### How to render audio and video

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

### Showing Videos

A peer represents one person in the video call.

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

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

### Mute/UnMute Audio

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

```dart section=MuteUnMuteAudio sectionIndex=1

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

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

### Mute/UnMute Video

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

```dart section=MuteUnMuteVideo sectionIndex=1

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

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

### Leave a video call

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

```dart section=LeaveVideoCall sectionIndex=1
hmsSDK.leave();
```

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

## Where to go from here

Checkout the [simple version](https://github.com/100mslive/100ms-flutter/tree/main/example) of the project.This uses provider as the state
management library.

For implementations with other state management libraries visit : 
* [Bloc](https://github.com/100mslive/100ms-flutter/tree/main/sample%20apps/bloc)
* [Getx](https://github.com/100mslive/100ms-flutter/tree/main/sample%20apps/getx)
* [Riverpod](https://github.com/100mslive/100ms-flutter/tree/main/sample%20apps/riverpod)
* [Mobx](https://github.com/100mslive/100ms-flutter/tree/main/sample%20apps/mobx)

### 100ms Flutter app

You can download & check out the 100ms Flutter app -

🤖 The Flutter Android app from [Google Play Store here](https://play.google.com/store/apps/details?id=live.hms.flutter)

📱 Flutter iOS app from [Apple App Store here](https://apps.apple.com/app/100ms-live/id1576541989)


### Github Repo 
You can checkout the 100ms Flutter SDK Github repo which also contains a fully fledged [Example app implementation here](https://github.com/100mslive/100ms-flutter/) 


100ms SDK Flutter Quickstart Guide


## Overview

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

Here are some sample apps demonstrating this.

[Simplest implementaion.](https://github.com/100mslive/hello-world-android/)

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

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

-   [Getting the video call joining link](#getting-the-video-call-joining-link)
-   [Add the sdk dependencies](#add-sdk-dependencies).
-   [Create a login token to authenticate the user](#login).
-   [Add permissions](#permissions)
-   [Create an instance of the `HMSSDK`](#instantiate-hmssdk).

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

-   [Call `hmssdk.join` with the video call link to join the call](#join-a-video-call).
-   [Know when people join or leave](#how-you-know-when-people-join-or-leave)
-   [How to render audio/video](#how-to-render-audio-and-video)
-   [Listening to updates effectively](#listening-to-updates-effectively)
    <hr />

## Prerequisites

Familiarity with Android Studio and the [fundamentals](https://developer.android.com/training/basics/firstapp) of android apps.

## Supported Android API Levels

100ms' Android SDK supports Android API level 21 and higher. It is built for armeabi-v7a, arm64-v8a, x86, and x86_64 architectures.

### Getting the video call joining link

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

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

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

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

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

### Add SDK dependencies

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

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

```json{7}:settings.gradle section=AddSDKDependencies sectionIndex=1
dependencyResolutionManagement {
 repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
 repositories {
 google()
 mavenCentral()
 jcenter() // Warning: this repository is going to shut down soon
 maven { url 'https://jitpack.io' }
    }
}
rootProject.name = "MyVideoCallApp"
include ':app'

```

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

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

### Login

#### Request

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

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

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

#### Response

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

### Permissions

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

```xml:AndroidManifest.xml section=Permissions sectionIndex=1
    <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 section=InstantiateHMSSDK sectionIndex=1 tab=Kotlin
    val hmsSdk = HMSSDK
        .Builder(application)
        .build()
```

</Tab>

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

```java section=InstantiateHMSSDK sectionIndex=1 tab=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 section=JoinVideoCall sectionIndex=1 tab=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 section=JoinVideoCall sectionIndex=1 tab=Java

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

hmsSdk.join(config, new MyHmsUpdateListener());

class MyHmsUpdateListener implements HMSUpdateListener {
    @Override public void onJoin(@NonNull HMSRoom hmsRoom) {}
    @Override public void onMessageReceived(@NonNull HMSMessage hmsMessage) {}
    @Override public void onPeerUpdate(@NonNull HMSPeerUpdate hmsPeerUpdate, @NonNull HMSPeer hmsPeer) {}
    @Override public void onReconnected() {}
    @Override public void onReconnecting(@NonNull HMSException e) {}
    @Override public void onRoleChangeRequest(@NonNull HMSRoleChangeRequest hmsRoleChangeRequest) {}
    @Override public void onRoomUpdate(@NonNull HMSRoomUpdate hmsRoomUpdate, @NonNull HMSRoom hmsRoom) {}
    @Override public void onTrackUpdate(@NonNull HMSTrackUpdate hmsTrackUpdate, @NonNull HMSTrack hmsTrack, @NonNull HMSPeer hmsPeer) {}
    @Override public void onError(@NonNull HMSException e) {}
}

```

</Tab>

### How you know when people join or leave

The join method takes an interface called `HMSUpdateListener`. It lets you know when peers join and leave the call, mute/unmute their audio and video and lots more.

The `HMSUpdateListener` has a callback to notify about people joining or leaving. It is `onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer)`.

> 💡`HMSPeer` is object that represents a person in the call.

### How to render audio and video

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

### Showing Videos

A peer represents one person in the video call.

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

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

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

```xml section=ShowingVideos sectionIndex=1

<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


## What is a room?

A room is a virtual space where one or more peers communicate with each other. It is a central entity that provides real-time communication capabilities for any video conferencing or live streaming session.

To allow users to join a 100ms video conferencing or a live streaming session inside your app, you first need to create a room.

![Room](/docs/v2/room.png)

The above diagram illustrates how a room acts as the central entity in the lifecycle of an interactive audio/video session and the transition of the room from one state to another based on the configuration of the room and the peer's presence.

## Room APIs

Room APIs will enable you to script actions from the server side based on your business logic and requirements, actions such as:

-   [creating a room](/server-side/v2/Rooms/create-via-api),
-   [updating room properties](/server-side/v2/Rooms/update-a-room),
-   [retrieving room details](/server-side/v2/Rooms/retrieve-room), and
-   [disabling/enabling a room](/server-side/v2/Rooms/disable-or-enable).

You can control peer behavior and build interactivity scenarios in an active room with the help of [active room APIs](/server-side/v2/active-rooms/overview).

## Postman collection

You can use our Postman collection to start exploring 100ms APIs.

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a?action=collection%2Ffork&collection-url=entityId%3D22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a%26entityType%3Dcollection%26workspaceId%3Dd9145dd6-337b-4761-81d6-21a30b4147a2)

Refer to the [Postman guide](/server-side/v2/introduction/postman-guide) to get started with 100ms API collection.


Overview


## Getting started

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

## Prerequisites

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

## Installing the dependencies

```bash section=InstallingTheDependencies sectionIndex=1
npm install --save @100mslive/react-native-hms
```

## Permissions

### For Android Permissions

Add following permissions in `AndroidManifest.xml`

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

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview. Please follow [Android Documentation](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

### For iOS Permissions

Add following lines in `Info.plist` file

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

## Concepts

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

## Initializing the SDK

Call the function given below to initialise the SDK

```js section=InitializingTheSDK sectionIndex=1
import { HMSSDK } from '@100mslive/react-native-hms';

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

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

## Add event listeners

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

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

```js section=AddEventListeners sectionIndex=1
import { HMSUpdateListenerActions } from 'react-native-hms';

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

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

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

## Joining a room

To join a room 3 fields are required:

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

```js section=JoinRoom sectionIndex=1
import { HMSConfig } from 'react-native-hms';

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

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

## Leaving the room

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

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

```js section=LeavingRoom sectionIndex=1
hmsInstance.leave();
```

## Render video

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

```js section=RenderVideo sectionIndex=1
import { HmsView, HMSVideoViewMode } from 'react-native-hms';

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

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

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

```js section=RenderVideo sectionIndex=2
const localTrackId = hmsInstance.localPeer.videoTrack.trackId;

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

These track IDs can directly be passed to HmsView component

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

```js section=RenderVideo sectionIndex=3
HmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);

HmsInstance.addEventListener(HMSUpdateListenerActions.ON_TRACK_UPDATE, onTrackListener);

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

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

## Mute/Unmute local Audio/Video tracks

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

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

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

```js section=MuteVideo sectionIndex=1
// instance acquired from build() method

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

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


### [Github Repo](https://github.com/100mslive/react-native-hms/)
You can checkout the 100ms React Native SDK Github repo which also contains a fully fledged [Example app implementation here](https://github.com/100mslive/react-native-hms/) 



### [Example App](https://github.com/100mslive/react-native-hms/tree/develop/example)

In the [100ms Example App](https://github.com/100mslive/react-native-hms/tree/main/example) we have shown how to setup the various listeners, what data to store in the redux and what all features you can implement.

We have also implemented multiple views which are commonly used. Checkout the [videos & relevant code in the Example app](https://github.com/100mslive/react-native-hms/tree/main/example#additional-features).


React Native Quickstart Guide


## Prerequisites

Familiarity with Xcode and iOS SDK, Cocoapods installed

## Xcode Project Setup

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

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

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

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

```jsx section=XcodeProjectSetup sectionIndex=1
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 section=XcodeProjectSetup sectionIndex=2
<key>NSCameraUsageDescription</key>
<string>Please allow access to Camera to enable video conferencing.</string>
<key>NSLocalNetworkUsageDescription</key>
<string>Please allow access to network usage to enable video conferencing.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Please allow access to Microphone to enable video conferencing.</string>
```

### Initialising The SDK

Open `ViewController.swift`

Add `HMSSDK` import

```swift section=InitializingTheSDK sectionIndex=1
import HMSSDK
```

Conform to HMSUpdateListener and add stubs when Xcode offers to

```swift section=InitializingTheSDK sectionIndex=2
extension ViewController: HMSUpdateListener {
}
```

Create an instance of HMSSDK

```swift section=InitializingTheSDK sectionIndex=3
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 section=JoinRoom sectionIndex=1
func joinRoom() {
    let config = HMSConfig(userID: UUID().uuidString,
            roomID: "replace with room id", authToken: "replace with token")
        hmsSDK.join(config: config, delegate: self)
}

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

Congratulations! You have an audio conference app.

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

## Adding Video

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

```swift{4-24} section=AddingVideo sectionIndex=1
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 section=AddingVideo sectionIndex=2
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} section=Cleanup sectionIndex=1
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 section=Cleanup sectionIndex=2
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 section=Cleanup sectionIndex=3
func removeVideoView(for track: HMSVideoTrack) {
    trackViewMap[track]?.removeFromSuperview()
}
```

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

```swift section=Cleanup sectionIndex=4
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 section=FinalPoints sectionIndex=1
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 section=FinalPoints sectionIndex=2
hmsSDK.leave()
```

### Ways to go from here

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

Checkout a sample code for a full featured conferencing app:

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


100ms SDK iOS Quickstart Guide


## 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). There is also a version of the quickstart using CDN [here](https://codepen.io/triptu/pen/dymxmoR?editors=0010).

### 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 section=InstallingTheDependencies sectionIndex=1
npm install --save @100mslive/hms-video-store@latest
```

### Initializing the SDK

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

```jsx:script.js section=InitializingTheSDK sectionIndex=1
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.

> Note: join is async from this [version](../release-notes/release-notes#2022-09-13)

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

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

```html:index.html section=JoiningRoom sectionIndex=1 tab=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 section=JoiningRoom sectionIndex=1 tab=JS
const joinBtn = document.getElementById("join-btn");
joinBtn.addEventListener('click', async () => {
    await 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 section=LeavingTheRoom sectionIndex=1
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 section=FetchingInformationFromState sectionIndex=1
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 section=SubscribingToTheState sectionIndex=1 tab=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 section=SubscribingToTheState sectionIndex=1 tab=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 section=SubscribingToTheState sectionIndex=2
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 section=ChangingUIBasedOnConnectionState sectionIndex=1
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 section=MutingUnmutingLocalTracks sectionIndex=1 tab=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 section=MutingUnmutingLocalTracks sectionIndex=1 tab=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 section=MutingUnmutingLocalTracks sectionIndex=2
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 section=MirroringLocalVideo sectionIndex=1 tab=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 section=MirroringLocalVideo sectionIndex=1 tab=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" />

There is also a version of the above quickstart using CDN [here](https://codepen.io/triptu/pen/dymxmoR?editors=0010).


JavaScript Quickstart Guide

Auth Token Quickstart Guide


<EndpointRequest title="https://api.100ms.live/v2/rooms" />

## Object

| Argument       | Description                                                                                                                                                                                                                                                                                                                                                |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id             | Unique identifier for the room                                                                                                                                                                                                                                                                                                                             |
| name           | Alias for the room                                                                                                                                                                                                                                                                                                                                         |
| enabled        | Indicates whether the room is enabled or disabled. <br/><br/> **Note:** If you disable a room, that room can be used for only the current session and users will not be able to join the room later. You can use the [Disable/Enable a room API](/server-side/v2/Rooms/disable-or-enable) with the `enabled` param set to `true` to enable the room again. |
| description    | Description for the room                                                                                                                                                                                                                                                                                                                                   |
| customer       | Unique identifier for your account                                                                                                                                                                                                                                                                                                                         |
| recording_info | Indicates whether the recording is enabled or disabled. <br/><br/> **Note:** This argument is only applicable to enable/disable [SFU recording](/server-side/v2/Destinations/recording). Refer to [RTMP Streaming & Browser Recording](/server-side/v2/Destinations/rtmp-streaming-and-browser-recording) guide for other options.                         |
| template_id    | Identifier for the template used for this room                                                                                                                                                                                                                                                                                                             |
| template       | Name for the template                                                                                                                                                                                                                                                                                                                                      |
| region         | The region in which the room has to be created                                                                                                                                                                                                                                                                                                             |

## Postman collection

You can use our Postman collection to start exploring 100ms APIs. 

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a?action=collection%2Ffork&collection-url=entityId%3D22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a%26entityType%3Dcollection%26workspaceId%3Dd9145dd6-337b-4761-81d6-21a30b4147a2)

Refer to the [Postman guide](/server-side/v2/introduction/postman-guide) to get started with 100ms API collection. 

Room object


## 100ms Android SDK 2.1.2 or higher

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

## Prior to Android SDK version 2.1.2

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

Add it to your `proguard-rules.pro`

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


Proguard configuration


## Attaching Preview and Error Listeners

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

```dart section=AttachingPreviewAndErrorListeners sectionIndex=1
import 'package:hmssdk_flutter/hmssdk_flutter.dart';

class HMSSDKInteractor {
  late HMSSDK hmsSDK;

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

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

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

}
```

## Calling Preview and Join functions

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

```dart section=CallingPreviewAndJoinFunctions sectionIndex=1
import 'package:hmssdk_flutter/hmssdk_flutter.dart';

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

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

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

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


Joining with Preview


Creates a new room. This provides a more scalable way of creating a room.

<PostRequest title="https://api.100ms.live/v2/rooms" />
<Request id="req-comp-0">

```bash
curl --location --request POST 'https://api.100ms.live/v2/rooms' \
--header 'Authorization: Bearer <management_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "new-room-1662723668",
    "description": "This is a sample description for the room",
    "template_id": "<template_id of the template you wish to associate with the room>",
    "recording_info": {
        "enabled": true,
        "upload_info": {
        "type": "s3",
        "location": "<Name of the AWS s3 bucket>",
        "prefix": "<Upload prefix path>",
        "options": {
            "region": "<region of the s3 bucket>"
        },
        "credentials": {
            "key": "<access key ID for the AWS account/S3 bucket>",
            "secret": "<secret access key for the AWS account/S3 bucket>"
            }
        }
    },
    "region": "in"
}'
```

</Request>
<ResponseBox id="resp-0" status="200 OK">

```json
{
    "id": "631b2654f771854d9bf633df",
    "name": "new-room-1662723668",
    "enabled": true,
    "description": "This is a sample description for the room",
    "customer": "627cdddff2e4e30487862ad1",
    "recording_info": {
        "enabled": true,
        "upload_info": {
            "type": "s3",
            "location": "<Name of the AWS s3 bucket>",
            "prefix": "<Upload prefix path>",
            "credentials": {
                "key": "<access key ID for the AWS account/S3 bucket>",
                "secret": "<secret access key for the AWS account/S3 bucket>"
            },
            "options": {
                "region": "<region of the s3 bucket>"
            }
        }
    },
    "template_id": "63188115d11d6db790c73c60",
    "template": "new-template-1662550293",
    "region": "in",
    "created_at": "2022-09-09T11:41:08.082Z",
    "updated_at": "2022-09-09T11:41:08.074Z",
    "active": true
}
```

</ResponseBox>

## Main Arguments

| Name                 | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Required |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| name <br/>           | `string` | An alias you can assign to 100ms rooms. This is `case-insensitive`. <br/><br/>Accepted characters are `a-z, A-Z, 0-9, and . - : _`. If not provided, this is generated automatically. <br/><br/>**Note**: If `Create room request` is triggered with an existing room name, then the corresponding room ID is returned.                                                                                                                                                                                            | No       |
| description <br/>    | `string` | A string to describe your room's usage. For example "9PM English Class Batch 2"                                                                                                                                                                                                                                                                                                                                                                                                                                    | No       |
| template_id <br/>    | `string` | Template ID of template you wish to associate with the room. You can get template ID either from the templates section on the [dashboard](https://dashboard.100ms.live/dashboard) or use the [Template API](../policy/retrieve-a-template). <br/><br/>**Note**: `default template` will be assigned if template is not specified in the `create room request`.                                                                                                                                                     | No       |
| recording_info <br/> | `object` | Object of type `recording_info`. This object contains information for enabling recording/setting storage location for recordings. <br/><br/>Check the [recording_info arguments](#recording-info-arguments) below for more information. <br/><br/> **Note:** This argument is only applicable to enable/disable [SFU recording](/server-side/v2/Destinations/recording). Refer to [RTMP Streaming & Browser Recording](/server-side/v2/Destinations/rtmp-streaming-and-browser-recording) guide for other options. | No       |
| region <br/>         | `string` | Region in which you want to create room. <br/><br/> `in` - India <br/> `us` - United States <br/> `eu` - European Union <br/> `auto` - Automatic region selection (default, and in case this parameter is not provided)                                                                                                                                                                                                                                                                                            | No       |

> **Warning:** If you create a room with the name of an existing room, the same room will be updated with the new configuration passed in the request payload. <br/> For example, if the existing room was assigned to template-ABC earlier and in the request payload you've used template-DEF, then template-DEF will be assigned to the existing room.

## recording_info arguments

| Name        | Type      | Description                                                                                                                                                                                                                                                                                             | Required |
| :---------- | :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------- |
| enabled     | `boolean` | Enable SFU recording. Disabled by default                                                                                                                                                                                                                                                               | No       |
| upload_info | `object`  | Object of type `upload_info`. This object contains information on recordings storage location. <br/><br/>If you want to store recording with 100ms, and not use your own s3, don't add this to the object. <br/><br/>Check the [upload_info object](#upload-info-arguments) below for more information. | No       |

`recording_info` in the room acts as an atomic property. It depends on the recording settings defined in a template as below:

-   If the `recording_info` key is not provided in the API, the room will fill it with recording settings from the template. And the response body will include `recording_source_template: true`. This implies that whenever recording info is modified in the template, the recording settings for the room will also be updated.
-   If the `recording_info` key is provided in the API, the recording settings of the room won't be affected by the template at all.

To know more about recording please visit [Recording](/server-side/v2/Destinations/recording).

### upload_info arguments

| 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` | Additional configurations of type `Options` to be used for uploading. <br/><br/>Check the options arguments below for more information.                                      | No       |
| credentials | `object` | Object of type `Credentials`. This is used to share AWS credentials to access the s3 bucket specified. <br/><br/>Check the credentials arguments below for more information. | No       |

#### Options arguments

| Name   | Type     | Description                                                                                                              | Required |
| :----- | :------- | :----------------------------------------------------------------------------------------------------------------------- | :------- |
| region | `string` | Region of the AWS account hosting the s3 bucket for storing recordings. If not provided it is assumed to be `ap-south-1` | No       |

#### Credentials arguments

| Name   | Type     | Description                                                                          | Required |
| :----- | :------- | :----------------------------------------------------------------------------------- | :------- |
| key    | `string` | `access key ID` for the AWS account hosting the s3 bucket for storing recordings     | Yes      |
| secret | `string` | `secret access key` for the AWS account hosting the s3 bucket for storing recordings | Yes      |

The access keys should have read(GetObject) and write(PutObject) permissions for the s3 bucket.
For more details check - https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html


Create via API


## Attaching Preview and Error Listeners

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

```js section=AttachingPreviewAndErrorListeners sectionIndex=1
import { HMSSDK, HMSUpdateListenerActions } from '@100mslive/react-native-hms';

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

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

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

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

## Calling Preview and Join functions

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

```js section=CallingPreviewAndJoinFunctions sectionIndex=1
import { HMSException } from '@100mslive/react-native-hms';

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

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

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

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



## Getting started

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

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

### Prerequisites

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

### Installing the dependencies

```bash section=InstallingTheDependencies sectionIndex=1
## npm
npm install --save @100mslive/react-sdk@latest
## yarn
yarn add @100mslive/react-sdk@latest
```

### Initializing the SDK

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

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

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

import App from "./App";

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

```

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

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

### Concepts

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

## Joining a room

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

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

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

> Note: join is async from this [version](../release-notes/release-notes#2022-09-13)


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

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

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

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

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

export default JoinForm;
```

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

```jsx:src/App.jsx section=JoiningRoom sectionIndex=2
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 section=LeavingTheRoom sectionIndex=1
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 section=FetchingInformation sectionIndex=1
import { useHMSStore, selectPeers } from '@100mslive/react-sdk';

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

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

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

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

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

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

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

export default Conference;
```

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

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

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

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

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

export default Peer;
```

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

## Changing UI based on connection state

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

We can do this with `selectIsConnectedToRoom` selector.

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

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

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

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

```

## Muting/unmuting local tracks

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

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

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

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

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

export default Footer;
```

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

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

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

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

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

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

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

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

Here's the complete example.

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


React Quickstart Guide


## 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 via 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 SFU recording.

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

![Create a room](/docs/v2/create-a-room.png)

> **Warning:** If you create a room with the name of an existing room, the same room will be updated with the new configuration passed in the request payload. <br/> For example, if the existing room was assigned to template-ABC earlier and in the request payload you've used template-DEF, then template-DEF will be assigned to the existing room.

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

![Room details on dashboard](/docs/v2/role-dashboard.png)


Create via dashboard


## Could not invoke HMSSDK.build

![error](https://user-images.githubusercontent.com/56931905/174788439-53a39a54-847e-46f7-9104-7524b1547992.jpg)

This error generally appears in development mode due to hot reloading. When the peer has joined the room and then the app is hot reloaded from the terminal, the peer is still in the room and when he tries to join back this error occurs. To make sure this error does not occur you have to remove your peer from the room.

-   To avoid you can add `instance.leave()` function on the unmounting of the Home Screen, so whenever the app is hot reloaded which leads to unmounting of the Home screen the leave function is called.

```js section=CouldNotInvokeHMSManagerBuild sectionIndex=1
const onLeavePress = async () => {
    await instance
        ?.leave()
        .then((d) => console.log('Leave Success: ', d))
        .catch((e) => console.log('Leave Error: ', e));
};

useEffect(() => {
    return () => {
        onLeavePress();
    };
}, []);
```

-   If this error occurred you can either join through web app and remove the peer which is still present due to hot reloading or you can kill the app and rebuild it.



Retrieves the details of a specific room. 100ms provides options to retrieve details of a room with their ID or name.

<GetRequest title="https://api.100ms.live/v2/rooms/<room_id>" />
<Request id="req-0">

```bash
curl --location --request GET 'https://api.100ms.live/v2/rooms/<room_id>' \
--header 'Authorization: Bearer <management_token>'
```

</Request>

<ResponseBox id="res-0" status="200 OK">

```json
{
    "id": "631a05390e6ffae22efa610b",
    "name": "sampleroom",
    "enabled": true,
    "description": "This is sample description for room",
    "customer": "627cdddff2e4e30487862ad1",
    "recording_source_template": false,
    "recording_info": {
        "enabled": true,
        "upload_info": {
            "type": "s3",
            "location": "brytecam-test-bucket-ap-south-1",
            "prefix": "dev/627cdddff2e4e30487862ad1"
        }
    },
    "template_id": "63188115d11d6db790c73c60",
    "template": "new-template-1662550293",
    "region": "in",
    "created_at": "2022-09-08T15:07:37.83Z",
    "updated_at": "2022-09-08T15:07:37.83Z",
    "active": true
}
```

</ResponseBox>


## Arguments

| Name                     | Type     | Description                                                                                                  | Required |
| :----------------------- | :------- | :----------------------------------------------------------------------------------------------------------- | :------- |
| id <br/> — path param    | `string` | Unique identifier of the room you wish to fetch details for. <br/><br/>**Example**: 627cda81ab4f3b56a077dc33 | Yes      |
| name <br/> — query param | `string` | Alias of the room you wish to fetch details for. <br/><br/>**Example**: test-room                            | No       |


Retrieve a specific room


## Overview

This API retrieves details of a list of rooms in your account. 100ms provides options to

-   retrieve the complete list of rooms or
-   rooms that are active or
-   rooms based on their creation time-range or
-   combinations of these.

## List all rooms

This API retrieves details of all the rooms in your account.

<GetRequest title="https://api.100ms.live/v2/rooms" />

<Request id="req-0">

```bash
curl --location --request GET 'https://api.100ms.live/v2/rooms' \
--header 'Authorization: Bearer <management_token>'
```

</Request>

<ResponseBox id="res-0" status="200 OK">

```json
{
    "limit": 10,
    "data": [
        {
            "id": "62bbc84********0a6aa1a",
            "name": "test-room",
            "enabled": true,
            "description": "This is a test room",
            "customer": "627cda********a39291b",
            "recording_source_template": true,
            "template_id": "627cd********784227d3",
            "template": "default_createown_e319635a-****-****-****-ae9e95891e31",
            "region": "in",
            "created_at": "2022-06-29T03:34:30.194Z",
            "key": "627***********a39291b:test-room",
            "updated_at": "0001-01-01T00:00:00Z"
        },
        {
            "id": "627cda81********6b077bc33",
            "name": "4b2705aa-****-****-****-f470c06d0c03",
            "enabled": true,
            "description": "This is a test room",
            "customer": "627cd********037a39291b",
            "recording_source_template": false,
            "recording": {
                "enabled": false
            },
            "template_id": "627cda********84227d3",
            "template": "default_createown_e319635a-****-****-****-ae9e95891e31",
            "region": "in",
            "created_at": "2022-05-12T09:59:29.343Z",
            "key": "627cda********037a39291b:4b2705aa-****-****-****-f470c06d0c03",
            "updated_at": "0001-01-01T00:00:00Z"
        }
    ],
    "last": "627cda81bd4f3b56b077bc33"
}
```

</ResponseBox>




## Allowed filters

| Name          | Type      | Description                                                                                                                                                      | Required |
| :------------ | :-------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| enabled <br/> | `boolean` | Flag to indicate if the room is enabled. <br/><br/>`Default`: true, <br/>`Allowed values`: true, false                                                           | No       |
| after <br/>   | `string`  | Check for rooms created with a timestamp greater than or equal to "after" <br/><br/>`Format`: YYYY-MM-DDTHH:mm:ss.s+z.                                           | No       |
| before <br/>  | `string`  | Check for rooms created with a timestamp less than or equal to "after" <br/><br/>`Format`: YYYY-MM-DDTHH:mm:ss.s+z.                                              | No       |
| limit <br/>   | `int`     | Determines the number of room objects to be included in response. <br/><br/>`Default`: 10, <br/>`Allowed values`: **Min**: 10, **Max**: 100                        | No       |
| start <br/>   | `string`  | Determines the starting point. <br/>`last` field of the response can be used as start for the subsequent request. <br/><br/>**For example** "627cda81ab4f3b56a077dc33". | No       |


List rooms


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

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

## Am I connected to the Room?

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

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

<Tab id='connect-0'>

```js section=AmIConnectedToTheRoom sectionIndex=1 tab=JS
const isConnected = hmsStore.getState(selectIsConnectedToRoom);
```

</Tab>

<Tab id='connect-1'>

```jsx section=AmIConnectedToTheRoom sectionIndex=1 tab=React
const isConnected = useHMSStore(selectIsConnectedToRoom);
```

</Tab>

## Am I in the Preview?

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

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

<Tab id='preview-0'>

```js section=AmIInThePreview sectionIndex=1 tab=JS
const isInPreview = hmsStore.getState(selectIsInPreview);
```

</Tab>

<Tab id='preview-1'>

```jsx section=AmIInThePreview sectionIndex=1 tab=React
const isInPreview = useHMSStore(selectIsInPreview);
```

</Tab>

## How many people have joined the room?

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

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

<Tab id='peerCount-0'>

```js section=HowManyPeopleHaveJoinedTheRoom sectionIndex=1 tab=JS
const count = hmsStore.getState(selectPeerCount);
```

</Tab>

<Tab id='peerCount-1'>

```jsx section=HowManyPeopleHaveJoinedTheRoom sectionIndex=1 tab=React
const count = useHMSStore(selectPeerCount);
```

 </Tab>

## Who all are in my room?

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

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

<Tab id='peers-0'>

```js section=WhoAllAreInMyRoom sectionIndex=1 tab=JS
const peers = hmsStore.getState(selectPeers);
```

</Tab>

<Tab id='peers-1'>

```jsx section=WhoAllAreInMyRoom sectionIndex=1 tab=React
const peers = useHMSStore(selectPeers);
```

</Tab>

## What is my current state of room?

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

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

<Tab id='roomState-0'>

```js section=WhatIsMyCurrentStateOfRoom sectionIndex=1 tab=JS
const roomState = hmsStore.getState(selectRoomState);
```

</Tab>

<Tab id='roomState-1'>

```jsx section=WhatIsMyCurrentStateOfRoom sectionIndex=1 tab=React
const roomState = useHMSStore(selectRoomState);
```

</Tab>

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

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

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

<Tab id='av-0'>

```js section=HowDoIKnowIfMyMicVideoIsOn sectionIndex=1 tab=JS
const audioOn = hmsStore.getState(selectIsLocalAudioEnabled);
const videoOn = hmsStore.getState(selectIsLocalVideoEnabled);
```

</Tab>

<Tab id='av-1'>

```jsx section=HowDoIKnowIfMyMicVideoIsOn sectionIndex=1 tab=React
const audioOn = useHMSStore(selectIsLocalAudioEnabled);
const videoOn = useHMSStore(selectIsLocalVideoEnabled);
```

</Tab>

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

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

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

<Tab id='rm-0'>

```js section=HowDoIKnowTheStatusOfRemoteMicVideoStatus sectionIndex=1 tab=JS
const audioOn = hmsStore.getState(selectIsPeerAudioEnabled(peerId));
const videoOn = hmsStore.getState(selectIsPeerVideoEnabled(peerId));
```

</Tab>

<Tab id='rm-1'>

```jsx section=MicVideoStatus sectionIndex=1 tab=React
const audioOn = useHMSStore(selectIsPeerAudioEnabled(peerId));
const videoOn = useHMSStore(selectIsPeerVideoEnabled(peerId));
```

</Tab>

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

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

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

<Tab id='cam-0'>

```js section=HowDoIGetTheVideoStreamOfAUser sectionIndex=1 tab=JS
const videoTrack = hmsStore.getState(selectCameraStreamByPeer(peerId));
```

</Tab>

<Tab id='cam-1'>

```jsx section=HowDoIGetTheVideoStreamOfAUser sectionIndex=1 tab=React
const videoTrack = useHMSStore(selectCameraStreamByPeer(peerId));
```

</Tab>


Useful Selectors


You can use this API to update various details of the room such as name, description, recording_info and region.

<PostRequest title="https://api.100ms.live/v2/rooms/<room_id>" />
<Request id="req-0">

```bash
curl --location --request POST 'https://api.100ms.live/v2/rooms/<room_id>' \
--header 'Authorization: Bearer <management_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "update-room-name",
    "description": "Updated description for the room",
    "recording_info": {
        "enabled": true,
        "upload_info": {
            "type": "s3",
            "location": "<Updated Name of the AWS s3 bucket>",
            "prefix": "<Updated Upload prefix path>",
            "options": {
                "region": "<Updated region of the s3 bucket>"
            },
            "credentials": {
                "key": "<Updated access key ID for the AWS account/S3 bucket>",
                "secret": "<Updated secret access key for the AWS account/S3 bucket>"
            }
        }
    },
    "region": "us"
}'
```

</Request>
<ResponseBox id="res-0" status="200 OK">

```json
{
    "id": "63215ea14354ff09328378c6",
    "name": "update-room-name",
    "enabled": true,
    "description": "Updated description for the room",
    "customer_id": "627cda54ff688c037a39291b",
    "recording_source_template": false,
    "enabled_source_template": false,
    "recording_info": {
        "enabled": true,
        "upload_info": {
            "type": "s3",
            "location": "<Updated Name of the AWS s3 bucket>",
            "prefix": "<Upload prefix path>",
            "credentials": {
                "key": "<Updated access key ID for the AWS account/S3 bucket>",
                "secret": "<Updated secret access key for the AWS account/S3 bucket>"
            },
            "options": {
                "region": "<Updated region of the s3 bucket>"
            }
        }
    },
    "template_id": "6311c9b3ba3f6f0133f899ee",
    "template": "new-template-1662110132",
    "region": "us",
    "created_at": "2022-09-14T04:54:57.707Z",
    "updated_at": "2022-09-26T12:17:48.37Z",
    "active": true,
    "customer": "627cda54ff688c037a39291b"
}
```

</ResponseBox>

## Arguments

| Name                 | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Required |
| :------------------- | :------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- |
| name <br/>           | `string` | An alias you can assign to 100ms rooms. This is `case-insensitive`. <br/><br/>Accepted characters are `a-z, A-Z, 0-9, and . - : _`. If not provided, this is generated automatically. <br/><br/>**Note**: `Update room request` is triggered with an existing room name, then the corresponding room ID is returned.                                                                                                                                                                                                          | No       |
| description <br/>    | `string` | A string to describe your room's usage. For example "9PM English Class Batch 2"                                                                                                                                                                                                                                                                                                                                                                                                                                    | No       |
| recording_info <br/> | `object` | Object of type `recording_info`. This object contains information for enabling recording/setting storage location for recordings. <br/><br/>Check the [recording_info arguments](/server-side/v2/Rooms/create-via-api#recording-info-arguments) below for more information. <br/><br/> **Note:** This argument is only applicable to enable/disable [SFU recording](/server-side/v2/Destinations/recording). Refer to [RTMP Streaming & Browser Recording](/server-side/v2/Destinations/rtmp-streaming-and-browser-recording) guide for other options. | No       |
| region <br/>         | `string` | Region in which you want to create room. <br/><br/> `in` - India <br/> `us` - United States <br/> `eu` - European Union <br/> `auto` - Automatic region selection (default, and in case this parameter is not provided)                                                                                                                                                                                                                                                                                            | No       |


Update a room


Trigger this request to disable a specific room.

> **Note:** If you disable a room, that room can be used for only the current session and users will not be able to join the room later. You can use this API with the `enabled` param set to `true` to enable the room again.

<PostRequest title="https://api.100ms.live/v2/rooms/<room_id>" />
<Request id="req-0">

```bash
curl --location --request POST 'https://api.100ms.live/v2/rooms/<room_id>' \
--header 'Authorization: Bearer <management_token>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "enabled": false
}'
```

</Request>
<ResponseBox id="res-0" status="200 OK">

```json
{
    "id": "6316d5cfae8c4271df5d0554",
    "name": "new-room-1662440912",
    "enabled": false,
    "description": "",
    "customer_id": "627cdddff2e4e30487862ad1",
    "recording_source_template": true,
    "enabled_source_template": true,
    "recording": null,
    "template_id": "",
    "template": "",
    "region": "",
    "created_at": "2022-09-06T05:08:31.935Z",
    "updated_at": "2022-09-08T14:58:25.629819038Z",
    "active": false
}
```

</ResponseBox>

## Arguments

| Name                       | Type      | Description                                                                                                         | Required |
| :------------------------- | :-------- | :------------------------------------------------------------------------------------------------------------------ | :------- |
| id <br/> — path param      | `string`  | Unique identifier of the room you wish to disable. <br/><br/>**Example**: 627cda81ab4f3b56a077dc33                  | Yes      |
| enabled <br/> — body param | `boolean` | Status of the room to be set. <br/>`Allowed values`: true, false. <br/>Should be set to `false` to disable the room | Yes      |


Disable/Enable a room


**CLASS**

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

## Properties

### maxBitrate

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

### trackDescription

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

## Methods

### init

```swift
public init()
```

### init

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


HMSAudioTrackSettings


## Installing our libraries

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

```dart
#pubspec.yaml

dependencies:
  flutter:
    sdk: flutter

  hmssdk_flutter:
```
> HMSSDK is supported with flutter 2.10.x or above versions.

## Setting up the library

Run following in command in terminal.

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

### Android 

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

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

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

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

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

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

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

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

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

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

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview. Please follow [Android Documentation](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

### Update target Android version

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

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

### iOS

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

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

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


## Debugging Tools

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

## Proguard configuration

Add this to your proguard-rules.pro

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


### 100ms Flutter app

You can download & check out the 100ms Flutter app - 

🤖 The Flutter Android app from [Google Play Store here](https://play.google.com/store/apps/details?id=live.hms.flutter)

📱 Flutter iOS app from [Apple App Store here](https://apps.apple.com/app/100ms-live/id1576541989)


### Github Repo 
You can checkout the 100ms Flutter SDK Github repo which also contains a fully fledged [Example app implementation here](https://github.com/100mslive/100ms-flutter/)


100ms Flutter SDK Integration Guide


## Installing the dependencies

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

## Permissions

### For iOS

Add following lines in `Info.plist` file

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

### For Android

Add following permissions in `AndroidManifest.xml`

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

You will also need to request Camera and Record Audio permissions at runtime before you join a call or display a preview. Please follow [Android Documentation](https://developer.android.com/training/permissions/requesting#request-permission) for runtime permissions.

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

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

### Proguard configuration

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

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

Add it to your proguard-rules.pro

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

### Expo Setup

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

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

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

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

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

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


### [Github Repo](https://github.com/100mslive/react-native-hms/)
You can checkout the 100ms React Native SDK Github repo which also contains a fully fledged [Example app implementation here](https://github.com/100mslive/react-native-hms/) 



### [Example App](https://github.com/100mslive/react-native-hms/tree/develop/example)

In the [100ms Example App](https://github.com/100mslive/react-native-hms/tree/main/example) we have shown how to setup the various listeners, what data to store in the redux and what all features you can implement.

We have also implemented multiple views which are commonly used. Checkout the [videos & relevant code in the Example app](https://github.com/100mslive/react-native-hms/tree/main/example#additional-features).


Integrating the SDK


## Installing our libraries

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

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

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

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

</Tab>

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

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

</Tab>

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

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

</Tab>

## Setting up the sdk

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

In case you want to use the CDN link, you can change the imports as present in the example [here](https://codepen.io/triptu/pen/dymxmoR?editors=0010). It's recommended to use a fixed version with CDN to avoid unintentional retrieval of a new release with breaking changes. Although CDN is great for quickstart and prototyping, we highly recommend setting up a bundler for production to improve page load speed and avoid a dependency on cdn provider.


### JavaScript

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

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

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

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

<Tab id='store-0'>

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

const hms = new HMSReactiveStore();

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

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

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

</Tab>

<Tab  id='store-1'>

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

</Tab>

### React Hooks

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

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

<Tab id='react-0'>

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

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

```

</Tab>

<Tab  id='react-1'>

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

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

  return </>;
}
```

</Tab>

## Debugging

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


Integrating The SDK


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

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

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

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


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

1. First, generate an auth token using any http request package 
   available on [pub.dev](https://pub.dev/) we are using [http](https://pub.dev/packages/http) package.

   ```dart
   Future<String> getToken({required String user, required String room}) async {
        http.Response response = await http.post(Uri.parse  (Constant.getTokenURL),
            body: {'room_id': room, 'user_id': user, 'role': Constant.defaultRole});

        var body = json.decode(response.body);
        return body['token'];
    }
   ```
    you need to do POST request at the endpoint generated which is present in your dashboard.
    You need three parameters to make POST request.

    `room_id`: room id. `user_id`: name you want. 
    `role`: role you want.


2. Next, create an object of HMSConfig class using the available  joining configurations

   ```dart
   HMSConfig config = HMSConfig(authToken: token,
                                userName: user);
   ```

3. You'll want to handle the callbacks from joining the room by making your ViewModel, Presenter or whatever you're using to handle business logic implement the HMSUpdateListener interface and overriding the methods.

4. Now, we are primed to join the room. All you have to do is pass the config object to `join` present in `HMSSDK` class.

   Create instance of HMSSDK -
   ```dart 
   HMSSDK hmsSDK = HMSSDK();
   ```
   
   Build HMSSDK -
   ```dart
   hmsSDK.build();
   ```

   Now join by passing config object created in previous step.
   ```dart 
   hmsSDK.join(config);
   ```

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

Now, let's take a look at the listener class you have to implement.
 
```dart

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

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

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

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

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

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

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

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

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

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

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

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

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

  ///whenever a new audio device gets connected to the device or audio device is switched this is triggered
  void onAudioDeviceChanged(
     {HMSAudioDevice? currentAudioDevice,
     List<HMSAudioDevice>? availableAudioDevice});
}

```

>HMSUpdateListener: A class conforming to HMSUpdateListener interface.
The methods of HMSUpdateListener are invoked to notify updates happening in the room like a peer joins/leaves, a track got muted/unmutes, etc.

Add this `updateListener` instance to hmsSDK : 
```dart
HMSSDK hmsSDK = HMSSDK();
hmsSDK.build();
hmsSDK.addUpdateListener(updateListener);
```

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

✅ If successful, the `onJoin({required HMSRoom room})` method of HMSUpdateListener will be invoked with information about the room encapsulated in the HMSRoom object.

❌ If failure, the `onHMSError({required HMSException error})` method will be invoked with exact failure reason.


Join Room


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.

> Note: join is async from this [version](../release-notes/release-notes#2022-09-13)

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

<Tab id='join-0'>

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

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

await hmsActions.join(config);

```

</Tab>

<Tab  id='join-1'>

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

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

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

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

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

</Tab>

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

## Getting Current Room State

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

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

<Tab id='connected-0'>

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

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

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

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

</Tab>

<Tab  id='connected-1'>

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

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

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

</Tab>

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



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


Before calling leave,remove the `HMSUpdateListener` instance as:
```dart
hmsSDK.removeUpdateListener(updateListener);
```

To leave the meeting,call `leave` method of `HMSSDK` as :
```dart
hmsSDK.leave();
```


Leave Room


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

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

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

## Leave on Navigating Away

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

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



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) peer's 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 peers by calling `hmsSDK.getRemotePeers()`

> 💡 You may get null for any track if the peer was not allowed to publish the track according to its role permissions.


```dart

hmsSDK.switchAudio(true);

hmsSDK.switchVideo(true);

hmsSDK.switchCamera();

hmsSDK.stopCapturing();

hmsSDK.startCapturing();
````

### Setting video and mic off while joining

If you want to join room with audio and video off. you can follow this
In `onJoin` you can call `switchAudio` and `switchVideo`.if you want both audio and video to be off while joining.

```dart

    HMSSDK hmssdk = HMSSDK();

    @override
    void onJoin({required HMSRoom room}) async {

        this.isLocalPeerVideoOn = false;
        this.isLocalPeerMicOn = false;

        hmssdk.switchAudio(isOn: true);
        hmssdk.switchVideo(isOn: true);
    }

```

Mute / Unmute


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,
    useVideo,
    selectPeers,
} from '@100mslive/react-sdk';

function VideoTile({ peer }) {
    const { videoRef } = useVideo({
        trackId: peer.videoTrack
    });
    
    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.

> Note that if you're using the `useVideo` hook from `react-sdk` this is already being taken care of.

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


Render Video


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 send a broadcast.

The parameters are:

1. *message*: The text of the message.


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


```dart
hmsSDK.sendBroadcastMessage(message: "Hi", hmsActionResultListener: hmsActionResultListener);
```

#### 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. *message*: The text of the message.
2. *peerTo*: The `HMSPeer` instance who should receive the message.


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



```dart
hmsSDK.sendDirectMessage(
        message: "Hi",
        peerTo: peerTo,
        hmsActionResultListener: hmsActionResultListener);
```


#### 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. *message*: The text of the message.
2. *hmsRolesTo*: The name of the role.


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

```dart
hmsSDK.sendGroupMessage(message: "Hi",
        hmsRolesTo: hmsRolesTo,
        hmsActionResultListener: hmsActionResultListener);
```

### Receiving Chat Messages

When you called `hmsSDK.join(config)` to join a room, the `HMSUpdateListener` implementation that was passed in had the callback `void onMessage({required HMSMessage message});`.

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

```dart
class HMSMessage(

  final HMSPeer? sender;
  final String message;
  final String type;
  final DateTime time;
  HMSMessageRecipient? hmsMessageRecipient;

  HMSMessage({
    required this.sender,
    required this.message,
    required this.type,
    required this.time,
    this.hmsMessageRecipient
  });
)
```

* *message*: Content of the text message or the text description of the raw message.
* *type*: Type of message sent. The default value is `chat`.
* *hmsMessageRecipient*: The intended recipient(s) of this message as a `HMSMessageRecipient`.
* *time*: DateTime 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 of 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 DateTime datatype.

### 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 `hmsMessageRecipient` field of `HMSMessage` lets you know who the message was for.

The `HMSMessageRecipient` contains:

```dart
class HMSMessageRecipient{
    HMSPeer? recipientPeer;
    List<HMSRole>? recipientRoles;
    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.

`hmsMessageRecipientType`: Can contain enum value `BROADCAST`, `PEER` and `ROLES`.

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

### Store Chat Messages

You can store chat message by creating a list of `HMSMessage` and append new messages from the callback `onMessage({required HMSMessage message})` as follow:

```dart
List<HMSMessage> messages = [];

@override
void onMessage({required HMSMessage message}) {
  messages.add(message);
}
```

### Filter Chat Messages

You can filter chat messages by creating a separate list of `HMSMessage`.

```dart
List<HMSMessage> broadcastList = [];
List<HMSMessage> rolesList = [];
List<HMSMessage> peerList = [];

List<HMSMessage> messageFilter(List<HMSMessage> messages, HMSMessageRecipientType type) {
  filterList = [];
  for(HMSMessage message in messages) {
    // Filter list on the basis of Broadcast chat.
    if(message.hmsMessageRecipient.hmsMessageRecipientType == HMSMessageRecipientType.BROADCAST) {
      broadcastList.add(message);
    }

    // Filter list on the basis of Roles chat.
    if(message.hmsMessageRecipient.hmsMessageRecipientType == HMSMessageRecipientType.ROLES) {
      rolesList.add(message);
    }

    // Filter list on the basis of Peer chat.
    if(message.hmsMessageRecipient.hmsMessageRecipientType == HMSMessageRecipientType.PEER) {
      peerList.add(message);
    }
  }
}
```

### Advanced Use-Cases

Sometimes the app requires to show messages in different styles. Something similar to this:

![Chat](/docs/v2/flutter-chat.gif)

HMSSDK provides the `type` parameter of the `HMSMessage` object to take care of such use cases.

You can send messages as:

```dart
hmsSDK.sendBroadcastMessage(message: "😁", type: "emoji", hmsActionResultListener: hmsActionResultListener);
```

Filter out the messages based on the `type` parameter and handle the UI accordingly.

```dart
//Example to show emoticons when the message type is set to `emoji`
@override
void onMessage({required HMSMessage message}) {
  if(message.type=="emoji"){
      //Show as emoticons on UI
  }
  else{
    //Handle other cases
  }
}
```


Chat


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

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

## Toggling current mute state

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

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

<Tab id='mute-0'>

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

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

</Tab>

<Tab id='mute-1'>

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

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

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

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

</Tab>



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 will be much faster.

Create an object of HMSConfig class using the available join configurations

   ```dart
   HMSConfig config = HMSConfig(authToken: token,
                                userName: user);
   ```

To invoke the Preview API call -

```dart
HMSSDK hmsSDK = HMSSDK();
hmsSDK.build();
hmsSDK.preview(config);
```

You need HMSConfig instance which you have created above.

Now you have started preview you need to listen to the updates. You get this via `PreviewUpdateListener`.

```dart
abstract class HMSPreviewListener {

  /// On success, when you want to preview listen to this callback
  ///
  /// - Parameters:
  ///   - room: the room which was joined
  ///   - localTracks: local audio/video tracks list
  void onPreview({required HMSRoom room, required List<HMSTrack>localTracks});

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

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

This 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 delegate callback will be fired with the `HMSException` instance you can use the object to find what went wrong (see [Error Handling](error-handling)).


Add the `previewListener` instance to 

```dart
hmsSDK.addPreviewListener(previewListener);
```


Preview


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)

> Note: Chat messages are not persistent. For example, if you joined a call, received some messages and got disconnected and rejoin the call, you won't be able to see the previous messages

## Sending Chat Messages

### Broadcast Message:

This will be received by everyone in the room.

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

### Group Message:

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

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

### Direct Message:

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

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

## Showing the messages

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

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

<Tab id='chat-0'>

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

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

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

</Tab>

<Tab id='chat-1'>

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

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

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

</Tab>

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

## Marking a message as read

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

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

## Message Notification

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

## Custom Events

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

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

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

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

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

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

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

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

## useCustomEvent

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

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

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

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

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

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

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

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

export default Confetti;
```



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

To render video you will use HMSVideoView. To use it we will need a few things:

1. HMSTrack: `HMSVideoView` will render video using trackId from HMSTrack.
2. `HMSVideoView` will use viewSize to get the height and width of the rendered video. If not passed, it will take whatever size is available to the widget.

## How to get HMSTrack 

`HMSTrack` is used to render video in HMSVideoView.Single `HMSVideoView` can be attached to only one `HMSVideoTrack`.

> For resetting the track or updating any property in `HMSVideoView` it is required to use the new HMSVideoView widget.

And you can get all tracks by listening to `HMSUpdateListener.onTrackUpdate`

Add a check on these tracks to see if they are video tracks or audio tracks.

> `HMSSDK` automatically handles audio tracks. So they are not required to be set in the application. Although [mute/unmute](../features/mute) or [set audio volume](../advanced-features/set-volume) features are provided
> by SDK.  

For example -

```dart
/// check if the track is video or audio

/// For Audio
track.kind == HMSTrackKind.kHMSTrackKindAudio

/// For Video
track.kind == HMSTrackKind.kHMSTrackKindVideo
```

Now, you can pass the video track to `HMSVideoView ` to get your live video on the screen.

## Render Video

To display video tracks `HMSSDK` provides the `HMSVideoView` widget.

```dart
class HMSVideoView extends StatelessWidget {
  ///  This will render video with trackId present in track and it will have height = 50 and width = 50
  //[track] - track to be displayed
  final HMSVideoTrack track;

  //[matchParent] - to match the size of parent widget
  final matchParent;

  //[scaleType] - To set the video scaling
  final ScaleType scaleType;

  //[setMirror] - To set mirroring of video
  //Generally true for local peer and false for a remote peer
  final bool setMirror;
}
```

> `HMSVideoView` also accepts `Key` as an optional parameter but it is recommended to always pass `Key` to `HMSVideoView` So that it can be disposed of and reset correctly during rebuilds.

Let's understand the `ScaleType` property a bit more. The `ScaleType` property decides how much space the video will take from the available space.

```dart
enum ScaleType { 
  
  //Video maintains the aspect ratio so it only occupies space based on the aspect ratio
  SCALE_ASPECT_FIT, 
  
  //Video occupies all the available space and may get cropped 
  SCALE_ASPECT_FILL, 

  //Video aspect ratio is balanced similar to SCALE_ASPECT_FIT
  SCALE_ASPECT_BALANCED 
}
```

> 🔑  Note: `SCALE_ASPECT_FIT` is the default scaleType for HMSVideoView

## Dispose HMSVideoView to conserve bandwidth and cleanup elements

Remove the HMSVideoView from UI and it will not render its video & conserve network bandwidth.

It is always advised to stop rendering video when it is not required to save bandwidth consumption.
This is done in the example app by setting the `isOffscreen` property of `PeerTrackNode` as true when the peer tile is off-screen. So that app does not download the video track when the tile is off-screen.

## Limit the number of HMSVideoView on-screen at a time 

`HMSVideoView` internally uses `SurfaceView` in android and `UiKitView` in iOS.It is recommended to render at most 4-6 videos at a time on-screen and 
rest should be paginated for better performance. 

For a full example try out our [Example app here](https://github.com/100mslive/100ms-flutter/tree/main/example).



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

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

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


Change User Name


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

## Manual Device Change

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

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

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

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

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

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

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

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

## Remember manually selected devices

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

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


Device Changes


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

These are returned as `HMSException` in the `onHMSError` callback of the `HMSUpdateListener`.

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

| **Error Code** | **Cause of the error**                                 | **Action to be taken**                                                                                     |
| :------------- | :----------------------------------------------------- | :--------------------------------------------------------------------------------------------------------- |
| **1003**       | Websocket disconnected - Happens due to network issues | Mention user to check their network connection or try again after some time.                                |
| **2002**       | Invalid Endpoint URL                                   | Check the endpoint provided while calling `join` on `HMSSDK`.                                               |
| **2003**       | Endpoint is not reachable                              | Mention user to check their network connection or try again after some time.                                |
| **2004**       | Token is not in proper JWT format                      | The token passed while calling `join` is not in correct format. Retry getting a new token.                  |
| **3001**       | Cant Access Capture Device                             | Ask user to check permission granted to audio/video capture devices.                                        |
| **3002**       | Capture Device is not Available                        | Ask user to check if the audio/video capture device is connected or not.                                    |
| **3003**       | Capture device is in use by some other application.    | Show notification to user mentioning that the capturing device is used by some other application currently. |
| **3012**       | [BLUETOOTH_CONNECT](https://developer.android.com/reference/android/Manifest.permission#BLUETOOTH_CONNECT) permission is not given.| Add the BLUETOOTH_CONNECT permission to your app and request it at runtime since it's a dangerous level permission.|
| **3013**       | [BLUETOOTH](https://developer.android.com/reference/android/Manifest.permission#BLUETOOTH) permission is not given.                     | Add the BLUETOOTH permission to your app.|
| **4001**       | WebRTC error                                           | Some webRTC error has occurred. Need more logs to debug.                                                     |
| **4002**       | WebRTC error                                           | Some webRTC error has occurred. Need more logs to debug.                                                     |
| **4003**       | WebRTC error                                           | Some webRTC error has occurred. Need more logs to debug.                                                     |
| **4004**       | WebRTC error                                           | Some webRTC error has occurred. Need more logs to debug.                                                     |
| **4005**       | ICE Connection Failed due to network issue             | Mention user to check their network connection or try again after some time.                                |
| **5001**       | Trying to join a room which is already joined          | Trying to join an already joined room.                                                                     |
| **6002**       | webRTC Error: Error while renegotiating                | Please try again.                                                                                           |
| **40101**      | Token Error: Invalid Access Key                        | Access Key provided in the token is wrong.                                                                  |
| **40102**      | Token Error: Invalid Room Id                           | RoomID provided in the token is wrong.                                                                      |
| **40103**      | Token Error: Invalid Auth Id                           | AuthID provided in the token is wrong.                                                                      |
| **40104**      | Token Error: Invalid App Id                            | App ID provided in the token is wrong.                                                                      |
| **40105**      | Token Error: Invalid Customer Id                       | Customer Id provided in the token is wrong.                                                                 |
| **40107**      | Token Error: Invalid User Id                           | User ID provided in the token is wrong.                                                                     |
| **40108**      | Token Error: Invalid Role                              | The role provided in the token is wrong.                                                                    |
| **40109**      | Token Error: Bad JWT Token                             | Bad JWT Token.                                                                                              |
| **40100**      | Generic Error                                          | Need to debug further with logs.                                                                            |
| **40001**      | Invalid Room                                           | Room ID provided while fetching the token is an invalid room.                                               |
| **40002**      | Room Mismatched with Token                             | Room ID provided while fetching the token does not match.                                                   |
| **40004**      | Peer already joined                                    | Peer who is trying to join has already joined the room.                                                     |
| **41001**      | Peer is gone                                           | The peer is no more present in the room.                                                                    |
| **7001**       | Platform Not Supported                                 | The platform is not supported for plugin                                                                    |
| **7002**       | Plugin Init Failed                                     | Plugin initialization has failed                                                                            |
| **7003**       | Plugin Processing Failed                               | Plugin processing failed                                                                                    |
| **7004**       | Plugin Add Already Going on                            | Plugin add is already in progress    

## HMSException

The SDK returns error as an object of `HMSException` in `onHMSError` method.

```dart
@override
void onHMSError({required HMSException error}){
    //Handle Error
}
```
Let's have a look at the `HMSException` object 
```dart
class HMSException {
  final String? id; 

  //HMSException code
  final HMSExceptionCode? code;

  //Error message
  final String message;

  //Error description 
  String description; 

  //Action in which SDK failed
  String action; 
   
  //Extra params sent with the error
  Map? params;

  //Whether the error is a terminal error or not
  bool isTerminal;
}
```

## Terminal Errors 

Terminal errors are raised when SDK has cleaned up the connection due to the error.
`isTerminal` property of HMSException object can be used to check whether the error is a terminal error.

> 💡 Note: `isTerminal` denotes if the SDK has cleaned up the connection due to the error or not.
If this is [true] it denotes that the error has removed user from the room
   else it denotes that user is still in the room even with the error.


Hence `isTerminal` property can be used to handle the UI as if `isTerminal:true` we can navigate user back to home screen or show them a popup.
While in other case the error can be handled accrodingly.

Terminal error example:

![Terminal Error](/docs/v2/flutter-errorCode-1003.png)

Above error(`errorCode:1003`) occurs when the reconnection fails.The SDK returns this error after trying to reconnect for 60 seconds.
In such cases the `isTerminal` property can be used to handle the UI updates.

> 🔑  More info on reconnection handling can be found [here](./reconnection-handling)

Error Handling


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

To invoke this API call

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

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

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

## Post Preview call

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

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

## When you do join

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

## Limitations

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

## Know Others in the room

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

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

<Tab id='peers-0'>

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

</Tab>

<Tab id='peers-1'>

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

</Tab>

## Network Quality in preview

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



Now, let's take a look at the listener class to be implemented.

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


  /// 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:
  ///   - peer: the peer who joined/left or was updated
  ///   - update: the triggered update type. Should be used to perform different UI Actions
  void onPeerUpdate({required HMSPeer peer, required HMSPeerUpdate update});


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


  /// This 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
  void onMessage({required HMSMessage message});


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


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

  /// 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 occurred
  void onHMSError({required HMSException error});


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


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


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

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

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

  ///whenever a new audio device gets connected to the device or audio device is switched this is triggered
  ///- Parameters
  ///  - currentAudioDevice - current audio output device
  ///  - availableAudioDevice - list of available audio output devices
  void onAudioDeviceChanged(
     {HMSAudioDevice? currentAudioDevice,
     List<HMSAudioDevice>? availableAudioDevice});
}
```

> `HMSUpdateListener` : A class conforming to HMSUpdateListener interface.
The methods of HMSUpdateListener are invoked to notify updates happening in the room like a peer join/leave, track mute/unmute etc.

Add this `updateListener` instance to
```dart
HMSSDK hmsSDK = HMSSDK();
hmsSDK.build();
hmsSDK.addUpdateListener(updateListener);
```

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

✅ If successful, the `onJoin({required HMSRoom room})` method of HMSUpdateListener will be invoked with information about the room encapsulated in the HMSRoom object.

❌ If failure, the `onHMSError({required HMSException error})` method will be invoked with exact failure reason.

Remove the `updateListener` instance as:

```dart
hmsSDK.removeUpdateListener(updateListener);
```

Update Listeners


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

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

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

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

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

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

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

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

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

</Tab>

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

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

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

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

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

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

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

</Tab>

## Notification types

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

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

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

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

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

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

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

</Tab>

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

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

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

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

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

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

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

</Tab>

## Listening to specific notifications

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

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

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

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

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

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

</Tab>

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

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

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

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

        console.log('notification type', notification.type);
        console.log('data', notification.data);
    }, [notification]);

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

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

</Tab>

## Unsubscribing from notifications

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

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

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

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

unsubscribe();
```

</Tab>

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

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

</Tab>

## Ideas

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

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


Notifications


## HMSPeerUpdate

Whenever there is an update related to a peer the `HMSSDK` sends it as `HMSPeerUpdate` enum type

```dart
///PeerUpdates in a room.
enum HMSPeerUpdate {
  ///When new peer joins the room.
  peerJoined,

  ///When peer left the room.
  peerLeft,

  ///when peer's role is changed
  roleUpdated,

  ///when meta data is changed(eg:Hand Raise)
  metadataChanged,

  ///When Peer name is changed
  nameChanged,

  ///Peer's network quality updates
  networkQualityUpdated
  
  ///Unknown Update
  defaultUpdate
}
```

## HMSTrackUpdate

Whenever there is an update related to track the `HMSSDK` sends it as `HMSTrackUpdate` enum type

```dart
///Track updates you will get when there is any change in the track
enum HMSTrackUpdate {
  //when a new track is added.
  trackAdded,

  ///when track is removed.
  trackRemoved,

  ///when track is muted could be audio,video or both.
  trackMuted,

  ///when track is unmuted could be audio,video or both.
  trackUnMuted,

  ///When track is degraded
  trackDegraded,

  ///When track is restored
  trackRestored,

  ///when track description is changed
  trackDescriptionChanged,

  ///default update
  defaultUpdate
}
```


## HMSRoomUpdate

Whenever there is an update related to room the `HMSSDK` sends it as `HMSRoomUpdate` enum type

```dart
enum HMSRoomUpdate {

  ///When room is muted
  roomMuted,

  ///When room is unmuted
  roomUnmuted,

  ///When server recording state is updated
  serverRecordingStateUpdated,

  ///When RTMP is started or stopped
  rtmpStreamingStateUpdated,

  ///When HLS is started or stopped
  hlsStreamingStateUpdated,

  ///When hls recording state is updated
  hlsRecordingStateUpdated,

  ///When browser recording state is changed
  browserRecordingStateUpdated,

  ///When room name changed
  RoomNameUpdated,

  ///Default Update
  defaultUpdate
}
```


Update Listeners Enums


## When does a room become active?

A room becomes active when one or more peers join a room to start real-time video/audio interactions in a video conferencing or live streaming session.

![Active room](/docs/v2/active-room.png)

## Active room APIs

Use Active Room APIs to perform server-to-server actions that automate your business logic in 100ms rooms. These actions can be used to control peer behavior and build interactivity scenarios

-   Control peers by [changing roles](/server-side/v2/active-rooms/update-a-peer), [removing peers](/server-side/v2/active-rooms/remove-peers), and [ending the room](/server-side/v2/active-rooms/end-active-room)
-   Build interactivity scenarios by [updating peer metadata](/server-side/v2/active-rooms/update-a-peer) and [sending broadcast/direct messages](/server-side/v2/active-rooms/send-message)
-   [Retrieving the details of an active room](/server-side/v2/active-rooms/retrieve-active-room) and [a specific peer](/server-side/v2/active-rooms/retrieve-peer) will act as supporting pillars to implement the above mentioned actions.

### When should I use room APIs and Active room APIs?

-   **Room APIs**: You can use room APIs to create a room, link a template, and update room properties such as recording configuration and server region.
-   **Active room APIs**: You can use these APIs to control peer behavior and build interactivity scenarios in an active room.

### What can I build?

We have drafted some examples to help you understand how active room APIs will enable you to control peer behavior and build interactivity scenarios:

-   [Fetch the list of peers](/server-side/v2/active-rooms/retrieve-active-room) in an active room and perform actions like:
    -   Nudge a specific peer if their [video is turned off](/server-side/v2/active-rooms/retrieve-peer#why-would-you-use-this-api).
    -   Send a broadcast message to all peers to inform the speaker's unavailability. For [example](/server-side/v2/active-rooms/send-message#why-would-you-use-this-api), send a message to all the students if the teacher cannot join the session at the last minute.
    -   [Kick a peer](/server-side/v2/active-rooms/remove-peers#why-would-you-use-this-api) in case of any misconduct(abusive chat).
-   To build real-time interactivity, like [updating a custom avatar](/server-side/v2/active-rooms/update-a-peer#why-would-you-use-this-api) in the video tile, [virtual poker handler](/server-side/v2/active-rooms/send-message#example2-poker-handler) for a multiplayer game, and more.

## Postman collection

You can use our Postman collection to start exploring 100ms APIs.

[![Run in Postman](https://run.pstmn.io/button.svg)](https://god.gw.postman.com/run-collection/22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a?action=collection%2Ffork&collection-url=entityId%3D22726679-47dcd974-29d5-4965-a35b-bf9b74a8b25a%26entityType%3Dcollection%26workspaceId%3Dd9145dd6-337b-4761-81d6-21a30b4147a2)

Refer to the [Postman guide](/server-side/v2/introduction/postman-guide) to get started with 100ms API collection.



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

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

## Setting up the HMS Instance

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

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

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

## Check Permissions

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

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

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

// ios
joinRoom();
```

## Add event listeners

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

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

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

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

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

## Join the room

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

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

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

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

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

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

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

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

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

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

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

## Joining room audio/video muted

There are 2 ways to join the room with muted state. First one is with change role which does not require mic and camera permissions. Second one is calling mic and camera mute in onPreview and onJoin which asks for camera and mic permissions.

To join room with audio & video muted using change role, you need to create 2 roles. First role with no audio & video permissions. Second role with audio & video permissions. Join the room using viewer role. Since viewer doesn’t have permissions no need to preview, directly call join and navigate to meeting screen. Once you have joined the room and now you need to speak or share video, call change role API. How to call change role API [here](./change-role).

![Viewer Audio & Video Publish Settings](/docs/v2/audio-video-publish.png)

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

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

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

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

## Get Room

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

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




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

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

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

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

then run `pod install --repo-update`

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

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



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

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

## Handling Autoplay Error

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

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

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

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

## Error Codes

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

| **Error Code** | **Cause of the error**                                                                                    | **Action to be taken**                                                                                      |
| :------------- | :-------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |
| **1000**       | Failed to connect to Websocket - Happens to due network issues or firewall blocking Websocket connections | Mention user to check their network connection and firewall/anti-virus/VPN or try again after some time.    |
| **1003**       | Websocket disconnected - Happens due to network issues                                                    | Mention user to check their network connection or try again after some time.                                |
| **2002**       | Invalid Endpoint URL                                                                                      | Check the endpoint provided while calling `join` on `HMSSDK`.                                               |
| **2003**       | Endpoint is not reachable                                                                                 | Mention user to check their network connection or try again after some time.                                |
| **2004**       | Token is not in proper JWT format                                                                         | The token passed while calling `join` is not in correct format. Retry getting a new token.                  |
| **3000**       | Overconstrained error                                                                                     | No Action needed from end user, we will be internally retrying.                                             |
| **3001**       | User denied permission to access capture device at browser level                                          | Ask user to check permission granted to audio/video capture devices in browser(in address bar).             |
| **3002**       | Capture Device is not Available                                                                           | Ask user to check if the audio/video capture device is connected or not.                                    |
| **3003**       | Capture device is in use by some other application                                                        | Show notification to user mentioning that the capturing device is used by some other application currently. |
| **3005**       | There is no media to return. Please select either video or audio or both.                                 | There is no media to return. Please select either video or audio or both.                                   |
| **3008**       | Browser has throw an autoplay exception                                                                   | Show notification to user mentioning that the browser blocked autoplay                                      |
| **3009**       | Device unable to satisfy requested media constraints                                                      | Reduce media constraints for the role in dashboard or upgrade device hardware.                              |
| **3010**       | No audio detected from track, indicates problem with device hardware                                      | Notify user to try using a headphone for microphone.                                                        |
| **3011**       | System denied permission to access capture device                                                         | Ask user to check permission granted to audio/video/screen capture devices in system settings.              |
| **4001**       | WebRTC error                                                                                              | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4002**       | WebRTC error                                                                                              | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4003**       | WebRTC error                                                                                              | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4004**       | WebRTC error                                                                                              | Some webRTC error has occured. Need more logs to debug.                                                     |
| **4005**       | ICE Connection Failed due to network issue                                                                | Mention user to check their network connection or try again after some time.                                |
| **5001**       | Trying to join a room which is already joined                                                             | Trying to join an already joined room.                                                                      |
| **5002**       | Trying to join a room when preview is in progress                                                         | Call join action only when room state is "Preview" and not "Connecting".                                    |
| **6000**       | Calling actions when not connected/joined to a room                                                       | Call the required action after joining a room.                                                              |
| **6002**       | WebRTC Error: Error while renegotiating                                                                   | We can add check `error.message` for more info.                                                             |
| **6003**       | WebRTC engine is not ready yet                                                                            | Wait for preview to complete before calling join.                                                           |
| **6008**       | Invalid arguments(peer ID, track ID, or others) passed to actions                                         | Check if the corresponding arguments are valid by checking the store when calling the action                |
| **6009**       | Trying to join a room when preview is in progress                                                         | Call join action only when room state is "Preview" and not "Connecting".                                    |
| **6010**       | navigator.mediaDevices is undefined in insecure contexts served over HTTP protocol                        | Deploy the app in a secure context with HTTPS protocol.                                                     |
| **6011**       | RTCPeerConnection is undefined in browser                                                                 | Switch/Upgrade browser to WebRTC compatible version/check for browser extenstion blocking WebRTC.           |
| **7001**       | Platform Not Supported                                                                                    | The platform is not supported for plugin                                                                    |
| **7002**       | Plugin Init Failed                                                                                        | Plugin initialization has failed                                                                            |
| **7003**       | Plugin Processing Failed                                                                                  | Plugin processing failed                                                                                    |
| **7004**       | Plugin Add Already Going on                                                                               | Plugin add is already in progress                                                                           |
| **8001**       | Playlist: Invalid action call                                                                             | Check current playing entry, next entry, previous entry when calling seek/seekTo, playNext, playPrevious.   |



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:

```dart
Future<bool> isAllowedToEndRoom() async{
    return (await hmsSDK.getLocalPeer()).role.permission?.endRoom;
}
```

`hmsSdk.getLocalPeer()` will not return null as long as you're in a preview or in a room. 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(reason: "Some reason to end room", lock: false)`.

```dart
void endRoom(
      {required bool lock,
      required String reason,
      HMSActionResultListener? hmsActionResultListener}) async {}
```

`endRoom` takes the following parameters -

_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.
_reason_: reason String is the text that is passed describing why the room is being ended.
_hmsActionResultListener_: It's the callback that would be called by SDK in case of a success or failure of `endRoom` operation

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

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

```dart
class HMSPeerRemovedFromPeer {
  String reason;
  bool roomWasEnded;
  HMSPeer? peerWhoRemoved;
}
```

> 💡 This is the same callback that will be triggered if a peer was [removed from a room](/flutter/v2/features/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.


End Room


Screenshare involves sharing either the complete screen, a specific window or, a browser tab.
For a peer to share their screen, their role must have screenshare enabled in the dashboard.

![ScreenshareDashboard](/docs/v2/screenshare-dashboard.png)

To start a screenshare:

```js
try {
    await hmsActions.setScreenShareEnabled(true);
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

## AudioOnly Screenshare

To start audio only screenshare, you can pass a config as second argument.

```js
try {
    await hmsActions.setScreenShareEnabled(true, {
        audioOnly: true
    });
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

## VideoOnly Screenshare

To start video only screenshare, you can pass a config as second argument.

```js
try {
    await hmsActions.setScreenShareEnabled(true, {
        videoOnly: true
    });
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

To stop the screenshare:

```js
hmsActions.setScreenShareEnabled(false);
```

## Useful Selectors

```js
// to know if someone is screensharing
const screenshareOn = hmsStore.getState(selectIsSomeoneScreenSharing);

// to get the HMSPeer object of the peer screensharing, will select  first if multiple screenshares
const presenter = hmsStore.getState(selectPeerScreenSharing);

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

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

// to get the screenshare video track, this can be used to call attachVideo for rendering
const screenshareVideoTrack = hmsStore.getState(selectScreenShareByPeerID(presenter.id));

// Get the peer who is sharing audio only screenshare
const peer = hmsStore.getState(selectPeerSharingAudio);
// Get the audio track of audio Only screenshare
const audioTrack = hmsStore.getState(selectScreenShareAudioByPeerID(peer?.id));
```

Find more [here](/api-reference/javascript/v2/home/content#functions).

## Screenshare with audio:

We also give support of adding screenshare with audio in chromium based browsers. This only applies if checkbox at bottom left
shown below is checked while sharing a browser tab.

![ScreenshareAudio](/docs/v2/screenshare-audio.png)


Screen Share


`Role` is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. 

Each `HMSPeer` instance has a `role` property which returns an `HMSRole` instance. You can use this property to do the following:

Check what this role is allowed to publish. Can it publish video (and at what resolution)? Can it publish audio? Can it share a screen? Who can this role subscribe to?

This is can be discovered by checking the `publishSettings` and `subscribeSettings` properties.


Check what actions this role can perform. i.e can it change someone else current role, end the meeting, or 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 a `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 the `HMSPeer` of the peer whose 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 the `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 the `getRoles` method of `HMSSDK`

Once you have both you can invoke.

```dart 
hmsSDK.changeRole(peerId,roleName,forceChange);
```

`peer`: the HMSPeer object of the peer.

`roleName`: name of the role.

`forceChange`: Optional boolean value. Set to `true` if you want to force the role change without the peer's explicit acceptance.


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

```dart
void onPeerUpdate({required HMSPeer peer, 
required HMSPeerUpdate update});
```

With the same peer, you passed as targetPeer and a `HMSPeerUpdate.roleUpdated` update type.

The `force` parameter in `changeRole`, when false, is basically a polite request: "Would you like to change your role from listener to speaker?" Which can be ignored by the peer. The way it works is the other peer will first receive a `onRoleChangeRequest` callback in `HMSUpdateListener`:


```dart
void onRoleChangeRequest({required HMSRoleChangeRequest roleChangeRequest});
```

At this point, the app should show a prompt to the user asking for permission to accept or deny role change. 

If the user wants to accepts the request, the app should invoke `acceptRoleChangeRequest` on `HMSSDK` instance:

```dart
hmsSDK.acceptRoleChangeRequest();
```

Now, both all peers in room will receive a `HMSPeerUpdate.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 let's imagine the newly nominated speaker is not behaving nicely and we want to move him back to the 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. 


`HMSPeerUpdate.roleUpdated` callback will still be fired so that the app can update the user's UI state.


Change Role


![Role Change](/guides/role-change.png)

## Introduction

Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. [Learn more about roles here.](../foundation/templates-and-roles)

Every peer is associated with a role. The [`HMSRole`](/api-reference/javascript/v2/interfaces/HMSRole) object can be used to know the following:

1. Check what this role is allowed to publish. i.e can it send video (and at what resolution)? can it send audio? can it share screen? This can be discovered by using `selectIsAllowedToPublish` to display the UI appropriately.
2. Check which other roles can this role subscribe to. This is internally taken care of by the 100ms infra and sdk, and your UI will only get tracks as per allowed subscriptions. `role.subscribeParams` can be used to get details.
3. Check what actions this role can perform. i.e can it change someone else's current role, mute others, end meeting, remove someone from the room. This can be discovered by using the `selectPermissions` selector.

### Example

Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe.
Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the `changeRole` API comes in.

## Know Thy Permissions

The below selectors can be used to know what the local peer is allowed to publish, and the permissions they have. To know about all the
permissions please check [`selectPermissions'`](../../../api-reference/javascript/v2/home/content#select-permissions) api reference.

```js
const role = hmsStore.getState(selectLocalPeerRole);
const permissions = hsmStore.getState(selectPermissions);
console.log("can I end room - ", permissions.endRoom);
console.log("can I end change role - ", permissions.changeRole);
const { video, audio, screen } = hmsStore.getState(selectIsAllowedToPublish);
```

## Change Role API

If the local peer has permissions to change role(`permissions.changeRole`), they can change either their or someone else's role using
the below interface.

```js
hmsActions.changeRole(forPeerId, toRoleName, force);
```

- `forPeerId`: The peer ID whose role needs to be changed, the peer can be either of local or remote.
- `toRoleName`: The target role name.
- `force`(optional): The other peer gets a request by default to accept a role change, by setting force to true, the role can be changed
  without requesting for approval.

> 💡 A list of all available role names in the current room can be accessed via the `selectAvailableRoleNames` selector. Further the `selectRoleByRoleName`
> selector can be used to get the full [HMSRole](/api-reference/javascript/v2/interfaces/HMSRole) object for a role name.

### Handling a Role Change Request

The `force` parameter in `changeRole`, when false, is a polite request: "Would you like to change your role from listener to speaker?" which can be ignored by the other party.
The way it works is the other party will first receive a [request](/api-reference/javascript/v2/interfaces/HMSRoleChangeRequest) which they can accept or reject.

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

<Tab id='roleChange-0'>

```js
function handleRoleChangeRequest(request) {
  if (!request) {
    return;
  }
  console.log(
    `${request.requestedBy.name} requested role change to - ${request.role.name}`
  );
  // shouldAccept can for example present a pop up to the user for deciding how to act on the request
  const accept = shouldAccept(request);
  if (accept) {
    hmsActions.acceptChangeRole(request);
  } else {
    hmsActions.rejectChangeRole(request);
  }
}

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

</Tab>

<Tab  id='roleChange-1'>

```jsx
function handleRoleChangeRequest(request) {
  const request = useHMSStore(selectRoleChangeRequest);
  const hmsActions = useHMSActions();

  useEffect(() => {
    console.log(
      `${request.requestedBy.name} requested role change to - ${request.role.name}`
    );
    // shouldAccept can for example present a pop up to the user for deciding how to act on the request
    const accept = shouldAccept(request);
    if (accept) {
      hmsActions.acceptChangeRole(request);
    } else {
      hmsActions.rejectChangeRole(request);
    }
  }, [request, hmsActions]);

  return null;
}
```

</Tab>

If the request is accepted, the `peer.roleName` field in the store will update re rendering a declarative UI as required.

### Forced Role Change

Imagine that the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt.
This is where the `force` parameter comes in. When it is set to `true` the other party will not receive a confirmation `roleChangeRequest`
but instead will straight away receive a new set of updated permissions and stop publishing.

![Listener Role](/guides/role-listener.png)

### Notifications

You'll get a notification of type `ROLE_UPDATED` when role change happens for the local peer. When a peer's role change
happens in a way where the updated role has new publish permissions, the track will be muted by default. So for example, if a viewer(no audio/video)
is changed to a host, their tracks will be muted right after the role change. They'll be able to manually unmute post role change though.
If you want this unmuting to happen automatically, you can listen to the notification to call the action.

## Ideas

### Breakout Rooms/Groups

You can have multiple roles which act as breakout rooms subscribing only to peers within the role. A peer can join another breakout room
or group easily using the change role API.

### Waiting Room

You can create a specific role for a waiting room which doesn't subscribe to anyone else. When someone joins waiting room,
hosts get a notification, and they can let the person join by changing their role to attendees.

### Audio Rooms

An audio room can be designed with moderators, speakers and listeners where a moderator can promote a listener to speaker
and vice versa.

### Classroom

Roles can be created for muted-student(not allowed to unmute), student-spotlight(publishes higher quality video),
student-screen(allowed to screenshare), prefect(can mute others) etc. to create an enriching feature rich classroom experience.



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

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

```dart
bool isAllowedToRemovePeer() async{
  return (await hmsSDK.getLocalPeer()).role.permission!.removeOthers;
}
```

`hmsSDK.getLocalPeer()` will not return null as long as you're in a preview or in a meeting room. 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.removePeer`.

The parameters are:

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

```dart
void removePeer(
      {required HMSPeer peer,
      required String reason,
      HMSActionResultListener? hmsActionResultListener}) async {}
```

```dart
hmsSDK.removePeer(peer: peerToRemove, reason: "Some good reason to remove the peer")
```

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

```dart
class HMSRemovedFromRoom {
  final HMSPeer peerWhoRemoved;
  final String reason;
  final bool roomWasEnded;
}
```

`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](/flutter/v2/features/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.


Remove Peer


You're running a room and decide that someone who's currently talking shouldn't be talking, or perhaps you want their video turned off. You're looking for a remote mute/unmute in this case.

## Muting/Unmuting

Use the [selectPermissions](./change-role#know-thy-permissions) selector to check whether the local peer has the
permission to `mute` or `unmute` others and then call one of the APIs below.

1. Muting Single Track

To mute a single track, call [`hmsActions.setRemoteTrackEnabled`](../../../api-reference/javascript/v2/interfaces/HMSActions#set-remote-track-enabled)
with the `trackID` of the track you want to mute/unmute and `enable`(`true` for unmuting, `false` for muting).

```js
try {
    await hmsActions.setRemoteTrackEnabled(peer.audioTrack, true);
} catch (error) {
    // Permission denied or invalid track ID or not connected to room
    console.error(error);
}
```

2. Muting Multiple Tracks

You can use this API to mute mute/unmute multiple peers at the same time either by their roles, track source, track type
or any combination of the above. Note that this API always excludes
the local peer from the operation and applies only to remote peers.

```js
try {
    const options = {
        enabled: false, // false to mute, true to unmute
        roles: ['student', 'parents'], // optional, array of roles to mute, mutes everyone if not passed
        type: 'audio', // optional, audio/video, mutes both if not passed
        source: 'regular' // optional, mutes all sources(regular, screen etc.) if not passed
    };
    await hmsActions.setRemoteTracksEnabled(options);
} catch (error) {
    // Permission denied or invalid track ID or not connected to room
    console.error(error);
}
```

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

## Handling a mute/unmute request

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

Once the peer with adequate permissions calls `setRemoteTrackEnabled`, the local peer will receive a [notification](notifications).
In case of single track mute it will be of type `CHANGE_TRACK_STATE_REQUEST` with a
[HMSChangeTrackStateRequest](../../../api-reference/javascript/v2/interfaces/HMSChangeTrackStateRequest) object as the data.

-   Mute requests are automatically applied to the receiver by the SDK. No action is required.

-   For unmute request, use the information in `notification.data` to show a dialog to the user to ask if they want to accept
    the change and then apply the settings locally. The same as in a regular user [Mute/Unmute](mute).

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

<Tab id='remotemutehandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // For Single Track Remote Mute
        case HMSNotificationTypes.CHANGE_TRACK_STATE_REQUEST:
            const { requestedBy, track, enabled } = notification.data;
            // Unmute Request
            if (enabled) {
                // Ask for consent using dialog or any other appropriate UI
                await hmsActions.setEnabledTrack(track.id, enabled);
            } else {
                // Mute Request
                // Show toast to user
            }
            break;
        // For bulk remote mute, notification will contain all the tracks which will be impacted by this request
        case HMSNotificationTypes.CHANGE_MULTI_TRACK_STATE_REQUEST:
            const { requestedBy, tracks, type, source, enabled } = notification.data;
            // Unmute Request
            if (enabled) {
                // Ask for consent using dialog or any other appropriate UI
                tracks.forEach(
                    async (track) => await hmsActions.setEnabledTrack(track.id, enabled)
                );
            } else {
                // Mute Request
                // Show toast to user
            }
            break;
    }
});
```

</Tab>

<Tab id='remotemutehandle-1'>

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

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

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

        switch (notification.type) {
            // For Single Track Remote Mute
            case HMSNotificationTypes.CHANGE_TRACK_STATE_REQUEST:
                const { requestedBy, track, enabled } = notification.data;
                // Unmute Request
                if (enabled) {
                    // Ask for consent using dialog or any other appropriate UI
                    await hmsActions.setEnabledTrack(track.id, enabled);
                } else {
                    // Mute Request
                    // Show toast to user
                }
                break;
            // For bulk remote mute, notification will contain all the tracks which will be impacted by this request
            case HMSNotificationTypes.CHANGE_MULTI_TRACK_STATE_REQUEST:
                const { requestedBy, tracks, type, source, enabled } = notification.data;
                // Unmute Request
                if (enabled) {
                    // Ask for consent using dialog or any other appropriate UI
                    tracks.forEach(
                        async (track) => await hmsActions.setEnabledTrack(track.id, enabled)
                    );
                } else {
                    // Mute Request
                    // Show toast to user
                }
                break;
        }
    }, [notification]);

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

</Tab>


Remote Mute/Unmute


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.

### 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 permission to mute or unmute others. You can do it like this:

```dart
Future<bool> isAllowedToMuteOthers() async{
    return (await hmsSDK.getLocalPeer()).role.permission!.mute;
}

Future<bool> isAllowedToUnMuteOthers(){
    return (await hmsSDK.getLocalPeer()).role.permission!.unMute;
}

```

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

### Mute/Unmute other peers

`HMSSDK` provides dedicated methods to mute/unmute:
- Individual peer
- Specific role

These methods will only work if the peer has permission to mute/unmute another peer's audio/video. The permission can be checked as the steps mentioned
above.


Let's look at each of them:

- Individual peer

We can use the `changeTrackState` method to mute/unmute remote peer's audio/video

```dart
// [forRemoteTrack] : track whose state needs to be changed
// Set [mute] to true if the track needs to be muted, false otherwise.
if(
    //peer has permission to change track state
    localPeer?.role.permissions.mute
  )
HMSSDK.changeTrackState(
        forRemoteTrack: forRemoteTrack,
        mute: mute,
        hmsActionResultListener: this);
```
If the `changeTrackState` method is successful we will get the `onSuccess` callback and track update in `onTrackUpdate`.

- Specific role

We can use the `changeTrackStateForRole` method to mute/unmute peers under specific roles.

```dart
// Set [mute] true if the track needs to be muted, false otherwise
  // [type] is the HMSTrackType which should be affected. If this and the source are specified, it is considered an AND operation. If not specified, all track sources are affected.
  // [source] is the HMSTrackSource that should be affected. If this and type are specified, it is considered an AND operation. If not specified, all track types are affected.
  // [roles] is a list of roles, that may have a single item in a list, whose tracks should be affected. 
  //If not specified, all roles are affected.
  // [hmsActionResultListener] - the callback that would be called by SDK in case of success or failure.
  /// `this` is used here since MeetingStore already implements 
  if(
    //peer has permission to change track state
    localPeer?.role.permissions.mute
    )
    HMSSDK.changeTrackStateForRole(
        mute: mute,
        kind: kind,
        source: source,
        roles: roles,
        hmsActionResultListener: this);
```
If the `changeTrackStateForRole` method is successful we will get the `onSuccess` callback and track update in `onTrackUpdate` similar to `changeTrackState`.

> If *roles* is passed as an empty list then all the roles will get affected.

### Handling a mute callback

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

### Handling an unmute callback

Let's turn the table now to what happens if a remote peer wishes to mute/unmute our audio/video.

- In case when remote peer mutes our audio/video `HMSSDK` performs it automatically without asking permission In another case, we get the `onChangeTrackStateRequest` if 
we accept the request we need to call `switchVideo` or `switchAudio` according to the request.

```dart
 @override
  void onChangeTrackStateRequest(
      {required HMSTrackChangeRequest hmsTrackChangeRequest}){}
```

How this is implemented in the example app can be found [here](https://github.com/100mslive/100ms-flutter/blob/main/example/lib/data_store/meeting_store.dart)

Let's look at the `HMSTrackChangeRequest` structure :

```dart
class HMSTrackChangeRequest {
  bool mute;
  HMSPeer requestBy;
  HMSTrack track;
}
```

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

```dart
public void checkTrack(HMSTrackKind track) {
    if( track.getType() == HMSTrackType.kHMSTrackKindAudio) {

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


If the local peer has [`removeOthers`](./change-role#know-thy-permissions) permission they can remove a peer using the below api.

```js
try {
    const reason = 'Good Bye';
    await hmsActions.removePeer(peer.id, reason);
} catch (error) {
    // Permission denied or invalid peer ID or not connected to room
    console.error(error);
}
```

> 🚧 If the local peer doesn't have the required `removeOthers` permission, a [HMSException](error-handling) will be thrown.

## Remove Peer Notification

Once the peer with adequate permissions calls `removePeer` for the local peer, the local peer will receive a [notification](notifications) with type `REMOVED_FROM_ROOM` with a [HMSLeaveRoomRequest](../../../api-reference/javascript/v2/interfaces/HMSLeaveRoomRequest) object as the data.

The SDK automatically calls leave and performs necessary clean ups immediately after this notification is sent, clients should show the appropriate UI(show a dialog, redirect to a 'good-bye' page) on receiving this notification.

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

<Tab id='removepeerhandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // ...Other notification type cases
        case 'REMOVED_FROM_ROOM':
            // Redirect or Show toast to user
            toast('Reason: ', notification.data.reason);
            break;
    }
});
```

</Tab>

<Tab id='removepeerhandle-1'>

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

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

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

        switch (notification.type) {
            // ...Other notification type cases
            case 'REMOVED_FROM_ROOM':
                // Redirect or Show toast to user
                toast('Reason: ', notification.data.reason);
                break;
        }
    }, [notification]);

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

</Tab>



Sometimes people have bad internet connections but everyone deserves a good meeting.

When the network is too slow to support audio and video conversations together, the 100ms SDK can automatically turn off downloading other peer's videos, which may improve the audio quality and avoid disconnections.

If the network quality improves, the videos will be restored automatically as well.

To turn on subscribe degradation in your room, open the [templates](https://dashboard.100ms.live/templates) in the dashboard and enable it for roles there. Here's more information about [templates](/flutter/v2/foundation/templates-and-roles).


## Responding in the app

All `videoTrack`, within the `HMSPeer`'s have a variable called `isDegraded`.

If `isDegraded` is true, treat it as if the video is turned off. If the UI is not changed, the video tile will appear black.

## Video Track Update

We can listen to the track update of `trackDegraded` and `trackRestored` in `HMSTrackUpdate` to update the UI whenever someone's track gets changed due to degradation.


Auto Video Degrade/Restore


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

If the local peer has [`endRoom`](./change-role#know-thy-permissions) permission they can end a room using the below api. It's also possible to lock
the room to prevent any future rejoins.

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

<Tab id='endroomcall-0'>

```js
function renderEndRoomButton(permissions) {
    const endRoomButton = document.getElementById('end-room-button');

    if (permissions.endRoom) {
        endRoomButton.addEventListener('click', function () {
            try {
                const lock = false; // set to true to disallow rejoins
                const reason = 'party is over';
                await hmsActions.endRoom(lock, reason);
            } catch (error) {
                // Permission denied or not connected to room
                console.error(error);
            }
        });
        endRoomButton.style.display = 'inline-block';
    } else {
        endRoomButton.style.display = 'none';
    }
}

// subscribe to the permissions, so render is called whenever there is a change due to role change
hmsStore.subscribe(renderEndRoomButton, selectPermissions);
```

</Tab>

<Tab id='endroomcall-1'>

```jsx
function EndRoomButton() {
    const permissions = useHMSStore(selectPermissions);
    const hmsActions = useHMSActions();

    const endRoom = () => {
        try {
            const lock = false; // set to true to disallow rejoins
            const reason = 'party is over';
            await hmsActions.endRoom(lock, reason);
        } catch (error) {
            // Permission denied or not connected to room
            console.error(error);
        }
    };

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

</Tab>

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

## End Room Notification

Once the peer with adequate permissions calls `endRoom`, all other peers in the room will receive a [notification](../features/notifications) with type `ROOM_ENDED` with a [HMSLeaveRoomRequest](../../../api-reference/javascript/v2/interfaces/HMSLeaveRoomRequest) object as the data.

The SDK automatically calls leave and performs necessary clean ups immediately after this notification is sent, clients should show the appropriate UI(show a toast, redirect to a 'good-bye' page) within this period.

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

<Tab id='endroomhandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // ...Other notification type cases
        case 'ROOM_ENDED':
            // Redirect or Show toast to user
            toast(notification.data.reason);
            break;
    }
});
```

</Tab>

<Tab id='endroomhandle-1'>

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

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

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

        switch (notification.type) {
            // ...Other notification type cases
            case 'ROOM_ENDED':
                // Redirect or Show toast to user
                toast(notification.data.reason);
                break;
        }
    }, [notification]);

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

</Tab>



Want to preserve your video call for posterity in a recording? Or live stream it out to millions of viewers on Twitch or YouTube or whatever gives you an RTMP injest URL?

Turn on RTMP Streaming or Recording!

In 100ms, recording and streaming is usually achieved by having a bot join your room and stream what it sees and hears to a file (recording) or to an rtmp injest url (streaming).

The topics covered in this doc are:
1. [How to start streaming / recording.](#starting-streaming-recording)
2. [How to stop streaming / recording.](#stopping-streaming-recording)
3. [How to check the current status for streaming / recording.](#current-room-status)
4. [When to check the current status](#when-to-check-for-room-status)

## Starting Streaming / Recording
To start recording, streaming or both, create an instance of `HMSRecordingConfig`.

`HMSRecordingConfig` takes the following:
1. **meetingUrl**: *String*. The url the 100ms bot user will open to join your room. It must allow access without any user level interaction.
2. **rtmpUrls**: *List<String\>*. If streaming is required, this has to be one or more RTMP Injest Urls with a max limit of 3 urls where the stream should go. If only recording, this can be an empty list.
3. **record**: *Boolean*. If recording is required, set true. If recording is not required, set false. This value has no effect on streaming.
4. **resolution**: *HMSResolution*. An optional value for the output resolution of the stream. For instance default is landscape at 1280x720 but this could be set for a portrait mode of 720x1280. Or smaller values like 480x80.

The `HMSResolution` takes Width and Height.

* If both rtmpUrls and record = true are provided, both streaming and recording will begin.
* If only rtmpUrls are provided, only streaming will begin.
* If only record true is provided, only recording will begin.

If either one is started, the other can't be started without stopping whatever is running.
Eg: If only streaming is started then recording can't be started unless streaming is stopped first.

If both are required, they have to be started together by providing both `RTMP Ingest Urls` and `recording = true`.

[hmsActionResultListener] is the callback that would be called by SDK in case of a success or failure.

```dart
  void startRtmpOrRecording(
      {required HMSRecordingConfig hmsRecordingConfig,
      HMSActionResultListener? hmsActionResultListener}) async {}
```


## Stopping Streaming / Recording

To stop streaming AND recording. It is not currently possible to stop just one, whatever is running will be stopped.

Here's how to stop both:

The result of the action is sent as `HMSException` if it is successfull then it will be null otherwise it is not.

[hmsActionResultListener] is the callback that would be called by SDK in case of a success or failure.

```dart
void stopRtmpAndRecording(
      {HMSActionResultListener? hmsActionResultListener}) async
```


## Current Room Status

The current status for the room is always reflected in the `HMSRoom` object that is returned from the `HMSUpdateListener`.

Here are the relevant properties inside the `HMSRoom` object which you can read to get the current recording/streaming status of the room namely: `rtmpHMSRtmpStreamingState`, `browserRecordingState` and `serverRecordingState`.

Each of them are objects which contain a boolean `running` which lets you know if it's active on the room right now and `error` which lets you know if there was an error.

Apart from the rtmp stream and the browser recording, which are ones you can start and stop, there is also a serverRecording, which can be turned on for the room for archival purposes and which cannot currently be stopped if enabled for the room from the dashboard.

1. **HMSRtmpStreamingState** an instance of `HMSRtmpStreamingState`, which looks like:

```dart
class HMSRtmpStreamingState {
  final HMSException? error;
  final bool running;
  HMSRtmpStreamingState({required this.error,required this.running});
}
```

This represents a livestream to one or more RTMP urls.

2. **browserRecordingState** an instance of `HMSBrowserRecordingState`, which looks like:

```dart
class HMSBrowserRecordingState {
  final HMSException? error;
  final bool running;
  HMSBrowserRecordingState({required this.error,required this.running});
}
```

This represents the recording that can be requested to start.

3. **serverRecordingState** an instance of `HMSServerRecordingState`, which looks like:

```dart
class HMSServerRecordingState {
  final HMSException? error;
  final bool running;
  HMSServerRecordingState({required this.error,required this.running});
}
```

This represents that the room was set to be recorded when it was created and all sessions within it will always be recorded for archival by the server.

## When to check for room status

The room status should be checked in three places:
1. `onJoin` callback of `HMSUpdateListener` 
2. When `hmsSDK.startRtmpOrRecording()` is called
3. When `hmsSDK.stopRtmpAndRecording()` is called.

- In the `onJoin(room: HMSRoom)` callback in `HMSUpdateListener`
    The properties mentioned above will be on the `HMSRoom` object.
- Whenever either of the start or stop recording functions is called, when their success or error callbacks are called, the values of the streaming and recording will be updated on the room object returned in onJoin.
So saving an instance of the room received at that time is recommended.


RTMP Streaming / Recording


HLS Streaming allows for scaling to millions of viewers in near real time. You can give a link of your
web-app which will be converted to a HLS feed by our server and can be played across devices for consumption.

Behind the scenes, this will be achieved by having a bot join your room and stream what it sees and hears. Once the feed is ready, the server will give a URL which can be played using any HLS Player.

> Note that the media server serving the content in this case is owned by 100ms. If you're looking for a way to stream
on YouTube, Twitch etc., please have a look at our RTMP streaming docs [here](./recording).

## Starting HLS

To start HLS you can call `hmsSDK.startHlsStreaming` method. The 100ms bot will open default meeting URL to join your room, so
it must allow access without any user level interaction. In the future it'll be possible to start HLS for multiple such URLs for the same room.

For this purpose the API supports taking in an array, although currently only the first element of the array will be used. To distinguish between multiple URLs an additional field `metadata` can be optionally passed. The `meetingUrl` and `metadata` are clubbed together to form what we'll call a `variant`.

You can call `hmsSDK.startHlsStreaming` with a optional parameter `HMSHLSConfig` having an array of such variants.

```dart
    hmsSDK.startHlsStreaming(hmsActionResultListener: hmsActionResultListener);
```

```dart
class HMSHLSConfig {
  List<HMSHLSMeetingURLVariant>? meetingURLVariant;
  HMSHLSRecordingConfig? hmsHLSRecordingConfig;
}
```


> Want to see how this works in a live project? [Take a look](https://github.com/100mslive/100ms-flutter/blob/37a36b9ce71da8aa007f4212001447f8b16de625/example/lib/hls_viewer/hls_viewer.dart#L18) at our advanced sample app.

## Current Room Status

The current status for the room is always reflected in the `HMSRoom` object.

Here are the relevant properties inside the `HMSRoom` object which you can read to get the current hls streaming status of the room namely: `hlsStreamingState`.

The object contains a boolean `running` which lets you know if it's active on the room right now as well as list of active variants.


1. **hlsStreamingState** an instance of `HMSHLSStreamingState`, which looks like:

```dart
class HMSHLSStreamingState(
  bool running;
  List<HMSHLSVariant?> variants;
)
```

This represents a livestream to one or more HLS URLs in the container of `HMSHLSVariant`. Which looks like:
```dart
class HMSHLSVariant(
  String? hlsStreamUrl;
  String? meetingUrl;
  String? metadata;
  DateTime? startedAt;
)
```

The room status should be checked in following two places -

1. In the `onJoin(room: HMSRoom)` callback of `HMSUpdateListener`
    The properties mentioned above will be on the `HMSRoom` object.
2. In the `onRoomUpdate(type: HMSRoomUpdate, hmsRoom: HMSRoom)` callback of `HMSUpdateListener`.
    The `HMSRoomUpdate` type will be `HMSRoomUpdate.HLS_STREAMING_STATE_UPDATED`.

## Tips

* If you're using the dashboard web-app from 100ms, please make sure to use a role which doesn't have publish permissions for beam tile to not show up.
* If using your own web-app, do put in place retries for API calls like tokens etc. just in case any call fails. As human users we're used to reloading the page in these scenarios which is difficult to achieve in the automated case.
* Make sure to not disable the logs for the passed in meeting URL. This will allow for us to have more visibility into the room, refreshing the page if join doesn't happen within a time interval.


HLS Streaming


Flutter SDK provides support for sharing the entire screen of the device to the room.

Please note that for a peer to share their screen, their role must have screenshare enabled in the dashboard. Also select the appropriate resolution for the Screen share quality. 1080p is recommended for better text readability.

## Android Setup

You also need to pass the intent from android native side to HMS SDK in the following way :

In your app's `MainActivity` add -

```kotlin
import live.hms.hmssdk_flutter.HmssdkFlutterPlugin
import android.app.Activity
import android.content.Intent
import live.hms.hmssdk_flutter.Constants

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
super.onActivityResult(requestCode, resultCode, data)

    if (requestCode == Constants.SCREEN_SHARE_INTENT_REQUEST_CODE && resultCode == Activity.RESULT_OK){
        HmssdkFlutterPlugin.hmssdkFlutterPlugin?.requestScreenShare(data)
    }

}

```
> DONOT forget to add the permission for foreground service in AndroidManifest.xml

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

## iOS Setup

You need to create an iOS broadcast upload extension. It uses Apple's ReplayKit framework to record the device screen and delivers frame samples to your broadcast extension. You can share not only your own app but also the entire device sceeen including other apps on the device.

### Step 1 - Open project
Open your iOS Xcode project, such as `ios/Runner.xcworkspace` for full-Flutter apps.

### Step 2 - Add Broadcast Upload Extension
Click on your project in the Project Navigator to show the project settings. 
Press + at the bottom of the target list to add a new target.

![AddExtension](/docs/v2/flutter-xcode.png)

Select the `Broadcast Upload Extension` type for your new target.

![SelectExtension](/docs/v2/flutter-select-extension.png)

Enter your new target detail in the dialog.
Uncheck Include UI Extension option.

![DetailExtension](/docs/v2/flutter-extension-detail.png)

In the following dialog, activate the new scheme for the new target.

![ActivateExtension](/docs/v2/flutter-activate-extension.png)

### Step 3 - Add App Group

Click + icon in `Signing & Capabilities` section.
Select `App Group` from the list of Capabilities.

![AddAppgroup](/docs/v2/flutter-add-appgroup.png)

New section should be added under `Signing & Capabilities` named App Groups. Click + icon under that.

![Appgroup](/docs/v2/flutter-appgroup.png)

Enter App group name (create unique app group name ex: group.your.domain.name)

![AppgroupDetail](/docs/v2/flutter-appgroup-detail.png)

### Step 4 - Edit Podfile
In ios folder of your flutter project and open `Podfile`.
Paste the following code and replace the extension name you just created:
```
target 'Your Extension Name here' do
  use_modular_headers!
  pod 'HMSBroadcastExtensionSDK'
end
```
![Podfile](/docs/v2/flutter-podfile.png)

In terminal change directory to ios and run `pod install` command.

### Step 5 - Edit SampleHandler
Expand `Runner > ExtensionName` and open SampleHandler file.

![SampleHandler](/docs/v2/flutter-sample-handler.png)

Replace the code with the code below and pass app group name to the respected field:

```swift
import ReplayKit
import HMSBroadcastExtensionSDK

class SampleHandler: RPBroadcastSampleHandler {

    let screenRenderer = HMSScreenRenderer(appGroup: "Enter App Group Name")

    override func broadcastStarted(withSetupInfo setupInfo: [String : NSObject]?) {
        // User has requested to start the broadcast. Setup info from the UI extension can be supplied but optional.
    }

    override func broadcastPaused() {
        // User has requested to pause the broadcast. Samples will stop being delivered.
    }

    override func broadcastResumed() {
        // User has requested to resume the broadcast. Samples delivery will resume.
    }

    override func broadcastFinished() {
        // User has requested to finish the broadcast.
        screenRenderer.invalidate()
    }

    override func processSampleBuffer(_ sampleBuffer: CMSampleBuffer, with sampleBufferType: RPSampleBufferType) {
        switch sampleBufferType {
        case RPSampleBufferType.video:
            // Handle video sample buffer
            if let error = screenRenderer.process(sampleBuffer) {
                if error.code == .noActiveMeeting {
                    finishBroadcastWithError(NSError(domain: "ScreenShare",
                                                     code: error.code.rawValue,
                                                     userInfo: [NSLocalizedFailureReasonErrorKey : "You are not in a meeting."]))
                }
            }
            break
        case RPSampleBufferType.audioApp:
            // Handle audio sample buffer for app audio
            break
        case RPSampleBufferType.audioMic:
            // Handle audio sample buffer for mic audio
            break
        @unknown default:
            // Handle other sample buffer types
            fatalError("Unknown type of sample buffer")
        }
    }
}
```

## How to start screenshare from the app

To start screen share, app needs to call the `startScreenshare` method of `HMSSDK`.

Following is the snippet on how to use this:

```dart
hmsSDK.startScreenShare(hmsActionResultListener: hmsActionResultListener);
```

To start screen share in iOS you need to pass `App Group` and `Extension` name to `HMSSDK` as follows:

```dart
HMSSDK(appGroup: "group.name", preferredExtension: "your.extension.name")
```
You can find `app group` and `extension` name in Xcode under `Signing and Capabilities` section under `target > yourExtensionName`.

![parameter](/docs/v2/flutter-dart-help.png)

## How to get Screen Share Status

Application needs to call the `isScreenShareActive` method of `HMSSDK`.

This method returns a `Boolean` which will be true inscase ScreenShare is currently active and being used, and False for inactive state.

```dart
hmsSDK.isScreenShareActive();
```

To start Screen share in iOS you need to pass appGroup and preferred Extension name to HMSSDK:

```dart
HMSSDK(appGroup: appGroup, preferredExtension: preferredExtension);
```

## How to stop screenshare

To stop the screenshare, you need to invoke `stopscreenShare` method of `HMSSDK`

Following is the snippet on how to use this:

```dart
hmsSDK.stopScreenShare(hmsActionResultListener: hmsActionResultListener);
```
## How to display screenshare in apps 

> Screenshare track can be differentiated from normal video track using track's `source` property as `track.source == "SCREEN"` for screenshare
>tracks

Screenshare tracks can be found in two ways, from `onTrackUpdate` when the track is added and other from peer's `auxiliaryTracks`.

## Screenshare track from onTrackUpdate

Get screenshare track directly from onTrackUpdate and display it as below: 

```dart
void onTrackUpdate(
      {required HMSTrack track,
      required HMSTrackUpdate trackUpdate,
      required HMSPeer peer}) {

    switch (update) {
      case HMSTrackUpdate.trackAdded:
        if (track.source == "SCREEN") {
            //This track is a screenshare track and can be rendered using HMSVideoView as
            HMSVideoView(track:track);
        }
    }
}
```

## Screenshare track from auxiliaryTracks

The peer's screenshare can also be found in `auxiliaryTracks` property of peer. `auxiliaryTracks` is of type `List<HMSTrack>?`.

To get screenshare track from `auxiliaryTracks` the implementation is as follows:

```dart
HMSTrack? screenShareTrack =
        peer.auxiliaryTracks?.firstWhere((track) => track.source == "SCREEN");
if(screenShareTrack != null){
  //The user is sharing the screen and has screenshare track.
  HMSVideoView(track: screenShareTrack);
}
```




Any peer can change their own name before or after joining a room. Before joining, the name would have to be specified in `HMSConfig` that is passed to the join method. This document shows how the name can be changed after joining.

## Responding to name changes

Whenever a remote peer's name is changed a callback will be received in `onPeerUpdate({required HMSPeer peer, required HMSPeerUpdate update})` of `HMSUpdateListener` where the `update` will be of type `HMSPeerUpdate.nameChanged`.

When this callback is received the UI for that peer should be updated as well.

## Changing the name

The peer who wants to change their name should call the following method on an `HMSSDK` instance.


```dart
void changeName(
      {required String name,
      required HMSActionResultListener hmsActionResultListener}) {
    hmsSDK.changeName(
        name: name, hmsActionResultListener: hmsActionResultListener);
      }
```



HMSRoleChangeStoreRequest

Properties

requestedBy

roleName

token