
/[lib](/)

## Packages

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


Android API reference

Server Side API reference

React API reference


## Protocols

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

## Classes

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

## Enums

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

## Extensions

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

## Structs

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

## Typealiases

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


iOS API reference


<Content alias="basics" />

### Quickstart

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


Basic Concepts


<Content alias="basics" />

### Quickstart

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



<Content alias="basics" />

### Quickstart

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


Basics


<Content alias="basics" />

### Quickstart

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



<Content alias="basics" />

### Quickstart

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


Templates and Roles


<Content alias="securityAndTokens" />

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

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

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

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

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

</Tab>

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

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

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


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


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

</Tab>

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

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

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

</Tab>

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

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

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

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

puts generateManagementToken
```

</Tab>

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

```php
<?php

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

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

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

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

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

</Tab>
<Note>

**Warning**

Don't expose management token to client apps.

</Note>

## App Token

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

### Sample app token generation code

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

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

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

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

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

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

</Tab>

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

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

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

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

</Tab>

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

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

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

</Tab>

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

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



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

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

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

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

```

</Tab>

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

```php
<?php

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

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

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

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

</Tab>


Authentication and Tokens

Handling audio-video edge cases


## Overview

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

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

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

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

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

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

## Prerequisites

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

### Getting the video call joining link

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

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

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

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

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

### Add SDK dependencies

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

```dart
#pubspec.yaml

dependencies:
flutter:
  sdk: flutter

hmssdk_flutter:
```

### Login

#### Request

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

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

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

#### Response

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

### Add Permissions

#### Android Permissions

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

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

#### iOS Permissions

Add following permissions in iOS Info.plist file

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

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

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

### Join a Video Call

To join a video call, call join method on HMSMeeting with the config settings. To listen the updates, call addMeetingListener on HMSMeeting.

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
_meeting = HMSMeeting();
_meeting.joinMeeting(config: this.config);
_meeting.addMeetingListener(listener);

class AppUpdateListener extends HMSUpdateListener {

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

  @override
  void onPeerUpdate({required HMSPeer peer, required HMSPeerUpdate update}) {}

  @override
  void onTrackUpdate({required HMSTrack track, required HMSTrackUpdate trackUpdate, required HMSPeer peer}) {}

  @override
  void onMessage({required HMSMessage message}) {}

  @override
  void onUpdateSpeakers({required List<HMSSpeaker> updateSpeakers}) {}

  @override
  void onRoleChangeRequest({required HMSRoleChangeRequest roleChangeRequest}) {}

  @override
  void onRoomUpdate({required HMSRoom room, required HMSRoomUpdate update}) {}

  @override
  void onReconnected() {}

  @override
  void onReconnecting() {}

  @override
  void onError({required HMSError error}) {}
}
```

### 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 HMSVideoView with height and width in arguments.

### Showing Videos

A peer represents one person in the video call.

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

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

### Mute/UnMute Audio

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

```dart

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

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

### Mute/UnMute Video

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

```dart

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

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

### Leave a video call

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

```dart
_meeting.leaveMeeting();
```

## Where to go from here

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

## Glossary

-   `Room`: When you join a particular video call, all the peers said to be in a video call `room`
-   `Track`: Media. Can be the audio track or the video track.
-   `Peer`: One participant in the video call. Local peers are you, remote peers are others.
-   `Broadcast`: Chat messages are broadcasts.


100ms SDK Flutter Quickstart Guide


## Getting started

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

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

### Prerequisites

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

### Installing the dependencies

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

### Initializing the SDK

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

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

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

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

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

### Concepts

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

## Joining a room

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

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

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

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

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

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

</Tab>

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

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

</Tab>

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

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

### Leaving the room

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

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

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

window.onunload = leaveRoom;
```

## Adding video tiles

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

### Fetching information from state

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

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

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

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

### Subscribing to the state

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

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

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

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

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

// ...

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

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

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

</Tab>

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

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

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

</Tab>

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

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

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

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

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

  return newElement;
}

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

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

    hmsActions.attachVideo(peer.videoTrack, video);

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

    peersContainer.append(peerContainer);
  });
}

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

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

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

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

## Changing UI based on connection state

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

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

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

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


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

## Muting/unmuting local tracks

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

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

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

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

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

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

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

  hmsActions.setLocalAudioEnabled(audioEnabled);

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

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

  hmsActions.setLocalVideoEnabled(videoEnabled);

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

</Tab>

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

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

</Tab>

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

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

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

  hmsActions.setLocalVideoEnabled(!videoEnabled);

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

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

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

## Mirroring local video

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

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

<Tab id="mirror-0" >

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

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

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

    hmsActions.attachVideo(peer.videoTrack, video);

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

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

</Tab>

<Tab id="mirror-1">

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

</Tab>

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

Here's the complete example.

<Codesandbox id="5rmes" />


JavaScript Quickstart Guide


<Content alias="basics" />

### Quickstart

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



## Getting started

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

## Prerequisites

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

## Installing the dependencies

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

## Permissions

### For Android Permissions

Add following permissions in `AndroidManifest.xml`

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
```

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

### For iOS Permissions

Add following lines in `Info.plist` file

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

## Concepts

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

## Initializing the SDK

Call the function given below to initialise the SDK

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

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

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

## Add event listeners

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

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

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

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

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

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

## Joining a room

To join a room 3 fields are required:

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

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

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

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

## Leaving the room

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

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

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

## Render video

Let us next add a way to show a tile for every participant in the room. We use HmsView component to render video on screen. this component takes TrackId of HMSVideoTrack and renders the corresponding track.

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

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

<HmsView style={styles.hmsView} trackId={trackId} />;
```

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

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

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

These track IDs can directly be passed to HmsView component

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

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

HmsInstance.addEventListener(HMSUpdateListenerActions.ON_TRACK_UPDATE, onTrackListener);

const onPeerListener = ({
    remotePeers,
    localPeer
}: {
    room?: any,
    localPeer: any,
    remotePeers: any
}) => {
    updateVideoIds(remotePeers, localPeer); // this function can be used to update local and remotePeers on React-Native side
};

const onTrackListener = ({
    remotePeers,
    localPeer
}: {
    room?: any,
    localPeer: any,
    remotePeers: any
}) => {
    updateVideoIds(remotePeers, localPeer);
};
```

## Mute/Unmute local Audio/Video tracks

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

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

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

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

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

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


React Native Quickstart Guide



## Prerequisites

Familiarity with Xcode and iOS SDK, Cocoapods installed

## Xcode Project Setup

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


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

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


Create "Podfile" in the project folder with the following contents
then run `pod install`

```jsx
platform :ios, '13.0'

target 'basicvideocall' do
  use_frameworks!
  pod 'HMSSDK'

end
```

Open .xcworkspace

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

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

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


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

### Initialising The SDK

Open `ViewController.swift`

Add `HMSSDK` import


```swift
import HMSSDK
```


Conform to HMSUpdateListener and add stubs when Xcode offers to


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


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


### Get Auth Token

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

[Token Setup Guide](Token)

### Join Room

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

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


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

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

    
Congratulations! You have an audio conference app.

Build and launch on device, then join same room on web app to try a call between web and iOS. 


## Adding Video

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


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

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


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

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


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

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


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

    
### Cleanup

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

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



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

    var trackViewMap = [HMSTrack: HMSVideoView]()

...
```

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


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

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


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


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


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

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


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


### Final Points

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

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


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


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

    
### Ways to go from here

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

Checkout a sample code for a full featured conferencing app: 

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



100ms SDK iOS Quickstart Guide


## Overview

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

Here are some sample apps demonstrating this.

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

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

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

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

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

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

## Prerequisites

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

## Supported Android API Levels

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

### Getting the video call joining link

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

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

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

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

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

### Add SDK dependencies

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

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

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

```

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

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

### Login

#### Request

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

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

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

#### Response

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

### Permissions

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

```xml:AndroidManifest.xml
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.INTERNET" />
```

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

### Instantiate HMSSDK

Instantiate the HMSSDK like this:

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

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

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

</Tab>

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

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

</Tab>

### Join a Video Call

To join a video call, call the `join` method of `hmssdk` with the config and appropriate listeners.

The main ones to know are:

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

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

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

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

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

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

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

```kotlin

val config = HMSConfig("user display name", authToken)

hmsSdk.join(config, MyHmsUpdateListener())

class MyHmsUpdateListener : HMSUpdateListener {
    override fun onJoin(room: HMSRoom) {}
    override fun onTrackUpdate(type: HMSTrackUpdate, track: HMSTrack, peer: HMSPeer) {}
    override fun onPeerUpdate(type: HMSPeerUpdate, peer: HMSPeer) {}
    override fun onMessageReceived(message: HMSMessage) {}
    override fun onRoleChangeRequest(request: HMSRoleChangeRequest) {}
    override fun onRoomUpdate(type: HMSRoomUpdate, hmsRoom: HMSRoom) {}
    override fun onError(error: HMSException) {}
}
```

</Tab>

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

```java

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

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

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

```

</Tab>

### How you know when people join or leave

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

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

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

### How to render audio and video

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

### Showing Videos

A peer represents one person in the video call.

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

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

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

```xml

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

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

### Listening to Updates Effectively

Each time there's a an onJoin, onPeerUpdate, or onTrackUpdate, you can add all the peers from `hmsSdk.getPeers()` into the adapter. You'd need to map them into TrackPeerPair's.

## Where to go from here

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

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

## Glossary

-   `Room`: When you join a particular video call, all the peers said to be in a video call `room`'
-   `Track`: Media. Can be the audio track or the video track.
-   `Peer`: One participant in the video call. Local peers are you, remote peers are others.
-   `Broadcast`: Chat messages are broadcasts.


100ms SDK Android Quickstart Guide

Auth Token Quickstart Guide


## Getting started

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

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

### Prerequisites

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

### Installing the dependencies

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

### Initializing the SDK

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

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

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

import App from "./App";

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

```

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

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

### Concepts

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

## Joining a room

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

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

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

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

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

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

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

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

export default JoinForm;
```

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

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

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

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

## Leaving the room

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

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

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

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

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

## Adding video tiles

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

### Fetching information from state

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

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

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

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

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

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

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

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

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

export default Conference;
```

For each peer, we'll render a `<video>` element and a `<div>` element with their name.
In order to render the video, we need to call `attachVideo` method of `hmsActions`, which accepts a trackId and a DOM element.

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

function Peer({ peer }) {
  const videoRef = useRef(null);
  const hmsActions = useHMSActions();
  const videoTrack = useHMSStore(selectVideoTrackByPeerID(peer.id));

   useEffect(() => {
    if (videoRef.current && videoTrack) {
      if (videoTrack.enabled) {
        hmsActions.attachVideo(videoTrack.id, videoRef.current);
      } else {
        hmsActions.detachVideo(videoTrack.id, videoRef.current);
      }
    }
  }, [videoTrack, hmsActions]);

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

export default Peer;

```

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

## Changing UI based on connection state

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

We can do this with `selectIsConnectedToRoom` selector.

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

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

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

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

```

## Muting/unmuting local tracks

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

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

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

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

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

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

  return (
    <div className="control-bar">
      <button className="btn-control" onClick={toggleAudio}>
        {audioEnabled ? "Mute" : "Unmute"}
      </button>
      <button className="btn-control" onClick={toggleVideo}>
        {videoEnabled ? "Hide" : "Unhide"}
      </button>
    </div>
  );
}

export default Footer;
```

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

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

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

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

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

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

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

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

Here's the complete example.

<Codesandbox id="q4ukf" />


React Quickstart Guide


<Content alias="securityAndTokens" />

## Management Token

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

### Sample management token generation code

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

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

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

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

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

</Tab>

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

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

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


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

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

</Tab>

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

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

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

</Tab>

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

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

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

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

puts generateManagementToken
```

</Tab>

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

```php
<?php

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

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

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

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

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

</Tab>
<Note>

**Warning**

Don't expose management token to client apps.

</Note>

## App Token

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

### Sample app token generation code

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

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

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

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

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

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

</Tab>

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

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

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

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

</Tab>

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

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

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

</Tab>

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

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



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

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

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

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

```

</Tab>

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

```php
<?php

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

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

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

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

</Tab>



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


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

Add it to your `proguard-rules.pro`

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



Proguard configuration


## Installing our libraries

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

```dart
#pubspec.yaml

dependencies:
  flutter:
    sdk: flutter

  hmssdk_flutter:
```

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

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


100ms Flutter SDK Integration Guide


## Installing our libraries

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

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

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

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

</Tab>

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

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

</Tab>

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

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

</Tab>

## Setting up the sdk

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

### JavaScript

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

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

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

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

<Tab id='store-0'>

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

const hms = new HMSReactiveStore();

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

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

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

</Tab>

<Tab  id='store-1'>

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

</Tab>

### React Hooks

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

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

<Tab id='react-0'>

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

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

```
</Tab>

<Tab  id='react-1'>


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

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

  return </>;
}
```

</Tab>

## Debugging

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


Integrating The SDK


## Installing the dependencies

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

## Permissions

### For iOS

Add following lines in `Info.plist` file

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

### For Android

Add following permissions in `AndroidManifest.xml`

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.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.

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


Integrating the SDK


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

When user indicates that they want to _join_ the room, your app should have -
1. User Name - the name which should be displayed to other peers in the room.
2. [Authentication Token](../guides/token) - the client side authentication token generated by the Token Service.

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

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


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

<Tab id='join-0'>

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

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

hmsActions.join(config);

```

</Tab>

<Tab  id='join-1'>

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

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

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

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

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

</Tab>

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

## Getting Current Room State

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

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

<Tab id='connected-0'>


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

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

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

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

```

</Tab>

<Tab  id='connected-1'>

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

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

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

</Tab>

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


Join Room


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

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

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

## Leave on Navigating Away

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

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


Leave Room


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

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

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

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

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

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

<Tab id='render-0'>


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

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

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

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

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

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

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

</Tab>

<Tab  id='render-1'>

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

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

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


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

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

</Tab>


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

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

## Detach video to conserve bandwidth and cleanup elements

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

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


Render Video


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

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

## Toggling current mute state

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

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

<Tab id='mute-0'>

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

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

</Tab>

<Tab id='mute-1'>

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

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

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

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



Mute / Unmute


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

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

## Sending Chat Messages

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

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


Chat


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

## Manual Device Change

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

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

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

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

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

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

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

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

## Remember manually selected devices

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

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


Device Changes


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

To invoke this API call

```js
hmsActions.preview(config)
```

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


Preview


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

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

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

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

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

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

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

hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

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

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

</Tab>

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

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

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

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

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

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

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

</Tab>

## Notification types

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

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

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

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

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

const unsubscribe = hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

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

    // you can use the following to show appropriate toast notifications for eg.
    switch (notification.type) {
        case HMSNotificationTypes.PEER_JOINED:
            console.log(`${notification.data.name} joined`);
            break;
        case HMSNotificationTypes.PEER_LEFT:
            console.log(`${notification.data.name} left`);
            break;
        case HMSNotificationTypes.NEW_MESSAGE:
            console.log(
                `${notification.data.message} received from ${notification.data.senderName}`
            );
            break;
        case HMSNotificationTypes.ERROR:
            console.log('[Error]', notification.data);
            console.log('[Error Code]', notfication.data.code);
            break;
        case HMSNotificationTypes.RECONNECTING:
            console.log('[Reconnecting]', notification.data);
            break;
        case HMSNotificationTypes.RECONNECTED:
            console.log('[Reconnected]');
            break;
        default:
            break;
    }
});
```

</Tab>

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

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

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

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

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

        // you can use the following to show appropriate toast notifications for eg.
        switch (notification.type) {
            case HMSNotificationTypes.PEER_JOINED:
                console.log(`${notification.data.name} joined`);
                break;
            case HMSNotificationTypes.PEER_LEFT:
                console.log(`${notification.data.name} left`);
                break;
            case HMSNotificationTypes.NEW_MESSAGE:
                console.log(
                    `${notification.data.message} received from ${notification.data.senderName}`
                );
                break;
            case HMSNotificationTypes.ERROR:
                console.log('[Error]', notification.data);
                console.log('[Error Code]', notfication.data.code);
                break;
            case HMSNotificationTypes.RECONNECTING:
                console.log('[Reconnecting]', notification.data);
                break;
            case HMSNotificationTypes.RECONNECTED:
                console.log('[Reconnected]');
                break;
            default:
                break;
        }
    }, [notification]);

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

</Tab>

## Unsubscribing from notifications

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

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

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

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

unsubscribe();
```

</Tab>

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

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

</Tab>

## Ideas

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

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


Notifications

Error Handling


## Create Account

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

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

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

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

## Build your app

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

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

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

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

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

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


Quickstart


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

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

## Setting up the HMS Instance

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

```js
import HmsManager from 'react-native-hms';

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

## Check Permissions

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

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

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

// ios
joinRoom();
```

## Add event listeners

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

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

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

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

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

## Join the room

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

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

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

```js
import HmsManager, { HMSUpdateListenerActions, HMSConfig } from '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
```

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.




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

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

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

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

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

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



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(userId: Uuid().v1(),
                                 roomId: roomId,
                                 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 `joinMeeting` present in `HMSMeeting` class.

    Create instance of HMSMeeting -

    ```dart
    HMSMeeting meeting = new HMSMeeting();
    ```

    Now join by passing config object created in previous step.

    ```dart
    meeting.joinMeeting(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
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});


  /// 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
  /// - 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 onError({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});


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


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

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

Add this `updateListener` instance to

```dart
PlatformService.addMeetingListener(updateListener);
```

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

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

❌ If failure, the `fun onError(error: HMSException)` method will be invoked with exact failure reason.



Screenshare involves sharing either the complete screen, a specific window or, a browser tab.
For a peer to share their screen, their role must have screenshare enabled in the dashboard.

![ScreenshareDashboard](/docs/v2/screenshare-dashboard.png)

To start a screenshare:

```js
try {
    await hmsActions.setScreenShareEnabled(true);
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

## AudioOnly Screenshare

To start audio only screenshare, you can pass a boolean as second argument. it defaults to false

```js
try {
    await hmsActions.setScreenShareEnabled(true, true);
} catch (error) {
    // an error will be thrown if user didn't give access to share screen
}
```

To stop the screenshare:

```js
hmsActions.setScreenShareEnabled(false);
```

## Useful Selectors

```js
// to know if someone is screensharing
const screenshareOn = hmsStore.getState(selectIsSomeoneScreenSharing);

// to get the HMSPeer object of the peer screensharing, will select  first if multiple screenshares
const presenter = hmsStore(selectPeerScreenSharing);

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

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

// to get the screenshare video track, this can be used to call attachVideo for rendering
const screenshareVideoTrack = hmsStore(selectScreenShareByPeerID(presenter.id));

// Get the peer who is sharing audio only screenshare
const peer = hmsStore.getState(selectPeerSharingAudio);
// Get the audio track of audio Only screenshare
const audioTrack = hmsStore.getState(selectScreenShareAudioByPeerID(peer?.id));
```

Find more [here](/api-reference/javascript/v2/home/content#functions).

## Screenshare with audio:

We also give support of adding screenshare with audio in chromium based browsers. This only applies if checkbox at bottom left
shown below is checked while sharing a browser tab.

![ScreenshareAudio](/docs/v2/screenshare-audio.png)


Screen Share


![Role Change](/guides/role-change.png)

## Introduction

Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. [Learn more about roles here.](../foundation/templates-and-roles)

Every peer is associated with a role. The [`HMSRole`](/api-reference/javascript/v2/interfaces/HMSRole) object can be used to know the following:

1. Check what this role is allowed to publish. i.e can it send video (and at what resolution)? can it send audio? can it share screen? This can be discovered by using `selectIsAllowedToPublish` to display the UI appropriately.
2. Check which other roles can this role subscribe to. This is internally taken care of by the 100ms infra and sdk, and your UI will only get tracks as per allowed subscriptions. `role.subscribeParams` can be used to get details.
3. Check what actions this role can perform. i.e can it change someone else's current role, mute others, end meeting, remove someone from the room. This can be discovered by using the `selectPermissions` selector.

### Example

Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe.
Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the `changeRole` API comes in.

## Know Thy Permissions

The below selectors can be used to know what the local peer is allowed to publish, and the permissions they have. To know about all the
permissions please check [`selectPermissions'`](../../../api-reference/javascript/v2/home/content#select-permissions) api reference.

```js
const role = hmsStore.getState(selectLocalPeerRole);
const permissions = hsmStore.getState(selectPermissions);
console.log("can I end room - ", permissions.endRoom);
console.log("can I end change role - ", permissions.changeRole);
const { video, audio, screen } = hmsStore.getState(selectIsAllowedToPublish);
```

## Change Role API

If the local peer has permissions to change role(`permissions.changeRole`), they can change either their or someone else's role using
the below interface.

```js
hmsActions.changeRole(forPeerId, toRoleName, force);
```

-   `forPeerId`: The peer ID whose role needs to be changed, the peer can be either of local or remote.
-   `toRoleName`: The target role name.
-   `force`(optional): The other peer gets a request by default to accept a role change, by setting force to true, the role can be changed
                        without requesting for approval.

> 💡 A list of all available role names in the current room can be accessed via the `selectAvailableRoleNames` selector. Further the `selectRoleByRoleName`
selector can be used to get the full [HMSRole](/api-reference/javascript/v2/interfaces/HMSRole) object for a role name.

### Handling a Role Change Request

The `force` parameter in `changeRole`, when false, is a polite request: "Would you like to change your role from listener to speaker?" which can be ignored by the other party.
The way it works is the other party will first receive a [request](/api-reference/javascript/v2/interfaces/HMSRoleChangeRequest) which they can accept or reject.


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

<Tab id='roleChange-0'>

```js
function handleRoleChangeRequest(request) {
    if (!request) {
        return;
    }
    console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
    // shouldAccept can for example present a pop up to the user for deciding how to act on the request
    const accept = shouldAccept(request);
    if (accept) {
        hmsActions.acceptChangeRole(request);
    } else {
        hmsActions.rejectChangeRole(request);
    }
}

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

</Tab>

<Tab  id='roleChange-1'>

```jsx
function handleRoleChangeRequest(request) {
    const request = useHMSStore(selectRoleChangeRequest);
    const hmsActions = useHMSActions();

    useEffect(() => {
        console.log(`${request.requestedBy.name} requested role change to - ${request.role.name}`);
        // shouldAccept can for example present a pop up to the user for deciding how to act on the request
        const accept = shouldAccept(request);
        if (accept) {
            hmsActions.acceptChangeRole(request);
        } else {
            hmsActions.rejectChangeRole(request);
        }
    }, [request, hmsActions])

    return null;
}
```

</Tab>

If the request is accepted, the `peer.roleName` field in the store will update re rendering a declarative UI as required.

### Forced Role Change

Imagine that the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt.
This is where the `force` parameter comes in. When it is set to `true` the other party will not receive a confirmation `roleChangeRequest`
but instead will straight away receive a new set of updated permissions and stop publishing.

![Listener Role](/guides/role-listener.png)


## Ideas

### Breakout Rooms/Groups

You can have multiple roles which act as breakout rooms subscribing only to peers within the role. A peer can join another breakout room
or group easily using the change role API.

### Waiting Room

You can create a specific role for a waiting room which doesn't subscribe to anyone else. When someone joins waiting room,
hosts get a notification, and they can let the person join by changing their role to attendees.

### Audio Rooms

An audio room can be designed with moderators, speakers and listeners where a moderator can promote a listener to speaker
and vice versa.

### Classroom

Roles can be created for muted-student(not allowed to unmute), student-spotlight(publishes higher quality video),
student-screen(allowed to screenshare), prefect(can mute others) etc. to create an enriching feature rich classroom experience.


Change Role


You're running a room and decide that someone who's currently talking shouldn't be talking, or perhaps you want their video turned off. You're looking for a remote mute/unmute in this case.

### Muting/Unmuting

Use the [selectPermissions](./change-role#know-thy-permissions) selector to check whether the local peer has the
permission to `mute` or `unmute` others and
then call [`hmsActions.setRemoteTrackEnabled`](../../../api-reference/javascript/v2/interfaces/HMSActions#set-remote-track-enabled)
with the `trackID` of the track you want to mute/unmute and `enable`(`true` for unmuting, `false` for muting).

```js
try {
    await hmsActions.setRemoteTrackEnabled(peer.audioTrack, true);
} catch (error) {
    // Permission denied or invalid track ID or not connected to room
    console.error(error);
}
```

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

### Handling a mute/unmute request

Once the peer with adequate permissions calls `setRemoteTrackEnabled`, the local peer will receive a [notification](notifications) with type `CHANGE_TRACK_STATE_REQUEST` with a [HMSChangeTrackStateRequest](../../../api-reference/javascript/v2/interfaces/HMSChangeTrackStateRequest) object as the data.

-   Mute requests are automatically applied to the receiver by the SDK. No action is required.

-   For unmute request, hold onto the information from the `HMSChangeTrackStateRequest` object, show a dialog to the user to ask if they want to accept the change and then apply the settings locally. The same as in a regular user [Mute/Unmute](mute).

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

<Tab id='remotemutehandle-0'>

```js
hmsNotifications.onNotification((notification) => {
    if (!notification) {
        return;
    }

    switch (notification.type) {
        // ...Other notification type cases
        case 'CHANGE_TRACK_STATE_REQUEST':
            // Unmute Request
            if (notification.data.enabled) {
                // Ask for consent using dialog or any other appropriate UI
                await hmsActions.setEnabledTrack(notification.data.track.id, enabled);
            } else {
                // Mute Request
                // Show toast to user
            }
            break;
    }
});
```

</Tab>

<Tab id='remotemutehandle-1'>

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

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

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

        switch (notification.type) {
            // ...Other notification type cases
            case 'CHANGE_TRACK_STATE_REQUEST':
                // Unmute Request
                if (notification.data.enabled) {
                    // Ask for consent using dialog or any other appropriate UI
                    await hmsActions.setEnabledTrack(track.id, enabled);
                } else {
                    // Mute Request
                    // Show toast to user
                }
                break;
        }
    }, [notification]);

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

</Tab>

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


Remote Mute/Unmute


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

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

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

        switch (notification.type) {
            // ...Other notification type cases
            case 'REMOVED_FROM_ROOM':
                // Redirect or Show toast to user
                toast('Reason: ', notification.data.reason);
                break;
        }
    }, [notification]);

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

</Tab>


Remove Peer


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

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

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

        switch (notification.type) {
            // ...Other notification type cases
            case 'ROOM_ENDED':
                // Redirect or Show toast to user
                toast(notification.data.reason);
                break;
        }
    }, [notification]);

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

</Tab>


End Room


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

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



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


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

When user indicates that they want to _join_ the room, your app should have -
1. `userName`, the name which should be displayed to other peers in the room
2. `userID`, a unique identifier for the user. It can be your reference identifier or a [UUID string](https://developer.apple.com/documentation/foundation/uuid/1779712-uuidstring).
3. `roomID`, the unique room identifier which would have been generated & passed to your app from backend
4. `authToken`, the client side authentication token generated by your Token Service
 
Now that you have aforementioned data, you can proceed to join a room.

1. First, create an instance of `HMSSDK` class. Store this instance as a property. Ensure that the SDK object is alive in memory so that you can receive event callbacks from SDK. Simplest way to do this is as follows -
```swift
import HMSSDK

class MyMeetingClass {
    
    let hmsSDK: HMSSDK // store instance of HMSSDK as a property in your class

    init() {
        hmsSDK = HMSSDK.build() // initialize the SDK using the `build()` class function
    }
}
```
Note: If you are using Preview then you must already have an instance of HMSSDK before invoking Preview APIs.

2. Next, create an object of `HMSConfig` class using the available joining configurations
```swift
let config = HMSConfig(userName: "My good name",
                         userID: UUID().uuidString,
                         roomID: "abc123",
                      authToken: "eyJH5c")
```

3. Now, we are primed to join the room. All you have to do is pass the `config` object to `hmsSDK`
```swift
hmsSDK.join(config: config, delegate: self)
```

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

Now, let's take a look at the signature of the Join API
```swift
func join(config: HMSConfig, delegate: HMSUpdateListener)
```
As evident, `join` accepts 2 arguments - 
- `config`: an object of type `HMSConfig` class, the room configuration object which encapsulates user & token data
- `delegate`: a class conforming to `HMSUpdateListener` protocol. 

The methods of `HMSUpdateListener` are invoked to notify updates happening in the room like a peer joins/leaves, a track got muted/unmutes, etc.

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

✅ If successful, the `func on(join room: HMSRoom)` method of `HMSUpdateListener` will be invoked with information about the room encapsulated in the `HMSRoom` object. 

❌ If failure, the `func on(error: HMSError)` method will be invoked with exact failure reason. 



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 few things:

1. HMSTrack: `HMSVideoView` will render video using trackId from HMSTrack.
2. `HMSVideoView` will use viewSize to get height and width of 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.

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.

For example -

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

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

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

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

## Render Video

To Render video you need track and size(optional).

For example - HMSVideoView with `HMSTrack` and `Size`

```dart
///  This will render video with trackId present in track and it will have height = 50 and width = 50

HMSVideoView(
  track: track,
  viewSize: Size(50,50),
);
```

For example - HMSVideoView with only `HMSTrack`

```dart
///  This will render video with trackId present in track and it will have height and width available to it

HMSVideoView(
  track: track,
  viewSize: Size(50,50),
);
```

## Detach video to conserve bandwidth and cleanup elements

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

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



Console logging from sdk can be controlled by using the [`setLogLevel`](https://docs.100ms.live/api-reference/javascript/v2/interfaces/HMSActions#set-log-level) api.

```js
hmsActions.setLogLevel(HMSLogLevel.WARN); // log warnings and errors
hmsActions.setLogLevel(HMSLogLevel.ERROR); // only errors will be logged
hmsActions.setLogLevel(HMSLogLevel.NONE); // nothing will be logged by our sdk
```


Log Level


Mute is something that applies to both audio and video.

When you mute audio, you can't be heard by other people.

When you mute video, you will not be broadcasting your video to other people.

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

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

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

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

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


Mute/Unmute


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

100ms SDK provides a simple, no fuss API to do exactly that. Invoke the `leave` method on instance of `HMSSDK`.

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

You should expect that the `leave` function always succeeds, even in scenarios like "No Internet Connection", "Low Battery", etc



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

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

```dart
HMSMeeting meeting = new HMSMeeting();

meeting.switchAudio(true);

meeting.switchVideo(true);

meeting.switchCamera();

meeting.stopCapturing();

meeting.startCapturing();
```



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

## Sending Chat Messages

With the HMSSDK instance call sendMessage to send a message.

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

const messageObject = {
    type: 'chat',
    time: new Date().toISOString(), // The time the message was sent is contained in time as a Java Date.
    message: value // The body of the message is in message as a String.
};

const message = new HMSMessage(messageObject);

// instance acquired from build() method
hmsInstance.send(message);
```

## Receiving Chat Messages

When you called hmsInstance.join(config) to join a room, add a ON_MESSAGE event listener with callback function onMessageReceived.

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

// instance acquired from build() method
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_MESSAGE, onMessageReceived);

const onMessageReceived = (message: HMSMessage) => {
    // perform action
};
```

## Putting together a list of chat messages.

The UI is completely up to you to decide! You'll also need to hold onto all the received messages if you want to display history.



Preview screen is a frequently used UX element which allows users to check if their input devices are working properly and set the initial state (mute/unmute) of their audio and video tracks before joining. 100ms SDKs provide an easy-to-use API to back this feature.

## Calling Preview function

We can call preview method in HMSSDK Instance. it is advised to attach error listener and preview listener before calling that function in order to get updates if preview got executed successfully or if it failed.

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

const hmsInstance = HmsManager.build()

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

hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);
```

once listeners are attached we can call preview method as shown in following snippet.

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

// instance acquired from build() method
const HmsConfig = new HMSConfig({ authToken, userID, roomID, userName });
hmsInstance.preview(HmsConfig); // to start preview
```



An user should be able to mute or unmute both audio & video as per their choice. 100ms SDK makes it simple to do just that in nifty way.

1. First, get the reference to local peer using the convenience method `localPeer` on `HMSSDK` class
2. Next, get the audio or video track of the local peer
3. Now, set it's mute status to true or false.
- When mute is true, local peer won't transmit any audio or video. 🤫🤐
- When mute is false, local peer can speak & show the world whatever they want to. 🕺💃

### Mute Audio 🙊
```swift
hmsSDK.localPeer?.localAudioTrack()?.setMute(true)
```

### Ummute Audio 🐵
```swift
hmsSDK.localPeer?.localAudioTrack()?.setMute(false)
```

### Mute Video 🙈
```swift
hmsSDK.localPeer?.localVideoTrack()?.setMute(true)
```

### Unmute Video 🐒
```swift
hmsSDK.localPeer?.localVideoTrack()?.setMute(false)
```

Note: Ensure that you call these functions from the main queue. 


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 the Preview API call -

```dart
HMSMeeting meeting =  new HMSMeeting();
meeting.previewVideo(hmsConfig);
```

You need HMSConfig instance which you have created.

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 [onError] will be called
  ///
  /// - Parameters:
  ///   - error: error which you get.
  void onError({required HMSError error});
}
```

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 HMSError instance you can use to find what went wrong (see [Error Handling](error-handling)).

Add the `previewListener` instance to

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



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

You can see an example of every way of sending messages and interpreting messages in the advanced sample app.

```dart
HMSMeeting meeting = new HMSMeeting();
meeting.sendMessage("Hi");
```

You will get updates about message sent by someone in `HMSUpdateListener`.

```dart
void onMessage({required HMSMessage message});
```



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

The React Native SDK provides a Component HmsView that renders the video on screen. We have to pass video trackId in this component. Here is a code snippet explaining the way to link a videoTrack to HmsView.

```js
import { HmsView } from 'react-native-hms';
...
const styles = StyleSheet.create({
  hmsView: {
    height: '100%',
    width: '100%',
  },
});
<HmsView style={styles.hmsView} trackId={trackId} />
...
```

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

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

these track IDs can directly be passed to HmsView component

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

```js
HmsInstance.addEventListener(HMSUpdateListenerActions.ON_PEER_UPDATE, onPeerListener);
HmsInstance.addEventListener(HMSUpdateListenerActions.ON_TRACK_UPDATE, onTrackListener);
const onPeerListener = ({
    remotePeers,
    localPeer
}: {
    room?: any,
    localPeer: any,
    remotePeers: any
}) => {
    updateVideoIds(remotePeers, localPeer); // this function can be used to update local and remotePeers on React-Native side
};
const onTrackListener = ({
    remotePeers,
    localPeer
}: {
    room?: any,
    localPeer: any,
    remotePeers: any
}) => {
    updateVideoIds(remotePeers, localPeer);
};
```



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

You can see an example of every way of sending messages and interpreting messages in the advanced [sample app](https://github.com/100mslive/100ms-ios-sdk).

### Addressing messages

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

* [Direct messages](#sending-direct-messages) let you send message to a specific person `hmssdk.sendDirectMessage`.

* [Group messages](#sending-group-messages) let you send a message to everyone with a particular `HMSRole`. Such as all `hosts` or all `teachers` or all `students` `hmsSdk.sendGroupMessage`

### Sending Chat Messages

#### Sending Broadcast Messages

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

The text of the message, its type and a listener for whther the message reached the server or not are the parameters.

> 💡 Note that the callback only lets you know if the server has received your request for the message or if there was some error. It does not convey whether the message was delivered to or read by the recipient.
> also it's important to make a new callback per message because it will only contain the results of that particular call for sending a message.


```swift
hmssdk.sendBroadcastMessage(type: "chat", message: "") { message, error in

}
```

#### Sending Direct Messages

Got secrets to share? Send a message directly to a single person in the chat with a direct message. Call `sendDirectMessage` on an instance of `HMSSDK`.

The text of the message, its type and a listener for whther the message reached the server or not are the parameters.

> 💡 Note that the callback only lets you know if the server has received your request for the message or if there was some error. It does not convey whether the message was delivered to or read by the recipient.
> also it's important to make a new callback per message because it will only contain the results of that particular call for sending a message.

```swift
hmssdk.sendDirectMessage(type: "chat", message: "", peer: recipientPeer) { message, error in

}
```

#### Sending Group Messages

Want to share with a group? Send a message directly to a group in the chat with a group message. Call `sendGroupMessage` on an instance of `HMSSDK`.

The text of the message, its type and a listener for whether the message reached the server or not are the parameters.

> 💡 Note that the callback only lets you know if the server has received your request for the message or if there was some error. It does not convey whether the message was delivered to or read by the recipient.
> also it's important to make a new callback per message because it will only contain the results of that particular call for sending a message.

```swift
hmssdk.sendGroupMessage(type: "chat", message: "", roles: recipientRoles) { message, error in

}
```

### Receiving Chat Messages

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

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

```swift
public class HMSMessage {
    public let message: String
    public let type: String
    public var sender: HMSPeer?
    public var recipient: HMSMessageRecipient
    public let time: Date
}    
```
`message`: Content of the text message or the text description of the raw message.

`type`: Type of message sent. Default value is `chat`.

`recipient`: The intended recipient(s) of this message as a `HMSMessageRecipient`.

`time`: Timestamp of when the messaging server receives this message. Update the time in your own messages when this comes back from the server in `on(message:)` for accurate ordering of your own messages.

`sender`: The `HMSPeer` who is sending this message.

Identifying Senders: The sender of a message is always contained in the `sender` field of HMSMessage. This lets you get the name and peer id for any message sender.

Message Body: The body of the message is in `message` as a String.

Time: The time the message was sent is contained in `time`.

#### Identifying who the message was for

The HMSMessageRecipient contained in the `recipient` field of `HMSMessage` lets you know who the message was for.

The `HMSMessageRecipient` contains:
```swift
public class HMSMessageRecipient {
    public let type: HMSMessageRecipientType
    public let peerRecipient: HMSPeer?
    public let rolesRecipient: [HMSRole]?
}
```

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

`rolesRecipient`: Only contains values when a group message is being sent to one or many roles.

`type`: Will be `broadcast` for a message being sent to everyone. If this is true, the other two field will be null, empty respectively.

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

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



# Error Handling

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 onError callback of the `HMSUpdateListner`.

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. |
| 3008       | Browser has thrown an autoplay exception.              | Show notification to user mentioning that the browser blocked autoplay                                      |
| 4001       | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| 4002       | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| 4003       | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| 4004       | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| 4005       | ICE Connection Failed due to network issue             | Mention user to check their network connection or try again after some time.                                |
| 5001       | Trying to join a room which is already joined          | Trying to join an already joined room.                                                                      |
| 6002       | webRTC Error: Error while renegotiating                | Please try again.                                                                                           |
| 40101      | Token Error: Invalid Access Key                        | 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.                                                                    |



When you make various function calls through HmsInstance, it may return errors with different error codes. ErrorCodes are returned when a problem that cannot be recovered without app intervention has occurred.

These are returned as HMSException in the onError callback of the HMSUpdateListner.

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

// instance acquired from build() method
hmsInstance.addEventListener(HMSUpdateListenerActions.ON_ERROR, onError);

const onError = (error) => {
    // console.log(error);
};
```

Following are the different error codes that are returned in the callback . Before returning any error code, it retries the errors (whichever is possible).

| Error Code  | Cause of the error                                     | Action to be taken                                                                                          |
| ----------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| **`1003`**  | Websocket disconnected - Happens due to network issues | Mention user to check their network connection or try again after some time.                                |
| **`2002`**  | Invalid Endpoint URL                                   | Check the endpoint provided while calling join on HMSSDK.                                                   |
| **`2003`**  | Endpoint is not reachable                              | Mention user to check their network connection or try again after some time.                                |
| **`2004`**  | Token is not in proper JWT format                      | The token passed while calling join is not in correct format. Retry getting a new token.                    |
| **`3001`**  | Cant Access Capture Device                             | Ask user to check permission granted to audio/video capture devices.                                        |
| **`3002`**  | Capture Device is not Available                        | Ask user to check if the audio/video capture device is connected or not.                                    |
| **`3003`**  | Capture device is in use by some other application     | Show notification to user mentioning that the capturing device is used by some other application currently. |
| **`3008`**  | Browser has thrown an autoplay exception.              | Show notification to user mentioning that the browser blocked autoplay                                      |
| **`4001`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4002`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4003`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4004`**  | WebRTC error                                           | Some webRTC error has occured. Need more logs to debug.                                                     |
| **`4005`**  | ICE Connection Failed due to network issue             | Mention user to check their network connection or try again after some time.                                |
| **`5001`**  | Trying to join a room which is already joined          | Trying to join an already joined room.                                                                      |
| **`6002`**  | webRTC Error: Error while renegotiating                | Please try again.                                                                                           |
| **`40101`** | Token Error: Invalid Access Key                        | Please try again.                                                                                           |
| **`40102`** | Token Error: Invalid Room Id                           | RoomID provided in the token is wrong.                                                                      |
| **`40103`** | Token Error: Invalid Auth Id                           | AuthID provided in the token is wrong.                                                                      |
| **`40104`** | Token Error: Invalid App Id                            | App ID provided in the token is wrong.                                                                      |
| **`40105`** | Token Error: Invalid Customer Id                       | Customer Id provided in the token is wrong.                                                                 |
| **`40107`** | Token Error: Invalid User Id                           | User ID provided in the token is wrong.                                                                     |
| **`40108`** | Token Error: Invalid Role                              | The role provided in the token is wrong.                                                                    |
| **`40109`** | Token Error: Bad JWT Token                             | Bad JWT Token.                                                                                              |
| **`40100`** | Generic Error                                          | Need to debug further with logs.                                                                            |
| **`40001`** | Invalid Room                                           | Room ID provided while fetching the token is an invalid room.                                               |
| **`40002`** | Room Mismatched with Token                             | Room ID provided while fetching the token does not match.                                                   |
| **`40004`** | Peer already joined                                    | Peer who is trying to join has already joined the room.                                                     |
| **`41001`** | Peer is gone                                           | The peer is no more present in the room.                                                                    |



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

How to do it? What should I be careful about? Is it easy? 😨😰😱

It's simpler than you think. That's what we are here for. 🙌✌️🤝

1. First, you need to create a `HMSVideoView` object in your View hierarchy.
`HMSVideoView` is a subclass of `UIView` so add it to your UI just as a regular view using Storyboard, XIB or in-code.

2. Next, you'll have a reference to a video track object. Specifically, a object of type `HMSVideoTrack` (or any of it's subclasses). For example, the local peer's video track can be accessed like so -
```swift
hmsSDK.localPeer?.localVideoTrack() // it's a HMSLocalVideoTrack, a subclass of HMSVideoTrack
```

3. Now, pass the video **track** object to video **view** using `setVideoTrack` method of `HMSVideoView`
```swift
videoView.setVideoTrack(track) // videoView is HMSVideoView, track is HMSVideoTrack
```
Video Track to Video View. Remember this. You'll be doing this often.

That's it. 

The video which the peer will be transmitting will now be rendered & start playing in your video view. 🥳 


# Leave Room

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

```dart
_meeting.leaveMeeting();
```



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

To invoke this API call

```swift
hmsSDK.preview(config: config, delegate: previewDelegate)
```

You would need the same config object that you would pass to [join API](Join). The `previewDelegate` is an object conforming to `HMSPreviewListener` protocol that has two callbacks:

```swift
func onPreview(room: HMSRoom, localTracks: [HMSTrack])
```

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

If however there was some error related to getting the input sources or some preflight check has failed 

```swift
func on(error: HMSError)
```

delegate callback will be fired with the HMSError instance you can use to find what went wrong (see [Error Handling](Error-Handling)).


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 following:

Check what this role is allowed to publish i.e can it send video (and at what resolution)? can it send audio? can it share screen? Who can this role subscribe to? (I.e student can only see the teacher's video).

This is can be discovered by checking `publishSettings` and `subscribeSettings` properties.

Check what actions this role can perform. i.e can it change someone else's current role, end meeting, remove someone from the room. This is can be discovered by checking permissions property.

In certain scenarios you may want to change someone's role. Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the `changeRole` API comes in.

To invoke the api you will need 2 things.

An instance of `HMSPeer` of the peer who's role you want to change and the `HMSRole` instance for the target role.

All the peers that are in the current room are accessible via peers property of `HMSRoom` instance that you can get via room property of HMSSDK instance after successful room join.

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

Once you have both you can invoke.

```dart
HMSMeeting meeting = new HMSMeeting();
meeting.changeRole(peerId,roleName,forceChange);
```

`peerId`: id of the peer.

`roleName`: name of the role.

`forceChange`: it is optional.if you are forcing the change to happen.

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

```dart
void onPeerUpdate({required HMSPeer peer,
required HMSPeerUpdate update});
```

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

The `force` parameter in `changeRole`, when false, is basically a polite request: "Would you like to change you role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a

```dart
void onRoleChangeRequest({required HMSRoleChangeRequest roleChangeRequest});
```

callback in HMSUpdateListener. At which point the app can choose to show a prompt to the user asking for permission.

If the user accepts, app should call

```dart
meeting.acceptRoleChangerequest();
```

with the same request which it received in `onRoleChangeRequest` which completes the `changeRole` loop. Both parties will receive a `roleUpdated` callback so that they both can do necessary UI updates. Now the user actually becomes a speaker and the audio publishing will start automatically.

Now lets imagine the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the force parameter comes in.

When it is set to true the other party will not receive a confirmation `roleChangeRequest` but instead will straight away receive a new set of updated permissions and stop publishing.

`roleUpdated` callback will still be fired so that the app can update the user's UI state.



You're chatting away on your video call and, uh-oh, a phone call comes in! No worries, the 100ms SDK abstracts away handling this situation for you.

When a telephonic voice call comes in and the user accepts the following happens.
- You and all the other parties are muted.
- If the app goes to background your video will be muted

When the call ends the SDK will restore the audio, taking care not to unmute you if you had muted yourself before the call came in. Neither will it unmute all the peers if you had muted them from the app.

No code required, this happens automatically for all calls!

Interruption Handling


Role is a powerful concept that takes a lot of complexity away in handling permissions and supporting features like breakout rooms. [Learn more about roles here.](../foundation/templates-and-roles)

Each `HMSPeer` instance has a `role` property which returns an `HMSRole` instance. You can use this property to do following:

1. Check what this role is allowed to publish. I.e can it send video (and at what resolution)? can it send audio? can it  share screen? Who can this role subscribe to? (I.e student can only see the teacher's video) This is can be discovered by checking `publishSettings` and `subscribeSettings` properties
2. Check what actions this role can perform. i.e can it change someone else's current role, end meeting, remove someone from the room. This is can be discovered by checking `permissions` property

In certain scenarios you may want to change someone's role. Imagine an audio room with 2 roles "speaker" and "listener". Only someone with a "speaker" role can publish audio to the room while "listener" can only subscribe. Now at some point "speaker" may decide to nominate some "listener" to become a "speaker". This is where the `changeRole` API comes in.

To invoke the api you will need 2 things. An instance of `HMSPeer` of the peer who's role you want to change and the `HMSRole` instance for the target role.  All the peers that are in the current room are accessible via `peers` property of `HMSRoom` instance that you can get via `room` property of `HMSSDK` instance after successful room join. A list of all available roles in the current room can be accessed via `roles` property of `HMSSDK` 

Once you have both you can invoke

```swift
 hmsSDK.changeRole(for: targetPeer, role: targetRole)
```

If the change role succeeds you will get a 

```swift
func on(peer: HMSPeer, update: HMSPeerUpdate)
```

delegate callback with the the same peer you passed as targetPeer and a `roleUpdated` update type.

`changeRole` has an optional `force` parameter which is `false` by default meaning that `changeRole` is basically a polite request: "Would you like to change you role from listener to speaker?" which can be ignored by the other party. The way it works is the other party will first receive a 

```swift
func on(roleChangeRequest: HMSRoleChangeRequest)
```

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

```swift
hmsSDK.accept(changeRole: roleChangeRequest)
```

which completes the `changeRole` loop. Both parties will receive a `roleUpdated` callback so that they both can do necessary UI updates. Now the user actually becomes a speaker and the audio publishing will start automatically. 

Now lets imagine the newly nominated speaker is not behaving nicely and we want to move him back to listener without a prompt. This is where the `force` parameter comes in. When it is set to `true` the other party will not receive a confirmation `roleChangeRequest` but instead will straight away receive a new set of updated permissions and stop publishing. `roleUpdated` callback will still be fired so that the app can update the user's UI state.


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

### Permissions

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

The permission to end a room is called `endRoom` and you should check for that within the `permissions` property of `HMSRole` of the peer to see if they have it.

 
### Ending the Room

Once you're sure the peer has the permissions to end the room they can call for the room to end when they're ready with `hmsSdk.endRoom`.

`endRoom` takes three parameters.

reason: Optional message you want to pass along the end room notification to other peers

lock: Whether you want to prevent anyone from rejoining the room. If false, they will be allowed to enter the room again if the client called `join`. If this is false, they will not able to join this room again.

completion handler: Lets you know whether the end room operation executed. was ended successfully or not. 

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

```swift
hmssdk.endRoom(lock: false, reason: "Meeting is over") { success, error in
if (success) {
    // pop to previous screen
}
}
```

### How to handle an end room callback

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

The `on(removedFromRoom:)` callback has a single parameter called `HMSRemovedFromRoomNotification` with the following structure.

```swift
class HMSRemovedFromRoomNotification {
    public let requestedBy: HMSPeer
    public let reason: String
    public let roomEnded: Bool
}
```

> 💡 This is the same callback that will be triggered if a peer was [removed from a room](Remove-Peer) as well. Except that `roomEnded` will be true when the entire room was ended.

reason: The string message detailing why the room was ended.

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

roomEnded: True if the entire room was ended. False if only the receiving peer was removed.

Clients should read this callback and show the appropriate UI.


You're running a room and decide that someone who's currently talking shouldn't be talking.

You'd prefer they'd stay mute. Or perhaps you want their video turned off as well as their audio. You're looking for a remote mute.

Muting can apply to both audio and video.

##### Unmuting

You may also decide that you want to let someone else speak who was currently muted. Or may want to ask someone to turn on their video.

You can request people to unmute themselves as well.

### Permissions

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

The permission to end a room is called `mute` and you should check for that within the `permissions` property of `HMSRole` of the peer to see if they have it.

### Muting/Unmuting

Once you have checked that the caller has permissions to mute another peer's audio or video, call for it with `hmsSdk.changeTrackState`.

To mute a track:

Get the audio or video track of the peer whom you want to mute and pass it as the first parameter to `hmsSdk.changeTrackState`.

The second parameter is a boolean for muting. If true, the track will be muted. If false the track will be requested to unmute.

Finally you can pass a completion handler to check whether changeTrackState suceeded or failed as the third parameter.

### Handling a mute callback

Muting is automatically applied to the receiver tracks. No action is required.

### Handling an unmute callback
Unmute callbacks are received in the target peer's `on(changeTrackStateRequest:)` callback of `HMSUpdateListener`.

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

Here's its structure.

```swift
class HMSChangeTrackStateRequest {
    public let track: HMSTrack
    public let mute: Bool
    public let requestedBy: HMSPeer
}
```

With the information here, show a dialog to the user to ask if they want to accept the change and then apply the settings locally. The same as in a regular user [Mute/Unmute](Mute).


Remote Mute


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


### Permissions

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

The permission to end a room is called `removeOthers` and you should check for that within the `permissions` property of `HMSRole` of the peer to see if they have it.

### Removing a peer

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

The parameters are:

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

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

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


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

### Handling the remove peer callback

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

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

```swift
class HMSRemovedFromRoomNotification {
    public let requestedBy: HMSPeer
    public let reason: String
    public let roomEnded: Bool
}
```

> 💡 This is the same callback that will be triggered if a room was [ended](End-Room) as well. Except that `roomEnded` will be false.

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

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

roomEnded: True if the entire room was ended. False if only the receiving peer was removed.

Clients should read this callback and show the appropriate UI.


## 0.1.2 - 2021-09-30
### Added
-  preview(role:completion:) API added to support showing preview screen mid call


## 0.1.1 - 2021-09-23
### Added
- changeRolesOfAllPeers API added to change roles of multiple peers at once
- changeTrackState API variant added to mute/unmute multiple peers at once
- startRTMPOrRecording and stopRTMPAndRecording APIs added to start/stop RTMP / browser recording
### Changed
- leave API now provides a completion handler that is called when leave operation has completed
- HMSTrack source property type has been changed to String to allow custom track sources
### Fixed
- onReconnecting callback was not firing upon network disconnect


## 0.0.12 - 2021-09-02
### Added
- Swift package manager support
- Bitcode support
### Changed
- Moved to xcframework


## 0.0.11 - 2021-08-25
### Added
- HMSVideoView now has a `mirror` property that controls mirroring of the video.
### Changed
- `changeRole` API now can be used to change role of a local peer.

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

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

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

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

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

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

## 0.0.4 - 2021-06-25

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

## 0.0.3 - 2021-06-22

-   Removed private modules to fix installing failure

## 0.0.2 - 2021-06-16

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

## 0.0.1 - 2021-06-04

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


Release Notes


[![Debugging](https://imgs.xkcd.com/comics/debugging.png)](https://xkcd.com/1722/)

No code ever runs in the first go. When things go wrong, debugging becomes an important aspect for a developer first SDK.
We have designed our APIs and error messages with developer experience and ease of debugging in mind. We hope that
you'll have a delightful experience walking through the features and integrating our sdk in your app.

## Console Logs

In case of any issues, we print error or warning logs in console to help with faster debugging.

![types](/guides/role-error.png)

> The [log level](../features/log-level) can be configured to control sdk logging.

## Fully Typed API

Since our Web SDK is written in TypeScript, you will get the amazing Intellisense / Autocompletion out of box.
This means that even if you use JavaScript, editors will be able to give a significantly improved experience.

![types](/guides/chat-types.png)

## Redux Devtools Integration

We take the debugging experience one step further by connecting our store to
[redux devtools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en) extension by default. This gives you transparency and
visibility into the whole room state while building your UI.

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

We highly recommend installing the [devtools](https://chrome.google.com/webstore/detail/redux-devtools/lmhkpmbekcpmknklioeibfkpmmfibljd?hl=en)
extension to visualize this state along with all the activities taking place in a single view. This makes it easier
to understand when and how the UI should change. You can use the time travel feature of the redux devtools
to recreate state changes for debugging specific issues as well.

## Feature Rich Sample App

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


## Error Codes

Do check the detailed page for listening to and handling errors [here](../features/error-handling).


Debugging


We'll list any issues related to our sdk or browsers/devices here along with any possible workarounds.

1. Audio routing issues in iOS Safari. The audio is sometimes routed to the phone speaker when an earphone is connected.

2. If there is no audio in the room for a while iOS Safari can take away autoplay permission requiring a user interaction
to play future audio. Check our section on handling autoplay errors [here](../features/error-handling#handling-autoplay-error).

3. Controlling the volume of audio elements is not supported by IOS. So, [locally muting remote peer](../advanced-features/volume-control) won't work in IOS.

Known Issues


## 0.2.0 - 2021-08-18

-   Added Support for Android! 🥳

## 0.1.0 - 2021-08-09

The first version of 100ms React Native SDK comes power-packed with support for multiple features like -

-   Join/Leave Rooms
-   Mute / Unmute Audio / Video
-   Switch Camera
-   Chat
-   Preview Screen
-   Network Switch Support
-   Subscribe Degradation in bad network scenarios
-   Error Handling and much more.

Take it for a spin! 🥳



Release Notes

0.1.0 - 2021-08-17

The first version of 100ms Flutter SDK comes power-packed with support for multiple features like -

-   Join/Leave Rooms
-   Mute / Unmute Audio / Video
-   Switch Camera
-   Chat
-   Preview Screen
-   Change Role
-   Network Switch Support
-   Subscribe Degradation in bad network scenarios
-   Error Handling and much more.

Take it for a spin! 🥳



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


Supported Devices


## Introduction

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

## Create Room

You can create room using either dashboard or API.

## Create Room using Dashboard

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

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


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

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

<Image width={2168} height={1139} alt="Room details on dashboard" src="/docs/v2/role-dashboard.png" />

## Create Room using API

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

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

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

<Tab id="req-0">

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

<Response res="200: OK" />

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

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

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

---

### recording_info
| 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. If you want to store recording with 100ms, and not use your own s3, don't add this to the object | No       |

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

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

### Options
| 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
| Name   | Type     | Description                                                                  | Required |
| :----- | :------- | :--------------------------------------------------------------------------- | :------- |
| key    | `string` | Access Key for the AWS account hosting the s3 bucket for storing recordings  | Yes      |
| secret | `string` | Secret for the AWS account hosting the s3 bucket for storing recordings      | Yes      |

## Disable Room

This API can be used to disable a room from further use

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

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

<Tab id="dis-0">

```bash
curl https://prod-in2.100ms.live/api/v2/rooms -H 'Authorization: Bearer  <management_token>' -X POST -H 'Content-Type: application/json' -d '{"name": "test-room", "active": "false"}'
```
</Tab>

<Tab id="dis-1">

<Response res="200: OK" />

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

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

### Body Paramters
| Name                 | Type     | Description                                                       | Required |
| :------------------- | :------- | :---------------------------------------------------------------- | :------- |
| name <br/>           | `string` | Room name as given during creation of the room                    | Yes      |
| active <br/>         | `bool`   | Flag to indicate disabling of the room, should be set to `false`  | Yes      |


Room


## Introduction

SFU recording can be used to save audio/video calls for offline viewing. SFU recording supports both individual and composite recordings.

## Types of SFU recording

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

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

## How to enable SFU recording

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

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

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

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

Where `Options` is

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

Where `Credentials` is

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

Composite recording mp4 will be placed at - `s3://<location>/<prefix>/<room_id>/<start_date>/<session_id>/Rec-<session_id>-<epoch>.mp4`. Example `s3://test-bucket/test-prefix/61101349d0f56e684b608c08/20210721/5fccb7dc72909272bf999014/Rec-5fccb7dc72909272bf999014-1626898422000.mp4`

Individual recording mp4s will be placed at - `s3://<location>/<prefix>/<room_id>/<start_date>/<session_id>/<peer_id>/<stream-id>/<stream-id>.mp4`. Example `s3://test-bucket/test-prefix/61101349d0f56e684b608c08/20210721/5fccb7dc72909272bf999014/76539d6b-d10d-4790-bdd2-ab57fa7facb0/9aeec8db-524d-4129-874d-7a71d340bdec/9aeec8db-524d-4129-874d-7a71d340bdec.mp4`


SFU Recording


## Introduction

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

## Pre-requisites

1. Management token

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

2. Single click meeting url to directly enter a room

## APIs

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

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

<div id="start-0">

#### Headers

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

#### Body Parameters

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

##### meeting_url

This is a url which lands into the meeting directly. If you are using 100ms apps then this will be like - `https://<domain>.app.100ms.live/preview/<room_id>/<role>?token=beam_recording`. Example - `https://myname.app.100ms.live/preview/61101349d0f56e684b608c08/beam?token=beam_recording`

#### cURL

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

</div>

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

---

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

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

<div id="stop-0">

#### Headers

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

#### Body Paramters

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

#### cURL

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

</div>

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

## Recording upload destination

By default recordings will be uploaded to 100ms storage and a presigned URL for the same will be provided to customers via a webhook. The presigned url will expire in 12hours.
Customers can also configure the recordings to be stored in their cloud storage. The configuration for the same can be provided when creating the room.

[Create Room](/server-side/v2/features/room)

Recording mp4 will be placed at - `s3://<location>/<prefix>/beam/<room_id>/<start_date>/Rec-<unique_id>-<epoch>.mp4`. Example `s3://test-bucket/test-prefix/beam/61101349d0f56e684b608c08/2021-July-21/Rec-61307a53b0f915dbebde5763-1626898422000.mp4`

## Postman Collection

<DownloadCollection type='rtmp' />


RTMP Streaming & Browser Recording


## Introduction

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


## Usage

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



Simulcast


## Introduction

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

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

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

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

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

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

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

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

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

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

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

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

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

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


Webhook


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

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

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

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

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

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

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

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


Show Audio Level


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

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

```js
const volume = 70;

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

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


Manage Audio Volume


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


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

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

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


## Accessing custom/auxiliary tracks

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

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

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

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


Name	Summary
name	[androidJvm] val name: String
ordinal	[androidJvm] val ordinal: Int

NO_DOMINANT_SPEAKER

Properties